Flex Friday Feature - Datagrid Component

Due to popular demand, we've got another flex tutorial here for you all. I am going to go over a Flex component that we get a lot of search traffic for, but I have not yet gone in depth about. The datagrid component is one of the most versatile and used UIComponents in the flex environment. After this tutorial you should have a good grasp on how to use the datagrid component and what can be done with it.

First off I will give a quick and dirty overview of the component. The DataGrid is a visual control that shows data in tabular form, it extends the functionality of List and farther down the line there is UIComponent, which all visual components extend. I should mention that you do not use the datagrid for a layout control, there is a grid layout control to use for this. If you want to learn some more about the cold hard details of DataGrid check out Adobe Livedocs Page.

So that brings us to a quick look at an empty DataGrid with no data attached. And as always, on any of the examples you can right click and view the source of the flex file.

So lets make a couple observations about the default DataGrid (by default I mean this was added using the designer in Flex Builder). There doesn't seem to be anything special but you will notice you can drag the columns around to order them anyway you want. That functionality is built into the DataGrid object.

So what's the code behind this? You can see below that this application just has a couple basic things in it. We add a panel and set the title. The <mx:DataGrid> comes next and we set a couple attributes that are typical to ui elements: x, y, height and width. Now inside our DataGrid we add a <mx:columns> tag to say that we are now going to add our column definitions. Inside this tag we add a couple <mx:DataGridColumn> tags and each one of these defines one column in our grid. They have two main attributes (properties) we define: headerText which is the name that is going to appear at the top of the column, and the dataField which tells the column what field in the data from our data provider to use when displaying information (we will be taking a look at the data provider later). Then we just close all the open tags, and that is all there is to our first example.

Now lets start adding some data to our DataGrid. To do this we are going to use a data provider: <mx:dataProvider>. This tag is going to go inside our dataGrid tag to let flex know we are going to explicitly define the dataProvider property of the DataGrid. Inside the data provider tag we simply add a few objects with properties that match the dataField names defined in the columns. In this example our dataField names are "name", "creator", and "publisher". After those objects we close our data provider tag and add our columns like the last example with slightly more descriptive headerText and dataFields properties . You will also notice that we added a property to our <mx:dataGrid> tag to limit the number of rows (rowCount). Right below is the application this creates, followed by the actual code.

That is the most basic way to put data in the DataGrid but is not very useful if your data isn't completely static. Fortunately, that is by no means the only way to hook in data. Lets look at another way to provide data to our DataGrid, binding an ArrayCollection to the dataProvider property of our DataGrid. This is done inside the <mx:DataGrid> tag, where we set the dataProvider property to "{gamesData}" - the name of our bindable ArrayCollection (for more on Bindable check out this post). Now the information in our arrayCollection will show up in our datagrid just like the last example, and if the information in that array happens to be the same as the static data above, the two datagrids will look identical. But this time we have a variable that we can change dynamically. And thats how we get the code below:

But when you run the code you notice there is no data in the datagrid, due to the fact that we have not initialized it yet. We can do this using an event on the datagrid component. The event we are going to use is the creationComplete event, which is dispatched once after the control is done being built and drawn. So to hook in to this event set it equal to "{initDataGridData()}", which tells flex to call our actionscript function initDataGridData when the event is fired. Now in this function we set our gamesData to a new ArrayCollection and add a couple items to our ArrayCollection. The code in the first block below gets added to our <mx:Script> tag and the code in the second block is our new <mx:DataGrid> opening tag.

And here is what that adding that new code creates:

Another use of the data provider property is that we can change what object is hooked to it on the fly. To do this we won't be using the dataProvider property in our <mx:DataGrid> tag at all. We are going to assign something to the property in actionscript. In the example below, pressing the button "Change Data" will populate the grid with a completely different array of data.

To do this though we need a way to identify our DataGrid in actionscript, which we do by setting the id property on the DataGrid (which in this case we will set to "dgGames"). The next thing we do is use the same tactic as the last example to initialize our data but this time we initialize two ArrayCollections, the two sets of data we will be displaying in the grid. And at the end of the actionscript function we do the very important step of setting the dataProvider on our dgGames. Here we set the dataProvider to our first ArrayCollection gamesDataA. So now we are where we were in the last example (we can show a DataGrid with our data from gamesDataA) but with a slight difference - we didn't actually bind the data. The code to do this is below:

It is also a good time to note a property which I set in the DataGridColumn for "name", I explicitly set the width to 115 pixels so that the creator and publisher columns would have more room because of names like "Sony Online Entertainment". But other than that this isn't anything too special - all we did is set the dataProvider property outside of the DataGrid tag. But to make it more interesting lets add a button to our application and add a actionscript function to the click event. Here we call the function changeGameData. Below is the code to add to your panel, this will go right below the <mx:DataGrid> tag.

