Description

Converts a JSON (JavaScript Object Notation) string data representation into CFML data, such as a CFML structure or array.

Returns

The data value in ColdFusion format: a structure, array, query, or simple value.

Category

Conversion functions

Syntax

DeserializeJSON(JSONVar[, strictMapping])

See also

IsJSON, SerializeJSON, cfajaxproxy, "Using Ajax Data and Development Features" in the ColdFusion Developer's Guide, http://www.json.org

History

ColdFusion 8: Added this function

Parameters

Usage

This function is useful any time a ColdFusion page receives data as JSON strings. It is useful in ColdFusion applications that use Ajax to represent data on the client browser, and lets you consume on the server JSON format data from the client-side Ajax JavaScript. You can also use it on pages that get data from services that supply data as JavaScript function calls with JSON parameters; the example shows this use case.

The DeserializeJSON function converts each JSON data type directly into the equivalent ColdFusion data type, as follows:

• If the strictMapping parameter is true (the default), all JSON objects become CFML structures.
• If the strictMapping parameter is false, ColdFusion determines if JSON objects represent queries and, if so, converts them to ColdFusion query object. All other JSON objects become ColdFusion structures. The DeserializeJSON function recognizes a JSON structure as a query and converts it properly if the structure uses either of the two query representation formats described in the SerializeJSON reference.
• JSON Arrays, Strings, and Numbers become ColdFusion arrays, strings, and numbers.
• The JSON null value becomes the string null.
• JSON string representations of a dates and times remain strings, but ColdFusion date/time handling code can recognize them as representing dates and times.

Example

This example displays weather information from a JSON-format data feed that is generated by the example for the SerializeJSON function. Similar code might consume data that is exported as a JavaScript page. The feed is in the form of a JavaScript function call where the parameter is a JSON string that contains the feed data. The example does the following operations:

1. Uses a cfhttp tag to get the feed (in the cfhttp.fileContent variable).
2. Strips the function call wrapper from the text.
3. Uses the IsJSON function to check whether the result of the previous step is a valid JSON format string. If it is not, it displays a message and stops processing.
4. If the string is valid JSON text, uses the DeserializeJSON function to convert the string to a ColdFusion variable; in this case, a structure that contains two arrays that represent a ColdFusion query. The first array has the query column names, the second has the query data.
5. Parses the object and displays the contents of its arrays.

To run this example, put this file and the example for the SerializeJSON function in an appropriate location under your ColdFusion web root, replace the URL with the correct URL for the serialization example, and run this page.

<!--- Get the JSON Feed --->
<cfhttp url="http://localhost:8500/My_Stuff/Ajax/Books/CreateJSON_NEW.cfm">

<!--- JSON data is sometimes distributed as a JavaScript function.
     The following REReplace functions strip the function wrapper. --->
<cfset theData=REReplace(cfhttp.FileContent, 
        "^\s*[[:word:]]*\s*\(\s*","")>
<cfset theData=REReplace(theData, "\s*\)\s*$", "")>

<!--- Test to make sure you have JSON data. --->
<cfif !IsJSON(theData)>
    <h3>The URL you requested does not provide valid JSON</h3>
    <cfdump var="#theData#">

<!--- If the data is in JSON format, deserialize it. --->
<cfelse>
    <cfset cfData=DeserializeJSON(theData)>
    <!--- Parse the resulting array or structure and display the data.
             In this case, the data represents a ColdFusion query that has been
             serialized by the SerializeJSON function into a JSON structure with
             two arrays: an array column names, and an array of arrays, 
             where the outer array rows correspond to the query rows, and the
             inner array entries correspond to the column fields in the row. --->
    <!--- First, find the positions of the columns in the data array. --->
    <cfset colList=ArrayToList(cfData.COLUMNS)>
    <cfset cityIdx=ListFind(colList, "City")>
    <cfset tempIdx=ListFind(colList, "Temp")>
    <cfset fcstIdx=ListFind(colList, "Forecasts")>
    <!--- Now iterate through the DATA array and display the data. --->
    <cfoutput>
        <cfloop index="i" from="1" to="#ArrayLen(cfData.DATA)#">
            <h3>#cfData.DATA[i][cityIdx]#</h3>
            Current Temperature: #cfData.DATA[i][tempIdx]#<br><br>
            <b>Forecasts</b><br><br>        
            <cfloop index="j" from="1" to="#ArrayLen(cfData.DATA[i][fcstIdx])#">
                <b>Day #j#</b><br>
                Outlook: #cfData.DATA[i][fcstIdx][j].WEATHER#<br>
                High: #cfData.DATA[i][fcstIdx][j].HIGH#<br>
                Low: #cfData.DATA[i][fcstIdx][j].LOW#<br><br>
            </cfloop>
        </cfloop>
    </cfoutput>
</cfif>