My First ExtJS DataGrid Pt 5: The ColumnModel

OK, we're winding down to the end of this tutorial, with only a few key components left. Today we cover the ColumnModel, which is how we manage the initial layout of our ExtJS DataGrid. We've already covered initial setup, our paging query, and defined out DataStore (see related entry links at the bottom of the post).

First things first, let's instantiate the ColumnModel

view plain print about
1var cm = new Ext.grid.ColumnModel([{
2    // cm is our ColumnModel object
3
4}]);

Next we'll define the layout of the first column in our grid

view plain print about
1var cm = new Ext.grid.ColumnModel([{
2    id: 'fname',
3    header: "First Name",
4    dataIndex: 'vcFirstName',
5    width: 120
6 }
7}]);

Alright, pretty basic stuff here. We've placed an 'id' on this column. This allows you to later reference the column specifically for styling. We didn't really mark this one for a particular reason, we just did it to explain. Next we have the 'header', which is the text that appears in your column header at the top of your DataGrid. This is then followed by the 'dataIndex' to define the data column it is mapped to within your DataStore. Lastly we have the 'width' attribute, which speaks for itself.

There are several other possible attributes that are available to you here, most of which are fairly easy to grab from the ExtJS API. We'll cover a few more in our next tutorial, but for now we'll just complete the layout of the ColumnModel.

view plain print about
1var cm = new Ext.grid.ColumnModel([{
2    id: 'fname',
3    header: "First Name",
4    dataIndex: 'vcFirstName',
5    width: 120
6 },{
7    header: "Last Name",
8    dataIndex: 'vcLastName',
9    width: 120
10    },{
11    header: "Is Admin",
12    dataIndex: 'bIsAdministrator',
13    width: 40
14    },{
15    header: "Is Active",
16    dataIndex: 'bIsActive',
17    width: 40
18    },{
19    id: 'last',
20    header: "Last Login",
21    dataIndex: 'tsDateLastLogin',
22    width: 150
23}]);
24// by default columns are sortable
25
26cm.defaultSortable = true;

The order you work in will be reflected in your final initial layout. Each column definition is contained in curly braces, separated by commas. Each attribute is also comma delimited, with the attribute name being un-quoted, while their values are quoted if string values and not if numeric. Also notice the double quotes around the 'header' values, but the single quotes around the others. I don't know if this is intentional, and haven't really tested it, but this is the way it was in all of the example files so I thought it best to stick with the convention. The last thing we did here was set a directive on the ColumnModel to state the the columns will be sortable by default.

Alright, now you have defined your ColumnModel. A few steps left to go just yet, like the grid itself, custom renderers, styles, and other things to give it a little more cowbell. We'll begin wrapping those up in our next edition. For those coming to the Nashville CFUG Scorpio Tour presentation tomorrow night I hope you'll flag me down and say high.

My First ExtJS DataGrid Pt 4: The Data Store

So, up until now we have setup our support files and written our paging query service. Now it's time to begin tying our data to our DataGrid. The Ext library provides you many different ways of pulling in data into the components. We're going to create a data 'Store' using a combination of the HttpProxy (a utility for pulling data from within the same domain) and the XmlReader (for parsing our returned datasets).

A 'Store' is "a client side cache of Ext.data.Record objects which provide input data for widgets." Basically you create this representation of your server side data by defining where it is and what it looks like. We're using the HttpProxy, in this case, because our service script (pagingService.cfm) resides within the same domain as our calling page. And, since we set our service script to return an XML document, we need the XmlReader to 'map' the data that we need.

First we'll setup the basic block

view plain print about
1var ds = new Ext.data.Store({
2
3});

Add in the location of our service script

view plain print about
1var ds = new Ext.data.Store({
2    // load using HTTP
3 proxy: new Ext.data.HttpProxy({url: 'http://cc.mytestserver.loc/jTesting/xmlSqlTest.cfm'}),
4
5});

Then we set up our XML 'reader'

