Creating item renderers and item editor components
Defining a custom item renderer or item editor by using an MXML component gives you greater flexibility and functionality than using a drop-in item renderer or item editor. Many of the rules for defining item renderers and item editors as custom components are the same as for using inline item renderers and editors. For more information, see Creating inline item renderers and editors.
For more information on working with custom components, see Creating and Extending Adobe Flex 3 Components.
Creating an item renderer component
The section Default item rendering and cell editing shows a DataGrid control that displays information about albums by using three text fields. You could add a visual element to your DataGrid control to make it more compelling. To do that, you modify the data provider so that it contains a URL for a JPEG image of the album cover.
The default item renderer for a DataGrid control displays data as text. To get the DataGrid control to display the image of the album cover, you use the custom item renderer defined in the RendererDGImage.mxml file, as the following example shows:
<?xml version="1.0"?>
<!-- itemRenderers\myComponents\RendererDGImage.mxml -->
<mx:HBox xmlns:mx="http://www.adobe.com/2006/mxml"
horizontalAlign="center" >
<mx:Image id="albumImage" height="175" source="{data.Cover}"/>
</mx:HBox>
The item renderer contains an Image control in an HBox container. The HBox container specifies to center the image in the container; otherwise, the image appears flush left in the cell. The Image control specifies the height of the image as 75 pixels. By default, an image has a height of 0 pixels; therefore, if you omit the height, the image does not appear.
You use data binding to associate fields of a data property with the controls in an item renderer or item editor. In this example, the data property that is passed to the item renderer contains the element of the data provider for the entire row of the DataGrid control. You then bind the Cover field of the data property to the Image control.
The following example illustrates using a custom item renderer with the DataGrid control:
<?xml version="1.0"?>
<!-- itemRenderers\MainDGImageRenderer.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
<mx:Script>
<![CDATA[
import mx.collections.ArrayCollection;
[Bindable]
private var initDG:ArrayCollection = new ArrayCollection([
{Artist:'Pavement', Album:'Slanted and Enchanted',
Price:11.99, Cover: '../assets/slanted.jpg'},
{Artist:'Pavement', Album:'Brighten the Corners',
Price:11.99, Cover: '../assets/brighten.jpg'}
]);
]]>
</mx:Script>
<mx:DataGrid id="myGrid"
dataProvider="{initDG}"
variableRowHeight="true">
<mx:columns>
<mx:DataGridColumn dataField="Artist"/>
<mx:DataGridColumn dataField="Album"/>
<mx:DataGridColumn dataField="Cover"
itemRenderer="myComponents.RendererDGImage"/>
<mx:DataGridColumn dataField="Price"/>
</mx:columns>
</mx:DataGrid>
</mx:Application>
The executing SWF file for the previous example is shown below:
The DataGrid control contains a column for the album cover that uses the itemRenderer property to specify the name of the MXML file that contains the item renderer for that column. Now, when you run this example, the DataGrid control uses your custom item renderer for the Cover column to display an image of the album cover.
Rather than having the album name and album image in separate cells of the DataGrid control, you can use an item renderer to make them appear in a single cell, as the following example shows:
<?xml version="1.0"?>
<!-- itemRenderers\inline\myComponents\RendererDGTitleImage.mxml -->
<mx:VBox xmlns:mx="http://www.adobe.com/2006/mxml"
horizontalAlign="center" height="75">
<mx:Text id="albumName"
width="100%"
selectable="false"
text="{data.Album}"/>
<mx:Image id="albumImage"
source="{data.Cover}"/>
</mx:VBox>
You save this item renderer to the RendererDGTitleImage.mxml file. The DataGrid control in the main application references the item renderer, as the following example shows:
<?xml version="1.0"?>
<!-- itemRenderers\MainDGTitleRenderer.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
<mx:Script>
<![CDATA[
import mx.collections.ArrayCollection;
[Bindable]
private var initDG:ArrayCollection = new ArrayCollection([
{Artist:'Pavement', Album:'Slanted and Enchanted',
Price:11.99, Cover: '../assets/slanted.jpg'},
{Artist:'Pavement', Album:'Brighten the Corners',
Price:11.99, Cover: '../assets/brighten.jpg'}
]);
]]>
</mx:Script>
<mx:DataGrid id="myGrid"
dataProvider="{initDG}"
variableRowHeight="true">
<mx:columns>
<mx:DataGridColumn dataField="Artist" />
<mx:DataGridColumn dataField="Album"
itemRenderer="myComponents.RendererDGTitleImage" />
<mx:DataGridColumn dataField="Price" />
</mx:columns>
</mx:DataGrid>
</mx:Application>
The executing SWF file for the previous example is shown below:
In the preceding example, you define three columns in the DataGrid control, and assign your item renderer to the second column. For an image that shows the output of this application, see Using custom item renderers and item editors.
Creating a simple item editor component
A simple item editor component defines a single control that you use to edit a cell, and returns a single value to the list control. For an example of a simple item editor component, see Using a component as an item renderer or item editor.
A complex item editor can contain multiple components, or can return something other than a single value to the list control. For more information, see Working with Item Editors.
Overriding the data property
All components that you use in a custom item renderer or item editor that require access to the data passed to the renderer must implement the mx.core.IDataRenderer interface to define the data property. All Flex containers and many Flex components support this property.
Classes implement the mx.core.IDataRenderer interface by defining the data property as a setter and getter method, with the following signature:
override public function set data(value:Object):void public function get data():Object
In the setter method, value is the data property passed to the item renderer.
If you define a custom component and you want to support the data property, your component must implement the mx.core.IDataRenderer interface. If your component is a subclass of a class that already implements the mx.core.IDataRenderer interface, you do not have to reimplement the interface.
To add programmatic logic to the controls in your item renderer or item editor that already implement the data property, you can override the setter or getter method for the data property. Typically, you override the setter method so that you can perform some operation based on the value that is passed to it.
For example, the following DataGrid control uses true and false for the values of the SalePrice field of the data provider. Although you could display these values in your DataGrid control, you can create a more compelling DataGrid control by displaying images instead, as the following item renderer shows:
<?xml version="1.0"?>
<!-- itemRenderers\component\myComponents\RendererDGImageSelect.mxml -->
<mx:HBox xmlns:mx="http://www.adobe.com/2006/mxml"
horizontalAlign="center">
<mx:Script>
<![CDATA[
import mx.events.FlexEvent;
[Embed(source="saleIcon.jpg")]
[Bindable]
public var sale:Class;
[Embed(source="noSaleIcon.jpg")]
[Bindable]
public var noSale:Class;
override public function set data(value:Object):void {
if(value != null) {
super.data = value;
if (value.SalePrice == true) onSale.source=new sale();
else onSale.source=new noSale();
}
// Dispatch the dataChange event.
dispatchEvent(new FlexEvent(FlexEvent.DATA_CHANGE));
}
]]>
</mx:Script>
<mx:Image id="onSale" height="20"/>
</mx:HBox>
In this example, you override the setter method for the HBox container. In the override, use super.data to set the data property for the base class, and then set the source property of the Image control based on the value of the SalePrice field. If the field is true, which indicates that the item is on sale, you display one icon. If the item is not on sale, you display a different icon.
The override also dispatches the dataChange event to indicate that the data property has changed. You typically dispatch this event from the setter method.
About using the creationComplete and dataChange events
Flex dispatches the creationComplete event once for a component after the component is created and initialized. Many custom components define an event listener for the creationComplete event to handle any postprocessing tasks that must be performed after the component is completely created and initialized.
However, although for an item renderer or item editor, Flex might reuse an instance of the item renderer or item editor, a reused instance of an item renderer or item editor does not redispatch the creationComplete event. Instead, you can use the dataChange event with an item renderer or item editor. Flex dispatches the dataChange event every time the data property changes. The example in the section Accessing the listData property uses the dataChange event to update the TextArea in an item renderer for a DataGrid control.
Creating an item renderer in ActionScript
Although you commonly create item renderers and editors in MXML, you can also create them in ActionScript, as the following example item renderer shows:
package myComponents {
// myComponents/CellField.as
import mx.controls.*;
import mx.core.*;
import mx.controls.dataGridClasses.DataGridListData;
public class CellField extends TextInput
{
// Define the constructor and set properties.
public function CellField() {
super();
height=60;
width=80;
setStyle("borderStyle", "none");
editable=false;
}
// Override the set method for the data property.
override public function set data(value:Object):void {
super.data = value;
if (value != null)
{
text = value[DataGridListData(listData).dataField];
if(Number(text) > 100)
{
setStyle("backgroundColor", 0xFF0000);
}
}
else
{
// If value is null, clear text.
text= "";
}
super.invalidateDisplayList();
}
}
}
In the preceding example, you create a subclass of the TextInput control as your item renderer. The class must be public to be used as an item renderer or editor. This item renderer displays a red background if the value of the DataGrid cell is greater than 100.
You can use this item renderer in a DataGrid control, as the following example shows:
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- itemRenderers\asRenderer\MainASItemRenderer.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
width="600" height="600">
<mx:Script>
<![CDATA[
import mx.collections.ArrayCollection;
[Bindable]
private var initDG:ArrayCollection = new ArrayCollection([
{Monday: 12, Tuesday: 22, Wednesday: 452, Thursday: 90},
{Monday: 258, Tuesday: 22, Wednesday: 45, Thursday: 46},
{Monday: 4, Tuesday: 123, Wednesday: 50, Thursday: 95},
{Monday: 12, Tuesday: 52, Wednesday: 111, Thursday: 20},
{Monday: 22, Tuesday: 78, Wednesday: 4, Thursday: 51}
]);
]]>
</mx:Script>
<mx:Text text="All cells over 100 are red" />
<mx:DataGrid id="myDataGrid"
dataProvider="{initDG}"
variableRowHeight="true">
<mx:columns>
<mx:DataGridColumn dataField="Monday"
itemRenderer="myComponents.CellField" />
<mx:DataGridColumn dataField="Tuesday"
itemRenderer="myComponents.CellField" />
<mx:DataGridColumn dataField="Wednesday"
itemRenderer="myComponents.CellField" />
<mx:DataGridColumn dataField="Thursday"
itemRenderer="myComponents.CellField" />
</mx:columns>
</mx:DataGrid>
</mx:Application>
The executing SWF file for the previous example is shown below: