Adobe Flex 3 Help

Using item renderers with the AdvancedDataGrid control

You customize the appearance and behavior of cells in an AdvancedDataGrid control by creating custom item renderers and item editors. Use the same process for assigning item editors and item renderers to columns of the AdvancedDataGrid control as you do with the DataGrid control. For an introduction to item renderers and item editors, see Using Item Renderers and Item Editors.

The AdvancedDataGrid control adds capabilities to support item renderers. These capabilities let you perform the following actions:

  • Create rows or columns not associated with data in the data provider. For example, you can create summary rows from the data provider.
  • Span multiple columns with a renderer.
  • Use multiple renderers in the same column. For example, when displaying hierarchical data, you can use a different renderer in the column based on the level of the row in the hierarchy.

Note: These capabilities support item renderers only; use item editors as you do with the DataGrid control.

Using an item renderer

To use the item renderer capabilities of the AdvancedDataGrid control, you assign the item renderer to the AdvancedDataGrid control itself, not to a specific column, by using the AdvancedDataGrid.rendererProviders property. The following example assigns an item renderer to the Estimate column:

<mx:AdvancedDataGrid>
    <mx:columns>
        <mx:AdvancedDataGridColumn dataField="Region"/>
        <mx:AdvancedDataGridColumn dataField="Territory_Rep" headerText="Territory Rep"/>
        <mx:AdvancedDataGridColumn dataField="Actual"/>
        <mx:AdvancedDataGridColumn dataField="Estimate"/>
    </mx:columns>

    <mx:rendererProviders>
        <mx:AdvancedDataGridRendererProvider 
            columnIndex="3"
            columnSpan="1" 
            renderer="myComponents.EstimateRenderer"/>
    </mx:rendererProviders>
</mx:AdvancedDataGrid>

The rendererProviders property contains an Array of AdvancedDataGridRendererProvider instances. Each AdvancedDataGridRendererProvider instance defines the characteristics for a single item renderer.

In the previous example, the AdvancedDataGridRendererProvider instance specifies to use the EstimateRenderer for column 3, where the first column in the control is column 0, and the renderer spans a single column. If you set the columnSpan property to 0, the renderer spans all columns in the row.

Rather than using the column index to assign the renderer, you specify an id property for the column, and then use the column property to associate the renderer with the column, as the following example shows:

<mx:AdvancedDataGrid>
    <mx:columns>
        <mx:AdvancedDataGridColumn dataField="Region"/>
        <mx:AdvancedDataGridColumn dataField="Territory_Rep" headerText="Territory Rep"/>
        <mx:AdvancedDataGridColumn dataField="Actual"/>
        <mx:AdvancedDataGridColumn id="estCol" dataField="Estimate"/>
    </mx:columns>

    <mx:rendererProviders>
        <mx:AdvancedDataGridRendererProvider 
            column="{estCol}"
            columnSpan="1" 
            renderer="myComponents.EstimateRenderer"/>
    </mx:rendererProviders>
</mx:AdvancedDataGrid>

The depth property lets you associate the renderer with a specific level in the hierarchy of the navigation tree of an AdvancedDataGrid control, where the depth of the top-most node in the navigation tree is 1. The following example associates the renderer with the third level of a navigation tree:

    <mx:rendererProviders>
        <mx:AdvancedDataGridRendererProvider 
            columnIndex="3"
            depth="3" 
            columnSpan="1" 
            renderer="myComponents.EstimateRenderer"/>
    </mx:rendererProviders>

In the previous example, the AdvancedDataGrid control uses the default renderer for the column until you expand it to the third level of the navigation tree, and then it uses EstimateRenderer component. You use the depth property to assign different renderers to the same column, where the depth property specifies the renderer to use for each level of the tree.

A renderer can span multiple columns. In the following example, you create a renderer that spans two columns:

<mx:AdvancedDataGrid>
    <mx:columns>
        <mx:AdvancedDataGridColumn dataField="Region"/>
        <mx:AdvancedDataGridColumn dataField="Territory_Rep" headerText="Territory Rep"/>
        <mx:AdvancedDataGridColumn id="actCol" dataField="Actual"/>
        <mx:AdvancedDataGridColumn dataField="Estimate"/>
    </mx:columns>

    <mx:rendererProviders>
        <mx:AdvancedDataGridRendererProvider 
            column="{actCol}"
            depth="3" 
            columnSpan="2" 
            renderer="myComponents.SummaryRenderer"/>
    </mx:rendererProviders>
