Flex Fun - Advanced DataGrid Topics

This tutorial is going to build on an earlier tutorial about the Flex DataGrid component. It's going to show how to do several things including how to use xml with a datagrid, how to use item renderers and label functions, and how to style and skin parts of the datagrid and scrollbar. Also at the end of the tutorial I supply a zip file with all the source code and assets needed to create the example in this tutorial.

We are going to start by looking at an example program that shows off what we are going to learn today. You will notice that the datagrid doesn't have any header labels or vertical grid lines. I have also skinned the scroll bar and changed some colors. All the data comes from two xml files that we will write here in a minute. The data shown in the datagrid is done in a couple different ways, which we will go over later.

Creating XML Data

The first item to take care of is getting our data together. This done using a couple of xml files. The first file has the people and their favorite game. The second xml file is a list of games that people can have for their favorite game and information about that game.

The first file is people.xml.

<?xml version="1.0"?>
<people>
  <person> 
    <name>
      <first>Charlie</first>
      <last>Key</last>
    </name> 
    <info>
      <age>23</age>
      <sex>Male</sex>
    </info>
    <favGameID>1</favGameID>
  </person> 
  <person> 
    <name>
      <first>Brandon</first>
      <last>Cannaday</last>
    </name>
    <info>
      <age>23</age>
      <sex>Male</sex>
    </info> 
    <title>CFO</title> 
    <favGameID>3</favGameID>
  </person> 
  <person> 
    <name>
      <first>Michael</first>
      <last>Kuehl</last>
    </name>
    <info>
      <age>23</age>
      <sex>Male</sex>
    </info>
    <title>CTO</title> 
    <favGameID>5</favGameID>
  </person> 
  <person> 
    <name>
      <first>Kevin</first>
      <last>Putvin</last>
    </name>
    <info>
      <age>23</age>
      <sex>Male</sex>
    </info> 
    <title>Lazy Guy</title> 
    <favGameID>2</favGameID>
  </person> 
  <person> 
    <name>
      <first>Richard</first>
      <last>Key</last>
    </name>
    <info>
      <age>20</age>
      <sex>Male</sex>
    </info> 
    <title>Underling</title> 
    <favGameID>4</favGameID>
  </person> 
  <person> 
    <name>
      <first>Caroline</first>
      <last>Andersen</last>
    </name>
    <info>
      <age>23</age>
      <sex>Female</sex>
    </info>
    <title>Supporter</title> 
    <favGameID>6</favGameID>
  </person> 
</people>

And the second is games.xml.

<?xml version="1.0"?>
<games>
  <game id="1">
    <name>World of Warcraft</name>
    <publisher>Vivendi Universal</publisher>
    <developer>Blizzard</developer>
    <imageURL>wow_small.jpg</imageURL>
  </game>
  <game id="2">
    <name>Halo 2</name>
    <publisher>Microsoft Game Studios</publisher>
    <developer>Bungie Studios</developer>
    <imageURL>halo_small.jpg</imageURL>
  </game>
  <game id="3">
    <name>Half Life 2</name>
    <publisher>Valve Corporation</publisher>
    <developer>Valve Corporation</developer>
    <imageURL>hl_2_small.jpg</imageURL>
  </game>
  <game id="4">
    <name>Gears of War</name>
    <publisher>Microsoft Game Studios</publisher>
    <developer>Epic Games</developer>
    <imageURL>gears_of_war_small.jpg</imageURL>
  </game>
  <game id="5">
    <name>The Elder Scrolls IV: Oblivion</name>
    <publisher>2K Games</publisher>
    <developer>Bethesda Game Studios</developer>
    <imageURL>oblivion_small.jpg</imageURL>
  </game>
  <game id="6">
    <name>The Legend of Zelda: Twilight Princess</name>
    <publisher>Nintendo EAD</publisher>
    <developer>Nintendo</developer>
    <imageURL>zelda_small.jpg</imageURL>
  </game>
</games>

Creating The Flex Interface

