itemRenderers: Part 2: External renderers

In Part 1 of this series I showed you how to make an inline itemRenderer. That is, an itemRenderer whose MXML tags and ActionScript code are in the same file as the list using the itemRenderer. The code is "in line" with the rest of the code in the file.

You’ll also recall that I said you should think of inline itemRenderers are being separate classes. The Flex compiler in fact extracts that inline code and makes a class for you. What we’re going to do in this article is make the class ourselves. The benefit of inline itemRenderers is that the code is in the same place as the list, but that’s also a drawback when the itemRenderer becomes complex.

Extracting the itemRenderer into an external file has several benefits:

  • The itemRenderer can easily be used in multiple lists;
  • the code is easier to maintain;
  • you can use Flex Builder’s Design View to sketch out the initial itemRenderer.

An MXML itemRenderer

From the previous article you saw there was a complex itemRenderer used for a DataGrid:

<mx:DataGridColumn headerText="Title" dataField="title">
<mx:HBox paddingLeft="2">
override public function set data( value:Object ) : void { = value;
var today:Number = (new Date()).time;
var pubDate:Number = Date.parse(;
if( pubDate > today ) setStyle("backgroundColor",0xff99ff);
else setStyle("backgroundColor",0xffffff);
<mx:Image source="{data.image}" width="50" height="50" scaleContent="true" />
<mx:Text width="100%" text="{data.title}" />

The itemRenderer is based on an HBox, contains an Image and a Text, and the background color is set according to the pubDate field of the item record. You can write this same itemRenderer as an external file using these steps:

  1. If you are using Flex Builder, create a new MXML Component file (I’ve named mine GridColumnSimpleRenderer, but use whatever you like) and set the root tag to be HBox. Don’t worry about the size.
  2. If you are using the SDK alone, create a new MXML file (call it GridColumnSimpleRenderer.mxml) and set the root tag to be HBox.
  3. With the file open, copy everything between <mx:HBox> and </mx:HBox>, but do not copy those tags since they are already in the file. The result should look something like this:
    <?xml version="1.0" encoding="utf-8"?>
    <mx:HBox xmlns:mx="" width="400" height="300">
    override public function set data( value:Object ) : void { = value;
    var today:Number = (new Date()).time;
    var pubDate:Number = Date.parse(;
    if( pubDate > today ) setStyle("backgroundColor",0xff99ff);
    else setStyle("backgroundColor",0xffffff);
    <mx:Image source="{data.image}" width="50" height="50" scaleContent="true" />
    <mx:Text width="100%" text="{data.title}" />
  4. Save the file.

Now modify the DataGridColumn definition by removing the inline itemRenderer and replacing it with this:

<mx:DataGridColumn headerText="Title" dataField="title" itemRenderer="GridColumnSimpleRenderer">

Now run the application. You’ll get a surprise.

The surprise is how tall the rows are. That’s because of the presence of height="300" on the itemRenderer.

Determining an itemRenderer’s width and height

The list control always sets the itemRenderer’s width. In this example, the explicit width="400" is ignored. You should write your itemRenderer to assume the width will change as the user changes the column or list’s width.

The height is a different matter. If the list has an explicit rowHeight set, it will impose that height on each row, ignoring any height you’ve set on the itemRenderer. However, if you set the list’s variableRowHeight property to true, then the list will seriously consider the itemRenderer’s height. In this example, the height is explicitly set to 300, so each row is 300 pixel’s high.

To fix this, remove the explict height from the itemRenderer file and the application will work correctly.

Dynamically Changing the itemRenderer

In this example the set data function has been overridden to examine the data and set the itemRenderer’s backgroundColor. This is very common. Overriding set data allows you to intercept the time when the data is being changed for a new row and you can you make style changes.

Common mistakes are:

  • Forgetting to call = value; this is VITAL – failure to do this will really mess up your itemRenderer;
  • Forgetting to reset the style(s) if any tests fail. It might be tempting to just set the color when the pubDate is in the future, but you have to remember that itemRenderers are recycled and so the else statement is very necessary.

An ActionScript itemRenderer

Now we’ll write another itemRenderer, this time using an ActionScript class. In the previous article there is a TileList with this inline itemRenderer:

<mx:HBox verticalAlign="top">
<mx:Image source="{data.image}" />
<mx:VBox height="115" verticalAlign="top" verticalGap="0">
<mx:Text text="{data.title}" fontWeight="bold" width="100%"/>
<mx:Spacer height="20" />
<mx:Label text="{}" />
<mx:Label text="Available {}" />
<mx:Spacer height="100%" />
<mx:HBox width="100%" horizontalAlign="right">
<mx:Button label="Buy" fillColors="[0x99ff99,0x99ff99]">
var e:BuyBookEvent = new BuyBookEvent();
e.bookData = data;

We’ll make that into an ActionScript, external, itemRenderer. You’ll need to follow these steps:

  1. Create a new ActionScript class. Call it and make it extend HBox, just like the inline itemRenderer.
    import mx.containers.HBox;
    import mx.containers.VBox;
    import mx.controls.Button;
    import mx.controls.Image;
    import mx.controls.Label;
    import mx.controls.Spacer;
    import mx.controls.Text;
    public class BookTileRenderer extends HBox
    public function BookTileRenderer()
  2. Create member variables to hold the references to the child components.
    		private var coverImage:Image;
    private var titleText:Text;
    private var spacer1:Spacer;
    private var authorLabel:Label;
    private var pubdateLabel:Label;
    private var spacer2:Spacer;
    private var buyButton:Button;
  3. Override the createChildren() function to create the child components and add them to the HBox.
    		override protected function createChildren():void
    coverImage = new Image();
    var innerBox:VBox = new VBox();
    innerBox.explicitHeight = 115;
    innerBox.percentWidth = 100;
    innerBox.setStyle("verticalGap", 0);
    titleText = new Text();
    titleText.percentWidth = 100;
    spacer1 = new Spacer();
    spacer1.explicitHeight = 20;
    authorLabel = new Label();
    pubdateLabel = new Label();
    spacer2 = new Spacer();
    spacer2.percentHeight = 100;
    var buttonBox:HBox = new HBox();
    buttonBox.percentWidth = 100;
    buyButton = new Button();
    buyButton.label = "Buy";
    buyButton.addEventListener(MouseEvent.CLICK, handleBuyClick);

     I’ve indented the code to show the parent-child relationships. Also, make sure you include an event listener on the Buy button.

  4. Override the commitProperties() function and set the user interface controls from the data.
    		override protected function commitProperties():void
    coverImage.source = data.image;
    titleText.text = data.title;
    authorLabel.text =;
    pubdateLabel.text =;
  5. Add the click event handler for the Buy button.
    		private function handleBuyClick( event:MouseEvent ) : void
    var e:BuyBookEvent = new BuyBookEvent();
    e.bookData = data;
  6. Modify the TileList in the main application to use the itemRenderer ActionScript class. Simply remove the inlineItemRenderer and replace it with an itemRenderer property right in the tag.
    <mx:TileList id="mylist" x="29" y="542" width="694" itemRenderer="BookTileRenderer"
    dataProvider="{}" height="232" columnWidth="275" rowHeight="135" >

If you are going to use an existing container class, such as HBox, I wouldn’t bother doing this in ActionScript. You can see it is more complex than using an MXML file and, quite frankly, there is little performance benefit to it.

Reusable itemRenderers

Here’s an example of an itemRenderer that displays a numeric value using the CurrencyFormatter. I call it PriceFormatter:

<?xml version="1.0" encoding="utf-8"?>
<mx:Text xmlns:mx="">

import mx.controls.dataGridClasses.DataGridListData;

[Bindable] private var formattedValue:String;

override public function set data(value:Object):void
{ = value;

formattedValue = cfmt.format( Number(data[(listData as DataGridListData).dataField]) );

<mx:CurrencyFormatter precision="2" id="cfmt" />



The key to this itemRenderer is shown in red, setting the bindable variable, formattedValue. First, you’ll see that <mx:CurrentFormatter> was defined as an MXML tag (you can do this in ActionScript, too, if you prefer) with an id of cfmt. In the example above, the formattedValue is set to the result of calling the CurrentFormatter’s format() function.

The function takes a Number as its parameter type, so the value is cast to Number – that’s because the dataProvider for the list is XML and everything in XML is text; if you use a Object for your data and you have real numeric values, doing the Number cast will be harmless.

As you know, data is the property which holds the item being displayed by the itemRenderer. Using [ ] notation is another way of accessing the fields of the data item. For example, data[‘price’] would be the price column. But to make this itemRenderer resuable we cannot code for a specific field, so a more generic way is needed.

That’s where listData comes in. All Flex components which implement the IDropInListItemRenderer interface have a listData property.

Most controls such as Text, Label, Button, CheckBox, and so forth, implement IDropInListItemRenderer. Most containers, such as HBox, Canvas, etc. do not implement that interface. If you want to use listData in an itemRenderer that extends a Container you will have to implement IDropInListItemRenderer yourself – I’ll cover that in the next article.

The listData given to an itemRenderer contains, among other things, the rowIndex and the control which owns the itemRenderer – the DataGrid, List, or TileList. When you have an itemRenderer being used for the DataGrid, the listData is actually a DataGridListData object – which includes the columnIndex and the dataField associated with the DataGridColumn. Here’s the breakdown of the statement above, starting from the inside:

  • listData as DataGridListData – This casts the listData to a DataGridListData object so you have access to its dataField
  • .dataField – the field for the column being rendered. This is what makes this itemRenderer generic. You can use this itemRenderer for multiple columns. In this example the dataField is ‘price’.
  • data[ … ] – This accesses the data for the specific field in the item. In this example it will be the price column.
  • Number( … ) – This casts the value to a Number because the format() function requires a Number parameter.
  • cfmt.format( … ) – This formats the value as a currency.


Use whatever makes you comfortable when implementing itemRenderers. Some people only work in ActionScript which is great when you’ve got experience with Flex and ActionScript. MXML makes quick work of simple itemRenderers, too.

In a future article we’ll look at making more efficient itemRenderers, which are ActionScript classes, but they extend UIComponent. In the next article I’ll discuss more communication between itemRenderers and the rest of the application.

11 Responses to itemRenderers: Part 2: External renderers

  1. Tikis Mikis says:

    When will your next article on itemRenderer communication with the rest of the app be posted? This is very interesting as I am currently working on something like this and CANNOT find any useful resources.

    Great tutorials! Thanks!
    Peter: It is now available. Thanks for asking.

  2. Derek Basch says:

    This is a great tutorial. Thanks for writing it!

  3. Derek Basch says:

    First, you’ll see that

    Should be:

    First, you’ll see that

  4. This comment/question is actually about the topic “Viewing PDFs with AIR.”

    How do I then print that PDF? and not a rendering of the HTML Container, and not using javascript embedded in the PDF (they will be generated by numerous sources, no access–and way too cumbersome–to put javascript in them.)

    Thank you.

  5. Peter Ent says:

    If there is no Print button on the PDF itself, then it is not possible at this time.

  6. Justin Cady says:


    Thank you for these fine articles. They’re the best Flex documentation out there. I really appreciate the effort.

  7. AJ says:

    I just started with flex & your tutorial helped out a lot.

    Thank you for taking the time


  8. ganesh says:


    I have one mxml application . In this i have a tileList control. I created a mxml component and use this component as itemrenderer in tileList.

    In mxml component i have one vbox ,image and textInput. I want set textcolor of selected items textinput from parent mxml application.

    so how can i access a particular item of selected items in tileList so that i can change their propety dynamically.

    i need your response as soon as possbile


    With Regards

  9. Peter Ent says:

    First, I suggest you read my articles on itemEditors which is more what you have – an itemRenderer with editing capabilities.

    Second, it is not regarded as good practice to change the style or values of an itemRenderer from outside of the itemRenderer or list. You have to remember that those renderers are recycled and dynamically generated.

    Third, since you have a single file and are using an in-line itemRenderer (see previous article), you might be able to use data binding in conjunction with the outerDocument keyword. So perhaps on the TextInput, something like color=”{outerDocument.inputColor}” would work were inputColor is defined as a [Bindable] public property in the Application’s scope.

    Fourth: if you are speaking of the actual selectedItems of a list, then you might try to intercept the change event within the itemRenderer and modify the color then.

    You have a number of options.

  10. Russ says:

    I have a pretty simple itemRenderer,
    <mx:Canvas xmlns:mx=”” height=”100%”>
    <mx:VBox width=”100%” verticalGap=”4″>
    <mx:HRule width=”100%”/>
    <mx:Label text=”{data.activityType} on {}”/>
    <mx:Text text=”{data.extra}” width=”100%” selectable=”false”/>

    the data that goes into the Text component is variable length, so sometimes it is multilined.
    This works fine for the items that are first visible, but when I scroll the List,the itemRenderers become single line height with scrollbars. I have my List to variableRowHeight = true, but it doesn’t work.

    problem is when I scroll my List

  11. Peter Ent says:

    Your renderer is a Canvas with a VBox inside. The VBox is growing to accomodate the height of its children – the text with multiline lines is making it taller. However, the Canvas is not changing size and that’s what is getting the scrollbar.

    Try removing the Canvas and just use the VBox as the renderer.