ATF's Blog

The DataGrid control is a list that can display more than one column of data. It is a formatted table of data that lets you set editable table cells, and is the foundation of many data-driven applications.

For information on the following topics, which are often important for creating advanced data grid controls, see:

• How to format the information in each DataGrid cell and control how users enter data in the cells; see Using Item Renderers and Item Editors.
• How to drag objects to and from the data grid; see Using Drag and Drop.

For complete reference information, see the Adobe Flex Language Reference.

About the DataGrid control

The DataGrid control provides the following features:

• Resizable, sortable, and customizable column layouts, including hidable columns
• Optional customizable column and row headers, including optionally wrapping header text
• Columns that the user can resize and reorder at run time
• Selection events
• Ability to use a custom item renderer for any column
• Support for paging through data
• Locked rows and columns that do not scroll

The following image shows a DataGrid control:

Rows are responsible for rendering items. Each row is laid out vertically below the previous one. Columns are responsible for maintaining the state of each visual column; columns control width, color, and size.

Creating a DataGrid control

You use the <mx:DataGrid> tag to define a 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. For more information, see Using Data Providers and Collections.

You specify the data for the DataGrid control by using the dataProvider property. You can specify data in several different ways. In the simplest case for creating a DataGrid control, you use the <mx:dataProvider> property subtag with <mx:ArrayCollection>, and <mx:Object> tags to define the entries as an ArrayCollection of Objects. Each Object defines a row of the DataGrid control, and properties of the Object define the column entries for the row, as the following example shows:

<?xml version="1.0"?>
<!-- dpcontrols/DataGridSimple.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
   <mx:DataGrid>
      <mx:ArrayCollection>
         <mx:Object>
            <mx:Artist>Pavement</mx:Artist>
            <mx:Price>11.99</mx:Price>
            <mx:Album>Slanted and Enchanted</mx:Album>
         </mx:Object>
         <mx:Object>
            <mx:Artist>Pavement</mx:Artist>
            <mx:Album>Brighten the Corners</mx:Album>
            <mx:Price>11.99</mx:Price>
         </mx:Object>
      </mx:ArrayCollection>
   </mx:DataGrid>
</mx:Application>

This example shows how you can take advantages of MXML defaults. You do not have to use an <mx:dataProvider> tag, because dataProvider is the default property of the DataGrid control. Similarly, you do not have to use an <mx:source> tag inside the <mx:ArrayCollection> tag because source is the default property of the ArrayCollection class. Finally, you do not have to specify an <mx:Array> tag for the source array.

You can also define the objects by using properties directly in the Object tags, as the following example shows:

<?xml version="1.0"?>
<!-- dpcontrols/DataGridSimpleAttributes.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
   <mx:DataGrid>
      <mx:ArrayCollection>
         <mx:Object Artist="Pavement"
            Album="Slanted and Enchanted" Price="11.99" />
         <mx:Object Artist="Pavement"
            Album="Brighten the Corners" Price="11.99" />
      </mx:ArrayCollection>
   </mx:DataGrid>
</mx:Application>

The column names displayed in the DataGrid control are the property names of the Array Objects. By default, the columns are in alphabetical order by the property names. Different Objects can define their properties in differing orders. If an Array Object omits a property, the DataGrid control displays an empty cell in that row.

Specifying columns

Each column in a DataGrid control is represented by a DataGridColumn object. You use the columns property of the DataGrid control and the <mx:DataGridColumn> tag to select the DataGrid columns, specify the order in which to display them, and set additional properties. You can also use the DataGridColumn class visible property to hide and redisplay columns, as described in Hiding and displaying columns.

For complete reference information for the <mx:DataGridColumn> tag, see DataGridColumn in the Adobe Flex Language Reference.

You specify an Array element to the <mx:columns> child tag of the <mx:DataGrid> tag, as the following example shows:

<?xml version="1.0"?>
<!-- dpcontrols/DataGridSpecifyColumns.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" >
   <mx:DataGrid>
      <mx:ArrayCollection>
         <mx:Object Artist="Pavement" Price="11.99"
            Album="Slanted and Enchanted" />
         <mx:Object Artist="Pavement"
            Album="Brighten the Corners" Price="11.99" />
      </mx:ArrayCollection>
      <mx:columns>
         <mx:DataGridColumn dataField="Album" />
         <mx:DataGridColumn dataField="Price" />
      </mx:columns>
   </mx:DataGrid>
</mx:Application>

In this example, you only display the Album and Price columns in the DataGrid control. You can reorder the columns as well, as the following example shows:

<mx:columns>
    <mx:DataGridColumn dataField="Price" />
    <mx:DataGridColumn dataField="Album" />
</mx: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 <mx:DataGridColumn> tag to set other options. The following example uses the headerText property to set the name of the column to a value different than the default name of Album, and uses the width property to set the album name column wide enough to display the full album names:

<mx:columns>
    <mx:DataGridColumn dataField="Album" width="200" />
    <mx:DataGridColumn dataField="Price" headerText="List Price" />
</mx:columns>

Hiding and displaying columns

If you might display a column at some times, but not at others, you can specify the DataGridColumn 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"?>
<!-- dpcontrols/DataGridVisibleColumn.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" >
   <mx:DataGrid id="myDG" width="350">
      <mx:dataProvider>
         <mx:ArrayCollection>
            <mx:source>
               <mx:Object Artist="Pavement" Price="11.99"
                  Album="Slanted and Enchanted" />
               <mx:Object Artist="Pavement"
                  Album="Brighten the Corners" Price="11.99" />
            </mx:source>
         </mx:ArrayCollection>
      </mx:dataProvider>
      <mx:columns>
         <mx:DataGridColumn dataField="Artist" />
         <mx:DataGridColumn dataField="Album" />
         <mx:DataGridColumn id="price" dataField="Price" visible="false"/>
      </mx:columns>
   </mx:DataGrid>

   <!-- The column id property specifies the column to show.-->
   <mx:Button label="Toggle Price Column"
      click="price.visible = !price.visible;" />
</mx:Application> 

Passing data to a DataGrid control

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"?>
<!-- dpcontrols/DataGridPassData.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
   initialize="initData()">
   <mx: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 ArrayCollection variable from the Array.
      //You can use this technique to convert an HTTPService,
      //WebService, or RemoteObject result to ArrayCollection.
      public function initData():void {
         initDG=new ArrayCollection(DGArray);
      }
   ]]>
   </mx:Script>

   <mx:DataGrid id="myGrid" width="350" height="200"
      dataProvider="{initDG}" >
      <mx:columns>
         <mx:DataGridColumn dataField="Album" />
         <mx:DataGridColumn dataField="Price" />
      </mx:columns>
   </mx:DataGrid>
</mx:Application>

In this example, you bind the variable initDG to the <mx:dataProvider> property. You can still specify a column definition event when using data binding. For a description of using a model as a data provider, see Populating a ComboBox control by using variables and models