view plain print about
1var ds = new Ext.data.Store({
2    // load using HTTP
3 proxy: new Ext.data.HttpProxy({url: 'http://cc.mytestserver.loc/jTesting/xmlSqlTest.cfm'}),
4
5    // the return will be XML, so lets set up a reader
6 reader: new Ext.data.XmlReader({
7        // records will have an "T4" tag
8        record: 'T4',
9        id: 'ID',
10        totalRecords: "recCount"
11    }, [
12        // set up the fields mapping into the xml doc
13        'vcFirstName', 'vcLastName', 'bIsAdministrator','bIsActive','tsDateLastLogin'
14    ]),
15
16});

Ok, here is where I have to put on the breaks for a minute. You have to understand a little about what the reader requires here. It helps if you take a look at a return recordset from your service script. I suggest you call it in Firefox for a nice representation, but basically it looks something like this:

view plain print about
1<userList>
2    <T4>
3        <recCount>5802</recCount>
4        <ID>2350</ID>
5        <vcFirstName>Robin</vcFirstName>
6        <vcLastName>Williams</vcLastName>
7        <bIsAdministrator>0</bIsAdministrator>
8        <bIsActive>1</bIsActive>
9        <tsDateLastLogin>2007-05-01T14:34:57</tsDateLastLogin>
10    </T4>
11    <T4>
12        <recCount>5802</recCount>
13        <ID>4027</ID>
14        <vcFirstName>Howie</vcFirstName>
15        <vcLastName>Mandel</vcLastName>
16        <bIsAdministrator>0</bIsAdministrator>
17        <bIsActive>1</bIsActive>
18        <tsDateLastLogin>2007-04-29T16:29:33</tsDateLastLogin>
19    </T4>
20    ...
21</userList>

You see, looking at the XML, that each record is denoted by the 'T4' node, which we have mapped in our reader to the 'record' attribute. You'll also note that the 'id' attribute was mapped to the 'ID' node in the XML document. This is a unique identifier within each record. We mapped 'totalRecords' to the 'recCount' node, as this is where we set up in our script to place the total record count, and then you see a basic comma delimited list of the nodes that will be included in our DataGrid.

It's important to note here that we have used a very basic XML return for our example here. You do have the power to map values from XML attributes and nested nodes, through the use of XPath syntax. You can even rename a 'field' when identifying a mapping. Look through the examples included in the ExtJS download to get a better idea of what you might be able to do.

OK, to finish our DataStore definition we're going to specify the ability to 'remotely' sort our data, and set up our default sort column and sort order.

view plain print about
1var ds = new Ext.data.Store({
2    // load using HTTP
3 proxy: new Ext.data.HttpProxy({url: 'http://cc.mytestserver.loc/jTesting/xmlSqlTest.cfm'}),
4
5    // the return will be XML, so lets set up a reader
6 reader: new Ext.data.XmlReader({
7        // records will have an "T4" tag
8        record: 'T4',
9        id: 'ID',
10        totalRecords: "recCount"
11    }, [
12        // set up the fields mapping into the xml doc
13        'vcFirstName', 'vcLastName', 'bIsAdministrator','bIsActive','tsDateLastLogin'
14    ]),
15    // turn on remote sorting
16    remoteSort: true
17});
18ds.setDefaultSort('vcLastName', 'desc');

And so begins our scripting for creating our DataGrid. The big "gotchas" that hit me along the way were the stupid things. Mis-identifying my 'record' mapping, or missing a trailing comma. Firebug and the JavaScript Console (Firefox) are your friends.

Next round we'll define our ColumnModel. This is how we'll define the order of initial column display, define column headings, and really button up the initial details before fine tuning our layout.

My First ExtJS DataGrid Pt 3: A Paging Query

OK, we're cooking with crisco now. You've probably taken a little time to look through the examples a little bit by now, and you've seen a little of what the paging grid looks like and can do, along with the many other examples. Our last tutorial covered setting things up, but before we dive into the JavaScript we'll need some data.

Now, the paging example that's included with the Ext download calls an external PHP page to retrieve the necessary JSON dataset. JSON is great, being small and lightweight, but I'm working with MS SQL at work, which can return XML data. Since the library has built in proxies for dealing with either, I change it up to take in the XML.

