ActionScript.org Flash, Flex and ActionScript Resources - http://www.actionscript.org/resources
Flex 2.0 ItemRenderers
http://www.actionscript.org/resources/articles/548/1/Flex-20-ItemRenderers/Page1.html
Nathan Daniel

A web developer specializing in web services and integration.  Along with HTML & PHP development, Nathan also develops RIAs utilizing Flex 2.0 and Flash!
Online portfolio and website can be seen at http://flex2.bsi-scs.com

 
By Nathan Daniel
Published on January 19, 2007
 
Difficulty: Beginner
Time: 15 minutes
Description: ItemRenderers - what, where, when, and why.  After developing Flex 2.0 applications for nearly a year (since Beta 2), I discovered ItemRenderers!  ItemRenderers are simple to implement and give greater control over the look and layout of your Flex 2.0 applications. 

The Main Application

To begin, you want to create a new Flex Project.  Open the main application MXML file for editing.  Once you're ready to edit, there are 2 steps needed

  • Add an "Array" component
  • Add a "List" component

With your main application file open, make sure you have the source editor selected (the only other choice is "design").  There are two ways to add an Array component.  You can add it via MXML or ActionScript.
MXML:
[code]
<mx:Array id="myArray">
  <mx:Object label="item one" image="one.jpg" />
  <mx:Object label="item two" image="two.jpg" />
  <mx:Object label="item three" image="three.jpg" />
</mx:Array>
[/code]
ActionScript:
[as]
[Bindable]
private var myArray:Array = new Array({label="item one",image="one.jpg"},
                                                  {label="item two",image="two.jpg"},
                                                   {label="item three",image="three.jpg"});
[/as]
The AS code must be within the <mx:Script> tag as well.

Once you've added the Array, switch to design mode and drag a "List" component onto the 'stage'.  In the Flex Properties panel (default is on the left), set the dataProvider variable to "{myArray}" (less the ").  Then, change the view of the Flex Properties panel to "Category View" (default is Standard View).  Open the "Data" element of the tree and set the "labelField" value to "label" (less the ").  This tells the List component to display the "label" field to identify the item.
If you want to bypass the design mode all together, just add in the following MXML for a List component.
[mxml]
<mx:List dataProvider="{myArray}" labelField="label" top="10" left="10" />
[/mxml]

Now, run your application.  You'll see three items in the list with the text of the label property from your Array component. 

This view is the default view of a List component.  However if you're like me, you want to spice things up a bit.  So, here is where I'll introduce the ItemRenderer!


The ItemRenderer

The next step is to design a "template" for the list items.  Our design will be fairly straightforward and simple.  Create a new MXML component based on the Canvas component.  Set the height to 22 and the width to 200.  Once you've added the component, switch to design mode.  Drag an Image component onto the stage.  In the Flex Properties panel, make sure you're in "Standard View" and select the layout tab.  On the left side you'll see 3 check boxes.  Select the center one.  On the right will pop up a text input with the current location of the image in relation to the vertical center of the stage.  Set this value to 0.  Along the top of the layout area are 3 more check boxes.  Select the left box.  In the corresponding text input at the bottom, change this value to 10. 
Next, open the "Common" tab (above the "Styles") and change the source field to "{data.image}" (less the ").
Drag out a "Label" component to the stage and place it somewhere to the right of the image component.  Open the Layout section of the Flex Properties window and select the center checkbox on the left and set the corresponding value to 0.  Select the left checkbox on top and set it's corresponding value to 34.  Also select the right check box and set it's corresponding value to 10.  This will extend the width of the label all the way out to 10 pixels from the right side of the components edge.
Open the Common tab and set the text property to "{data.label}" (less the ").  Your MXML code will look look like this:
[code]
<mx:Canvas xmlns:mx=http://www.adobe.com/2006/mxml" width="200" height="22">
 <mx:Image width="16" height="16" verticalCenter="0" left="10" source="{data.image}"/>
 <mx:Label text="{data.label}" verticalCenter="0" left="34" right="10"/> 
</mx:Canvas>
[/code]
 Now save your new component and close it's editor window.  In the next step, you'll incorporate it into your List component.


Mixing it all together

The final step is to implement your new component.  Open source view of the main application and replace labelField="label" with itemRenderer="ListItem" (ListItem is the name of my component I created, if you named your something different, it should be changed to match the name of your component).
From:
[code]
<mx:List id="myList" dataProvider="{myArray}" labelField="label"  width="200" left="10" top="10"/> 
[/code]
To:
[code]
<mx:List id="myList" dataProvider="{myArray}" itemRenderer="ListItem"  width="200" left="10" top="10"/> 
[/code]

That's it!  Run your application and your list items will now be your new component!

The beauty of the ItemRenderer is it can be used in ALL list based components - List, TileList, ComboBox, etc.  Using the ItemRenderer, you can change a ComboBox component to include more than just text as a choice - it can be an image!  Great for a product catalog or anything else you could image!