Adobe Flex 3 Help

Creating an item renderer and item editor

One of the first decisions that you must make when using custom item renderers and item editors is how to implement them. Flex lets you define item renderers and item editors in three different ways:

Drop-in item renderers and item editors 

Insert a single component to define an item renderer or item editor. For more information, see Using a drop-in item renderer or item editor.



Inline item renderers and item editors 

Define one or more components using child tags of the list control to define an item renderer or item editor. For more information, see Using an inline item renderer or item editor.



Item renderer and item editor components 

Define an item renderer or item editor as a reusable component. For more information, see Using a component as an item renderer or item editor.



The following sections describe each technique.

Using a drop-in item renderer or item editor

For simple item renderers and item editors, such as using a NumericStepper control to edit a field of a DataGrid control, you can use a drop-in item editor. A drop-in item renderer or drop-in item editor is a Flex component that you specify as the value of the itemRenderer or itemEditor property of a list control.

In the following example, you specify the NumericStepper control as the item editor for a column of the DataGrid control: 

<?xml version="1.0"?>
<!-- itemRenderers\dropin\DropInNumStepper.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
    
    <mx:Script>
        <![CDATA[                
            import mx.collections.ArrayCollection;
        
            [Bindable]
            private var myDP:ArrayCollection = new ArrayCollection([
                {label1:"Order #2314", quant:3, Sent:true},
                {label1:"Order #2315", quant:3, Sent:false}     
            ]);               
        ]]>
    </mx:Script>

    <mx:DataGrid id="myDG" dataProvider="{myDP}" 
        variableRowHeight="true" 
        editable="true" >
        <mx:columns>
            <mx:DataGridColumn dataField="label1" headerText="Order #"/>
            <mx:DataGridColumn dataField="quant" 
                headerText="Qty"
                itemEditor="mx.controls.NumericStepper"  
                editorDataField="value"
            />
        </mx:columns >
    </mx:DataGrid> 
</mx:Application>

The executing SWF file for the previous example is shown below:

In this example, when the user selects a cell of the column to edit it, Flex displays the NumericStepper control in that cell. Flex automatically uses the data property to populate the NumericStepper control with the current value of the column.

You use the editorDataField property to specify the property of the item editor that returns the new data for the cell. By default, the list control uses the text field of the TextInput control to supply the new value; therefore, the default value of the editorDataField property is "text". In this example, you specify that the value field of the NumericStepper supplies the new value for the cell.

You can use only a subset of the Flex components as drop-in item renderers and item editors--those components that implement the IDropInListItemRenderer interface. For more information on using drop-in item renderers and item editors, and for a list of controls that support drop-in item renderers and item editors, see Creating drop-in item renderers and item editors.

Using an inline item renderer or item editor

In the section Using a drop-in item renderer or item editor, the example shows how easy it is to use drop-in item renderers and item editors. The only drawback to using them is that you cannot configure them. You can specify the drop-in item renderers and item editors only as the values of a list control property.

To create more flexible item renderers and item editors, you develop your item renderer or item editor as an inline component. In the next example, you modify the previous example to use a NumericStepper control as an inline item editor. With an inline item editor, you can configure the NumericStepper control just as if you used it as a stand-alone control.

<?xml version="1.0"?>
<!-- itemRenderers\inline\InlineNumStepper.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
    
    <mx:Script>
        <![CDATA[
            import mx.collections.ArrayCollection;
        
            [Bindable]                
            private var myDP:ArrayCollection = new ArrayCollection([
                {label1:"Order #2314", quant:3, Sent:true},
                {label1:"Order #2315", quant:3, Sent:false}     
            ]);               
        ]]>
    </mx:Script>

    <mx:DataGrid id="myDG" dataProvider="{myDP}" 
        variableRowHeight="true" 
        editable="true" >
        <mx:columns>
            <mx:DataGridColumn dataField="label1" headerText="Order #"/>
            <mx:DataGridColumn dataField="quant" editorDataField="value" headerText="Qty">
                <mx:itemEditor>
                    <mx:Component>
                        <mx:NumericStepper stepSize="1" maximum="50"/>
                    </mx:Component>
                </mx:itemEditor>
            </mx:DataGridColumn>
        </mx:columns>
    </mx:DataGrid> 
