Skip to content

DataList

Jump to bottom
Mark Reeves edited this page Jan 4, 2018 · 2 revisions

Complex user interfaces may have lists which contain hundreds of items. Furthermore, these lists may be repeated within a single section of the interface.

DataLists allow for significantly reduced network usage and some in-client performance optimisation for any application which uses a specific list of selectable options more than once in the entire application flow. It is especially useful if the list appears more than once in any given screen. This optimization comes from separating the loading of the option list from the loading of the underlying page and allows the option list to be cached by the browser. The list is then injected wherever it is needed without any additional download.

Large and/or repeated lists may account for the bulk of XML and will waste a lot of network bandwidth. DataLists provide a mechanism to cache these large data sets on the client to improve application performance. The feature is enabled by default, but applications must have lists which source their items from cacheable look-up tables.

Illustrative example

A typical example of this is a country code list. Take, for example, the case of a screen which includes a country of birth list for several people (such as all members of a family group). This country of birth list can be specified to be implemented using a DataList and the list of countries (over 300) would only be dowloaded once.

Even for a single person it is common for screen to include a particular list several times. An application may, for example, provide lists for country of birth, country of citizenship and country of passport.

These may be different lists and not an immediate candidate for data list. If, however, the application includes a review screen (as required to attain WCAG 2.0 compliance for a legally binding or financial transaction - section 3.3.4 Error Prevention (Legal, Financial, Data)) then the three lists, which will each be rather lengthy with a large number of options and some options being long strings, will be repeated within the same application flow and using a DataList for these options will measurably improve performance.

Implementing Cacheable DataLists

Requirements

All of the list-type components support reading their options look-up table. WDropdown, for example, offers a constructor which takes in a table identifier. The table identifier has no special meaning to WComponents, and is used by the application to retrieve the data for the drop-down using an implementation of the LookupTable interface.

The requirements for a client-side cacheable list are:

  1. A list component, e.g. WDropdown must be created by passing in a table identifier.
  2. Applications must have a class which implements the LookupTable interface. The class must be public and have a public no-args constructor.
  3. The configuration parameter bordertech.wcomponents.factory.impl.com.github.bordertech.wcomponents.util.LookupTable must be set to the fully qualified name of the class in #2.
  4. The theme in use must support client-side caching, though it would be extremely unusual for one to not offer this support. Note: When using a theme which does not support client-side caching, developers can globally turn off caching by setting the configuration parameter bordertech.wcomponents.dataListCaching.enabled to false instead of modifying application code.

Implementing a LookupTable

Only one LookupTable implementation is used per application, and is determined by the configuration parameter bordertech.wcomponents.factory.impl.com.github.bordertech.wcomponents.util.LookupTable. There is no default implementation of this interface, but the ExampleLookupTable class in the wcomponents-examples contains an example implementation which caches certain tables on the client.

When writing a LookupTable implementation, the following methods are responsible for retrieving and interpreting table data:

List<Object> getTable(Object table);
String getCode(Object entry);
String getDescription(Object entry);

The getTable method is called by WComponents to retrieve the contents of a table given a table identifier. The identifier is the same object which is passed as the "lookupTable" parameter into the constructor for the list components. The returned lists must contain one object per option in the list, but the objects do not have to be of any specific object type.

The getCode and getDescription methods are used by WComponents to translate objects returned in the lists from getTable into a format which is usable by the client. The description is the textual information which is presented to the user and the code can be used to control the values which are sent between the client and server.

For a given table to cacheable on the client, the following methods must return non-null values.

String getCacheKeyForTable(Object table);
List<Object> getTableForCacheKey(String key);

The getCacheKey method is responsible for serializing the table identifier into a compact format suitable for passing between the client and server. Themes will cache data sets on the client for as long as the client-side cache allows and there is no way to invalidate the client-side cache. Developers are therefore strongly encouraged to include versioning information in the cache key, to avoid serving up stale data when the lists change.

The getCachedTable method is called to retrieve a table based on its cache key. Applications may wish to just deserialize the key and delegate to the getTable method.

Implementing Components

The following WComponents may implement a cacheable data list:

Some start pages

Clone this wiki locally