Formeln (JSON)
Eine Formel ist ein XQuery 3.1-Ausdruck, der eine Ausgabe (entweder ein Nodeset oder eine Berechnung) für die Anzeige in der JSON/YAML-Grid-Ansicht generiert. In der Abbildung unten wird z.B. die Summe der Elemente (Items) 1 bis 4 in einem JSON-Dokument berechnet und das Resultat (28) in einer separaten Zeile angezeigt. Jede Formel wird separat ausgeführt. Andere Filter oder Formeln im Dokument haben keine Auswirkung darauf.
Informationen zur Erstellung von XQuery-Ausdrücken für JSON/YAML-Dokumente finden Sie im Abschnitt XQuery-Ausdrücke für JSON.
Beachten Sie, dass die Formel als JSON-Kommentar, das Ergebnis der Formel jedoch direkt im JSON-Code gespeichert wird. Der unten stehende Code (dessen Formelergebnis gespeichert wurde) ist das Resultat, wenn Sie auf das Diskettensymbol der Formel geklickt haben.
{ "receiptID": "123-456-7890", "paymentMethod": "Cash", "items": [ { "itemID": "1", "displayName": "Milk", "price": 1, "quantity": 3 }, { "itemID": "2", "displayName": "Yogurt", "price": 2, "quantity": 2 }, { "itemID": "3", "displayName": "Chocolate 85%", "price": 1, "quantity": 1 }, { "itemID": "4", "displayName": "Fancy Wine", "price": 20, "quantity": 1 } ], //(:altova_xq_embed:)totalPrice(:altova_xq_key:)sum(for $item in ?items?* return $item?price * $item?quantity) "totalPrice": 28 //(:altova_xq_end:) } |
In der obigen Abbildung werden mit der Formel die Mitglieder einer Sequenz addiert. Bei diesen Mitgliedern handelt es such jeweils um das Produkt der Werte price und quantity der einzelnen Objekte des Array items. Die Iteration, um die einzelnen Objekte auszuwählen und diese jeweils der Variablen $item zuzuweisen, wird folgendermaßen definiert: for $item in ?items?*. Wichtig in diesem Zusammenhang ist der Kontext-Node. Es handelt sich hierbei um den Parent Node der Formel und folglich um den Parent-Node des Node items. Jedes Produkt wird durch Ermittlung der Child-Nodes price und quantity des aktuellen Objekts in der Variablen $item und durch Multiplikation dieser beiden Werte miteinander berechnet. Die so berechneten Produkte bilden die Mitglieder der Sequenz, die anschließend addiert wird, um den Gesamtpreis zu generieren.
Erstellen einer Formel
Um eine Formel zu erstellen, gehen Sie folgendermaßen vor:
1.Wählen Sie den gewünschten Node, zu dem Sie die Formel hinzufügen möchten, entweder als gleichrangigen Node oder als Child-Node aus. Klicken Sie mit der rechten Maustaste darauf und fügen Sie den gleichrangigen Node bzw. den Child-Node hinzu. Beachten Sie bei der Entscheidung, wo die Formel angezeigt werden soll (als gleichrangiger Node oder als Child-Node), dass der Kontext-Node des XQuery-Ausdrucks der Formel den Parent-Node der Formel bildet. So ist z.B. der Kontext-Node im XQuery-Ausdruck in der Abbildung oben der Parent Node der Formel (totalPrice) und ihres gleichrangigen Node, nämlich des Array items. Um die Formel in der Abbildung oben zu erstellen, wurde an das items-Array ein gleichrangiger Node angehängt (siehe Abbildung unten).
2.Ändern Sie den Typ des Node in "Formel" (siehe Abbildung unten).
3.Doppelklicken Sie in die Zelle, die das Symbol f(x) enthält, und geben Sie den Namen der Formel ein (siehe Abbildung unten). Wenn es sich beim Dokument um ein JSON5- oder JSONC-Dokument handelt, wird ein Diskettensymbol angezeigt. Sie können auf dieses Symbol klicken, um die Ausgabe der Formel im Dokument zu speichern.
4.Standardmäßig ist der XQuery-Ausdruck der String 'XQuery', d.h. die Ausgabe ist der String XQuery (wird in der Zelle unterhalb des Ausdrucks angezeigt). Durch Doppelklick auf die Zelle des Ausdrucks, Eingabe des gewünschten Ausdruck und Drücken der Eingabetaste können Sie Ihren Ausdruck definieren. Dadurch wird die Formel ausgewertet und ihr Ergebnis wird angezeigt. Anderen Formeln werden nicht geändert.
5.Wenn das Dokument mehrere Formeln enthält, klicken Sie auf dem Menübefehl JSON | Alle erneut auswerten, um die Ergebnisse aller Formeln zu aktualisieren. Dieser Befehl ist vor allem dann hilfreich, wenn mit Formeln im Dokument Daten nachgeschlagen werden, die sich dynamisch ändern (z.B. Wechselkurse).
Zusammenfassung der wichtigsten Punkte
Beachten Sie bei Formeln die folgenden Punkte, insbesondere die speziellen Eigenschaften von JSON5 und JSONC-Dokumenten:
•Der Kontext-Node des XQuery-Ausdrucks der Formel ist der Parent-Node des Formel-Node.
•Um in einem Ausdruck eine neue Zeile hinzuzufügen, drücken Sie Strg+Eingabetaste. Dies ist nützlich, wenn Sie einen Ausdruck mehrzeilig anzeigen möchten, um eine bessere Übersicht zu haben.
•Die XQuery-Ausdrücke der Formeln eines Dokuments werden in einer speziellen Metadatendatei in Ihrem Applikationsordner (Eigene) Dokumente: Altova\XMLSpyCommon\json-metadata.json gespeichert. Wenn das Dokument in der Grid-Ansicht erneut geöffnet wird, werden automatisch die Formeln aus dieser Datei darauf angewendet.
•In JSON5- uznd JSONC-Dokumenten können Sie Formeln zusätzlich als Kommentare speichern. Aktivieren Sie dazu die Option Persistenz der Grid-Ansichtseinstellungen (Extras | Optionen | Einstellungen für Grid-Ansicht). Diese Option ist standardmäßig aktiviert.
•Das Berechnungsergebnis einer Formel wird in der Zelle unterhalb des XQuery-Ausdrucks der Formel angezeigt. Im Fall von JSON5 und JSONC kann die Ausgabe zusätzlich dazu im Dokument gespeichert werden. Wenn die Option Persistenz (siehe vorheriger Punkt) aktiviert wurde, wird neben dem XQuery-Ausdruck das Speichersymbol angezeigt. Schalten Sie dieses Symbol ein, um das Ergebnis der Formel im Dokument zu speichern.
 | Formelausgabe wird nicht im JSON-Inhalt gespeichert; Zum Speichern anklicken. Nur in JSON5 und JSONC. |
 | Formelausgabe wird im JSON-Inhalt gespeichert. Um diese nicht zu speichern, klicken Sie auf das Symbol. Nur in JSON5 und JSONC. |
•Unabhängig davon, ob Sie auf das Diskettensymbol klicken oder nicht, wird die Ausgabe der Formel berechnet und in den Metadaten das Dokuments gespeichert.
•Wenn es sich bei der Ausgabe um eine Berechnung handelt, die im Inhalt gespeichert wird, wird diese unter dem Namen, den Sie der Formel zugewiesen haben, als Eigenschaft gespeichert. So wird die Ausgabe etwa in der oben beschriebenen Formel totalPrice folgendermaßen gespeichert: "totalPrice": 28.
•Beachten Sie diesen Unterschied: In JSON5- und JSONC-Dokumenten werden Formeln als JSON-Kommentare gespeichert. Deren Ausgabe wird in Form von JSON-Eigenschaften gespeichert.
| Anmerkung: | Weder Formeln noch deren Ergebnisse können in Dokumenten, bei denen es sich nicht um JSON5- oder JSONC-Dokumente handelt, gespeichert werden. Da die Formeln der Grid-Ansicht bei einem jeden JSON-Dokument jedoch immer in der Metadatendatei der Applikation gespeichert werden, werden diese immer auf das Dokument angewendet, wenn es in der Grid-Ansicht angezeigt wird. |
| Anmerkung: | Da eine Formel auf XQuery basiert, funktioniert er in YAML-Dokumenten, die der JSON-Syntax nicht entsprechen, nicht. Wenn Sie in Ihrem YAML-Dokument z.B. Anker oder Aliasse verwenden, hat die Berechnung einer Formel eine XQuery-Fehlermeldung zur Folge. |
Formeln in Tabellen
Wenn alle Zellen einer Tabellenspalte (in der Tabellenansicht) dieselbe Formel enthalten, so wird die Formel nur einmal angezeigt, und zwar in der Spaltenüberschrift (siehe Abbildung unten). Die Berechnungsergebnisse der Formel werden jedoch in den jeweiligen Zellen angezeigt. Die Formel in der Spaltenüberschrift ist eine Darstellung in der Grid-Ansicht. Im Inhalt des JSON/YAML-Dokuments (in der Textansicht) wird die Formel für jedes Tabellenzeilenelement wiederholt.
Wenn sich auch nur eine einzige Formel von den anderen unterscheidet (wie in der markierten Zelle in der Abbildung unten), so wird jede Formel in ihrer dazugehörigen Zelle angezeigt.
Alle Formeln erneut auswerten
Um die Ergebnisse aller Formeln im Dokument zu aktualisieren, klicken Sie auf den Menübefehl JSON | Alle erneut auswerten.
Vorgangsweise für häufig verwendete Aktionen
•So fügen Sie zur Tabelle eine neue leere Spalte hinzu: Wechseln Sie von der Listenanzeige in die Tabellenansicht. Klicken Sie mit der rechten Maustaste auf ein beliebiges Schlüssel:Wert-Paar in der Listenanzeige und fügen Sie über das Kontextmenü des Elements mittels Einfügen oder Anhängen ein neues Schlüssel:Wert-Paar hinzu. Wenn Sie in die Tabellenansicht zurückwechseln, wird für das neu angehängte/eingefügte Schlüssel:Wert-Paar eine neue Spalte erstellt. Sie können diese Spalte nun in der Grid-Ansicht bearbeiten.
•Wenn alle Formeln einer Tabellenspalte identisch sind, sodass die Formel in der Überschrift angezeigt wird und Sie für eine einzelne Zelle eine andere Formel erstellen möchten, wechseln Sie in die Listenanzeige und bearbeiten Sie die Formel dieser Zelle.