Creating a Spark DataGrid control

You use the <s:DataGrid> tag to define a Spark DataGrid control in MXML. Specify an id value if you intend to refer to a component elsewhere in your MXML, either in another tag or in an ActionScript block.

The DataGrid control uses a list-based data provider to supply the data to display. The data provider consists of a list of objects called items. Each item corresponds to one row of the DataGrid control. Each grid column typically corresponds to one property of each row item. For more information, see Data providers and collections.

You can specify data in several different ways. In the simplest case, use the <s:ArrayList> and <fx:Object> tags to define the entries. Each Object defines a row of the DataGrid control. The properties of each Object define the column entries for the row, as the following example shows:
<?xml version="1.0" encoding="utf-8"?>
<!-- dpcontrols\sparkdpcontrols\SparkDGSimple.mxml -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx">

    <s:DataGrid> 
        <s:dataProvider>
            <s:ArrayList> 
                <fx:Object> 
                    <fx:Artist>Pavement</fx:Artist> 
                    <fx:Price>11.99</fx:Price> 
                    <fx:Album>Slanted and Enchanted</fx:Album> 
                </fx:Object> 
                <fx:Object> 
                    <fx:Price>11.99</fx:Price> 
                    <fx:Artist>Pavement</fx:Artist> 
                    <fx:Album>Brighten the Corners</fx:Album> 
                </fx:Object> 
            </s:ArrayList> 
        </s:dataProvider>
    </s:DataGrid> 
</s:Application>

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

Note: You do not have to specify the dataProvider tag in MXML because dataProvider is the default property of the DataGrid control.

By default, each column displays one property from each data provider item. Each column heading displays the name of the associated property in the data provider item.

The index of rows in the DataGrid control is zero-based, meaning values are 0, 1, 2, ... , n ‑ 1, where n is the total number of items in the data provider. Column indexes are also zero-based. Therefore, if you select the first cell in the second row, the row index is 1 and the column index is 0.

Passing data to a DataGrid control

Specify the data provider for the DataGrid control by using the dataProvider property. The data type of the dataProvider property is IList. That lets you use an ArrayList, ArrayCollection, or any other class that implements IList as the data provider.

ArrayList is a lightweight implementation of IList that is useful if you do not support row sorting in the DataGrid control. To support row sorting, use a class that implements the ICollectionView interface, such as ListCollectionView. Typically, you use a subclass of ListCollectionView, such as ArrayCollection or XMLListCollection, as the data provider to support row sorting.

Each row in the data grid corresponds to one item in the data provider. Data provider items can define their properties in differing orders. By default, the order of the columns corresponds to the order of the properties as defined in the first item in the data provider.

If a data provider item omits a property or a value for a property, the DataGrid control displays an empty cell in the corresponding column for that row.

Flex lets you populate a DataGrid control from an ActionScript variable definition or from a Flex data model. The following example populates a DataGrid control by using a variable:
<?xml version="1.0" encoding="utf-8"?>
<!-- dpcontrols\sparkdpcontrols\SparkDGPassedData.mxml -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx"
    initialize="initData();"> 
    
    <fx:Script> 
        <![CDATA[ 
            import mx.collections.*; 
            private var dgArray:Array = [ 
                {Artist:'Pavement', Album:'Slanted and Enchanted', Price:11.99}, 
                {Artist:'Pavement', Album:'Brighten the Corners', Price:11.99}]; 
            
            [Bindable] 
            public var initDG:ArrayCollection; 
            
            // Initialize initDG variable from the Array. 
            public function initData():void { 
                initDG = new ArrayCollection(dgArray); 
            } 
        ]]> 
    </fx:Script> 
    
    <s:DataGrid id="myGrid" 
        width="350" height="200" 
        dataProvider="{initDG}"/>
</s:Application>

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

In this example, you bind the variable initDG to the <s:dataProvider> property.

The following example populates the DataGrid control from XML data. In this example, you define the XML data by using the XMLList class. You then create an XMLListCollection object from the XMLList:

