Accessibility

Flex Quick Starts: Building an advanced user interface

Table of contents

Using item renderers

Adobe® Flex™ supports several controls that you can use to represent lists of items. These controls let the application user scroll through the item list and select one or more items from the list. All Flex list components are derived from the ListBase class, and include the following controls: DataGrid, HorizontalList, List, Menu, TileList, and Tree.

A list control gets its data from a data provider, which is a collection of objects. For example, a Tree control reads data from a data provider to define the structure of the tree and any associated data that is assigned to each tree node.

The data provider creates a level of abstraction between Flex components and the data that you use to populate them. You can populate multiple components from the same data provider, switch data providers for a component at run time, and modify the data provider so that changes are reflected by all components that use the data provider.

You can think of the data provider as the model, and the Flex components as the view of the model. By separating the model from the view, you can change one without changing the other.

Each list control has a default mechanism for controlling the display of data, or view, and lets you override that default. To override the default view, you create a custom item renderer.

There are various ways of creating and using item renderers:

Using the default item renderer

The following example contains a DataGrid control that uses the default item renderer to display the information in an XML file. Flex automatically uses the default when you do not specify a custom item renderer.

Example

<artwork>
    <piece>
        <name>The Wall</name>
        <image>artwork1.jpg</image>
        <price>250</price>
        <quantity>5</quantity>
    </piece>
    <piece>
        <name>Blue Flake</name>
        <image>artwork5.jpg</image>
        <price>400</price>
        <quantity>2</quantity>
    </piece>
    <piece>
        <name>Butterfly</name>
        <image>artwork6.jpg</image>
        <price>375</price>
        <quantity>17</quantity>
    </piece>
</artwork>

MXML file

<?xml version="1.0" encoding="utf-8"?>
<mx:Application 
    xmlns:mx="http://www.adobe.com/2006/mxml"
    viewSourceURL="src/ItemRendererDefault/index.html"
    width="450" height="140"
>
    
    <mx:Model id="artwork" source="model/artwork.xml"/>

    <mx:DataGrid rowCount="4" dataProvider="{artwork.piece}"/> 

</mx:Application>

Result

AlertThis content requires Flash

Download the free Flash Player now!

Get Adobe Flash Player

To view the full source, right-click the Flex application and select View Source from the context menu.

Back to top

Using a drop-in item renderer

Several Flex controls are designed to work as item renderers. This lets you specify these controls as values of the itemRenderer property of a list-based control. When you specify one of these controls as a property value, it is called a drop-in item renderer or drop-in item editor.

To use a component as a drop-in item renderer or drop-in item editor, a component must implement the IDropInListItemRenderer interface. The following controls implement the IDropInListItemRenderer interface, making them usable directly as a drop-in item renderer or drop-in item editor: Button, CheckBox, DateField, Image, Label, NumericStepper, Text, TextArea, and TextInput.

You can define your own components for use as drop-in item renderers or drop-in item editors. The only requirement is that they, too, implement the IDropInListItemRenderer interface.

In this example, you use the Image control as a drop-in item renderer to display thumbnail representations of various artwork and the NumericStepper control as a drop-in item renderer to give the user an easy way of altering the quantity field.

Example

<artwork>
    <piece>
        <name>The Wall</name>
        <image>assets/artwork1.jpg</image>
        <price>250</price>
        <quantity>5</quantity>
    </piece>
    <piece>
        <name>Blue Flake</name>
        <image>assets/artwork5.jpg</image>
        <price>400</price>
        <quantity>2</quantity>
    </piece>
    <piece>
        <name>Butterfly</name>
        <image>assets/artwork6.jpg</image>
        <price>375</price>
        <quantity>17</quantity>
    </piece>
</artwork>

MXML file

<?xml version="1.0" encoding="utf-8"?>
<mx:Application 
    xmlns:mx="http://www.adobe.com/2006/mxml"

    viewSourceURL="src/ItemRendererDropIn/index.html"
    width="470" height="340"
