Creating Data Grids with cfgrid

The cfgrid tag to creates a cfform grid control. A grid control resembles a spreadsheet table and can contain data populated from a cfquery or from other sources of data. As with other cfform tags, cfgrid offers a wide range of data formatting options as well as the option of validating user selections with a JavaScript validation script.

You can also do the following with cfgrid:

Users can sort the grid entries in ascending order by double-clicking any column header. Double-clicking again sorts the grid in descending order. You can also add sort buttons to the grid control.

When users select grid data and submit the form, ColdFusion passes the selection information as form variables to the application page specified in the cfform action attribute.

Just as the cftree tag uses cftreeitem, cfgrid uses the cfgridcolumn tag. You can define a wide range of row and column formatting options, as well as a column name, data type, selection options, and so on. You use the cfgridcolumn tag to define individual columns in the grid or associate a query column with a grid column.

The cfgrid tag provides many attributes that control grid behavior and appearance. This document can only cover the most important of these. For detailed information on these attributes, see the CFML Reference.

Populating a grid from a query

To populate a grid from a query:

  1. Open a new file named grid1.cfm in ColdFusion Studio.
  2. Edit the file so that it appears as follows:
    <cfquery name="empdata" datasource="CompanyInfo">
      SELECT * FROM Employee
    </cfquery>
    
    <cfform name="Form1" action="submit.cfm" method="Post">
    
      <cfgrid name="employee_grid" query="empdata"
          selectmode="single">
        <cfgridcolumn name="Emp_ID">
        <cfgridcolumn name="LastName">
        <cfgridcolumn name="Dept_ID">
      </cfgrid>
    
    <br><input type="Submit" value="Submit">
    </cfform>
    

    Note

    Use the cfgridcolumn display="No" attribute to hide columns you want to include in the grid but not expose to an end user. You would typically use this attribute to include columns such as the table's primary key column in the results returned by cfgrid without exposing this data to the user.


  3. Save the file and view it in your browser.

Reviewing the code

The following table describes the highlight code and its function:
Code
Description
<cfgrid name="employee_grid"
  query="empdata" 
Create a grid named "employee_grid" and populate it with the results of the query "empdata".
selectmode="single"> 
Allow the user to select only one cell. Other modes are row, column and edit.
<cfgridcolumn NAME="Emp_ID"> 
Put the contents of the Emp_ID column in the query results in the first column of the grid.
<cfgridcolumn NAME="LastName"> 
Put the contents of the LastName column in the query results in the second column of the grid.
<cfgridcolumn name="Dept_ID"> 
Put the contents of the Dept_ID column in the query results in the third column of the grid.


Note

If you specify a cfgrid tag with a query attribute defined and no corresponding cfgriditem attributes the grid contains all the columns in the query.