API to customize the JSON output

The return value from json() supports several methods to customize the generated output. Methods can be chained and combined in arbitrary order.

Entry points into the API are:

• de.espirit.firstspirit.generate.functions.json
• de.espirit.firstspirit.json

set

Replacing or adding of keys in a json object is possible by calling

json(..).set(key, value)

Example 1:

$CMS_VALUE(json({"example": "value"}).set("additional_key", "additional_value"))$

Result:

{"additional_key":"additional_value","example":"value"}

Example 2:

$CMS_VALUE(json({"example": "value"}).set("a", "A").set("a", "B"))$

Result:

{"a":"B","example":"value"}

Even though the JSON specification allows duplicate entries in a JSON object (two entries with the same key), the FirstSpirit JSON solution does not support this. So adding an entry with an existing key will replace the former entry.

get

With .get() you can access the values of a JSON object’s fields. Here’s a more complex example:

1) Store a section’s JSON representation in the variable jsonObject:

$CMS_SET(jsonObject, json(#this))$

2) Add a new string value to the jsonObject’s data field:

$CMS_SET(void, jsonObject.get("data").set("anotherString","anotherValue"))$

3) Print the modified jsonObject:

$CMS_VALUE(jsonObject)

Result:

{
       "fsType": "Section", 
        "name": "filter", 
        "identifier": "filter", 
        "formData": {
            "anotherString": "anotherValue",
            [...]
        }
}

You can achieve the same modification with the following two lines of template code:

$CMS_SET(set_data, json(#this).get("data").set("anotherString","anotherValue"))$
$CMS_VALUE(json(#this).set("data",set_data))$

removeKey

Remove a key from a json object with the function removeKey.

Example 1:

$CMS_VALUE(json({"example": "value"}))$

Result:

{"example":"value"}

Example 2:

$CMS_VALUE(json({"example": "value"}).removeKey("example"))$

Result:

{}

mapKeys

To modify key names use the function mapKeys.

Example 1:

$CMS_SET(example, {"example": "value", "recursion": {"example2": "value2"}})$
$CMS_VALUE(json(example).mapKeys(key -> key.toUpperCase))$

Result:

{"EXAMPLE":"value","RECURSION":{"EXAMPLE2":"value2"}}

Example 2:

$CMS_VALUE(json(example)	.mapKeys(key -> if(key.startsWith("ex"), "s" + key.substring(2), key)))$

Result:

{"recursion":{"sample2":"value2"},"sample":"value"}

These examples do not actually modify the example object, they only create modified output.

But of course you could also override example with this modified output:

$CMS_SET(example,json(example).mapKeys(key -> key.toUpperCase))$

filter

To filter json object entries according to a predicate use the filter function.

Example 1:

$CMS_SET(example, {"example": "value", "recursion": {"example2": "value2"})$
$CMS_VALUE(json(example))$

Result:

{ "example": "value","recursion":{"example2":"value2"}}

Example 2:

$CMS_VALUE(json(example).filter(entry -> ! entry.key.startsWith("ex")))$

Result:

{"recursion":{}}

Example 3:

$CMS_SET(example2, {"example3": null, "recursion2": { "example4": null }})$
$CMS_VALUE(json(example2))$

Result:

{"example3":null,"recursion":{"example4":null}}

Example 4:

$CMS_VALUE(json(example2).filter(entry -> entry.value != null))$

Result:

{"recursion2":{}}