Coldfusion Tutorials

Spry Tutorials

Air Tutorials

Beginner Tutorials
Intermediate Tutorials
Advanced Tutorials

CFGRID Tutorial

Coldfusion 8 CFGRID

I wrote in my blog on June 14 about the CFGRID's new features with the release of Coldfusion 8.
I thought it would be a good idea to revisit it here in my tutorials section as well. To create a cfgrid that binds directly to a coldfusion compoenent we write the following code in a cfm template.

The Details

First of all, the CFGRID must be contained within a CFFORM tag for it to work so in line 1 we set up our cfform tag and give it a name.
On line two we set up a basic grid, we must specify that it is an HTML grid (there are also flash and java grids but we won't go into that here). What we also need to do is tell the grid how many rows we want displayed per page and what type, if any, selection mode we want to have I specified row here.
lin 3 is where things start getting a bit interesting. Here we set up the bind parameter. The bind parameter tells the grid where to find the component based on the dot notation and also which method in our component to call in this case getArtist. The arguments that are listed in the {} braces are socalled bind arguments, and are filled automatically by coldfusion. We can also add additional arguments if our component takes them.
lines 4 through 8 we are setting up the columns we want to display, our component could return more columns but they won't be displayed, and neither will the ARTISTID column since we set the display attribute to "no". Typically coldfusion components return the column names in all capitals so you should do likewise with your name attributes as they are case sensitive.

Here is what it looks like using the default styling:

One of the great things about the CFGRID is that it automatically comes with column sorting and paging functionality built right in, we no longer have to build anything special or specific to perform pagination or column sorting. This is a really big plus!

On to the Component

Lets take a quick look at the code for the Artist cfc:

<cffunction name="getArtists" access="remote">
      <cfargument name="page" required="yes">
      <cfargument name="pageSize" required="yes">
      <cfargument name="gridsortcolumn" required="yes">
      <cfargument name="gridsortdirection" required="yes">

   <cfquery name="members" datasource="cfartgallery">
      SELECT ARTISTID, FIRSTNAME, LASTNAME, CITY, STATE
      FROM ARTISTS
      <cfif gridsortcolumn neq ''>
      order by #gridsortcolumn# #gridsortdirection#
      </cfif>
   </cfquery>
   <cfreturn queryconvertforgrid(members,page,pagesize)/>
   </cffunction>

The Details

I won't go through a line by line explanation of the component I think the biggest thing here worth mentioning is the queryConvertForGrid() function which is also new to Coldfusion 8. This function handles the details of the pagination for you, you don't have to keep track of figure out what page a user is on in your grid and/or what page of information you need to display next, its all taken care of. You just need to pass your query, and the arguemnts page and pagesize and all the rest is done.

Another thing, since you are calling this component from one of the now Ajax tags an additional argument is passed along from the bind statement to the component telling the component to return the information as a JSON data set. You could also subsequently add the new attribute returntype="json" to the function definition. Here is the call from the grid to my component (I left off the arguments collection to keep the url shorter):

http://localhost/mycf/components/artgallery/artist.cfc?method=getArtists&returnFormat=json&argumentCollection=

My next tutorial will be on how to bind a CFTREE to a coldfusion component, following that we will look at the cflayout tag and then look at combining the three tags together to create a simple file explorer application.