>
    <mx:Model id="artwork" source="model/artwork.xml"/>

    
    <mx:DataGrid 
        rowCount="10" variableRowHeight="true" 
        dataProvider="{artwork.piece}"
    >
        <mx:columns>

        
            <!-- Drop-in item renderer: Image control -->
            <mx:DataGridColumn 
                dataField="image" headerText="Image" 
                itemRenderer="mx.controls.Image" 
            />

            
            <mx:DataGridColumn headerText="Name" dataField="name"/>
            <mx:DataGridColumn headerText="Price" dataField="price"/>

            
            <!-- Drop-in item renderer: NumericStepper control -->
            <mx:DataGridColumn
                headerText="Quantity" dataField="quantity"
                itemRenderer="mx.controls.NumericStepper" 
            />

        </mx:columns>
    </mx:DataGrid>
    
    <mx:LinkButton
        textAlign="center"
        label="Photos (c) 2006 geishaboy500 (CC Attribution License)" 
        click="{navigateToURL(new URLRequest('http://www.flickr.com/photos/geishaboy500/'));}"

    />
    
    <mx:Script>
        <![CDATA[
            import flash.net.navigateToURL;
        ]]>

    </mx:Script>
    
</mx:Application>

Result

AlertThis content requires Flash

Download the free Flash Player now!

Get Adobe Flash Player

To view the full source, right-click the Flex application and select View Source from the context menu.

Back to top

Creating an inline item renderer

Drop-in item renderers are very easy to use but their major drawback is that you cannot configure them. To create more flexible item renderers, you can develop your item renderer as an inline component.

Note: The data model for this example differs from the one in the drop-in item renderer example. In that example, each image field contains the relative path to the folder that the images are stored in. The reason this information is in the data model is because you cannot configure the drop-in item renderer to manipulate its source property before setting it. The data model for this example is much cleaner because using an inline item renderer does allow this.

Example

<artwork>
    <piece>
        <name>The Wall</name>
        <image>artwork1.jpg</image>
        <price>250</price>
        <quantity>5</quantity>
    </piece>
    <piece>
        <name>Blue Flake</name>
        <image>artwork5.jpg</image>
        <price>400</price>
        <quantity>2</quantity>
    </piece>
    <piece>
        <name>Butterfly</name>
        <image>artwork6.jpg</image>
        <price>375</price>
        <quantity>17</quantity>
    </piece>
</artwork>

MXML file

<?xml version="1.0" encoding="utf-8"?>
<mx:Application 
    xmlns:mx="http://www.adobe.com/2006/mxml"

    viewSourceURL="src/ItemRendererInline/index.html"
    width="525" height="525"
>
    <mx:Model id="artwork" source="model/artwork.xml" />

    
    <mx:DataGrid 
        rowCount="3" variableRowHeight="true"
        dataProvider="{artwork.piece}"
    >

        <mx:columns>
        
            <!-- Drop-in item renderer: Image control -->
            <mx:DataGridColumn 
                dataField="image" headerText="Image" 
                width="150"

            >
                <mx:itemRenderer>
                    <mx:Component>
                        <mx:VBox 
                            width="100%" height="140"

                            horizontalAlign="center" verticalAlign="middle"
                        >
                            <mx:Image source="{'assets/'+data.image}"/>

                            <mx:Label text="{data.image}" />
                        </mx:VBox>
                    </mx:Component>
                </mx:itemRenderer>

            </mx:DataGridColumn>
            
            <mx:DataGridColumn headerText="Name" dataField="name"/>
            <mx:DataGridColumn headerText="Price" dataField="price"/>

            
            <mx:DataGridColumn headerText="Quantity" dataField="quantity">
                <!-- Inline item renderer -->
                <mx:itemRenderer>

                    <mx:Component>
                        <mx:VBox horizontalAlign="center" verticalAlign="middle">
                            <mx:NumericStepper 
                                maximum="{data.quantity}"

                            />
                        </mx:VBox>
                    </mx:Component>
                </mx:itemRenderer>
            </mx:DataGridColumn>

        </mx:columns>

    </mx:DataGrid>
    
    <mx:LinkButton
        textAlign="center"
        label="Photos (c) 2006 geishaboy500 (CC Attribution License)" 
        click="{navigateToURL(new URLRequest('http://www.flickr.com/photos/geishaboy500/'));}"

    />
    
    <mx:Script>
        <![CDATA[
            import flash.net.navigateToURL;
        ]]>

    </mx:Script>
    
