Recipe 21.6 Using Recordsets with DataGrids

21.6.1 Problem

You want to display recordset data in a grid.

21.6.2 Solution

Use the DataGrid component.

21.6.3 Discussion

The DataGrid component is available for purchase from Macromedia as part of the DevNet Resource Kit (DRK) Volume 1, available from http://www.macromedia.com/software/drk/productinfo/product_overview/volume1. It is invaluable for displaying complex data sets such as recordsets. Normal menus, such as list boxes, work great for showing one-dimensional lists of values, but when it comes to displaying two-dimensional (row and column) data, they are not up to par. The DataGrid component allows you to display data as rows and columns, and with the DataGrid.setDataProvider( ) method or the DataGlue class, you can populate a data grid with recordset data in short order.

The setDataProvider( ) method populates the data grid with data from a recordset. If the data grid has no defined columns, columns that match the columns of the recordset in name and order are automatically created.

#include "NetServices.as"

// Create a new recordset with columns ID, FIRST, LAST.
rs = new RecordSet(["ID", "FIRST", "LAST"]);
rs.addItem({ID: 24, FIRST: "Bob", LAST: "Bobson"});
rs.addItem({ID: 42, FIRST: "Sarah", LAST: "Littlefoot"});
rs.addItem({ID: 66, FIRST: "George", LAST: "Georgeman"});

// Set the data grid to alternate row colors between white and light blue.
myDataGrid.alternateRowColors(0xFFFFFF, 0xC1E0FD);

// Populate the data grid with the recordset data. It creates 
// three columns: ID, FIRST, and LAST, in that order, which is the 
// same order as the columns from the recordset.
myDataGrid.setDataProvider(rs);

If you want to change the order of the columns as they are displayed in the data grid, add columns to the data grid before calling the setDataProvider( ) method. The easiest way to add columns to the data grid is with the setColumns( ) method. You should call this method and pass it the names of the columns to add in the order you want them to be displayed. When you use this technique with setDataProvider( ), you must make sure the columns you add to the data grid match the column names of the recordset.

myDataGrid.setColumns("ID", "LAST", "FIRST");
myDataGrid.setDataProvider(rs);

The setDataProvider( ) method works in many cases—especially when you want to display the raw data from a recordset without modification, except, perhaps, the column order. If you want to have more control over how the recordset data is displayed, use the DataGlue class.

The DataGlue class has two static methods, as described in Recipe 21.5. The bindFormatStrings( ) method is not of much use with data grids, but you can use the bindFormatFunction( ) method with a format function to preprocess the recordset data and populate the data grid with custom objects. The format function should create and return objects with properties corresponding to the columns you want to display in the data grid. For example:

#include "DataGlue.as"

// Define the format function.
function formatter (record) {

  // Define the object that is used to populate a row of the data grid.
  var obj = new Object(  );

  // Add a Name property to the object that is in the format of LAST, FIRST.
  obj.Name = record.LAST + ", " + record.FIRST;

  // Add an ID property to the object with the value of the record's ID column.
  obj.ID = record.ID;

  // Return the object.
  return obj;
}

// Populate the data grid with the recordset using the format function. The result is
// a data grid that has columns Name and ID.
DataGlue.bindFormatFunction(myDataGrid, rs, formatter);

Remember that you must always include the DataGlue.as file when you use the DataGlue class.

When you use the format function technique and you have not previously defined the columns within the data grid, the order of the columns is not under your control. However, if you add columns to the data grid before populating it, you can control the order in which they display. The column names you add to the data grid and the properties of the object returned by the format function must match.

#include "DataGlue.as"

function formatter (record) {
  var obj = new Object(  );
  obj.Name = record.LAST + ", " + record.FIRST;
  obj.ID = record.ID;
  return obj;
}

// Set the column names and order within the data grid before 
// populating it. The column names match those of the properties 
// of the object returned by the format function.
myDataGrid.setColumns("Name", "ID");
DataGlue.bindFormatFunction(myDataGrid, rs, formatter);

21.6.4 See Also

Macromedia sells additional components as part of the DRKs available at http://www.macromedia.com/software/drk/. Third-party vendors also sell components. For example, B-Line Express (http://www.blinex.com) sells a package of charting components that provide a flexible and extensible library of charting and graphics functions for displaying data as pie charts, bar charts, and much, much more.