Each database has different ways of writing a 'paging' query. MySQL makes it really easy by providing multiple arguments for the LIMIT statement. MS SQL makes it a little harder. See, the trick is to only pull in the records, on each db call, that you actually need. Some people pull the entire recordset and then use a query-of-query to poll their required data, but if you're dealing with very large datasets then it makes more sense to only pull what your need when the time comes. I found a great article on MSDN (which I can no longer find) that gives a good suggestion on how to approach this, by using multiple sub select statements. But, the first thing we'll do is define some default parameters for those that will eventually be passed in on the AJAX calls.

view plain print about
1<cfparam name="URL.start" default="0" />
2<cfparam name="FORM.start" default="#URL.start#" />
3<cfparam name="URL.limit" default="25" />
4<cfparam name="FORM.limit" default="#URL.limit#" />
5<cfparam name="URL.dir" default="DESC" />
6<cfparam name="FORM.dir" default="#URL.dir#">
7<cfparam name="URL.sort" default="vcLastName" />
8<cfparam name="FORM.sort" default="#URL.sort#" />

First thing you probably noticed is that I have a FORM scoped variable that matches every URL scoped variable, defaulting the URL var first then defaulting the FORM var to the URL var's value. What this allows me to do is testing. I can call the page without any additional info and it will properly run, since I have defaulted all values, and I can tag on query string variables for initial output testing, or tap it directly from a form post. These variables are pretty basic: 'start' is the starting record row, 'limit' is the number of records to be returned, 'dir' is the sort order, and 'sort' is the column to sort on. After this we move to the query itself.