Creating the Flex interface is a simple task in which nothing really complex is done. I created a new application and added a panel to it. This panel holds all the other user interface components. We have a label at the top of the panel telling everyone that the information displayed is our favorite games. Below this is our datagrid which will hold the bulk of the data. After the datagrid there are a couple items to show details of a game including a large image, which is the image url from our xml data. The following code is our simple interface.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute" 
    width="530" height="610" viewSourceURL="/files/AdvancedDatagrid.mxml">
  <mx:Panel width="530" height="610" layout="absolute" title="Advanced Datagrids">
    <mx:Label horizontalCenter="0" y="1" text="Our Favorite Games" 
        fontSize="16" fontWeight="bold"/>
    <mx:DataGrid id="dgPeeps" x="0" y="25" width="510" height="260" selectedIndex="0">
      <mx:columns>
        <mx:DataGridColumn headerText="Name" width="75"/>
        <mx:DataGridColumn headerText="Info" width="80"/>
        <mx:DataGridColumn headerText="Favorite Game"/>
      </mx:columns>
    </mx:DataGrid>
    <mx:Image x="10" y="318" width="300" height="240" id="imgGameScreen"/>
    <mx:Label x="10" y="293" fontWeight="bold" fontSize="13" id="lblGameName"/>
    <mx:Label x="318" y="318" text="Developer:"/>
    <mx:Label x="318" y="335" id="lblDeveloper"/>
    <mx:Label x="318" y="361" text="Publisher:"/>
    <mx:Label x="318" y="378" id="lblPublisher" />
  </mx:Panel>
</mx:Application>

Well that takes care of the beginning of our application.

Binding the XML Data

Now we get to have little fun. Binding the xml data to the datagrid isn't that bad. We take advantage of some components that make our life much easier. The first step is creating an object from the xml source file. Below is the code to accomplish this. It creates a <mx:Model> (click here for more info on this tag) object that represents the xml data from the source file.

<mx:Model id="people" source="/data/people.xml"/>

Next we create another component of type <mx:XML>. This, as you can probably figure out, makes a XML object. I don't use a data model this time because we are going to use the games xml data a little differently. We will take advantage of one of the xml tricks we can do in Flex and we also do not need to bind the data to a DataGrid. Grabbing our games xml data looks like:

<mx:XML id="games" source="/data/games.xml"/>

Both of the above tags will go right after the opening application tag.

Now we can simply bind the datagrid to our data model of the people from our xml data. The only thing we need to do is make sure that we bind to the correct property. Using <mx:Model> creates an object of the entire xml data, therefore we need to go down one level to the person property of our people model. The new datagrid looks like:

<mx:DataGrid id="dgPeeps" x="0" y="25" width="510" height="260" 
    selectedIndex="0" dataProvider="{people.person}">

This takes care of binding the data but none of it is going to show up yet because we haven't added any rendering code. The next thing we are going to do is display the data we now have.

Displaying DataGrid Data

This section is going to introduce a few new concepts. The first feature we are going to look at and use are label functions. A lot of the time we have complex data that we want to display in our datagrids and using the dataField property just doesn't cut it. A label function will take in the current item being processed and the data grid column and will return a string. The returned string is what will be displayed in the cell.

We are going to use a label function for the info column. To declare we are going to use one, all that is needed is to set the labelFunction property. This is set to displayPersonInfo which is an actionscript function we will create in just a moment. The new datagrid column code looks like the following.

<mx:DataGridColumn headerText="Info" width="80" labelFunction="displayPersonInfo"/>