<?xml version="1.0" encoding="utf-8"?>
<!-- dpcontrols\sparkdpcontrols\SparkDGXMLData.mxml -->
<s:Application
    xmlns:fx="http://ns.adobe.com/mxml/2009"
    xmlns:s="library://ns.adobe.com/flex/spark"
    xmlns:mx="library://ns.adobe.com/flex/mx"
    width="500">
    <s:layout>
        <s:VerticalLayout/>
    </s:layout>
    <fx:Declarations>
        <fx:XMLList id="employees">
            <employee>
                <name>Joanne Wall</name>
                <phone>555-219-2012</phone>
                <email>jwall@fictitious.com</email>
                <active>true</active>
            </employee>            
            <employee>
                <name>Mary Jones</name>
                <phone>555-219-2000</phone>
                <email>mjones@fictitious.com</email>
                <active>true</active>
            </employee>            
            <employee>
                <name>Maurice Smith</name>
                <phone>555-219-2012</phone>
                <email>maurice@fictitious.com</email>
                <active>false</active>
            </employee>            
            <employee>
                <name>Dave Davis</name>
                <phone>555-219-2000</phone>
                <email>ddavis@fictitious.com</email>
                <active>true</active>
            </employee>            
            <employee>
                <name>Tom Maple</name>
                <phone>555-219-2000</phone>
                <email>tmaple@fictitious.com</email>
                <active>true</active>
            </employee>            
        </fx:XMLList>
        <s:XMLListCollection id="employees2" source="{employees}"/>
    </fx:Declarations>

    <s:DataGrid id="dg" width="500" dataProvider="{employees2}">
        <s:columns>
            <s:ArrayList>
                <s:GridColumn dataField="name" headerText="Name"/>
                <s:GridColumn dataField="phone" headerText="Phone"/>
                <s:GridColumn dataField="email" headerText="Email"/>
            </s:ArrayList>
        </s:columns>
    </s:DataGrid>
    
    <s:Form>
        <s:FormItem label="Name">
            <s:Label text="{dg.selectedItem.name}"/>
        </s:FormItem>
        <s:FormItem label="Email">
            <s:Label text="{dg.selectedItem.email}"/>
        </s:FormItem>
        <s:FormItem label="Phone">
            <s:Label text="{dg.selectedItem.phone}"/>
        </s:FormItem>
    </s:Form>
</s:Application>

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

You can use Flex data access components: HTTPService, WebService, and RemoteObject, to supply data to the DataGrid. To use a remote data source to provide data, you represent the result of the remote service with the appropriate object, as follows:

  • A RemoteObject component automatically returns an ArrayCollection for any data that is represented on the server as a java.util.List object, and you can use the returned object directly.

  • For HTTPService and WebService results, cast the result data to a collection class if the data changes or if you use the same result in multiple places (the latter case is more efficient). As a rule, use an ArrayCollection for serialized (list-based) objects and an XMLListCollection for XML data.

The following code snippet shows this use, casting a list returned by a web service to an ArrayCollection:

    <s:WebService id="employeeWS" wsdl="http://server.com/service.wsdl" 
        showBusyCursor="true" 
        fault="alert(event.fault.faultstring)"> 
        <s:operation name="getList"> 
            <mx:request> 
                <deptId>{dept.selectedItem.data}</deptId> 
            </mx:request> 
        </s:operation> 
        ... 
    </s:WebService> 
 
    <fx:ArrayCollection id="ac" 
        source="mx.utils.ArrayUtil.toArray(employeeWS.getList.lastResult)"/> 
    <s:DataGrid dataProvider="{ac}" width="100%">

For more information on using data access component, see Accessing server-side data.

Configuring columns

A GridColumn object represents each column in a DataGrid control. By default, the DataGrid control creates a column for every property in the first item of the data provider.

Use the DataGrid.columns property to explicitly define the columns of the DataGrid. By explicitly defining the columns, you can set the column order, set column visibility, and set additional column properties.

The data type of the columns property is IList. That lets you use an ArrayList, ArrayCollection, or any other class that implements IList as the data provider. Most of the applications in this document use ArrayList to set the columns property.

To support column sorting, use a class that implements the ICollectionView interface, such as ListCollectionView. Typically, you use a subclass of ListCollectionView, such as ArrayCollection, as the data provider.

Note: You can only sort the columns of the DataGrid programmatically by sorting the IList passed to the columns property. That is, you cannot use the mouse to drag a column to rearrange the columns.

Use the GridColumn.dataField property to specify the property of the data provider items displayed in a column, as the following example shows:

