Accessibility

Flex Quick Starts: Building an advanced user interface

Table of contents

Creating item editors

Item editors let you modify the value of a cell of a list control. The DataGrid, List, and Tree controls support item editors.

Link: Adobe® Flex™ also supports item renderers for customizing how components display data. For more information, see Using item renderers in the Quick Start tutorials.

The DataGrid, List, and Tree controls include an editable property that you set to true to let users edit the contents of the control. By default, the value of the editable property is false, which means that you cannot edit the cells.

There are various ways of creating and using item renderers:

Using the default item editor

By default, Flex expects an item editor to return a single value to the list control. You use the editorDataField property of the list control to specify the property of the item editor that contains the new data. Flex converts the value to the appropriate data type for the cell.

The default item editor is a TextInput control. Therefore, the default value of the editorDataField property is text, which corresponds to the text property of the TextInput control.

The following example contains a DataGrid control that has its editable property set to true. This example doesn't define a custom item editor, so the DataGrid uses the default item editor. Users can modify the values in each of its fields by clicking a cell and editing the displayed value in the TextInput control.

Tip: For a DataGrid control, setting the editable property to true enables editing for all columns of the grid. You can disable editing for any column by setting the editable property of the DataGridColumn instance to false.

Example

Data model (artwork.xml)

<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/ItemEditorDefault/index.html"

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

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


</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 editor

The simplest way to use custom item editors is to use a drop-in item editor. A drop-in item editor is a Flex component that you specify as the value of the itemEditor property of a list-based control such as the List, Tree, ComboBox or DataGrid controls. For example, you can use a NumericStepper control to edit a field of a DataGrid control.

To use a component as a 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 to use as drop-in item editors. The only requirement is that they, too, implement the IDropInListItemRenderer interface.

In the following example, you use the NumericStepper control as a drop-in item editor to give the user an easy way of altering the quantity field of the DataGrid control. You must click on a cell in the Quantity column to enable the item editor. This example also uses an Image control as an item renderer to display thumbnail images of the artwork.

Tip: The example uses the editorXOffset, editorYOffset, editorWidthOffset and editorHeightOffset properties of the DataGridColumn object to size and position the NumericStepper control in the middle of the cell.

Example

Data model (artwork.xml)

<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 files

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

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

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

        editable="true"
    >
        <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 editor: NumericStepper control -->
            <mx:DataGridColumn
                headerText="Quantity" 
                dataField="quantity"
                itemEditor="mx.controls.NumericStepper"

                editorDataField="value" 
                editorXOffset="22"
                editorYOffset="25"
                editorWidthOffset="-40"
                editorHeightOffset="-50"

            />

        </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 editor

Drop-in item editors are very easy to use but their major drawback is that you cannot configure them. To create more flexible item editors, you can develop your item editor as an inline component by using the <mx:Component> tag.

In the following example, you create an inline item editor that contains a Numeric Stepper control. The example uses an inline item editor, so you can configure the NumericStepper by setting its maximum and stepSize properties.

Example

Data model (artwork.xml)

<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/ItemEditorInline/index.html"
    width="525" height="525"
>
    <mx:Model id="artwork" source="model/artwork.xml"/>

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

    >
        <mx:columns>
        
            <!-- Inline 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"/>

            <!-- Inline item editor: NumericStepper -->            
            <mx:DataGridColumn 
                headerText="Quantity" 
                dataField="quantity"
                editorDataField="value"

            >
                <mx:itemEditor>
                    <mx:Component>
                        <mx:NumericStepper 
                            maximum="100" stepSize="10"

                        />
                    </mx:Component>
                </mx:itemEditor>
            </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 editor

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

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

In this example, you create a reusable item editor that uses a Numeric Stepper control.

Example

Data model (artwork.xml)

<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/ItemEditorReusable/index.html"
    width="525" height="525"
>
    <mx:Model id="artwork" source="model/artwork.xml"/>

    <!-- Reusable inline item editor -->
    <mx:Component id="NumericStepEditor">
        <mx:NumericStepper 
            maximum="100" stepSize="10"

        />
    </mx:Component>

    <!-- Reusable inline item renderer -->
    <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:DataGrid 
        rowCount="3" variableRowHeight="true" 
        dataProvider="{artwork.piece}"

        editable="true"
    >

        <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"

                itemEditor="{NumericStepEditor}"
                editorDataField="value"
            >
            </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 editor

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 reusable inline item renderer containing the Image and Label controls and the reusable inline item editor containing the NumericStepper control into their own MXML documents, making them custom components.

To use a custom component as an item renderer, you specify its name as the value for another control's itemRenderer property. Similarly, to use a custom component as an item editor, you specify its name as the vlaue for another control's itemEditor property.

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

Example

NumericStepEditor component

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

>
    <mx:Script>
        <![CDATA[
            // Expose the editor's value
            public function get newQuantity ():uint
            {

                return myStepper.value;
            }
        ]]>
    </mx:Script>

    <mx:NumericStepper 
        id="myStepper" 
        maximum="100" 
        stepSize="1"

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

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>

Main application file

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

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

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

    >
        <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"

                itemEditor="NumericStepEditor"
                editorDataField="newQuantity"
            >
            </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
ActionScript
Flash
Related Resources
Flex support center
Flex bug base
Flex documentation
Adobe Labs
Article archive