</mx:AdvancedDataGrid>

The previous example uses a single renderer that spans the Actual and Estimate columns to display a combined view of the data for these columns. For an implementation of the SummaryRenderer component, see Using a renderer to generate column data.

The following table describes the properties of the AdvancedDataGridRendererProvider class that you use to configure the renderer:

Property

Description
column

The ID of the column for which the renderer is used. If you omit this property, you can use the columnIndex property to specify the column.

columnIndex

The column index for which the renderer is used, where the first column has an index of 0.
columnSpan

The number of columns that the renderer spans. Set this property to 0 to span all columns. The default value is 1.
dataField

The data field in the data provider for the renderer. This property is optional.

depth

The depth in the tree at which the renderer is used, where the top-most node of the tree has a depth of 1. Use this property when the renderer should be used only when the tree is expanded to a certain depth, not for all nodes in the tree. By default, the control uses the renderer for all levels of the tree.
renderer

The renderer.
rowSpan

The number of rows that the renderer spans. The default value is 1.

Using a renderer to generate column data

The following example shows the results when an item renderer is used to calculate the value of the Difference column of the AdvancedDataGrid control:

An item renderer used to calculate the value of the Difference column

This example defines a column with the id of diffCol that is not associated with a data field in the data provider. Instead, you use the rendererProvider property to assign an item renderer to the column. The item renderer calculates the difference between the actual and estimate values, and then displays a message based on whether the representative exceeded or missed their estimate.

The following code implements this example:

<?xml version="1.0"?>
<!-- dpcontrols/adg/HierarchicalADGSimpleRenderer.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:Script>
        <![CDATA[
              import mx.collections.ArrayCollection;
                
              include "SimpleHierarchicalData.as";
        ]]>
    </mx:Script>

    <mx:AdvancedDataGrid width="100%" height="100%">
        <mx:dataProvider>
            <mx:HierarchicalData source="{dpHierarchy}"/>
        </mx:dataProvider>
        <mx:columns>
            <mx:AdvancedDataGridColumn dataField="Region"/>
            <mx:AdvancedDataGridColumn dataField="Territory_Rep"
                headerText="Territory Rep"/>
            <mx:AdvancedDataGridColumn dataField="Actual"/>
            <mx:AdvancedDataGridColumn dataField="Estimate"/>
            <mx:AdvancedDataGridColumn id="diffCol" 
                headerText="Difference"/>
        </mx:columns>

        <mx:rendererProviders>
            <mx:AdvancedDataGridRendererProvider column="{diffCol}"
                depth="3" renderer="myComponents.SummaryRenderer"/>
        </mx:rendererProviders>
    </mx:AdvancedDataGrid>
</mx:Application>

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

The following code shows the SummaryRenderer component:

<?xml version="1.0"?>
<!-- dpcontrols/adg/myComponents/SummaryRenderer.mxml -->
<mx:Label xmlns:mx="http://www.adobe.com/2006/mxml" textAlign="center">
    <mx:Script>
        <![CDATA[

        override public function set data(value:Object):void
        {
            // Calculate the difference.
            var diff:Number = 
                Number(value["Actual"]) - Number(value["Estimate"]);
            if (diff < 0)
            {
                // If Estimate was greater than Actual, 
                // display results in red.
                setStyle("color", "red");
                text = "Undersold by " + usdFormatter.format(diff);
            }
            else
            {
                // If Estimate was less than Actual, 
                // display results in green.
                setStyle("color", "green");
                text = "Exceeded estimate by " + usdFormatter.format(diff);
            }
        }
        ]]>
    </mx:Script>
    
    <mx:CurrencyFormatter id="usdFormatter" precision="2" 
        currencySymbol="$" decimalSeparatorFrom="."
        decimalSeparatorTo="." useNegativeSign="true" 
        useThousandsSeparator="true" alignSymbol="left"/>
</mx:Label>

Using an item renderer that spans an entire row

You can use an item renderer with a hierarchical data set to display an entire row of data. The following example shows a PieChart control that displays the data from the detail field of the hierarchical data set. Each row contains detailed information about sales revenues for the representative, which is rendered as a segment of the pie chart:

PieChart control that displays the data from the detail field of the hierarchical data set.

The following code implements this example:

