< Jewel Components list

Jewel DataContainer


Available since version 0.9.4.

Class Extends Implements
org.apache.royale.jewel.DataContainer Jewel ContainerBase Jewel IListWithPresentationModel

Note: This component is currently only available for JavaScript.


The Jewel DataContainer class is a component that displays multiple data items.

This component gets the data through its dataProvider property that receives an ArrayList of data objects. To represent each item the component uses a suitably-configured ItemRenderer class. The component generates dynamically as many instances of its ItemRenderer as there are items in the data provider array, and fills each instance with the appropiate data. By default it uses StringItemRenderer as the item renderer.

By default items are laid out vertically using Jewel VerticalLayout. This component has a Viewport that clips generated items.

Example of use

In MXML declare a DataContainer like this:

<j:DataContainer width="100%" height="250">
    <js:ArrayList localId="avengers" source="[Iron Man, Hulk, Thor, Captain America, Black Widow, Hawkeye]"/>

Note that we can nest the ArrayList directly to the DataContainer tag because “dataProvider” is its DefaultProperty.

In ActionScript we can do the same in the following way:

var dc:DataContainer = new DataContainer();
dc.dataProvider = new ArrayList(["Iron Man", "Hulk", "Thor", "Captain America", "Black Widow", "Hawkeye"]);
// add the Container to the parent

where parent is the container where the control will be added.

Relevant Properties and Methods

Check the Reference of org.apache.royale.jewel.DataContainer for a more detailed list of properties and methods.


PROPERTY Type Description
currentState String The name of the current state.
itemRenderer String The class or factory used to display each item.
labelField String The name of field within the data used for display.
dataProvider Object The data being display by the List. Is the DefaultProperty. In Jewel an ArrayList
numElements int The number of element children that can be laid out.
states Array The array of view states. These should be instances of org.apache.royale.states.State
strandChildren IParent An object to access the immediate children of the strand.


Method Parameters Description
addElement c(IChild), dispatchEvent(Boolean=true) Add a component to the parent.
addElementAt c(IChild), index(int), dispatchEvent(Boolean=true) Add a component to the parent at the specified index.
getElementIndex c(IChild) Gets the index of this subcomponent.
getElementAt index(int) Get a component from the parent at specified index.
removeElement c(IChild), dispatchEvent(Boolean=true) Remove a component from the parent.

Relevant Events

The most important event is initComplete, which indicates that initialization of the container is complete.

It is needed when some action coded in a callback function needs to be triggered when the data container is ready to use after initialization.

You can attach callback listeners to the initComplete event in MXML as follows:

<j:DataContainer initComplete="initCompleteHandler(event)"/>

the initComplete event will use the initCompleteHandler callback function you provide in ActionScript:

        private function initCompleteHandler(event:Event):void {
            trace("Container is ready!");

When the data container is initialized the message “Container is ready!” appears in the console log.

In ActionScript we can add an event handler this way:

var dc:DataContainer = new DataContainer();
dc.addEventListener('initComplete', initCompleteHandler);

Relevant Beads

Bead Type Implementation Description
DataProviderModel org.apache.royale.core.IBeadModel This is the default model bead.
DataContainerView org.apache.royale.core.IBeadView This is the default view bead.
VerticalLayout org.apache.royale.core.IBeadLayout This is the default layout bead.
DataItemRendererFactoryForCollectionView IDataProviderItemRendererMapper Map data to itemrenders.
ItemRendererClassFactory IItemRendererClassFactory The factory of itemrenders.
StringItemRenderer org.apache.royale.core.IItemRenderer The itemrenders class to instantiate.
DataContainerItemRendererInitializer IItemRendererInitializer Configuration of itemrenders to instantiate.
Viewport org.apache.royale.core.IViewport Define the area that display content.

Common Beads

Jewel DataContainer can use any of the layout beads available in the Jewel library. Also you can check the Related controls section to see some advanced or preconfigured data containers.

More examples

Other useful Jewel containers components are: