Merge pull request #1642 from KamasamaK/serializejson-20240306

Update serialization options

data/en/application-cfc.json

@@ -21,7 +21,7 @@
 		{"name":"this.customTagPaths","description":"CF8+ A comma delimited list of absolute file paths pointing to directories containing custom tags.","required":false,"default":"","type":"string","values":[]},
 		{"name":"this.mappings","description":"CF8+ A structure of application mappings where they key is the mapping and the value is the directory path.","required":false,"default":"","type":"struct","values":[]},
 		{"name":"this.welcomeFileList","description":"CF8+ A comma separated list of file names that will skip onMissingTemplate invocation - typically only necessary if you are using a built-in web server like Tomcat or JRun.","required":false,"default":"","type":"string","values":[]},
-		{"name":"this.serverSideFormValidation","description":"CF9+ Enable\/Disable ColdFusion‚ server side validation on CFFORM.","required":false,"default":"","type":"boolean","values":[true,false]},
+		{"name":"this.serverSideFormValidation","description":"CF9+ Enable\/Disable ColdFusion, server side validation on CFFORM.","required":false,"default":"","type":"boolean","values":[true,false]},
 		{"name":"this.googleMapKey","description":"CF9+ the google maps api when cfmap is used.","required":false,"default":"","type":"string","values":[]},
 		{"name":"this.datasource","description":"CF9+ Defines the default datasource for the application. As of CF9.0.1+ it can also accept a struct with keys: name, username, password.","required":false,"default":"","type":"string","values":[]},
 		{"name":"this.s3","description":"CF9+ A struct with keys accessKeyId, awsSecretKey and defaultLocation.","required":false,"default":"","type":"struct","values":[]},
@@ -52,9 +52,10 @@
 		{"name":"this.datasources","description":"CF11+ This struct of structs is used to define multiple application specific datasources. This value is a structure whose keys are the name of the datasource to be created, and the values are another structure with keys such as: database, driver, host, username, password, url. Lucee / Railo also support this setting, but are configured with keys class, connectionString, username, password.\nCF2021 added MongoDB as a valid datasource type.","required":false,"default":"","type":"struct","values":[]},
 		{"name":"this.serialization.preserveCaseForStructKey","description":"CF11+ Preserves the case of your variable names when generating JSON using the serializeJSON function.","required":false,"default":"false","type":"boolean","values":[]},
 		{"name":"this.serialization.preserveCaseForQueryColumn","description":"CF11.0.5+ Preserves the case of your query column names when generating JSON using the serializeJSON function.","required":false,"default":"false","type":"boolean","values":[]},
+		{"name":"this.serialization.serializeQueryAs","description":"CF11+ Sets the default method for serializing a query.","required":false,"default":"row","type":"string","values":["row","column","struct"]},
 		{"name":"this.customSerializer","description":"CF11+ The name of a CFC pointing to a custom serializer. See https://helpx.adobe.com/coldfusion/developing-applications/changes-in-coldfusion/restful-web-services-in-coldfusion.html","required":false,"default":"","type":"numeric","values":[]},
 		{"name":"this.locale","description":"Lucee4+ The default locale used for formatting dates, numbers.","required":false,"default":"en_US","type":"string","values":[]},
-		{"name":"this.timezone","description":"Lucee4+ ACF2021+ The default timezone used for date handling.","required":false,"default":"","type":"string","values":["America/Chicago","America/New_York","UTC"]},
+		{"name":"this.timezone","description":"Lucee4+ CF2021+ The default timezone used for date handling.","required":false,"default":"","type":"string","values":["America/Chicago","America/New_York","UTC"]},
 		{"name":"this.sessionType","description":"Lucee4+ Use CFML or JEE based sessions.","required":false,"default":"","type":"string","values":["cfml","jee"]},
 		{"name":"this.sessionStorage","description":"Lucee4+ The name of the storage provider for session variables.","required":false,"default":"memory","type":"string","values":[]},
 		{"name":"this.localMode","description":"Lucee4+ Defines how the local scope of a function is invoked when a variable with no scope definition is used. When classic the local scope is only invoked when the key already exists in it, with modern the local scope is always assumed on unscoped variables.","required":false,"default":"classic","type":"string","values":["classic", "modern"]},