<?xml version="1.0"?>
<!-- dpcontrols/adg/GroupADGChartRenderer.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

  <mx:Script>
    <![CDATA[
      import mx.collections.ArrayCollection;
                             
      [Bindable]
      private var dpHierarchy:ArrayCollection= new ArrayCollection([
        {name:"Barbara Jennings", region: "Arizona", total:70, children:[  
          {detail:[{amount:5},{amount:10},{amount:20},{amount:45}]}]},
        {name:"Dana Binn", region: "Arizona", total:130,  children:[ 
          {detail:[{amount:15},{amount:25},{amount:35},{amount:55}]}]},
        {name:"Joe Smith", region: "California", total:229,  children:[ 
          {detail:[{amount:26},{amount:32},{amount:73},{amount:123}]}]},
        {name:"Alice Treu", region: "California", total:230, children:[ 
          {detail:[{amount:159},{amount:235},{amount:135},{amount:155}]}
        ]}
      ]);                                            
    ]]>
  </mx:Script>

  <mx:AdvancedDataGrid id="myADG" 
    width="100%" height="100%" 
    variableRowHeight="true">
    <mx:dataProvider>
       <mx:HierarchicalData source="{dpHierarchy}"/>
    </mx:dataProvider>
    <mx:columns>
        <mx:AdvancedDataGridColumn dataField="name" headerText="Name"/>
        <mx:AdvancedDataGridColumn dataField="total" headerText="Total"/>
    </mx:columns>   
        
    <mx:rendererProviders>            
        <mx:AdvancedDataGridRendererProvider 
            dataField="detail" 
            renderer="myComponents.ChartRenderer" 
            columnIndex="0"
            columnSpan="0"/>         
    </mx:rendererProviders>   
  </mx:AdvancedDataGrid>
</mx:Application>

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

The following code renders the ChartRenderer.mxml component: 

<?xml version="1.0"?>
<!-- dpcontrols/adg/myComponents/ChartRenderer.mxml -->
<mx:VBox height="200" width="100%" xmlns:mx="http://www.adobe.com/2006/mxml">
    <mx:PieChart dataProvider="{data.detail}"
        width="100%"
        height="100%"
        showDataTips="true">
        <mx:series>
            <mx:PieSeries labelPosition="callout" field="amount"  />
        </mx:series>
    </mx:PieChart>    
</mx:VBox>

You can modify this example to display the PieChart control in a column. In the following example, you add a Detail column to the control, and then specify that the item renderer is for column 2 of the control:

<?xml version="1.0"?>
<!-- dpcontrols/adg/GroupADGChartRendererOneRow.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

  <mx:Script>
    <![CDATA[
      import mx.collections.ArrayCollection;
                             
      [Bindable]
      private var dpHierarchy:ArrayCollection= new ArrayCollection([
        {name:"Barbara Jennings", region: "Arizona", total:70, children:[  
          {detail:[{amount:5},{amount:10},{amount:20},{amount:45}]}]},
        {name:"Dana Binn", region: "Arizona", total:130,  children:[ 
          {detail:[{amount:15},{amount:25},{amount:35},{amount:55}]}]},
        {name:"Joe Smith", region: "California", total:229,  children:[ 
          {detail:[{amount:26},{amount:32},{amount:73},{amount:123}]}]},
        {name:"Alice Treu", region: "California", total:230, children:[ 
          {detail:[{amount:159},{amount:235},{amount:135},{amount:155}]}
        ]}
      ]);                                            
    ]]>
  </mx:Script>

  <mx:AdvancedDataGrid id="myADG" 
    width="100%" height="100%" 
    variableRowHeight="true">
    <mx:dataProvider>
       <mx:HierarchicalData source="{dpHierarchy}"/>
    </mx:dataProvider>
    <mx:columns>
        <mx:AdvancedDataGridColumn dataField="name" headerText="Name"/>
        <mx:AdvancedDataGridColumn dataField="total" headerText="Total"/>
        <mx:AdvancedDataGridColumn dataField="detail" headerText="Detail"/>
    </mx:columns>   
        
    <mx:rendererProviders>            
        <mx:AdvancedDataGridRendererProvider 
            dataField="detail" 
            renderer="myComponents.ChartRenderer" 
            columnIndex="2"/>         
    </mx:rendererProviders>   
  </mx:AdvancedDataGrid>
</mx:Application>

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