The framework provides a mechanism, ‘Data Binding’ for constructing complex widgets from data feeds.
Specifically, lists and carousels can be populated based on data provided in an object array.
Data Binding is a multi-stage process.
The DataSource object (antie/datasource) provides an interface for List (or extensions from List such as HorizontalCarousel) to obtain data.
When creating a DataSource you must supply
onError()callback functions. The method should invoke the
onSuccess()callback with an array of data objects if data is obtained successfully, or invoke
onError()if an error occurs.
This is best illustrated with an example.
Instantiating the DataSource From within a Component:
For this example, we’ve used a class called SimpleFeed which contains some static data. There’s no way this can fail to load, so we ignore the
A Formatter must provide the
format() should return a widget that makes up a single item for a List or Carousel.
An item can be something simple like a Button (see below), or a more complicated composite such as a List, Carousel or Container full of widgets.
format() is supplied with an iterator with which to access the data it will use.
You should call iterator.next() within the
format() function to acquire a data item (one of the objects in the array defined by the feed).
Here is a simple formatter that creates a labeled button for each item in the SimpleFeed:
Now to tie them together in a component. This example creates a HorizontalCarousel, but a plain List will work in the same way.
In the example, the DataSource is bound to the widget after it has been constructed. It is possible to pass the dataSource to the widget as a third parameter in its constructor, but it is more common to bind on
beforerender to ensure widgets are reconstructed if the component is hidden and reshown.
List and any extensions of List fire the following three events related to data binding:
|Event name||Event description|
||Fired just before before the load method is called on a DataSource.|
||Fired when data has loaded and any items generated by the Formatter have been added. This event has an
||Fired if there is an exception or non-success response whilst performing any network requests.|
If you would like to associate data with one of the created widgets for later retrieval, you can use the
setDataItem() method on a Widget from within a Formatter. It can be retrieved by calling
The framework will not set default focus on a widget which is not ‘focussable’, i.e. one which is not a Button or does not contain buttons.
As data bound widgets are initially empty, when you need default focus to fall on a data bound widget, you may need to manually set focus post bind in some circumstances.
This can be done using the
setActiveChildWidget() method of Component or a higher level Container within a function that listens for the
databound event on the widget in question.