JSON function: Configuring JSON output of metadata
| Contents |
Metadata is additional information that is available for an object in FirstSpirit. In addition to system-specific metadata, such as “last change date”), project-specific metadata can be maintained as well.
Project-specific metadata is defined via a metadata template (see Options (→Documentation for Administrators)) for the project and can then be maintained on the corresponding FirstSpirit objects (e.g., on a page or page reference) on the “Metadata” register via a form. Some of this project-specific metadata is maintained hierarchically. This means the metadata is maintained on the root node of the store or a subtree and then automatically passed on to all hierarchically subordinate FirstSpirit objects (e.g., with the definition of user rights via the CMS_INPUT_PERMISSION input component).
See also
Metadata can be transferred to a JSON object structure. The JSON output format thereby considers the persistent metadata on the respective FirstSpirit object (pages, page references, media) at the time of generation. The output then contains the metaFormData attribute (see example).
A special case is the JSON output of user rights that were defined for an object via the CMS_INPUT_PERMISSION input component on the “Metadata” register (see JSON output of user permissions).
Configuration of the JSON output
The JSON output of the metadata can be configured via the JSON function.
The output may also include metadata that was not defined on the object itself but inherited by an hierarchically superordinate object.
metaDataRenderMode
The JSON rendering of metadata can be controlled with the switch.
$CMS_SET(#global.json.metaDataRenderMode, <String>)$
The following values are supported:
- NONE: No metadata will be output.
$CMS_SET(#global.json.metaDataRenderMode, "NONE")$ - IF_DEFINED (default value): The metadata defined for the current element is output.
$CMS_SET(#global.json.metaDataRenderMode, "IF_DEFINED)$ - INHERITED_OR_DEFINED: All metadata is recursively inherited from a store element's parent nodes.
$CMS_SET(#global.json.metaDataRenderMode, "INHERITED_OR_DEFINED")$ - INTELLIGENT: As INHERITED_OR_DEFINED, however, it is avoided that redundant outputs of the metadata occur.
$CMS_SET(#global.json.metaDataRenderMode, "INTELLIGENT")$
The following applies to all metadata on Sections that are inherited from the page (or a higher node):
- Metadata values that are null will not be output.
- Metadata values that have already been output with the same value in the same JSON object will not be output again.
- INTELLIGENT_CAAS: As INTELLIGENT, where inheritance occurs only from the next higher metadata definition point.
$CMS_SET(#global.json.metaDataRenderMode, "INTELLIGENT_CAAS")$
- If metadata is set on a node, no inherited metadata will be output.
- If no metadata is set, the metadata from the next higher metadata definition point will be output.
- All metadata that is not set there will not be inherited from higher nodes.
metadataRendering (deprecated)
 |
Starting from FirstSpirit version , the switch metaDataRenderMode is available. |
The JSON rendering of metadata can be activated or deactivated with the $CMS_SET(#global.json.metaDataRendering, <BOOLEAN>)$ switch.
Default setting: true
$CMS_SET(#global.json.metaDataRendering, true)$
With the $CMS_SET(#global.json.metaDataRendering, true)$ setting (default setting), metadata for all objects is rendered. If no metadata is set, an empty element will be rendered.
$CMS_SET(#global.json.metaDataRendering, false)$
With the $CMS_SET(#global.json.metaDataRendering, false)$ setting, the JSON rendering of metadata is explicitly switched off.
metaInheritanceRendering (deprecated)
|
Starting from FirstSpirit version , the switch metaDataRenderMode is available. |
The JSON rendering of inherited metadata can be activated or deactivated with the $CMS_SET(#global.json.metaInheritanceRendering, <BOOLEAN>)$ switch.
Default setting: false
$CMS_SET(#global.json.metaInheritanceRendering, false)$
In the default setting $CMS_SET(#global.json.metaInheritanceRendering, false)$, only metadata that was defined on the object itself will be rendered. If no metadata is defined on the object, an empty value is rendered via the metaFormData attribute, even if the object has inherited metadata.
$CMS_SET(#global.json.metaInheritanceRendering, true)$
In the $CMS_SET(#global.json.metaInheritanceRendering, true)$ setting, the metadata that is rendered was not defined on the FirstSpirit object itself but on a hierarchically superordinate object. The inherited metadata is transferred to a JSON object structure. The values of the next higher object that are valid at that time, for which the corresponding metadata was defined, are thereby used (up to the root node of the store).
|
Changes to a pass-on node will not cause the inheriting nodes to be seen as changed. If the inheritance of the metadata is activated, a suitable mechanism must ensure that the data is updated accordingly. |
Special characteristics for the rendering of inherited metadata
$CMS_SET(#global.json.metaDataRenderMode, "INHERITED_OR_DEFINED")$: For the rendering of inherited metadata, the metadata of the hierarchically superordinate FirstSpirit objects will be analyzed. Starting from the source object, the process runs step by step through the entire parent chain until an object is found for which the metadata was defined. The analysis ends at the root node of the store (inclusively).
The following applies: If the input component that contains the metadata is not set in the metadata form on a FirstSpirit object, the value of the next higher FirstSpirit object will be analyzed. An input component is not set when the instruction isSet() renders the value false, which means that an object is not available in the current context. This state is reached when an input component was never set or an input component that has been set is overwritten with NULL, e.g., via a script (see example: “Switch input component to 'not set'”).
The simple deletion of a value in the input component is insufficient. In this case, the input component is empty (isEmpty() == true), but remains set (isSet() == true) (see API Documentation, Interface FormField, method isEmpty()).
Examples
JSON rendering of inherited metadata
{
"fsType": "PageRef",
"name": "pt_metadata_selective_1",
"displayName": "pt_metadata_selective",
"identifier": "15ff7b8d-9059-4721-b92b-e697e153fc85",
"uid": "pt_metadata_selective_1",
"uidType": "SITESTORE_LEAF",
"metaDataIsInherited": true,
"metaFormData": {
"meta_field1": {
"fsType": "CMS_INPUT_TEXT",
"name": "meta_field1",
"identifier": "meta_field1",
"value": null,
"valueSchema": {
"type": "null"
}
},
"meta_field2": {
"fsType": "CMS_INPUT_TEXT",
"name": "meta_field2",
"identifier": "meta_field2",
"value": "value_field2_set",
"valueSchema": {
"type": "string"
}
},
"meta_field3": {
"fsType": "CMS_INPUT_DATE",
"name": "meta_field3",
"identifier": "meta_field3",
"value": null,
"valueSchema": {
"type": "null"
}
}
},
(...)Switch input component to 'not set'
FS_BUTTON input component:
<FS_BUTTON name="meta_field1" noBreak="yes" onClick="script:delete_meta_data">
<LANGINFOS>
<LANGINFO lang="*" label="Delete meta data"/>
<LANGINFO lang="DE" label="Metadaten entfernen"/>
</LANGINFOS>
<PARAMS>
<PARAM name="meta_data">#field.meta_field1</PARAM>
</PARAMS>
</FS_BUTTON>
Script (“delete_meta_data”):
import de.espirit.firstspirit.forms.FormField;
if (meta_data instanceof FormField) {
meta_data.set(null);
}