SerializeJSON()

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


	SerializeJSON( var=any, queryFormat=any, useSecureJSONPrefixOrCharset=any, compact=boolean );

Returns: String

Argument	Description	Default
var _{any, required}	edit A CFML data value or variable that represents one. _{Alias: data}
queryFormat _{any, optional}	edit Either a Boolean value that specifies whether to serialize CFML queries by Column, or one of the following formats as a String 'struct' 'row' 'column' _{Alias: serializeQueryByColumns}
useSecureJSONPrefixOrCharset _{any, optional}	edit String characters that cannot be encoded by this charset get escaped, if not set the web charset is used. _{Alias: charset, charsetName, useSecureJSONPrefix}
compact _{boolean, optional}	edit If true, it does not use end-of-lines and indentation. Defaults to true. Also commonly called pretty printing Introduced: 6.0.0.405	No

Usage Notes

edit

Date format

By default serializeJSON writes date/time values in the traditional Lucee format, for example January, 29 2021 11:45:26 +0100.

From Lucee 9.0 you can change this with the setting dateFormat, either per application in the Application.cfc (this.serialization.dateFormat) or for the whole server in the configuration (serialization.dateFormat in .CFConfig.json). A value defined in the Application.cfc overrides the value in the configuration.

Value	Result
`cf` (default)	traditional Lucee format, `January, 29 2021 11:45:26 +0100`
`iso` (or `iso8601`)	ISO 8601, `2021-01-29T11:45:26+01:00`
`isoms` (or `isoMillis`)	ISO 8601 including milliseconds, `2021-01-29T11:45:26.123+01:00`
any other value	used as a custom date/time mask, for example `yyyy-MM-dd HH:mm:ss`

An invalid mask throws an exception.

The date is written in the time zone of the current request (see Application.cfc / <cfapplication> attribute timezone).

The setting only affects serializeJSON. In the format iso, a date in the UTC time zone is written with the offset Z, for example 2021-01-29T10:45:26Z.

The setting can also be defined with the system property lucee.serialization.dateformat or the environment variable LUCEE_SERIALIZATION_DATEFORMAT.

For versions before 9.0, format the dates yourself before you serialize the data, for example with dateTimeFormat( date, "iso8601" ).

Examples

edit

  st = structNew();
  st.id = 1;
  st.Name = "Water";
  st.DESIGNATION = "Important source for all";
  st.data = [1,2,3,4,5];
  json= serializeJSON(st);
  writeDump(json);
  writeDump(deserializeJSON(json));

Query Formats

    q = queryNew(
        "id,name",
        "numeric,varchar",
        {
            id: [1,2,3],
            name: ['Neo','Trinity','Morpheus']
        }
    );
    dump(q);
    dump( var=deserializeJSON( serializeJSON(q) ),
        label="default" );
     dump( var=deserializeJSON( serializeJSON(q, true), false ),
        label="true" );     
    dump( var=deserializeJSON( serializeJSON(q, true) ),
        label='serializeQueryByColumns');
    dump( var=deserializeJSON( serializeJSON(q, 'struct') ),
        label="'struct'" );
    dump( var=deserializeJSON( serializeJSON(q, 'row') ),
        label="'row'" );
    dump( var=deserializeJSON( serializeJSON(q, 'column') ),
        label="'column'" );

Pretty Printing

<cfscript>
    obj = {
        name: "lucee",
        versions: [ 5,6,7 ]
    }
</cfscript>
<cfoutput>
<pre>
<b>Default behavior</b>
#serializeJson(var=obj,compact=true)#
<b>Pretty Print (compact=false)</b>
#serializeJson(var=obj,compact=false)#
</pre>
</cfoutput>

Serializing a CFC's properties to JSON

myCfc = new component {
  property name="foo" type="string";
  property name="bar" type="numeric";
  foo = "hello";
  bar = 42;
};
dump(myCfc); // See CFC object with properties
jsonString = serializeJson(var=myCfc, compact=false);
writeOutput(jsonString); // Output: {"foo":"hello","bar":42}

Date format (Lucee 9.0 and later)

Define the format for dates in the Application.cfc:

component {
	this.name = "myApp";
	this.timezone = "Europe/Zurich";
	// "cf" (default), "iso", "isoms" or a custom mask like "yyyy-MM-dd HH:mm:ss"
	this.serialization.dateFormat = "iso";
}
<div class="highlight"><pre><span></span>
</pre></div>
<br>luceescript
echo( serializeJSON( { "created": createDateTime( 2021, 1, 29, 11, 45, 26 ) } ) );
// {"created":"2021-01-29T11:45:26+01:00"}

Or for all applications in the .CFConfig.json:

{
	"serialization": {
		"dateFormat": "iso"
	}
}