ColdFusion Grid Editing Basic
When the new grid features were announced in ColdFusion 8 people got very excited. I am not quite sure why but not to many people are talking about this feature these days. If you are new to grid editing support I encourage you to read an article by Ben Forta that outlines how to edit data in a grid. I am going to repeat some of that article but also show you a little more. Think of this as a refresher because the next tutorial I have will dive into some customization techniques.
Getting started with the tutorial we are going to stick with what got us here. I will be using the cfartgallery data source that ships with ColdFusion 8 so this should work out of the box. Here we have the code that creates our grid. There are only 2 attributes we need to add to our grid to make this work. First we set select mode to edit. This tells our grid to add editing capabilities. If we wanted to add deleting capabilities we could set the delete attribute to true but we will just be editing in this tutorial. The second difference is the the onChange attibute. We will look into this a little deeper in a second.
SELECT artistId, firstname, lastname, address, city, state, postalcode, email
FROM Artists
</cfquery>
<cfset args = structNew()>
<cfset args.name = "ArtistGrid">
<cfset args.format = "html">
<cfset args.query = "getArtists">
<cfset args.stripeRows = true>
<cfset args.selectColor = "##D9E8FB">
<cfset args.selectmode = "edit">
<cfset args.onchange = "cfc:artists.editArtist({cfgridaction},{cfgridrow},{cfgridchanged})">
<cfform>
<cfgrid attributeCollection="#args#">
<cfgridcolumn name="artistid" display="false">
<cfgridcolumn name="firstname" header="First Name">
<cfgridcolumn name="lastname" header="Last Name">
<cfgridcolumn name="email" header="Email Address">
<cfgridcolumn name="address" header="Address">
<cfgridcolumn name="city" header="City">
<cfgridcolumn name="state" header="State">
<cfgridcolumn name="postalcode" header="Zip">
</cfgrid>
</cfform>
Here is a how our grid turns out. You will notice that when you double click in a cell a text editor appears and after you make a change a red marker appears in the grid noting that the data has changed.
Now that we understand how to enable editing we need to cover how we actually save the changed data. If you look at the grid image you will notice that the last name Donolan now has a z on the end. If we enable firebug and take a look at the post we will see the following information. As you can see our grid passes 3 parameters; gridAction, gridRow and gridChanged. The gridAction argument will pass U for update and D for delete. The gridRow is a name value pair of the row being changed. Finally the gridChanged argument tells us what column is being changed and what the new value is.
If we look back at our code we should look at the onChange attribute. Here we are telling the grid that when the data changes we want to call our artists cfc and the method editArtist and into that method we are going to pass those 3 parameters.
Finally here is the code from Ben's tutorial. If we get passed U for update we set the name of the column being changed and the new value and use that to update our database.
<cfargument name="gridaction" type="string" required="yes">
<cfargument name="gridrow" type="struct" required="yes">
<cfargument name="gridchanged" type="struct" required="yes">
<cfset var colname = "">
<cfset var value = "">
<cfswitch expression="#arguments.gridaction#">
<!--- update --->
<cfcase value="U">
<cfset colname = StructKeyList(arguments.gridchanged)>
<cfset value = arguments.gridchanged[colname]>
<cfquery datasource="#variables.dsn#">
UPDATE Artists
SET #colname# = '#value#'
WHERE artistid = <cfqueryparam value="#arguments.gridrow.artistid#" cfsqltype="cf_sql_integer">
</cfquery>
</cfcase>
<!--- delete --->
<cfcase value="D">
<cfquery datasource="#THIS.dsn#">
DELETE FROM Artists
where artistid = <cfqueryparam value="#arguments.gridrow.artistid#" cfsqltype="cf_sql_integer">
</cfquery>
</cfcase>
</cfswitch>
</cffunction>
As you can see editing inline on the grid is very easy to do. I see many question out there about customizing the editing features, stay tuned because I have something you are going to like.
