If you're doing any sort of Ajax development, then you undoubtedly already are quite familiar with the different ways you can use an Ajax call. For instance, you can have the call return a fragment of fully formed html (such as a table populated with data). For a more advanced user, you may have your Ajax calls returning raw data in the form of JSON or XML and parse it on the client side. In either case, though, your single Ajax call is returning a single value. But what if you want several different discrete pieces of "stuff" returned in a single call? You could get creative, and do something such as this in your backend code:
<cfsetting enablecfoutputonly="true" />
<cfscript>
stReturnData = structnew();
stReturnData.htmlBlob = "<table><tr><td>bla bla bla</td></tr></table>";
stReturnData.statistics = structnew();
stReturnData.statistics.recordcount = 212;
stReturnData.statistics.redWidgets = 32;
stReturnData.statistics.blueWidgets = 54;
stReturnData.someQuery = qryIRanPriorToThis;
returnVal = serializeJSON(stReturnData);
</cfscript>
<cfoutput>#returnVal#</cfoutput>
The above would work perfectly fine. It would, however, require that you be willing to write some serious Javascript to access the individual pieces of data, and compels you to have to visualize how the data sets are structured and nested as a whole.
Again, nothing wrong with doing something like the above. But, when I find myself wanting to return more than one value with a single Ajax call, more often than not I will approach it by leveraging response headers.
Response headers are like the saddle bags on a Harley. If your Ajax response is the Harley, then the burley tatted dude (or dudette) riding it is your primary response value. This Harley, however, comes equipped with a pre-defined set of saddle bags that contain what I'm calling "peripheral" information, or metadata about the response, AND (this is most critical), the ability for you to add your own custom saddle bags before the response comes riding home to its caller!
I have never had a need to even look at or care about those pre-canned response headers. They contain name value pairs such as "Transfer-encoding:chunked", "content-type:text-html", "Date: Tue, 16 Mar 2010 15:43:35 GMT", and a couple of others. But, in order to satisfy needs such as I described above in the code sample, I DO add my own response headers and stuff them with values my Javascript needs.
Doing this in Coldfusion is very simple and easy (as are most tasks). Re-doing the example above, then, I'm going to choose one of the values to be my burley tatted rider (typically the value consuming the most bytes), and designate the rest to response headers, like so:
<cfsetting enablecfoutputonly="true" />
<cfset ReturnData = "<table><tr><td>bla bla bla</td></tr></table>" />
<cfheader name="recordcount" value="212" />
<cfheader name="redWidgets" value="32" />
<cfheader name="blueWidgets" value="54" />
<cfheader name="someQuery" value="#serializeJSON(qryIRanPriorToThis,true)#" />
<cfoutput>#ReturnData#</cfoutput>
So now my Harley has several new, custom saddle bags attached, each containing the value I set in the "value" attribute of the cfheader tag, and my main rider, or the actual response value is my ReturnData (the blob of html).
Let's look at the Javascript needed to utilize this response. In this example we are going to use the Prototype library to create a new Ajax Updater. Updaters simplify the task of making an Ajax call and stuffing the response value directly into a target element. So let's say we have a div with an ID 'dataDiv' that will hold a table of data. The Ajax updater line will look like this:
Now, the line above deals exclusively with the response value and ignores anything to do with the response headers. In order to access those headers, we have to tell our Updater to pass its response (Harley, rider, saddlebags, and all) to a function that we designate. This is called "using a callback function", and our line of code will now look like this:
The Updater will update its target div with the response value, then hand the Harley off to the processSaddlebags function, which will look something like this:
function processSaddlebags(ajaxResponse){
//let's set each of our response header values to a local variable...
var recordcount = ajaxResponse.getHeader('recordcount');
var redWidgets = ajaxResponse.getHeader('redWidgets');
var blueWidgets = ajaxResponse.getHeader('blueWidgets');
var objQuery = ajaxResponse.getHeader('someQuery');
//now we can do 'stuff' with these values!
alert('total number of records in our query: ' + objQuery['ROWCOUNT']);
//etc....
}
It should be noted at this point that a most MAHVELOUS way for you to get a clearer picture of what is happening when your code makes Ajax calls is to use the Firefox browser with the Firebug plugin. By doing this simple thing, Firebug will provide you with all the details of every Ajax call you make. Here's a screenshot of a sample Ajax call and the kinds of info you get back (notice the custom header 'total' that I added, and the fact that I'm outputting that value in the html as the "Total Records" value):
response headers
response value
Now, all that having been said, there are size limitations to the usage of response headers that you should keep in mind. I could not find a specific reference that talked about the size limit of response headers, but I did do some experimentation to try and approximate what that limit is. I stuffed as many characters as I could into a response header, and the value was truncated at 6,653 characters (including spaces). I created two custom headers with the same 6,653 characters in it, and both were returned, so I'm assuming the limitation is per header (though common sense tells me there is probably a cumulative maximum size as well). Knowing that there IS a limit, my recommendation is that you use headers for smaller pieces of data and never to convey something as large as a JSON data set unless you know that it will be limited in size.
That's it boys and girls! Now go out there and leverage those response headers!
