Usage
This function
is useful for generating JSON format data to be consumed by an Ajax
application.
The SerializeJSON function converts
ColdFusion dates and times into strings that can be easily parsed
by the JavaScript Date object. The strings have the
following format:
MonthName, DayNumber Year Hours:Minutes:Seconds
The SerializeJSON function
converts the ColdFusion date time object for October 3, 2007 at
3:01 PM, for example, into the JSON string “October, 03 2007 15:01:00”.
The SerializeJSON function
with a falseserializeQueryByColumns parameter
(the default) converts a ColdFusion query into a row-oriented JSON Object
with the following elements:
Element
|
Description
|
|---|
COLUMNS
|
An array of the names of the columns.
|
DATA
|
A two-dimensional array, where:
Each entry in the outer array corresponds to a row of query
data.
Each entry in the inner arrays is a column field value in
the row, in the same order as the COLUMNS array
entries.
|
For example, the SerializeJSON function
with a serializeQueryByColumns parameter value
of false converts a ColdFusion query with two columns,
City, and State, and two rows of data into following format:
{"COLUMNS":["CITY","STATE"],"DATA":[["Newton","MA"],["San Jose","CA"]]}
The SerializeJSON function
with a serializeQueryByColumns parameter value
of true converts a ColdFusion query into a column-oriented JSON
Object that is equivalent to the WDDX query representation. The
JSON Object has three elements:
Element
|
Description
|
|---|
ROWCOUNT
|
The number of rows in the query.
|
COLUMNS
|
An array of the names of the columns.
|
DATA
|
An Object with the following:
|
The SerializeJSON function
with a serializeQueryByColumns parameter value
of true converts a ColdFusion query with two columns,
City, and State, and two rows of data into following format:
{"ROWCOUNT":2, "COLUMNS":["CITY","STATE"],"DATA":{"City":["Newton","San Jose"],"State":["MA","CA"]}}
Note: The SerializeJSON function generates
an error if you try to convert binary data into JSON format.
The SerializeJSON function
converts all other ColdFusion data types to the corresponding JSON
types. It converts structures to JSON Objects, arrays to JSON Arrays,
numbers to JSON Numbers, and strings to JSON Strings.
Note: ColdFusion internally represents structure key
names using all-uppercase characters, and, therefore, serializes
the key names to all-uppercase JSON representations. Any JavaScript
that handles JSON representations of ColdFusion structures must
use all-uppercase structure key names, such as CITY or STATE. You
also use the all-uppercase names COLUMNS and DATA as
the keys for the two arrays that represent ColdFusion queries in
JSON format.
Example
This
example creates a JSON-format data feed with simple weather data
for two cities. The data feed is in the form of a JavaScript application
that consists of a single function call that has a JSON Object as
its parameter. The example code does the following:
Creates a query object with two rows of weather data. Each
row has a city, the current temperature, and an array of forecast
structures, with each with the high, low, and weather prediction
for one day. Normally, datasource provides the data; to keep the
example simple, the example uses the same prediction for all cites
and days.
Converts the query to a JSON format string and surrounds
it in a JavaScript function call.
Writes the result to the output.
If you view
this page in your browser, you see the resulting JavaScript function and
JSON parameter. To use the results of this page in an application,
put this file and the example for the DeserializeJSON function
in an appropriate location under your ColdFusion web root, replace
the URL in the DeserializeJSON example code with
the correct URL for this page, and run the DeserializeJSON example.
<!--- Generate a clean feed by suppressing white space and debugging
information. --->
<cfprocessingdirective suppresswhitespace="yes">
<cfsetting showdebugoutput="no">
<!--- Generate the JSON feed as a JavaScript function. --->
<cfcontent type="application/x-javascript">
<cfscript>
// Construct a weather query with information on cities.
// To simplify the code, we use the same weather for all cities and days.
// Normally this information would come from a data source.
weatherQuery = QueryNew("City, Temp, Forecasts");
QueryAddRow(weatherQuery, 2);
theWeather=StructNew();
theWeather.High=73;
theWeather.Low=53;
theWeather.Weather="Partly Cloudy";
weatherArray=ArrayNew(1);
for (i=1; i<=5; i++) weatherArray[i]=theWeather;
querySetCell(weatherQuery, "City", "Newton", 1);
querySetCell(weatherQuery, "Temp", "65", 1);
querySetCell(weatherQuery, "ForeCasts", weatherArray, 1);
querySetCell(weatherQuery, "City", "San Jose", 2);
querySetCell(weatherQuery, "Temp", 75, 2);
querySetCell(weatherQuery, "ForeCasts", weatherArray, 2);
// Convert the query to JSON.
// The SerializeJSON function serializes a ColdFusion query into a JSON
// structure.
theJSON = SerializeJSON(weatherQuery);
// Wrap the JSON object in a JavaScript function call.
// This makes it easy to use it directly in JavaScript.
writeOutput("onLoad( "&theJSON&" )");
</cfscript>
</cfprocessingdirective>