</mx:Application>

Result

AlertThis content requires Flash

Download the free Flash Player now!

Get Adobe Flash Player

To view the full source, right-click the Flex application and select View Source from the context menu.

Back to top

Creating a reusable inline item renderer

Rather than defining an inline item renderer in the definition of a component, you can define a reusable inline item renderer for use in multiple locations in your application. You create reusable inline item renderers by using the <mx:Component> tag, setting your inline component's id property, and binding the itemRenderer property of your control to your inline component's id property.

Even if you do use an item renderer more than once, using reusable inline item renderers results in code that is easier to maintain because you can group all your item renderers in a single place in your MXML document.

In this example, you create two reusable item renderers. The first one displays an image of the current art piece and a label with the image's file name in a VBox container. The second item renderer displays a Numeric Stepper component and sets its maximum property to use the quantity value of a specific art piece so that the user cannot choose to purchase more items than there are in stock.

Example

<artwork>
    <piece>
        <name>The Wall</name>
        <image>artwork1.jpg</image>
        <price>250</price>
        <quantity>5</quantity>
    </piece>
    <piece>
        <name>Blue Flake</name>
        <image>artwork5.jpg</image>
        <price>400</price>
        <quantity>2</quantity>
    </piece>
    <piece>
        <name>Butterfly</name>
        <image>artwork6.jpg</image>
        <price>375</price>
        <quantity>17</quantity>
    </piece>
</artwork>

MXML file

<?xml version="1.0" encoding="utf-8"?>
<mx:Application 
    xmlns:mx="http://www.adobe.com/2006/mxml"

    viewSourceURL="src/ItemRendererReusable/index.html"
    width="525" height="525"
>
    <mx:Model id="artwork" source="model/artwork.xml"/>

    <!-- Reusable inline item renderers -->
    <mx:Component id="ImageRenderer">
        <mx:VBox 
            width="100%" height="140"

            horizontalAlign="center" verticalAlign="middle"
        >
            <mx:Image source="{'assets/'+data.image}"/>

            <mx:Label text="{data.image}" />
        </mx:VBox>
    </mx:Component>

    <mx:Component id="NumericStepRenderer">
        <mx:VBox horizontalAlign="center" verticalAlign="middle">
            <mx:NumericStepper 
                maximum="{data.quantity}"

            />
        </mx:VBox>
    </mx:Component>
        
    <mx:DataGrid rowCount="3" variableRowHeight="true" dataProvider="{artwork.piece}">

        <mx:columns>
            <mx:DataGridColumn 
                dataField="image" headerText="Image" width="150"
                itemRenderer="{ImageRenderer}"

            />
            <mx:DataGridColumn headerText="Name" dataField="name"/>
            <mx:DataGridColumn headerText="Price" dataField="price"/>            
            <mx:DataGridColumn 
                headerText="Quantity" dataField="quantity"

                itemRenderer="{NumericStepRenderer}"
            >
            </mx:DataGridColumn>
        </mx:columns>
        
    </mx:DataGrid>

    
    <mx:LinkButton
        textAlign="center"
        label="Photos (c) 2006 geishaboy500 (CC Attribution License)" 
        click="{navigateToURL(new URLRequest('http://www.flickr.com/photos/geishaboy500/'));}"

    />
    
    <mx:Script>
        <![CDATA[
            import flash.net.navigateToURL;
        ]]>

    </mx:Script>
    
</mx:Application>

Result

AlertThis content requires Flash

Download the free Flash Player now!

Get Adobe Flash Player

To view the full source, right-click the Flex application and select View Source from the context menu.

Back to top

Using a component as an item renderer

