Easy Rich Internet Applications With ColdFusion 8

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, lets 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.

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.

Displaying a Details Window

First up, here's the code that comprises the showUserForm method:

function showUserForm(){  
   var userId = ColdFusion.getElementValue("userGrid", "userGridForm", "userId");  
   var url = "userForm.cfm?UserId="+userId ;  
   ColdFusion.navigate(url, "userWin");      
   ColdFusion.Window.show("userWin");  
 }

The first line in the method above retrieves the userId of the selected row. ColdFusion.getElementValue accepts three arguments:

• the name of the control we want to look at
• the name of the form that the items belongs to
• the attribute we're looking for

In this case, we're telling ColdFusion to retrieve the userId attribute from the userGrid control in the userGridForm form.

We then set a variable named url, which will store the URL to which we'll take the user. We append the userId as a parameter to the URL. This URL is used in the next line, which makes an http request to the URL and displays the result inside a <cfwindow> element named userWin. You can use the ColdFusion.navigate method to populate any HTML element on a page, such as a div. The last line will display the <cfwindow>.

Next up is the code for creating a JavaScript-based popup window using the <cfwindow> tag:

<cfwindow name="userWin" title="User Information" initShow="false" modal="true" center="true"></cfwindow>

Pretty simple, huh? Let's look at what each of these attributes represents:

• title - This attribute specifies the text that will appear at the top of the window.
• initShow - This attribute can be used to control whether or not the window is initially visible.
• modal - This attribute specifies whether the popup window is modal or not. Remember, modal windows prevent the user from interacting with the underlying page.
• center - If this attribute is set to true, the popup window will be centered on the screen.

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 <cfwindow>.

The next part of our application that we'll look at is the form.