Next we create the actionscript function in a new <mx:Script> tag which goes right beneath the opening application tag. Inside our function we are going to concatenate the two pieces of info (check the xml structure to see what I mean) from our item. In the code below you can see the two parameters that I brought in which were explained in the earlier paragraph. We use the item parameter and grab item.info.age and item.info.sex and return them as a combined string. That is the basics of a label function. Also note that any label function needs to take in both parameters (even if they're not used) and return a string.

<mx:Script>
  <![CDATA[
    import mx.controls.dataGridClasses.DataGridColumn;

    private function displayPersonInfo(item:Object, col:DataGridColumn):String
    {
      return item.info.age + " " + item.info.sex;
    }
  ]]>
</mx:Script>

At least we are displaying something now. Lets move on to the harder display components. For the other two columns we are going to use item renderers. An item renderer is a set of custom code that displays the data in a column in particular way using mxml components and/or your own custom components. There are four different kinds of item renderers: drop-in, inline, reusable, and component. In this tutorial we use two of them - inline and component. Look for a snippet tutorial in future going over all of them.

The first one we use is the inline item renderer. You might have noticed when we created the interface that the first DataGridColumn had an opening and closing tag. Well this was on purpose. We add the item renderer inside the DataGridColumn tags, hence the name inline. After the opening tag we add a <mx:itemRenderer> telling Flex that we are going to define the itemRenderer property right here. Inside the itemRenderer tag we build a <mx:Component>. Inside the <mx:Component> tag we can use all the normal ui components we have at our disposal. Now to refer to the current row data we use the data object. In ours we simply have two <Label> components added to a <VBox> and bind the text to the first and last names. Below you will see our new complete DataGridColumn code.

<mx:DataGridColumn headerText="Name" width="75">
  <mx:itemRenderer>
    <mx:Component>
      <mx:VBox verticalGap="2">
        <mx:Label text="{data.name.first}" />
        <mx:Label text="{data.name.last}" />
      </mx:VBox>
    </mx:Component>
  </mx:itemRenderer>
</mx:DataGridColumn>

The other item renderer we use is going to be its own mxml component. This means we are going to create an entire new file. This component is going to use data from the row and also data from our games xml file to display a small picture and name of the game. We create a new file which we name "ImageRenderer.mxml" and I put it in a folder named "comp" - this doesn't matter except when you reference it. In this file we are going to create a simple custom component which is based off of a HBox and has an <mx:Image> and a <mx:Label> in it. I also add the same XML tag as we have in the main file because we are going to need this data. The basic structure of the component looks like:

<?xml version="1.0" encoding="utf-8"?>
<mx:HBox xmlns:mx="http://www.adobe.com/2006/mxml" height="60" verticalAlign="top">
  <mx:XML id="games" source="/data/games.xml" />
  <mx:Image scaleX=".25" scaleY=".25"/>
  <mx:Label width="250" />
</mx:HBox>

Everything looks alright except we aren't setting any data. We set the source of the image to something a little complex - earlier I mentioned we were going to use a cool XML object feature and here is the first place we use it. First off the image tag now looks like:

<mx:Image source="{games.game.(@id == data.favGameID).imageURL}" 
    scaleX=".25" scaleY=".25"/>

This looks a little crazy but we'll step through it. Ignoring (@id == data.favGameID) and it looks like we are grabbing an imageURL from the games XML object. Which is exactly what is going on, but we need to tell it which game in the xml. To do this we use the id attribute we defined for each of the games in the xml file. Also in our people xml file we referred to each person's favorite game by the id so we can use this to match up the correct game. Then all that (@id == data.favGameID) is saying is that we are going use the id attribute on game (because it comes right after that property) and get the game with id equal to data.favGameID, this is the same data object as before.

That takes care of the image, on to the label. We use the same technique as above but we just get the game name now. The new Label looks like the code below.

<mx:Label text="{games.game.(@id == data.favGameID).name}" width="250" />

This completes our new component. The whole file now looks like:

<?xml version="1.0" encoding="utf-8"?>
<mx:HBox xmlns:mx="http://www.adobe.com/2006/mxml" height="60" verticalAlign="top">
  <mx:XML id="games" source="/data/games.xml" />
  <mx:Image source="{games.game.(@id == data.favGameID).imageURL}" 
      scaleX=".25" scaleY=".25"/>
  <mx:Label text="{games.game.(@id == data.favGameID).name}" width="250" />
</mx:HBox>

To hook this into our last datagrid column we simply set the itemRenderer property equal to the name of this component. In my case comp.ImageRenderer - remembering that I put it in the "comp" folder so I have to put this at the beginning. The DataGridColumn code now looks like the following.

<mx:DataGridColumn headerText="Favorite Game" itemRenderer="comp.ImageRenderer"/>

We now have a datagrid fully displaying all the information. Take a break and grab a drink...Ok we're back - on to the next part.

Display Selected Data

In this part we are going to display the large image and data about the currently selected game. We will use the xml feature we went over earlier extensively in this section. I am not going to go real far in depth about these components because it is all things that we have done before.

The larger image will have its source set to the image url of the currently selected item's favorite game. The labels will have their values set in the same fashion. To get to the selected item's favorite game id we will use dgPeeps.selectedItem.favGameID. This grabs the currently selected item from the datagrid and then gets the favGameID from the selected item. So the whole new lower ui section now looks like.

<mx:Image x="10" y="318" width="300" height="240" id="imgGameScreen" 
    source="{games.game.(@id == dgPeeps.selectedItem.favGameID).imageURL}"/>
<mx:Label x="10" y="293" fontWeight="bold" fontSize="13" id="lblGameName" 
    text="{games.game.(@id == dgPeeps.selectedItem.favGameID).name}"/>
<mx:Label x="318" y="318" text="Developer:"/>
<mx:Label x="318" y="335" id="lblDeveloper" 
    text="{games.game.(@id == dgPeeps.selectedItem.favGameID).developer}"/>
<mx:Label x="318" y="361" text="Publisher:"/>
<mx:Label x="318" y="378" id="lblPublisher" 
    text="{games.game.(@id == dgPeeps.selectedItem.favGameID).publisher}"/>

Sorry about the formatting atrocity (we have a limited page width to work with). Next we get to do some styling and skinning.

Styling the Application

Adobe has given Flex some great features when it comes to styling an application, I will touch on just a small number of them in this tutorial. The first change we are going to make is simply setting a property of the datagrid. We set the showHeaders property to false to remove the header row. The new DataGrid component has the following code.

<mx:DataGrid id="dgPeeps" x="0" y="25" width="510" height="260" 
    selectedIndex="0" dataProvider="{people.person}" showHeaders="false">

The rest of our changes are going to be done in a new file which is going to be a css file. Flex has the ability to use css syntax to define the style of components. You can define styles for components or create css classes and use them in your mxml to give a component a certain style just like in html. My css file is in a folder called "assets" and is named "app.css".

In this file we are going to start by actually embedding a new font from a .swf file - which is included in the zip file. In "fonts.swf" the font face "Myriad Web" is defined. To use this we need to define the different font faces we are going to use. I set up three different font faces one for normal, one for bold, and one for italics. To learn more about fonts in Flex check out the Adobe livedocs here. The following code goes in our css file and will use the "fonts.swf" to create the new font faces.

/** Font Info **/
@font-face 
{
  src:url("/assets/fonts.swf");
  fontFamily: "Myriad Web";
}

@font-face 
{
  src:url("/assets/fonts.swf");
  fontFamily: "Myriad Web";
  fontWeight: bold;
}

@font-face 
{
  src:url("/assets/fonts.swf");
  fontFamily: "Myriad Web";
  fontStyle: italic;
} 

To use these we will set some styles for the Application, we set the font-family and font-size. To use the new font family I refer to it using the fontFamily name in the @font-face code. The Application style is added to the css file and looks like:

Application 
{
  font-family: "Myriad Web";
  font-size: 12;
}

To use these styles we add a new tag to our main mxml file. The tag is <mx:Style> and we simply set the source property to our css file. The new tag will go right underneath the opening application tag and will enable the example to use the new Application style.

<mx:Style source="/assets/app.css"/>

Styling the datagrid is going to be done in the same fashion. Now we will setup a "DataGrid" style in which we remove the vertical grid lines and border. Along with these we also set some colors of the selected row, the rolled over row, and the alternating row colors. This is all pretty self explanatory so I won't go into any more detail. The following code goes into our css file.

DataGrid
{
  vertical-grid-lines: false;
  border-style: none;
  selection-color: #C1FFC5;
  roll-over-color: #7CFF77;
  alternating-item-colors: #F4FBFF, #FFFFFF;
}

This takes care of updating the style of our datagrid. The last item we are going to play with is the vertical scroll bar. We can style VScrollBar to modify all the application's vertical scroll bars. Using some images I created for the up (upArrow.png) and down (downArrow.png) arrows and the scroll bar (thumb.png) and scroll background (scrolltrack.png) I can skin what the scroll bar looks like. All these images are included in the "assets" folder in the zip file.

We set each of the needed skin styles to our new images. Each piece except the scroll background has an up, over, and down skin but I set all three to the same image for simplicity sake. For the thumb image I used scale-9 to define edge scales, more info on this can be found here. That isn't all that's important though. Remember to use the Embed tag to embed the image into our application. The style ends up looking like the following.

VScrollBar {
  downArrowUpSkin: 
    Embed(source="/assets/downArrow.png");

  downArrowOverSkin: 
    Embed(source="/assets/downArrow.png");
  downArrowDownSkin: 
    Embed(source="/assets/downArrow.png");
  upArrowUpSkin: 
    Embed(source="/assets/upArrow.png");
  upArrowOverSkin: 
    Embed(source="/assets/upArrow.png");
  upArrowDownSkin: 
    Embed(source="/assets/upArrow.png");
  thumbDownSkin: 
    Embed(source="/assets/thumb.png", scaleGridLeft="7", scaleGridTop="5", 
        scaleGridRight="8", scaleGridBottom="7");
  thumbUpSkin: 
    Embed(source="/assets/thumb.png", scaleGridLeft="7", scaleGridTop="5",
        scaleGridRight="8", scaleGridBottom="7");        
  thumbOverSkin: 
    Embed(source="/assets/thumb.png", scaleGridLeft="7", scaleGridTop="5",
        scaleGridRight="8", scaleGridBottom="7");       
  trackSkin:
    Embed(source="/assets/scrolltrack.png", scaleGridLeft="7", 
        scaleGridTop="4", scaleGridRight="8", scaleGridBottom="6");       
} 

I know that was a real quick intro into styling and skinning in Flex using css. It should be enough to get you started when customizing the look and feel of your own applications. You can find more information about skinning here.

Final Source Code

Well all that is left is to show you all the final code we end up with.

CSS Code:

/* CSS file */
Application 
{
  font-family: "Myriad Web";
  font-size: 12;
}

DataGrid
{
  vertical-grid-lines: false;
  border-style: none;
  selection-color: #C1FFC5;
  roll-over-color: #7CFF77;
  alternating-item-colors: #F4FBFF, #FFFFFF;
}

VScrollBar {
  downArrowUpSkin: 
    Embed(source="/assets/downArrow.png");
  downArrowOverSkin: 
    Embed(source="/assets/downArrow.png");
  downArrowDownSkin: 
    Embed(source="/assets/downArrow.png");
  upArrowUpSkin: 
    Embed(source="/assets/upArrow.png");
  upArrowOverSkin: 
    Embed(source="/assets/upArrow.png");
  upArrowDownSkin: 
    Embed(source="/assets/upArrow.png");
  thumbDownSkin: 
    Embed(source="/assets/thumb.png", scaleGridLeft="7", scaleGridTop="5", 
        scaleGridRight="8", scaleGridBottom="7");
  thumbUpSkin: 
    Embed(source="/assets/thumb.png", scaleGridLeft="7", scaleGridTop="5",
        scaleGridRight="8", scaleGridBottom="7");        
  thumbOverSkin: 
    Embed(source="/assets/thumb.png", scaleGridLeft="7", scaleGridTop="5",
        scaleGridRight="8", scaleGridBottom="7");       
  trackSkin:
    Embed(source="/assets/scrolltrack.png", scaleGridLeft="7", 
        scaleGridTop="4", scaleGridRight="8", scaleGridBottom="6");        
} 

/** Font Info **/
@font-face 
{
  src:url("/assets/fonts.swf");
  fontFamily: "Myriad Web";
}

@font-face 
{
  src:url("/assets/fonts.swf");
  fontFamily: "Myriad Web";
  fontWeight: bold;
}

@font-face 
{
  src:url("/assets/fonts.swf");
  fontFamily: "Myriad Web";
  fontStyle: italic;
} 

The main mxml file.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute" 
  width="530" height="610" viewSourceURL="/files/AdvancedDatagrid.mxml">
  <mx:Style source="/assets/app.css"/>
  <mx:Script>
    <![CDATA[
      import mx.controls.dataGridClasses.DataGridColumn;

      private function displayPersonInfo(item:Object, col:DataGridColumn):String
      {
        return item.info.age + " " + item.info.sex;
      }
    ]]>
  </mx:Script>
  <mx:Model id="people" source="/data/people.xml"/>
  <mx:XML id="games" source="/data/games.xml"/>
  <mx:Panel width="530" height="610" layout="absolute" title="Advanced Datagrids">
    <mx:Label horizontalCenter="0" y="1" text="Our Favorite Games" 
        fontSize="16" fontWeight="bold"/>
    <mx:DataGrid id="dgPeeps" x="0" y="25" width="510" height="260" 
        selectedIndex="0" dataProvider="{people.person}" showHeaders="false">
      <mx:columns>
        <mx:DataGridColumn headerText="Name" width="75">
          <mx:itemRenderer>
            <mx:Component>
              <mx:VBox verticalGap="2">
                <mx:Label text="{data.name.first}" />
                <mx:Label text="{data.name.last}" />
              </mx:VBox>
            </mx:Component>
          </mx:itemRenderer>
        </mx:DataGridColumn>
        <mx:DataGridColumn headerText="Info" width="80" 
            labelFunction="displayPersonInfo"/>
        <mx:DataGridColumn headerText="Favorite Game"
            itemRenderer="comp.ImageRenderer"/>
      </mx:columns>
    </mx:DataGrid>
    <mx:Image x="10" y="318" width="300" height="240" id="imgGameScreen" 
        source="{games.game.(@id == dgPeeps.selectedItem.favGameID).imageURL}"/>
    <mx:Label x="10" y="293" fontWeight="bold" fontSize="13" id="lblGameName" 
        text="{games.game.(@id == dgPeeps.selectedItem.favGameID).name}"/>
    <mx:Label x="318" y="318" text="Developer:"/>
    <mx:Label x="318" y="335" id="lblDeveloper" 
        text="{games.game.(@id ==  dgPeeps.selectedItem.favGameID).developer}"/>
    <mx:Label x="318" y="361" text="Publisher:"/>
    <mx:Label x="318" y="378" id="lblPublisher" 
        text="{games.game.(@id == dgPeeps.selectedItem.favGameID).publisher}"/>
  </mx:Panel>
</mx:Application>

Well I hope that this tutorial is useful for many different things.

Source Files:

• SOTC-AdvancedDatagrid.zip