The function will check to see if dgGames.dataProvider is equal to gamesDataA and if it is we set the dataProvider equal to our other ArrayCollection, gamesDataB. Otherwise we set the dataProvider back equal to gamesDataA. This code will go into the <mx:Script> tag. And this completes the current example - if you'd like to see the full source, you can scroll back up and choose "View Source" from its right click menu.

In the final example of this tutorial I am going to show a few different things that can be done using the DataGrid component. I will show how to get information about selected rows (single and multiple) and also how to bind the information in your datagrid back to a variable. But getting the information back from the DataGrid isn't all that useful unless we are able to edit that information on the grid, so we are going to cover that as well. To get an idea of what I am talking about you can play with the example we are going to create right below. In this example there are two datagrids - the top one holds all the game data we have and the bottom one shows the data for whatever we have selected in the top grid. Also on the top you you can edit the various fields and changes will be automatically saved. You can also select multiple games by the standard Ctrl or Shift Clicking on the rows. On the bottom grid, you can only select one row at a time, and whatever is selected is also displayed in labels below the grid.

And now to get into the code. The first thing to do is to set up the interface, and since the interface is not particularly complex, the code should be self-explanatory. We have a panel which takes up the entire application, two datagrids (and on both we limit the width of the name column), and six labels (three for the static text and three which we are going to update). Now anything that we are going to refer to or change needs to have an id property: the datagrids and the changing labels. And all this results in the code below:

Now lets start by hooking the data for the top grid. We do this using a [Bindable] ArrayCollection named allGames like earlier in the tutorial. And we set the initialized data by adding a function, initDGAllGames to the creationComplete event for the top DataGrid. So now we have some script code which is going to go right below our <mx:Application> tag.

The opening tag of our top DataGrid (which is named dgAllGames) now needs the dataProvider property set to our allGames ArrayCollection and a creationComplete event calling initDGAllGames(). This results in the following tag:

All of that we have done in previous examples, but now we are going to make the top grid editable. All we have to do to enable that is set the editable property in the DataGrid tag to true. The opening tag for dgAllGames should now look like this:

But this does not cause any changes to the data in the grid to be saved - in order to do that we need to add a <mx:Binding> tag below our closing script tag. This source property in this binding tag will contain dgAllGames.dataProvider as ArrayCollection. What that means is that we are going to use the dataProvider data from dgAllGames as the data source, but we will treat it as an ArrayCollection. The destination property will be the original allGames ArrayCollection. So now our data is being saved back into the ArrayCollection. The binding code is below:

Now we have a DataGrid which can display our data and update our data. One more thing we want to do with our top GataGrid is allow multiple rows to be selected at once, which is again just another property in our DataGrid tag. So we just set the allowMultipleSelection property to true and now we have ability to Ctrl or Shift Click multiple items. That should be it for the dgAllGames tag, which now looks like this:

But whats the point of selecting items, if you can't tell what has been selected? An easy way to solve this is to bind the currently selected items to an array. So in our script code we add a [Bindable] array for our currently selected items. This means the following code gets added in our <mx:Script> tag.

And we bind to this array using another binding tag just under our allGames binding. We set the source equal to dgAllGames.selectedItems - which is a property of the DataGrid object which returns an array of the currently selected items. Our destination is just going to be our new array selectedGames. This new binding tag is below:

Just a couple things left to do now. First we will bind our selectedGames array to our dataProvider for our second datagrid, which means that whatever is selected in the first DataGrid gets displayed in the second. We also add an event hook to the second DataGrid's change event. A DataGrid fires the change event whenever its selectedIndex or selectedItem changes. We are going to use this event to update our labels. So the opening tag to our second DataGrid component, dgSelectedGames, now looks like the following code:

All that is left now is to add the function referenced by the change event hook of the second DataGrid. This function (selectedItemChanged()) goes inside our script tag, and will be in charge of updating the three labels at the bottom of the example. What we do in here is set the text of our labels to the contents the selected item in our dgSelectedGames DataGrid. We can get to our selected item using the property dgSelectedGames.selectedItem and then we can simply reference the name, creator, and publisher as properties of the selectedItem object. The following code goes inside our <mx:Script> tag and will finish off our example.

And when you put all of this together, it results in the full source code for this example:

Hopefully this tutorial gave you a give overview of what the DataGrid component can do and what it can be used for. Look for a tutorial on advanced DataGrid techniques in the future, and remember that the examples here are not always done the best/fastest way, but are done in ways that show off certain features of the DataGrid component. If you have any questions about the examples or DataGrid in general feel free to leave a comment.