The Flex ItemRenderer – What is It and Why Use It

August 17, 2009 by Lance Jones

Item renders are the way to override the display mechanism for Flex’s list-based objects. If you are looking to add any degree of style or complexity to any of these objects above the default “out-of-the-box” capabilities, then item renderers are a must.

The itemRenderer object is available in different flavors, and depending on what you would like to accomplish, there is a flavor for you. The Drop-In, the Inline and the Custom itemRenderer are three possible solutions for adding rich content and components, and can give your project a greater level of sophistication. In this example I use the DataGrid as my list-based component.

Drop-In Item Renderers

The simplest of the itemRenderers is the Drop-In. It is written directly in the MXML so even though the Drop-In can get your project to higher levels of usability, the additional effort may not make it the first choice for more complex objectives. However if you would simply like to add a component, you need only reference that component as the value of the itemRenderer property for the list-based control.

The data can be located in the MXML itself as part of the DataGrid, located in the outerDocument or as an external file. The DataGrid in this first example has the dataProvider wrapped inside the DataGrid, so there is no need to identify it as the dataProvider for the DataGrid. However, if the data to be used is outside the DataGrid control, the DataGrid would need to be made aware of the data through it’s dataProvider property.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

<xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute">
<mx:DataGrid>
	<mx:columns>
		<mx:DataGridColumn headerText="Song #" dataField="songID" />
		<mx:DataGridColumn itemRenderer="mx.controls.Image" headerText="Image" dataField="img" />
	</mx:columns>
	<mx:dataProvider>
		<mx:ArrayCollection>
			<mx:Array>
				<mx:Object img="images/0.jpg" songID="0" />
				<mx:Object img="images/1.jpg" songID="1" />
				<mx:Object img="images/2.jpg" songID="2" />
			</mx:Array>
		</mx:ArrayCollection>
	</mx:dataProvider>
</mx:DataGrid>
</mx:Application>

Inline Item Renderers

Inline itemRenderer’s offer a bit more in terms of flexibility. Inline itemRenderers allow you to set of properties of the components used by the itemRenderer. When using the Inline version the component you wish to use must be wrapped by a Component tag. The Component tag creates a new scope and where there can only be one root node. If you want to call a method or make use of a property defined outside that scope, you can use outerDocument.methodName or outerDocument.propertyName. I find that using parentDocument in place of outerDocument also works as well.

Notice the value for the source property in the Image component. The dataProvider attribute provides the data for the DataGrid:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute">
 
<mx:Script>
	<![CDATA[
		import mx.controls.Alert;
		import mx.collections.ArrayCollection;
 
		[Bindable] 
		public var inlineAC:ArrayCollection= new ArrayCollection(
			[
				{songID:"3", img:'3.jpg'},
				{songID:"4", img:'4.jpg'}
			]
		);
 
		public function firedButton():void {
			Alert.show("Button fired!")
		}
	]]>
</mx:Script>
 
<mx:DataGrid rowCount="3" variableRowHeight="true" dataProvider="{inlineAC}">
	<mx:columns>
		<mx:DataGridColumn headerText="Song #" dataField="songID" />
		<mx:DataGridColumn headerText="Image">
			<mx:itemRenderer>
				<mx:component>
					<mx:VBox horizontalAlign="center" height="100" verticalAlign="middle" width="100%">
						<mx:VBox source="{'images/'+data.img}" />
					</mx:VBox>
				</mx:component>
			</mx:itemRenderer>
		</mx:DataGridColumn>
		<mx:DataGridColumn headerText="Various Components">
			<mx:itemRenderer>
				<mx:component>
					<mx:HBox>
						<mx:Button click="{outerDocument.fireButton()}" label="Button" />
						<mx:RadioButton />
					</mx:HBox>
				</mx:component>
			</mx:itemRenderer>
		</mx:DataGridColumn>
	</mx:columns>
</mx:mx:Image>
</mx:Application>

Customer Item Renderers

A custom itemRenderer offers the most in flexibility – both in ease of reuse and in seperation. In the third DataGrid the data source is located in an external xml file and the itemRenderer is in a seperate MXML file. Having the files seperate enables the class to be repurposed and can save significant development time on larger, more robust projects.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute">
 
<mx:Script>
	<![CDATA[
		import mx.controls.Alert;
		public function fireButton():void {
			Alert.show("Button fired!");
		}
	]]>
</mx:Script>
 
<mx:Model id="externalXML" source="model/sample.xml" />
 
<mx:DataGrid height="300" dataProvider="{externalXML.album}">
	<mx:columns>
		<mx:DataGrid headerText="Song #" dataField="songID" />
		<mx:DataGridColumn headerText="Image">
			<!-- Example Drop-In item renderer -->
			<mx:itemRenderer>
				<mx:component>
					<mx:VBox horizontalAlign="center" height="100" verticalAlign="middle" width="100%">
						<mx:Image source="{data.img}" />
					</mx:VBox>
				</mx:component>
			</mx:itemRenderer>
		</mx:DataGridColumn>
		<!-- Example Custom item renderer -->
		<mx:DataGridColumn itemRenderer="view.customRenderer" headerText="Various Components" />
	</mx:columns>
</mx:DataGrid>
</mx:Application>
1
2
3
4
5
6
7

<!-- FILE: view/customRenderer.mxml -->
 
<?xml version="1.0" encoding="utf-8"?>
<mx:HBox height="300" xmlns:mx="http://www.adobe.com/2006/mxml" width="400">
	<mx:Button click="{parentDocument.fireButton()}" label="Button" />
	<mx:RadioButton />
</mx:HBox>
<!-- FILE: model/sample.xml -->
 
<?xml version="1.0" encoding="utf-8"?>
<externalxml>
    <album>
        <songid>5</songid>
        <img>images/AlbumArt1.jpg</img>
    </album>
    <album>
        <songid>6</songid>
        <img>images/AlbumArt2.jpg</img>
    </album>
</externalxml>

Incorporating itemRenderers into your project adds value and really opens the door for producing significantly more functional and dynamic projects. Hopefully this post makes starting down that path a little less daunting.

Tags: , , ,

Share