Standardisierte JSON-Ausgabe
| Inhaltsverzeichnis |
JSON (JavaScript Object Notation, siehe auch json.org) ist ein verbreitetes Standard-Datenaustauschformat.
FirstSpirit unterstützt die Ausgabe von Seiten als JSON-Dokumente mit einem einzigen CMS_VALUE-Ausdruck: $CMS_VALUE(json(#this))$
Ausgabe von Werten
Werte werden entsprechend der JSON-Spezifikation ausgegeben, d.h. boolean als true oder false, Zahlen mit einem Punkt „.“ als Dezimaltrennzeichen und das Fehlen eines Wertes wird als „null“ dargestellt. Einige Zeichen in Zeichenketten werden mit einem umgekehrten Schrägstrich \ geschützt. Datumswerte werden als String im ISO 8601 Standard dargestellt, das auch in JavaScript Verwendung findet:
"2019-05-28T10:50:47.684Z"
Objekte werden mit geschweiften Klammern { } und Listen (Arrays) mit eckigen Klammern [ ] umschlossen.
Struktur
Die JSON-Ausgabe einer Seite beinhaltet die Seite, ihre Inhaltsbereiche und Absätze sowie die inhaltlichen Daten, falls vorhanden. Jedes Seiten-, Inhalts- und Absatz-Element wird als separates JSON-Objekt innerhalb einer JSON-Objekthierarchie dargestellt. Jedes Seiten-Wurzelobjekt enthält seine Inhaltsbereiche („Bodies“) als JSON-Array im Attribut children und jeder Inhaltsbereich wiederum seine Absatzobjekte („Sections“) als JSON-Array im Attribut children.
Für Seiten und Absätze werden die Daten im Attribut formData als JSON-Objekt ausgegeben. Das JSON-Objekt formData enthält die Daten der Eingabekomponenten als Schlüssel-Werte-Paare, wobei der Name der Eingabekomponente der Schlüssel und der Inhalt der Eingabekomponente ein JSON-Objekt ist. Diese Wert-Objekte haben, wie im Beispiel ersichtlich, jeweils die Attribute fsType, name und value.
Abhängig vom Typ der Eingabekomponente kann der value-Wert eine Zeichenkette, eine Zahl, eine boolesche Variable (true/false) oder eine andere JSON-Darstellung eines FormField-Wertes sein.
Beispiel:
{
"fsType": "PageRef",
"name": "pt_components",
"displayName": "pt_components",
"identifier": "1c2c3d4b-2896-43ab-a2ec-e2fbdb0d8b1d",
"uid": "pt_components",
"uidType": "SITESTORE_LEAF",
"metaFormData": {
},
"page": {
"fsType": "Page",
"name": "pt_components",
"displayName": "pt_components",
"identifier": "d658ed13-3318-4eb7-a442-f0b893270ed0",
"translated": false,
"uid": "pt_components",
"uidType": "PAGESTORE",
"template": {
"fsType": "PageTemplate",
"name": "pt_components",
"displayName": "pt_components",
"identifier": "481d928b-cd65-42b3-9799-1e1bb6d63c92",
"uid": "pt_components",
"uidType": "TEMPLATESTORE"
},
"formData": {
"st_headline": {
"fsType": "CMS_INPUT_TEXT",
"name": "st_headline",
"value": "Text der Seite"
}
},
"metaFormData": {
},
"children": [
{
"fsType": "Body",
"name": "content",
"identifier": "f592ef7b-9ae3-4c03-ac46-f44766547e30",
"children": [
{
"fsType": "Section",
"name": "text_absatz",
"displayName": "Text_Absatz",
"identifier": "c4c29467-f948-484a-b09f-72870ec66b96",
"template": {
"fsType": "SectionTemplate",
"name": "Text_Absatz",
"displayName": "Text_Absatz",
"identifier": "fc152884-1f75-4028-8979-19e549e75945",
"uid": "text_absatz",
"uidType": "TEMPLATESTORE"
},
"formData": {
"st_input_text": {
"fsType": "CMS_INPUT_TEXT",
"name": "st_input_text",
"value": "Text des Absatzes "
}
}
}
]
}
]
}
}Ausgabe von Absätzen
Wenn die JSON-Konfiguration #global.json.sectionTemplateRendering „true“ ist, werden Absatzvorlagen von Absätzen einzeln ausgewertet, anstatt bei der Standard-Ausgabe automatisch erzeugt zu werden.
Wenn die JSON-Konfiguration #global.json.sectionTemplateRendering „false“ ist, werden Absatzvorlagen ignoriert und das Standard-Ausgabeformat mit den im vorherigen Abschnitt beschriebenen Attributen verwendet.
Bei Verwendung von sectionTemplateRendering kann die Standard-Ausgabe innerhalb der Absatzvorlage ausgelöst werden durch:
$CMS_VALUE(json(#this))$
Wenn eine Vorlage keinen Inhalt hat, wird ein leeres JSON-Objekt "{}" als Fallback dargestellt, um eine gültige JSON-Ausgabe zu gewährleisten.
Manuelle Ausgabe von Inhaltsbereichen
Soll nicht der Standardausdruck $CMS_VALUE(json(#this))$ verwendet werden, kann auch eine eigene JSON-Ausgabe für die Seite erstellt werden. Wenn in der JSON-Konfiguration sectionTemplateRendering „true“ ist, dann kann der Inhalt aller Absätze eines Inhaltsbereiches als JSON-Array mit Hilfe dieses Template-Codes dargestellt werden:
$CMS_VALUE(json(#global.page.body("<bodyname>")))$Es muss sichergestellt werden, dass jeder Absatz ein gültiges JSON-Element erzeugt. Die Elemente werden automatisch zusammengesetzt.
Ausgabe von Tabellenvorlagen
Bei der Verwendung von Tabellenvorlagen (oder Content-Projektionen) wird durch
$CMS_VALUE(json(#this))$
jeder für die Ausgabe gültige Datensatz als JSON-Objekt ausgegeben.
Wenn der Bereich „Daten“ in der Struktur-Verwaltung so konfiguriert ist, dass drei Einträge angezeigt werden sollen (siehe dazu Einstellungen auf Seitenreferenzebene (→Handbuch FirstSpirit SiteArchitect)), dann werden in der JSON-Ausgabe drei JSON-Objekte im Children-Array des übergeordneten Inhaltsbereichs (Body) ausgegeben.
Jede aus einem Datensatz erzeugte Absatzinstanz kann wie jede andere JSON-Absatz geändert werden, z. B. mit der json API:
$CMS_VALUE(json(#this).set("my_attr", "my_value"))$ Die Variablen #row, #cs sowie Formularvariablen sind im Kontext von json/tabletemplate nicht verfügbar.
Bei erkannten Zirkelbezügen wird lediglich eine entsprechende Referenz auf das Ursprungselement ausgegeben. D.h. Datensätze, die mehrmals in dem selben Stack gefunden werden, werden ab dem zweiten Vorkommen nur noch als Referenz ausgegeben.
Beispiel:
"fsType": "CircularReference"