Adobe ColdFusion 8

SerializeJSON

Description

Converts ColdFusion data into a JSON (JavaScript Object Notation) representation of the data.

Returns

A string that contains a JSON representation of the parameter value.

Category

Conversion functions

Syntax

SerializeJSON(var[, serializeQueryByColumns])

See also

DeserializeJSON, IsJSON, cfajaxproxy, "Using data interchange formats" in the ColdFusion Developer's Guide, http://www.json.org

History

ColdFusion 8: Added function

Parameters

Parameter

Description
var

A ColdFusion data value or variable that represents one.
serializeQueryByColumns

A Boolean value that specifies how to serialize ColdFusion queries.

  • false (the default): Creates an object with two entries: an array of column names and an array of row arrays. This format is required by the HTML format cfgrid tag.
  • true: Creates an object that corresponds to WDDX query format.

For more information, see the Usage section.

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 false serializeQueryByColumns 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 keys are the query column names
  • The values are arrays that contain the column data

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:

  1. 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. This data would normally be provided by a data source; to keep the example simple, the example uses the same prediction for all cites and days.
  2. Converts the query to a JSON format string and surrounds it in a JavaScript function call.
  3. 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>