Whatever message this page gives is out now! Go check it out!
Using data interchange formats
Last update:
May 18, 2026
All complex data that is communicated over an HTTP connection must be serialized into a string representation that can be transmitted over the web. Most commonly, web client applications use XML or JSON.
As a general rule, ColdFusion automatically handles all necessary serialization and deserialization when you use ColdFusion Ajax features. The proxies that you create with the cfajaxproxy tag, and the bind expressions that call CFC functions automatically request data in JSON format, and automatically deserialize JSON data to JavaScript variables.
ColdFusion also provides the capability to create, convert, and manage data in web interchange formats. This is helpful, for example, if you use custom Ajax elements to get data from ColdFusion servers.
Also, you use ColdFusion data serialization capability for any applications that create or consume complex data transmitted over an HTTP connection. For example, if you want to make a web service or feed available in JSON format, many Yahoo! web services currently are accessible by using simple URLS that return data as JSON.
As a general rule, ColdFusion automatically handles all necessary serialization and deserialization when you use ColdFusion Ajax features. The proxies that you create with the cfajaxproxy tag, and the bind expressions that call CFC functions automatically request data in JSON format, and automatically deserialize JSON data to JavaScript variables.
ColdFusion also provides the capability to create, convert, and manage data in web interchange formats. This is helpful, for example, if you use custom Ajax elements to get data from ColdFusion servers.
Also, you use ColdFusion data serialization capability for any applications that create or consume complex data transmitted over an HTTP connection. For example, if you want to make a web service or feed available in JSON format, many Yahoo! web services currently are accessible by using simple URLS that return data as JSON.
Note: For information on ColdFusion tags and functions for handling XML or WDDX data, see Using XML and WDDX.
Controlling CFC remote return value data format
By default, CFC functions convert data that they return to remote callers to WDDX format. However, they can also return the data in JSON format, or as plain string data. (XML objects are automatically converted to string representation when returning plain data.)
ColdFusion Ajax elements that request data from CFC functions, including bind expressions and the function proxies generated by the cfajaxproxy tag, automatically generate a returnFormat parameter in the HTTP URL to request JSON data from the CFC function.
Control the CFC function return format in the following ways:
ColdFusion Ajax elements that request data from CFC functions, including bind expressions and the function proxies generated by the cfajaxproxy tag, automatically generate a returnFormat parameter in the HTTP URL to request JSON data from the CFC function.
Control the CFC function return format in the following ways:
- Use the returnFormat attribute on the cffunction tag.
- Set a returnFormat parameter in the HTTP request that calls the CFC function.
- Use the CFC proxy setReturnFormat function. (You do this only if your client-side code requires non-JSON format data, for example, XML or WDDX.) If the requested return format is JSON and the function returns a query, ColdFusion serializes the query into a JSON object in either of the following formats:
- As a JSON object with two entries: an array of column names, and an array of column data arrays.These entries are returned in the following situations:
- By default
- If you specify an HTTP URL parameter of queryFormat="row"
- If you use the cfajaxproxy tag and call the proxy object's setReturnFormat function with a parameter value of row ColdFusion client-side binding and proxy code automatically converts this data into JavaScript that is consumed directly by HTML grids.
- As a JSON object with three entries: the number of rows, an array of column names, and an object where each key is a column name and each value is an array with the column dataThese entries are returned in the following situations:
- If you specify an HTTP URL parameter of queryFormat="column"
- If you use the cfajaxproxy tag and call the proxy object's setQueryFormat function with a parameter value of column ColdFusion client-side binding and proxy code does not convert column format data into JavaScript that is consumed directly by HTML grids. However, use this format with the cfajaxproxy tag, because you can refer to the returned data by using the column names directly. For example, if a CFC function returns a query with user data, you get the user names in your JavaScript by specifying values such as userData.firstName0 and userData.lastName0. For more information, see the SerializeJSON function in the CFML Reference.
Using JSON
JSON (JavaScript Object Notation) is a lightweight JavaScript-based data interchange format for transmission between computer systems. It is a much simpler format than XML or WDDX, and is an efficient, compact format for transmitting data required for Ajax applications. ColdFusion Ajax bind expressions that use CFCs tell the CFC function to send the data in JSON format by including a returnformat="json" parameter in the HTTP request, and automatically handle the JSON-formatted result.
JSON represents objects by using { key: value, key: value... } notation, and represents arrays in standard [_ value_ , value... ] notation. Values can be strings, numbers, objects, arrays, true, false, or null. Therefore, you can nest arrays and objects inside each other. For a detailed specification of the JSON format, see www.JSON.org.
Although ColdFusion Ajax-based controls and the cffunction tag interoperate transparently, without you converting anything to JSON format, other applications can take advantage of JSON format data. Many public feeds are now available in JSON format. For example, the Yahoo! search interface returns a JSON data set, del.icio.us provides JSON feeds showing your posts and tags, and Blogger feeds are available in JSON format. You don't have to use Ajax to display these feeds; use standard ColdFusion tags and functions to display the results.
The following CFML functions support using JSON format in server-side code:
JSON represents objects by using { key: value, key: value... } notation, and represents arrays in standard [_ value_ , value... ] notation. Values can be strings, numbers, objects, arrays, true, false, or null. Therefore, you can nest arrays and objects inside each other. For a detailed specification of the JSON format, see www.JSON.org.
Although ColdFusion Ajax-based controls and the cffunction tag interoperate transparently, without you converting anything to JSON format, other applications can take advantage of JSON format data. Many public feeds are now available in JSON format. For example, the Yahoo! search interface returns a JSON data set, del.icio.us provides JSON feeds showing your posts and tags, and Blogger feeds are available in JSON format. You don't have to use Ajax to display these feeds; use standard ColdFusion tags and functions to display the results.
The following CFML functions support using JSON format in server-side code:
- DeserializeJSON
- SerializeJSON
- IsJSON For more information about these functions and examples, see the CFML Reference. The following example shows how to use ColdFusion JSON functions in a non-Ajax application. It does a Yahoo search for references to "ColdFusion Ajax" and displays these results:
- The total number of web pages found
- The titles and summaries of the (by default 10) returned results. The title is a link to the web pageURL.
<!--- Send an http request to the Yahoo Web Search Service. --->
<cfhttp
url='http://api.search.yahoo.com/WebSearchService/V1/webSearch?appid=YahooDemo&query=
"ColdFusion Ajax"&output=json'>
<!--- The result is a JSON-formatted string that represents a structure.
Convert it to a ColdFusion structure. --->
<cfset myJSON=DeserializeJSON(#cfhttp.FileContent#)>
<!--- Display the results. --->
<cfoutput>
<h1>Results of search for "ColdFusion 9"</h1>
<p>There were #myJSON.ResultSet.totalResultsAvailable# Entries.<br>
Here are the first #myJSON.ResultSet.totalResultsReturned#.</p>
<cfloop index="i" from="1" to="#myJSON.ResultSet.totalResultsReturned#">
<h3><a href="#myJSON.ResultSet.Result[i].URL#">
#myJSON.ResultSet.Result[i].Title#</a></h3>
#myJSON.ResultSet.Result[i].Summary#
</cfloop>
</cfoutput>Serialization of numeric values
Note: To use this feature, you must install ColdFusion 9 Update 1.
In the previous releases (including ColdFusion 9), serializing an integer using serializeJSON, converts the number to a double. For example, SerializeJSON (123) returns 123.0.
In ColdFusion 9.0.1, the integer is retained in its original format but enclosed within quotes. That is, SerializeJSON (123) returns "123". This is applicable only to positive integers.
The following table gives more examples:
In ColdFusion 9.0.1, the integer is retained in its original format but enclosed within quotes. That is, SerializeJSON (123) returns "123". This is applicable only to positive integers.
The following table gives more examples:
Input | Serialized JSON |
10 | "10" |
012 | "012" |
10.25 | "10.25" |
10.25E5 | "1025000.0" |
10.25E-5 | "1.025E-4" |
-10 | "-10.0" |
-10.25 | "-10.25" |
Note: To remove the quotes in the returned value, for positive integers and integers within quotes, set the jvm argument json.numberasdouble to true . However, negative integers such as -10 will still be serialized to "-10.0" even if json.numberasdouble=true.
Ajax plumbing enhancement in ColdFusion 9.0.1
ORM CFCs support the attribute remotingfetch for a property.
By default, remotingfetch is set to false.
While serializing ORM CFCs, ColdFusion introspects the remotingfetch property and if it is false, does not return any relationship information.
If it is set to true, relationship information is shown. If circular reference is detected, only one level of relationship is shown.
By default, remotingfetch is set to false.
While serializing ORM CFCs, ColdFusion introspects the remotingfetch property and if it is false, does not return any relationship information.
If it is set to true, relationship information is shown. If circular reference is detected, only one level of relationship is shown.
We're glad. Tell us how this page helped.
We're sorry. Can you tell us what didn't work for you?
Share additional feedback to help us improve.
0/255
|