<?xml version="1.0" encoding="utf-8"?>
<!-- dpcontrols\sparkdpcontrols\SparkDGSpecifyColumns.mxml -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx">

    <s:DataGrid> 
        <s:dataProvider>
            <s:ArrayCollection> 
                <fx:Object Artist="Pavement" Price="11.99" 
                           Album="Slanted and Enchanted"/> 
                <fx:Object Artist="Pavement" 
                           Album="Brighten the Corners" Price="11.99"/> 
            </s:ArrayCollection> 
        </s:dataProvider>
        <s:columns> 
            <s:ArrayList>
                <s:GridColumn dataField="Album"/> 
                <s:GridColumn dataField="Price"/> 
            </s:ArrayList>
        </s:columns> 
    </s:DataGrid> 
</s:Application>

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

When you use the <s:columns> tag, the DataGrid only displays the columns corresponding to the specified GridColumn objects. In this example, you only define columns for the Album and Price properties of the data provider. Therefore, the DataGrid does not display a column for the Price property.

You can reorder the columns by changing the order of the GridColumn objects, as the following example shows:

<s:columns> 
    <s:ArrayList> 
        <s:GridColumn dataField="Price"/> 
        <s:GridColumn dataField="Album"/> 
    </s:ArrayList> 
</s:columns>

In this example, you specify that the Price column is the first column in the DataGrid control, and that the Album column is the second.

You can also use the <s:GridColumn> tag to set other options. The following example uses the headerText property to set the name of the column to a value different from the default name of Album, and uses the width property to set an explicit column width:

<s:columns> 
    <s:ArrayList> 
        <s:GridColumn dataField="Album" width="200"/> 
        <s:GridColumn dataField="Price" headerText="List Price"/> 
    </s:ArrayList> 
</s:columns>
Rather than explicitly set the width of a column, you can define a typical item for the DataGrid control. The DataGrid uses the typical item, and any item renderer associated with a column, to compute the initial width of each column that does not specify an explicit width. Use the typicalItem property to specify the data item, as the following example shows:
<?xml version="1.0" encoding="utf-8"?>
<!-- dpcontrols\sparkdpcontrols\SparkDGTypicalItem.mxml -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark">
        
    <s:DataGrid requestedRowCount="5">
        <s:typicalItem>
            <s:DataItem key="9999999" name="Typical name length" 
                price="1234.56" call="false"/>
        </s:typicalItem>
            
        <s:ArrayCollection id="items">
            <s:DataItem key="1000" name="Abrasive" price="100.11" call="false"/>
            <s:DataItem key="1001" name="Brush" price="110.01" call="true"/>
            <s:DataItem key="1002" name="Clamp" price="120.02" call="false"/>
            <s:DataItem key="1003" name="Drill" price="130.03" call="true"/>
            <s:DataItem key="1004" name="Epoxy" price="140.04" call="false"/>
            <s:DataItem key="1005" name="File" price="150.05" call="true"/>
        </s:ArrayCollection>
    </s:DataGrid>
</s:Application>

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

Sorting the columns of the Spark DataGrid control

By default, the DataGrid control displays rows in the order specified in the data items passed to its dataProvider property. The control lets you sort data based on the cell value of a single column. To sort ascending order of a column, select the column header. Select it again to sort in descending order.

To disable sorting for the control, set the DataGrid.sortableColumns property to false. To disable sorting for an individual column, set the GridColumn.sortable property to false.

Create a custom sort by implementing a sort compare function. You can define a different sort compare function for each column of the control. For more information, see Create a custom sort for the Spark DataGrid control.

Hiding and displaying columns

If you display a column at some times, but not at others, you can specify the GridColumn class visible property to hide or show the column. The following example lets you hide or show the album price by clicking a button:
<?xml version="1.0" encoding="utf-8"?>
<!-- dpcontrols\sparkdpcontrols\SparkDGVisibleColumn.mxml -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx">
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
    
    <s:DataGrid id="myDG" width="350"> 
        <s:ArrayCollection> 
            <fx:Object Artist="Pavement" Price="11.99" 
                Album="Slanted and Enchanted"/> 
            <fx:Object Artist="Pavement" 
                Album="Brighten the Corners" Price="11.99"/> 
        </s:ArrayCollection> 
        <s:columns> 
            <s:ArrayList>
                <s:GridColumn dataField="Artist"/> 
                <s:GridColumn dataField="Album"/> 
                <s:GridColumn id="price" dataField="Price" visible="false"/>
            </s:ArrayList>
        </s:columns> 
    </s:DataGrid> 
    
    <!-- The column id property specifies the column to show.--> 
    <s:Button label="Toggle Price Column" 
        click="price.visible = !price.visible;" /> 
</s:Application>

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