It is easier to create maintainable and scalable applications if you break them into multiple smaller, well-encapsulated pieces. In Flex, you can follow such a modular workflow by using custom components.

One way of defining custom components in Flex is by using MXML. A custom component has its own MXML document in which the root tag may be any Flex component other than the Application container.

In the following example, you extract the two reusable inline item renderers into their own MXML documents, making them custom components. To use a custom component as an item renderer, specify its name as the value for another control's itemRenderer property.

Note: With reusable inline item renderers you use data binding to bind to the item renderer. When you use a component as an item renderer, you do not use data binding but specify the name of the custom component to use as an item renderer.

Example

ImageRenderer component

<?xml version="1.0" encoding="utf-8"?>
<mx:VBox 
    xmlns:mx="http://www.adobe.com/2006/mxml" 
    horizontalAlign="center" verticalAlign="middle"

    width="100%" height="140"
>
    <mx:Image source="{'assets/'+data.image}"/>

    <mx:Label text="{data.image}"/>
</mx:VBox>

NumericStepRenderer component

<?xml version="1.0" encoding="utf-8"?>
<mx:VBox 
    xmlns:mx="http://www.adobe.com/2006/mxml"
    horizontalAlign="center" verticalAlign="middle"

>
    <mx:NumericStepper maximum="{data.quantity}"/>
</mx:VBox>

Main application file

<?xml version="1.0" encoding="utf-8"?>
<mx:Application 
    xmlns:mx="http://www.adobe.com/2006/mxml"
    viewSourceURL="src/ItemRendererComponent/index.html"

    width="525" height="525"
>
    <mx:Model id="artwork" source="model/artwork.xml"/>

    <mx:DataGrid rowCount="3" variableRowHeight="true" dataProvider="{artwork.piece}">
        <mx:columns>

            
            <!-- Use the ImageRenderer custom component as an item renderer -->
            <mx:DataGridColumn 
                dataField="image" headerText="Image" width="150"

                itemRenderer="ImageRenderer"
            />
            
            <mx:DataGridColumn headerText="Name" dataField="name"/>

            <mx:DataGridColumn headerText="Price" dataField="price"/>            

            <!-- 
                Use the NumericStepRenderer custom component 
                as an item renderer. 
            -->
            <mx:DataGridColumn 
                headerText="Quantity" dataField="quantity"

                itemRenderer="NumericStepRenderer"
            >
            </mx:DataGridColumn>
        
        </mx:columns>
    </mx:DataGrid>
    
    <mx:LinkButton

        textAlign="center"
        label="Photos (c) 2006 geishaboy500 (CC Attribution License)" 
        click="{navigateToURL(new URLRequest('http://www.flickr.com/photos/geishaboy500/'));}"

    />
    
    <mx:Script>
        <![CDATA[
            import flash.net.navigateToURL;
        ]]>

    </mx:Script>
    
</mx:Application>

Result

AlertThis content requires Flash

Download the free Flash Player now!

Get Adobe Flash Player

To view the full source, right-click the Flex application and select View Source from the context menu.

Back to top

For more information

About the author

Aral Balkan acts and sings, leads development teams, designs user experiences, architects rich Internet applications, and runs OSFlash.org, the London Macromedia User Group, and his company, Ariaware. He loves talking design patterns and writing for books and magazines. He also authored Arp, the open-source RIA framework for the Flash platform. Aral is generally quite opinionated, animated, and passionate. He loves to smile, and can even chew gum and walk at the same time.

Next Steps

Overview
What is an RIA?
What is Flex?
Technology overviews
Development
Architecture
Components
Designer/developer workflow
Flex and Ajax
Flex and ColdFusion
Flex and Java
Flex and .NET
Flex and PHP
Testing, security, & deployment
UI design
Related Developer Centers
Adobe AIR
BlazeDS
Force.com Toolkit for Adobe AIR and Flex
ILOG Elixir for Adobe AIR and Flex
ActionScript
Flash
Related Resources
Flex support center
Flex bug base
Flex documentation
Adobe Labs
Article archive