ColdFusion 7, Spry 1.6, and JSON - A Beginner's Tutorial
Introduction
Spry now supports the JavaScript Object Notation (JSON) data format. You can use ColdFusion to generate JSON formatted data that can be used by Spry. One advantage of using the JSON data format over XML is the JSON format enables a smaller file size and quicker processing (see references 1 and 2). I wanted to test using JSON formatted data instead of XML with a project I was working on so I researched how to use ColdFusion to create JSON formatted data and use that data with Spry. This post provides a step-by-step tutorial to create a very simple example of using JSON formatted data with Spry.
Step 1: Get Your Backend Working
I first created a ColdFusion file that queries one of my databases and return the submission id numbers and titles of presentations for a specific conference. I tested this CFM page to ensure it was working correctly before modifying it to output a JSON data set.
Step 2: Use CFJSON
I downloaded CFJSON (see reference 5) into my project folder. CFJSON provides "services to encode CF variables (except cfcs) to JSON strings and vice versa." CFJSON has a encode method that I can pass my query result object into and receive back the query results in the JSON format. Below is the code for the CFM page that gets the data from the database, uses CFJSON to format the query results into JSON, and output it.
<cfprocessingdirective suppresswhitespace="yes">
<cfquery name="qrySubmissions" datasource="">
select submissionID, pres_title
from submissions
where accepted = 1
and cancelled = 0
and rejected = 0
and confid = <cfqueryparam cfsqltype="cf_sql_integer" value="148">
order by pres_title
</cfquery>
<cfset aCFJSON = createObject("component", "CFJSON") />
<cfset subJSON = aCFJSON.encode(qrySubmissions) />
</cfprocessingdirective>
<cfcontent type="application/JSON" reset="yes" />
<cfoutput>
#subJSON#
</cfoutput>
Note that initially I tried to have a CFC function return the JSON formatted data, but I could not get that to work. No matter what function return type I used (string, any, binary) I could not get Spry to accept the value returned by the CFC as a JSON data set. Please comment if you know how to use a CFC function to return JSON formatted data to Spry using either CF 7 or 8.
Step 3: Use Spry To Process The JSON Data
Get the latest version of Spry by visiting reference 6. To use JSON formatted data with Spry you need to include two Spry files: SpryJSONDataSet.js and SpryData.js. Then you can use a statement like the one below to create a JSON data set.
var dsPresentations = new Spry.Data.JSONDataSet("jsonData.cfm",
{path:"data", pathIsObjectOfArrays: true});
The first argument is the CFM page that returns JSON formatted data. The second argument is the descriptor of the path to the data (eg, data) and that the data is an object of arrays. This second argument allows Spry to recognize the JSON data as it was formatted by the CFJSON encode function. See reference 2 for more information about using the pathIsObjectOfArrays argument.
Step 4: Display the JSON Data Using Spry
Once you have the JSON data correctly loaded in your page by using the above code, you can use the usual Spry attributes (eg, spry:region, spry:repeat) to display the data.
You can view a working example of this tutorial here. You can view source on that web page to see how the JSON data set was created and how the data was displayed.
Issues
I already mentioned the issue with trying to return JSON formatted data from a CFC function. I could not get that to work. I know that ColdFusion 8 does have the cfsprydataset tag that can be used to create JSON formatted data.
If you examine the data displayed on the working example, you'll see some strange characters. These characters are caused by "smart quotes" and other symbols that could not be correctly included in the JSON formatted data. In XML, I can use the CDATA section to prevent the XML parser from trying to interpret these characters. I could not figure out how to do something similar when creating the JSON formatted data. Thus if your data includes special characters, the JSON format may not work.
Summary
Using the JSON format with Spry to display dynamic data does have some advantages over XML. The file size of JSON formatted data is smaller than the same data formatted using XML. Also, Spry (JavaScript) is able to process faster JSON formatted data then XML. However, you must be careful that your data can be properly parsed into the JSON format and then redisplayed using Spry.
1) In CF7, all CFC methods return WDDX, unless returnType=xml, in which case your return data will be XML. There is no way to return a JSON string that isn't WDDX-wrapped.
2) In CF8, JSON support is built in. If you pass returnFormat=json to the CFC method, not only will CF handle converting your stuff to JSON, it will return a simple JSON string that will work in Spry. You also need to use queryFormat as well. I did a post on this on my blog, but don't have the URL handy right now.
http://www.coldfusionjedi.com/index.cfm/2007/10/3/...
The code download for the above entry includes an example of how to use a CFC function in CF 8 to return JSON formatted data. See the dynamic4 example in Ray's code download.
I also found this reference about ColdFusion 8's ability to return JSON formatted data in the ColdFusion 8 developer's guide here:
http://livedocs.adobe.com/coldfusion/8/htmldocs/aj...
As Ray's blog entry points out (but took me a little while to understand):
1. Your CFC function can have a return type of query and just be a call to a database using cfquery and return the query result.
2. When you create your JSON data set using Spry, you provide values for returnformat (JSON) and queryformat (column) and ColdFusion 8 will automatically convert the query results returned by your CFC function into JSON formatted data. YOU DON'T HAVE TO MODIFY YOUR CFC FUNCTION.
See Ray's blog entry for how to create a JSON data set using these extra values to force the conversion of the query result to JSON formatted data.