view plain print about
1SELECT    (SELECT COUNT(ID) AS recCount FROM tblUsers) AS recCount,
2            ID,
3            vcFirstName,
4            vcLastName,
5            bIsAdministrator,
6            bIsActive,
7            tsDateLastLogin
8    FROM ( SELECT TOP #FORM.limit# ID,
9                    vcFirstName,
10                    vcLastName,
11                    bIsAdministrator,
12                    bIsActive,
13                    tsDateLastLogin
14            FROM (SELECT TOP #FORM.start + FORM.limit# ID,
15                            vcFirstName,
16                            vcLastName,
17                            bIsAdministrator,
18                            bIsActive,
19                            tsDateLastLogin
20                 FROM (SELECT TOP #FORM.start + FORM.limit# ID,
21                                vcFirstName,
22                                vcLastName,
23                                bIsAdministrator,
24                                bIsActive,
25                                tsDateLastLogin
26                        FROM tblUsers AS T1
27                        WHERE tsDateLastLogin IS NOT NULL
28                 ORDER BY #FORM.sort# ) AS T2
29             WHERE tsDateLastLogin IS NOT NULL
30                    ORDER BY #FORM.sort# DESC ) AS T3
31            WHERE tsDateLastLogin IS NOT NULL) AS T4
32    WHERE tsDateLastLogin IS NOT NULL
33    ORDER BY #FORM.sort# #FORM.dir#
34    FOR        XML AUTO, ELEMENTS

Notice a few things here. I only call the columns that I need. The two inner most sub selects use the TOP functionality to retrieve the 'start' row number plus the 'limit', so if you 'limit' yourself to 25 records and you are now calling page 3 (which would start with row 50) then you would say in these statements 'retrieve the TOP 50+25 rows', with the first sub-select then only asking for the 'limit' of the TOP 25. This gives you the TOP 25 rows of 50+25. You also see that a COUNT was added to the first select. Although this number appears in each record as 'recCount', it also gives you the total number of records that could be returned, thereby giving us the ability to say 'these are rows 50 thru 75 out of 38,543 records.'

If you cfdump the query return you will see multiple query rows returned, but nothing like you might expect. We now have to convert the returned query into a properly formated XML string. For this I use a function that Andrew Powell showed us in a Spry presentation that he did for the Nashville ColdFusion User Group. This was something that one of his compadres at Universal Mind wrote, and that I've adjusted slightly here.

view plain print about
1<cffunction name="sqlXMLtoCFXML" access="public" output="false" returntype="any">
2    <cfargument name="doc" type="string" required="false" default="xml" />
3    <cfargument name="qry" type="query" required="true" />
4    <cfscript>
5        var x = "";
6        var y = "";
7        var retXML = "";
8        x = listFirst(ARGUMENTS.qry.columnList);
9        for (y=1;y lte ARGUMENTS.qry.recordCount;y=y+1){
10            retXML = retXML & ARGUMENTS.qry[x][y];
11        }
12        retXML = "<" & ARGUMENTS.doc & ">" & retXML & "</" & ARGUMENTS.doc & ">";
13    
</cfscript>
14    <cfreturn retXML />
15</cffunction>

Basically this will take your MS SQL query output and format it into a proper XML document, with the ability for you to also define the 'root' element (doc). I keep this function in a utility library so that I can call it at anytime. I then take the return of this and output it between some cfcontent tags with a type of 'text/xml' to get a dynamic xml doc to be consumed by these AJAX calls.

view plain print about
1<cfcontent type="text/xml"><cfoutput>#sqlXMLtoCFXML(VARIABLES.qryReturned)#</cfoutput></cfcontent>

The Ext library makes the call to the pages via a form post, then inspects the XML return to map fields to their assigned grid columns.

But, that's another lesson. This wraps it up for today. Tune in next time (same Bat-time, same Bat-channel) for our next installment: Defining the DataStore.

P.S. Sample files will be added to this post sometime tomorrow.

The sample files are now included in the download area below. Let me know if you have any questions, comments, or war stories.

My First ExtJS DataGrid Pt 2: Setting Up

So, off we go. First things first, you'll need the JQuery and ExtJS libraries. I also found out (the hard way, since it's not in the install notes) that you'll need the Dimensions JQuery Plugin. The full ExtJS download contains the project core files, JS library 'adapter' files, all of the Ext components, examples, documentation, and a 'resource' directory of images and stylesheets to help you get started.

I start off by placing the necessary script tags in the header of my document. Order of placement is important.

view plain print about
1<script type="text/javascript" src="js/jquery/jquery.js"></script>
2<script type="text/javascript" src="js/jquery/plugins/dimensions.js"></script>
3<script type="text/javascript" src="js/ext-1.0/adapter/jquery/ext-jquery-adapter.js"></script>
4<script type="text/javascript" src="js/ext-1.0/ext-all.js"></script>
5<script type="text/javascript" src="js/paging.js"></script>
6<link rel="stylesheet" type="text/css" href="resources/css/ext-all.css" />

Now, for reference, you don't need the 'all' ext library for this to work, but I'm just doing personal testing right now and figured that it's easier than breaking things out at this point. The 'all' library is the complete component collection, core, and utilities within one script file. While nice to have it all, it is large, and you can use just the components you need. The 'Build your own Ext' section of the ExtJS site can show you all of the necessary dependencies to put together only what you need.

I'm going to copy the paging.js file out of the ExtJS example directory and place it in the root of my js directory. I'm going to adjust this existing file to create my first paging grid. I know that this works, so I might as well not re-write the wheel. You'll also noticed that I used the included stylesheet file from the resources directory. Now, with all of this in place, all I need is my container div that will hold my DataGride. In the body of my document I place the following container code:

view plain print about
1<div id="topic-grid" style="border:1px solid #99bbe8;overflow: hidden; width: 665px; height: 300px;"></div>

And that's the end of the initial setup. In part 3 I'll cover creating a paging sql page that will only call the records needed for each 'view' in our paging grid, returning the records in an XML format to be consumed by our grid. Until then, take a good look at the 'examples' directory in your ExtJS download, as well as the API and Examples section of Learn area of the ExtJS site. Also, included in the download below you will find the complete document we created today.

My First ExtJS DataGrid Pt 1

I can write my own code. I can take a process, define a proper algorithm for addressing an issue, and tap it out. In fact I enjoy the art of writing code, it's kinda like working on puzzles day in and day out, and I like a good puzzle. On the other hand I think it's also smart not to re-invent the wheel. Many minds have dealt with the same problems that I encounter every day, and someone has probably found a solution by now. Why fight that?

[More]

Previous Entries