CFGrid Event Listeners
As you all know by now the grid in ColdFusion 8 is powered by the Ext framework. If you dive into the documentation you will find out that there is more that you can do with it then advertised. We have been looking at ways to customize the grid, today we will learn about event listeners. The grid has the ability to announce events as they are happening even if you are not listening for them. Events can include clicking on a row double clicking on a cell or even using a keyboard shortcut. Just knowing that the gird announces these events will do you no good, you need the ability to listen for them.
The grid gives you 2 methods to listen for events. The following methods will append an event handler to this component the on method is just shorthand for addListener.
- addListener( String eventName, Function handler, [Object scope], [Object options] ) : void
- on( String eventName, Function handler, [Object scope], [Object options] ) : void
These methods belong to the grid so to use them you need to have the grid object. Fortunately for you ColdFusion provides an easy way to get the grid object. If you have been following my examples than the following should look familiar. I am using the cfartgallery data source that ships with CF8 so you can follow along at home. The code below will run a query and create a grid with the name of ArtistGrid. The name is important because that is how we will get our grid object later on. Finally the last line will call the init method when the page loads.
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.selectOnLoad = false>
<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>
<cfset ajaxOnLoad("init")>
Now that our grid is setup we can setup our init method. Remember I said ColdFusion makes it easy, I was not lying, the getGridObject will get our grid for us.
function init(){
//get the grid component grid = ColdFusion.Grid.getGridObject("ArtistGrid");
</script>
Now that we have our grid object we can start adding listeners. Lets say we wanted to call a method when a row is clicked. Here we are listening to for a row to be clicked and then calling a method named editArtist. Our editArtist method also get some information about the row being clicked. So How did i know what information would be passed?
function init(){
//get the grid component grid = ColdFusion.Grid.getGridObject("ArtistGrid");
//Fires when a row is clicked grid.addListener("rowclick",editArtist);
}
function editArtist(grid,rowIndex,e){
var record = grid.getDataSource().getAt(rowIndex);
console.log(record);
}
</script>
If we look at the documentation for the grid event listeners we will get some more details about them. The arguments are what will get passed to use when that event is fired.
- bodyscroll : ( Number scrollLeft, Number scrollTop ) - Fires when the body element is scrolled
- cellclick : ( Grid this, Number rowIndex, Number columnIndex, Ext.EventObject e ) - Fires when a cell is clicked
- cellcontextmenu : ( Grid this, Number rowIndex, Number cellIndex, Ext.EventObject e ) - Fires when a cell is right clicked
- celldblclick : ( Grid this, Number rowIndex, Number columnIndex, Ext.EventObject e ) - Fires when a cell is double clicked
- click : ( Ext.EventObject e ) - The raw click event for the entire grid.
- columnmove : ( Number oldIndex, Number newIndex ) - Fires when the user moves a column
- columnresize : ( Number columnIndex, Number newSize ) - Fires when the user resizes a column
- contextmenu : ( Ext.EventObject e )The raw contextmenu event for the entire grid.
- dblclick : ( Ext.EventObject e ) - The raw dblclick event for the entire grid.
- dragdrop : ( Grid this, Ext.GridDD dd, String targetId, event e ) - Fires when dragged row(s) are dropped on a valid DD target
- dragenter : ( Grid this, Ext.GridDD dd, String targetId, event e ) - Fires when the dragged row(s) first cross another DD target while being dragged
- dragout : ( Grid this, Ext.GridDD dd, String targetId, event e ) - Fires when the dragged row(s) leave another DD target while being dragged
- dragover : ( Grid this, Ext.GridDD dd, String targetId, event e ) - Fires while row(s) are being dragged. "targetId" is the id of the Yahoo.util.DD object the selected rows are being dr...
- enddrag : ( Grid this, Ext.GridDD dd, event e ) - Fires when a drag operation is complete
- headerclick : ( Grid this, Number columnIndex, Ext.EventObject e ) - Fires when a header is clicked
- headercontextmenu : ( Grid this, Number columnIndex, Ext.EventObject e ) - Fires when a header is right clicked
- headerdblclick : ( Grid this, Number columnIndex, Ext.EventObject e ) - Fires when a header cell is double clicked
- keydown : ( Ext.EventObject e ) - The raw keydown event for the entire grid.
- keypress : ( Ext.EventObject e ) - The raw keypress event for the entire grid.
- mousedown : ( Ext.EventObject e ) - The raw mousedown event for the entire grid.
- mouseout : ( Ext.EventObject e ) - The raw mouseout event for the entire grid.
- mouseover : ( Ext.EventObject e ) - The raw mouseover event for the entire grid.
- mouseup : ( Ext.EventObject e ) - The raw mouseup event for the entire grid.
- render : ( Grid grid ) - Fires when the grid is rendered
- rowclick : ( Grid this, Number rowIndex, Ext.EventObject e ) - Fires when a row is clicked
- rowcontextmenu : ( Grid this, Number rowIndex, Ext.EventObject e ) - Fires when a row is right clicked
- rowdblclick : ( Grid this, Number rowIndex, Ext.EventObject e ) - Fires when a row is double clicked
- startdrag : ( Grid this, Ext.GridDD dd, event e ) - Fires when row(s) start being dragged
And that is how we are able to find out more information about the event that is happening. In our editArtist method we are getting passed the rowIndex, this allows us to look up what record what clicked. As you can see event listeners can be very powerful and just another way that you can customize your grid components. Please feel free to leave me any questions you might have about them.
