CFQueryReader Logo


Note: CFQueryReader has now been upgraded for Ext JS 4.x, and no further work will be done to support past versions. The last working version for Ext JS 2 & 3 is version 1.2. See our GitHub repository for previous versions. Special thanks to Sencha's Ed Spencer for some of this verbiage, and to the whole Sencha team for Ext JS and SenchaTouch. Links to demos, using Ext JS 2, 3 and 4, can be found at the bottom of this page.


The CFQueryReader custom ExtJS Data Reader is used by a Proxy to read a ColdFusion server response that is sent back in JSON format. This usually happens as a result of loading a Store - for example we might create something like this:


Ext.define('User', {
    extend: 'Ext.data.Model',
    fields: ['id', 'name', 'email']
});

var store = Ext.create('Ext.data.Store', {
    model: 'User',
    proxy: {
        type: 'ajax',
        url : '/some/cfc/path.cfc',
        extraParams: {
        	method: 'someMethod',
        	returnFormat: 'json'
        },
        reader: {
            type: 'cfquery'
        }
    }
});

The example above creates a 'User' model. Models are explained in the Model docs if you're not already familiar with them.

We created the simplest type of CFQueryReader possible by simply telling our Store's Proxy that we want a CFQueryReader. The Store automatically passes the configured model to the Store, so it is as if we passed this instead:


reader: {
    type : 'cfquery',
    model: 'User'
}

The reader we set up is ready to read data from our server - at the moment it will accept a response like this:


{
	"COLUMNS":["ID","NAME","EMAIL"],
	"DATA":[
		[1,"Ed Spencer","ed@sencha.com"],
		[2,"Abe Elias","abe@sencha.com"],
		[3,"Cutter","no@address.giv"]
	]
}

CFQueryReader will also, natively, treat output from a ColdFusion QueryConvertForGrid function call. That function returns a ColdFusion struct, which is then serialized into a JSON object like this:


{
    "TOTALROWCOUNT":3, 
	"QUERY":{
	    "COLUMNS":["ID","NAME","EMAIL"],
        "DATA":[
		    [1,"Ed Spencer","ed@sencha.com"],
			[2,"Abe Elias","abe@sencha.com"],
			[3,"Cutter","no@address.giv"]
		]
	}
}

Reading this response is automatic for the CFQueryReader, with minimal configuration:


reader: {
    type: 'cfquery'
}

Reading other JSON formats

If you already have your JSON format defined and it doesn't look quite like what we have above, you can usually pass CFQueryReader a couple of configuration options to make it parse your format. For example, we can use the {@link #query} configuration to parse data that comes back like this:


{
    "recordCount":3,
	"success":true,
	"message":"",
	"activeUsers":{
	    "COLUMNS":["ID","NAME","EMAIL"],
        "DATA":[
		    [1,"Ed Spencer","ed@sencha.com"],
			[2,"Abe Elias","abe@sencha.com"],
			[3,"Cutter","no@address.giv"]
		]
	}
}

To parse this we just pass in a query configuration that matches the serialized query object above:


reader: {
    type: 'cfquery',
    query: 'activeUsers',
    totalProperty: 'recordCount',
	successProperty: 'success',
	messageProperty: 'message'
}

Response MetaData

The server can return metadata in its response, in addition to the record data, that describe attributes of the data set itself or are used to reconfigure the Reader. To pass metadata in the response you simply add a `metaData` attribute to the root of the response data. The metaData attribute can contain anything, but supports a specific set of properties that are handled by the Reader if they are present:

An initial Reader configuration containing all of these properties might look like this ("fields" would be included in the Model definition, not shown):


reader: {
    type : 'cfquery',
    query : 'data',
    idProperty     : 'id',
    totalProperty  : 'total',
    successProperty: 'success',
    messageProperty: 'message'
}

If you were to pass a response object containing attributes different from those initially defined above, you could use the `metaData` attribute to reconifgure the Reader on the fly. For example:


{
    "count": 3,
    "ok": true,
    "msg": "Users found",
	"users":{
		"COLUMNS":["ID","NAME","EMAIL"],
		"DATA":[
			[1,"Ed Spencer","ed@sencha.com"],
			[2,"Abe Elias","abe@sencha.com"],
			[3,"Cutter","no@address.giv"]
		]
	},
    "metaData": {
        "root": "users",
        "idProperty": 'id',
        "totalProperty": 'count',
        "successProperty": 'ok',
        "messageProperty": 'msg'
    }
}

You can also place any other arbitrary data you need into the `metaData` attribute which will be ignored by the Reader, but will be accessible via the Reader's metaData property (which is also passed to listeners via the Proxy's metachange event (also relayed by the store). Application code can then process the passed metadata in any way it chooses.

A simple example for how this can be used would be customizing the fields for a Model that is bound to a grid. By passing the `fields` property the Model will be automatically updated by the Reader internally, but that change will not be reflected automatically in the grid unless you also update the column configuration. You could do this manually, or you could simply pass a standard grid column config object as part of the `metaData` attribute and then pass that along to the grid. Here's a very simple example for how that could be accomplished:


// response format:
{
    ...
    "metaData": {
        "fields": [
            { "name": "userId", "type": "int" },
            { "name": "name", "type": "string" },
            { "name": "birthday", "type": "date", "dateFormat": "Y-j-m" },
        ],
        "columns": [
            { "text": "User ID", "dataIndex": "userId", "width": 40 },
            { "text": "User Name", "dataIndex": "name", "flex": 1 },
            { "text": "Birthday", "dataIndex": "birthday", "flex": 1, "format": 'Y-j-m', "xtype": "datecolumn" }
        ]
    }
}

The Reader will automatically read the meta fields config and rebuild the Model based on the new fields, but to handle the new column configuration you would need to handle the metadata within the application code. This is done simply enough by handling the metachange event on either the store or the proxy, e.g.:


var store = Ext.create('Ext.data.Store', {
    ...
    listeners: {
        'metachange': function(store, meta) {
            myGrid.reconfigure(store, meta.columns);
        }
    }
});