</mx:Application>

The executing SWF file for the previous example is shown below:

In this example, you define the NumericStepper control as the item editor for the column, and specify a maximum value of 50 and a step size of 1 for the NumericStepper control.

For more information on creating inline item renderers and item editors, see Creating inline item renderers and editors.

Using a component as an item renderer or item editor

One disadvantage of using drop-in and inline item renderers and editors is that you define the item renderer or editor in the application file; therefore, it is not reusable in another location in the application, or in another application. You can create a reusable item renderer or item editor as a Flex component, and then use that component anywhere in an application that requires the item renderer.

For example, the following code uses a NumericStepper control to define a custom item editor as an MXML component:

<?xml version="1.0"?>
<!-- itemRenderers\component\myComponents\NSEditor.mxml -->
<mx:NumericStepper xmlns:mx="http://www.adobe.com/2006/mxml" 
    stepSize="1" 
    maximum="50"/>

The custom MXML component defines the item editor as a NumericStepper control. In this example, the custom item editor is named NSEditor and is implemented as an MXML component in the NSEditor.mxml file. You place the file NSEditor.mxml in the myComponents directory beneath your main application directory.

You can then use this component anywhere in an application, as the following example shows:

<?xml version="1.0"?>
<!-- itemRenderers\component\MainNSEditor.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
    
    <mx:Script>
        <![CDATA[
            import mx.collections.ArrayCollection;
        
            [Bindable]
            private var myDP:ArrayCollection = new ArrayCollection([
                {label1:"Order #2314", quant:3, Sent:true},
                {label1:"Order #2315", quant:3, Sent:false}     
            ]);               
        ]]>
    </mx:Script>

    <mx:DataGrid id="myDG" dataProvider="{myDP}" 
            variableRowHeight="true" 
            editable="true" >
        <mx:columns>
            <mx:DataGridColumn dataField="label1" 
                headerText="Order #"/>
            <mx:DataGridColumn dataField="quant" 
                itemEditor="myComponents.NSEditor" 
                editorDataField="value"/>
        </mx:columns >
    </mx:DataGrid> 
</mx:Application>

The executing SWF file for the previous example is shown below:

When the user selects a cell in the quant column of the DataGrid control, Flex displays a NumericStepper control with the current cell value.

You might have several locations in your application where users can modify a numeric value. You defined this item editor as a custom component; therefore, you can reuse it anywhere in your application.

For more information on creating item renderers and item editors as components, see Creating item renderers and item editor components.

Using editable controls in an item renderer

Item renderers do not impose restrictions on the types of Flex components that you can use in them. For example, you can use controls, such as the Label, LinkButton, Button, and Text controls, to display data, but these controls do not let the user modify the contents of the control.

Or you can use controls such as the CheckBox, ComboBox, and TextInput controls that both display data and let users interact with the control to modify or change it. For example, you could use a CheckBox control to display a selected (true value) or unselected (false value) cell in a DataGrid control.

When the user selects the cell of the DataGrid control that contains the CheckBox control, the user can interact with the control to change its state. To the user, it appears that the DataGrid control is editable.

However, an item renderer by default is not connected to the editing mechanism of the list control; it does not propagate changes to the list control's data provider, nor does it dispatch an event when the user modifies the cell. Although the list control appears to the user to be editable, it really is not.

In another example, the user changes the value of the CheckBox control, and then sorts the DataGrid column. But the DataGrid sorts the cell by the value in the data provider, not the value in the CheckBox control, so the user perceives that the sort works incorrectly.

You can manage this situation in several ways, including the following:

  • In your item renderer, do not use controls that let users modify them (CheckBox, ComboBox, and others).
  • Create custom versions of these controls to prohibit user interaction with them.
  • Use the rendererIsEditor property of the list control to specify that the item renderer is also an item editor. For more information, see Example: Using an item renderer as an item editor.
  • Write your own code for the item renderer and hosting control to pass data back from the item renderer when you do let users interact with it. For more information and an example, see Example: Passing multiple values back from an item editor.