data/en/serialize.json

@@ -1,14 +1,14 @@
 {
 	"name":"serialize",
 	"type":"function",
-	"syntax":"serialize( objToBeSerialized, type, useCustomSerializer );",
+	"syntax":"serialize( object, type, useCustomSerializer )",
 	"returns":"string",
 	"related":["deserialize"],
 	"description":"Serializes the object to a specified type",
 	"params": [
-		{"name":"objToBeSerialized","description":"An object to be serialized.","required":true,"default":"","type":"any","values":[]},
-       		{"name":"type","description":"CF11+ A type to which the object will be serialized. ColdFusion, by default supports XML and JSON formats. You can also implement support for other types in the CustomSerializer CFC.","required":true,"default":"","type":"string","values":[]},
-        	{"name":"useCustomSerializer","description":"CF11+ Whether to use the custom serializer or not. The custom serializer will be always used for XML deserialization.\nIf false, the XML/JSON deserialization will be done using the default ColdFusion behavior.\nIf any other type is passed with useCustomSerializer as false, then TypeNotSupportedException will be thrown.","required":true,"default":"true","type":"boolean","values":[]}
+		{"name":"object","description":"An object to be serialized.","required":true,"default":"","type":"any","values":[]},
+		{"name":"type","description":"A type to which the object will be serialized. ColdFusion, by default supports XML and JSON formats. You can also implement support for other types in the CustomSerializer CFC.","required":true,"default":"","type":"string","values":[]},
+		{"name":"useCustomSerializer","description":"Whether to use the custom serializer or not. The custom serializer will be always used for XML deserialization.\nIf false, the XML/JSON deserialization will be done using the default ColdFusion behavior.\nIf any other type is passed with useCustomSerializer as false, then TypeNotSupportedException will be thrown.","required":false,"default":true,"type":"boolean","values":[]}
 	],
 	"engines": {
 		"coldfusion": {"minimum_version":"11", "notes":"", "docs":"https://helpx.adobe.com/coldfusion/cfml-reference/coldfusion-functions/functions-s/serialize.html"},
@@ -17,16 +17,16 @@
 	},
 	"links": [],
 	"examples": [
-        	{
-			"title": "Script Syntax",
-			"description": "Lucee5+ This function will serialize the object to a specified type using ColdFusion's default serialization mechanism.",
+		{
+			"title": "Serialize with Lucee's default serializer (Script syntax)",
+			"description": "Lucee5+ This will serialize the object using the default serialization mechanism.",
 			"code": "serialize({ \"firstName\": \"John\", \"lastName\": \"Doe\" });",
 			"runnable": true,
 			"result": "{\"lastName\":\"Doe\",\"firstName\":\"John\"}"
-		}, 
-        	{
-			"title": "Script Syntax",
-			"description": "CF11+ This function will serialize the object to a specified type using ColdFusion's default serialization mechanism.",
+		},
+		{
+			"title": "Serialize to JSON (Script syntax)",
+			"description": "This will serialize the object to JSON using ColdFusion's default serialization mechanism.",
 			"code": "serialize({ \"firstName\": \"John\", \"lastName\": \"Doe\" }, 'json');",
 			"runnable": true,
 			"result": "{\"lastName\":\"Doe\",\"firstName\":\"John\"}"

data/en/serializejson.json

@@ -1,19 +1,19 @@
 {
 	"name":"serializeJSON",
 	"type":"function",
-	"syntax":"serializeJSON(var[, serializeQueryByColumns[, useSecureJSONPrefix[, useCustomSerializer]]])",
-	"member":"someVar.toJSON([serializeQueryByColumns[, useSecureJSONPrefix[, useCustomSerializer]]])",
+	"syntax":"serializeJSON(data[, queryFormat[, useSecureJSONPrefix[, useCustomSerializer]]])",
+	"member":"someVar.toJSON([queryFormat[, useSecureJSONPrefix[, useCustomSerializer]]])",
 	"returns":"string",
-	"related":["deserializeJSON", "structSetMetadata"],
-	"description":"Converts a ColdFusion variable into a JSON (JavaScript Object Notation) string.",
+	"related":["deserializeJSON", "structSetMetadata", "arraySetMetadata"],
+	"description":"Converts a ColdFusion value into a JSON (JavaScript Object Notation) string.",
 	"params": [
-		{"name":"var","description":"A ColdFusion variable.","required":true,"default":"","type":"variableName","values":[]},
-		{"name":"serializeQueryByColumns","description":"A Boolean value that specifies how to serialize ColdFusion queries.","required":false,"default":"false","type":"boolean","values":[]},
+		{"name":"data","description":"A serializable ColdFusion data value","required":true,"default":"","type":"any","values":[]},
+		{"name":"queryFormat","description":"This specifies how to serialize ColdFusion queries. Prior to CF11+, this would only accept Boolean values. If it is a Boolean, the false value is equivalent to 'row' and true is 'column'.","required":false,"default":"row","type":"any","values":["row","column","struct",false,true]},
 		{"name":"useSecureJSONPrefix","description":"CF11+ When Prefix Serialized JSON is enabled in the ColdFusion Administrator, then by default this function inserts the secure JSON prefix at the beginning of the JSON.","required":false,"default":"false","type":"boolean","values":[]},
 		{"name":"useCustomSerializer","description":"CF11+ Use custom serializer if defined. See: https://helpx.adobe.com/coldfusion/developing-applications/changes-in-coldfusion/restful-web-services-in-coldfusion.html","required":false,"default":"true","type":"boolean","values":[]}
 	],
 	"engines": {
-		"coldfusion": {"minimum_version":"8", "notes":"CF11+ Added Application.cfc setting this.serialization.preserveCaseForStructKey which defaults to true, also added useCustomSerializer argument. Member syntax added for CF2016+.", "docs":"https://helpx.adobe.com/coldfusion/cfml-reference/coldfusion-functions/functions-s/serializejson.html"},
+		"coldfusion": {"minimum_version":"8", "notes":"CF11+ Added `useSecureJSONPrefix` and `useCustomSerializer` arguments. Changed `queryFormat` (formerly known as `serializeQueryByColumns`) from a boolean type to also allowing strings, adding the 'struct' functionality in the process. The default for `queryFormat` can be set using the newly added Application.cfc setting `this.serialization.serializeQueryAs`. Also added Application.cfc settings `this.serialization.preserveCaseForStructKey` and `this.serialization.preserveCaseForQueryColumn`. CF2016+ Added member syntax.", "docs":"https://helpx.adobe.com/coldfusion/cfml-reference/coldfusion-functions/functions-s/serializejson.html"},
 		"lucee": {"minimum_version":"", "notes":"Member syntax added for Lucee5.3.8+", "docs":"https://docs.lucee.org/reference/functions/serializejson.html"},
 		"railo": {"minimum_version":"", "notes":"", "docs":"http://railodocs.org/index.cfm/function/serializejson"},
 		"openbd": {"minimum_version":"", "notes":"", "docs":"http://openbd.org/manual/?/function/serializejson"}
@@ -51,15 +51,21 @@
 		},
 		{
 			"title": "ACF Possible Issues",
-			"description": "Adobe ColdFusion may incorrectly serializes some strings if they can be automatically converted into other types, like numbers or booleans. One workaround is to use a CFC with cfproperty to specify types. Another workaround is to prepend Chr(2) to the value and it will be forced to a string, however that is an unofficial / undocumented workaround.",
+			"description":"Adobe ColdFusion may incorrectly serializes some strings if they can be automatically converted into other types, like numbers or booleans. One workaround is to use a CFC with cfproperty to specify types. Another workaround is to prepend chr(2) to the value and it will be forced to a string, however that is an unofficial / undocumented workaround.",
 			"code":"person = { \"phone\"=\"123456789\", \"firstname\"=\"no\",\"lastname\"=\"yes\" };\nwriteOutput( serializeJson(person) );",
 			"result": "{\"phone\":123456789,\"firstname\":false,\"lastname\":true}"
 		},
 		{
 			"title":"Using setMetadata to force types",
-			"description":"As of CF2016.0.2+ (update 2) you can call `setMetadata()` as a member function on a struct to force a type",
+			"description":"As of CF2016.0.2+ you can call `setMetadata()` as a member function on a struct to force a type",
 			"code":"myStruct = {\"zip\"=\"00123\"};\nmyStruct.setMetadata( { \"zip\": \"string\" } );\nwriteOutput(serializeJSON(myStruct));",
 			"result": "{\"zip\":\"00123\"}"
+		},
+		{
+			"title":"Serialize a Query as an array of structs",
+			"description":"Serialize a CF Query into a JSON representation of an array of structs",
+			"code":"news = queryNew(\"id,title\",\n    \"integer,varchar\",\n    [ {\"id\":1,\"title\":\"Dewey defeats Truman\"}, {\"id\":2,\"title\":\"Man walks on Moon\"} ]);\nwriteOutput(serializeJSON(news, \"struct\"));",
+			"result": "[{\"ID\":1,\"TITLE\":\"Dewey defeats Truman\"},{\"ID\":2,\"TITLE\":\"Man walks on Moon\"}]"
 		}
 	]
 }

data/en/serializexml.json

@@ -1,24 +1,24 @@
 {
 	"name":"serializeXML",
 	"type":"function",
-	"syntax":"serializeXML( Object objToBeSerialized, boolean useCustomSerializer );",
+	"syntax":"serializeXML( objToBeSerialized, useCustomSerializer )",
 	"returns":"string",
 	"related":["xmlParse","xmlNew","deserializeXML","isXMLDoc","encodeForXML"],
-	"description":"Serializes a ColdFusion object to XML.",
+	"description":"Serializes the given object to XML.",
 	"params": [
 		{"name":"objToBeSerialized","description":"An object to be serialized.","required":true,"default":"","type":"any","values":[]},
-        	{"name":"useCustomSerializer","description":"Boolean. Whether to use the custom serializer or not. The default value is true. The custom serializer will be always used for XML deserialization. If false, the XML/JSON deserialization will be done using the default ColdFusion behavior. If any other type is passed with useCustomSerializer as false, then TypeNotSupportedException will be thrown.","required":true,"default":"","type":"boolean","values":[]}
+		{"name":"useCustomSerializer","description":"Whether to use the custom serializer. The default value is true. The custom serializer will be always used for XML deserialization. If false, the XML/JSON deserialization will be done using the default ColdFusion behavior. If any other type is passed with useCustomSerializer as false, then TypeNotSupportedException will be thrown.","required":false,"default":true,"type":"boolean","values":[]}
 	],
 	"engines": {
 		"coldfusion": {"minimum_version":"11", "notes":"", "docs":"https://helpx.adobe.com/coldfusion/cfml-reference/coldfusion-functions/functions-s/serializexml.html"}
 	},
 	"links": [],
 	"examples": [
-        	{
-			"title": "Tag Syntax",
-			"description": "serializeXML is a new function added in ColdFusion 11. This function will serialize the object to XML using ColdFusion's default serialization mechanism.",
-			"code": "... <cfreturn serializeXML(arguments.arg)> \r\n",
-			"result": ""
+	{
+			"title": "Serialize a struct to XML (Script syntax)",
+			"description": "This will serialize the object to XML using ColdFusion's default serialization mechanism.",
+			"code": "serializeXML({ \"firstName\": \"John\", \"lastName\": \"Doe\" })",
+			"result": "<STRUCT ID=\"1\"><ENTRY NAME=\"lastName\" TYPE=\"STRING\">Doe<\/ENTRY><ENTRY NAME=\"firstName\" TYPE=\"STRING\">John<\/ENTRY><\/STRUCT>"
 		}
 	]
 }