Displaying a grid with <cfgrid>

Normally, displaying a grid or table that has sortable columns and pagination requires a considerable amount of code (even with other frameworks). But with ColdFusion 8, it's as simple as using the following ColdFusion tags:

<cfgrid name="userGrid" format="html" pagesize="5" preservePageOnSort="true" bind="cfc:com.user.UserService.getAllUsers( {cfgridpage}, {cfgridpagesize}, {cfgridsortcolumn}, {cfgridsortdirection})" sort="true" stripeRows="true"> 
 <cfgridcolumn name="USERID" header="ID" display="false" /> 
 <cfgridcolumn name="FIRSTNAME" header="First Name" width="200" /> 
 <cfgridcolumn name="LASTNAME" header="Last Name" width="300" /> 
 <cfgridcolumn name="EMAILADDRESS" header="Email" width="220" /> 
 <cfgridcolumn name="PHONE" header="Phone" /> 
</cfgrid>

That's all we need to do! There's no JavaScript [5]—there's not even any HTML. All we need are a few lines of ColdFusion code. Let's look at what each of the attributes in the cfgrid tag represents.

• name - This attribute specifies the name of the grid. This also how you reference the grid within JavaScript.
• format - This attribute determines the format that ColdFusion should use to build the grid. To create an AJAX grid, as we've done in the above example, specify "HTML".
• pageSize - This attribute defines the number of items to display per page.
• bind - This attribute tells ColdFusion from where to retrieve the data that populates the grid. In the above example, we're telling ColdFusion to use the method named getAllUsers in a ColdFusion Component (CFC) named UserService in the com/user/ directory. Note that when we're invoking CFCs in ColdFusion, we use the dot notation to specify the path to the CFC. Also note that we're passing in some arguments to the getAllUsers method, namely {cfgridpage}, {cfgridpagesize}, {cfgridsortcolumn}, and {cfgridsortdirection}. These variables describe the current state of the grid, and how we need to retrieve our information to sort or paginate the grid.
• sort - This attribute tells ColdFusion that the columns are sortable.
• preservePageOnSort - This attribute controls whether the current page should be redrawn when the user performs a sort of the data (for example, when a user is viewing page 2, and they resort the data, show page 2 of the new dataset). If you don't set this value, the grid will be reset to page 1 whenever the grid is sorted.
• stripeRows - This attribute tells ColdFusion to alternate the row colors.

There are many other attributes that can be used to dictate how the grid will look and behave. For more information, check out the LiveDocs for the cfgrid element.

The next group of tags, <cfgridcolumn>, provides ColdFusion with information about the columns that we wish to display.

• name - This attribute contains as a value the name of the element (query column) that will be used to populate this column.
• header - This attribute is the text that is displayed in the column header.
• width - This attribute specifies the width of the column.

Note: The userID is not displayed
You may notice that our data source retrieves a userId column, but hides it with the attribute display="false". The value of userId is used to uniquely identify this user in our database—we need this value for a selected row so that we can retrieve and display all of the user's information in the User Information window.

There are many other attributes that can be set to dictate how a grid column will look and behave. For more information, check out the LiveDocs help for <cfgridcolumn>.

Let's now take a look at the CFC that's referenced in the bind attribute of our <cfgrid>. There are several methods here that we use to retrieve and save individual users. There's also a method that retrieves all of our users in order to populate the <cfgrid>, and it's this code that we'll dissect next.

Retrieving all users with queryConvertForGrid

Here's the code for our queryConvertForGrid method:

<cffunction name="getAllUsers" output="false" access="remote" returntype="struct"> 
<cfargument name="cfgridpage"> 
<cfargument name="cfgridpageSize"> 
<cfargument name="cfgridsortcolumn"  /> 
<cfargument name="cfgridsortdirection"  /> 
<cfset var qRead=""> 
<cfquery name="qRead" datasource="ria"> 
SELECT userId,firstName,lastName,emailAddress,phone 
FROM  users 
<cfif len(arguments.cfgridsortcolumn) and len(arguments.cfgridsortdirection)> 
ORDER BY #arguments.cfgridsortcolumn# #arguments.cfgridsortdirection# 
<cfelse> 
ORDER BY lastName ASC 
</cfif> 
</cfquery> 
<cfreturn queryConvertForGrid(qRead, cfgridpage, cfgridpageSize) /> 
</cffunction>

This is a very basic function that accepts four arguments:

• cfgridpage
• cfgridpagesize
• cfgridsortcolumn
• cfgridsortdirection

These arguments match the arguments that we specified in the bind attribute of our <cfgrid>.

One thing that's worth noting about the <cffunction> tag is the access attribute. Any time you use Ajax to retrieve data from a CFC, the function that you call must have the access attribute set to "remote".

The function runs a very simple query against the users table in our database, and uses the arguments cfgridsortcolumn and cfgridsortdirection to order the results accordingly. If both of these values are empty strings, the results are sorted by last name.

Finally, we use <cfreturn> to return the value returned from the queryConvertForGrid function. queryConvertForGrid is a native ColdFusion function, and exists solely for the purpose of taking the results of a query and formatting them in a way that they can be used to automatically populate a <cfgrid>. This function takes three arguments:

• the query result
• the page number requested
• the page size

It returns a ColdFusion structure that's formatted in such a way that the <cfgrid> can easily interpret and display the data.

Adding a listener to the grid

Now we'll explore the task of opening the details window. Before we delve into the details, let's look at these two lines of code from index.cfm:

<cfset ajaxOnLoad("initGrid") /> 
<cfajaximport tags="cfform" />

The first line simply tells ColdFusion that the first time an Ajax call is made, it should run the initGrid JavaScript function. The second line tells ColdFusion that the ColdFusion elements we'll be using will require that we load some libraries in the main page.

The initGrid JavaScript function simply adds a listener to the grid. With this listener in place, the showUser JavaScript function will be called when a row is double-clicked. The code for initGrid looks like this:

function initGrid(){ 
 var grid = ColdFusion.Grid.getGridObject("userGrid"); 
 grid.on("rowdblclick", showUserForm); 
 }

The first line in the initGrid method provides us with an instance of the grid named userGrid, which is the value we specified in the name attribute of the <cfgrid>.

The second line sets the listener for the rowdblclick event, and specifies that the showUserForm function should be called when this event occurs. ColdFusion actually uses the Ext JS JavaScript library to create the grid, so rowdblclick is an event that's native to the grid object. More information about the Ext JS grid object can be found at the ExtJS site [6].

Now that we've told the grid to run showUserForm when a row is double-clicked, let's look at the code that displays the details window.

Page 3 of 6

Previous Page

Next Page