Formules (JSON)
Une formule est une expression XQuery 3.1 qui génère un résultat (soit un nodeset ou des calculs) pour un affichage en Mode Grille JSON/YAML. Dans la capture d’écran ci-dessous, par exemple, le prix total des items 1 à 4 dans un document JSON est calculé et le résultat (28) est affiché sur une ligne séparée. Chaque formule est exécutée de manière indépendante et n’est pas affectée par d’autres filtres ou formules dans le document.
Pour toute information sur la construction d’expressions XQuery pour des documents JSON/YAML, voir la section Expressions XQuery pour JSON.
Notez que la formule est stockée en tant que commentaire JSON mais le résultat de la formule est stockée en tant que code JSON direct. Le code ci-dessous (avec le résultat de la formule étant stocké) est le résultat de l’icône du disque de la formule lorsque vous cliquez dessus.
{ "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:) } |
Dans la capture d’écran ci-dessus, la formule résume les membres d’une séquence. Ces membres sont chacun des produits des valeurs de prix et de quantité de chaque projet contenu dans le tableau des items. L’itération de spécifier chaque objet et de l’attribuer, à son tour, à la variable $item est spécifiée par : pour $item dans ?items?*. Il est important de noter ici le nœud contextuel, qui est le parent de la formule—et, en conséquence, le parent du nœud des items. Chaque produit est obtenu en vérifiant le prix et la quantité des nœuds enfants de l’objet actuellement dans la variable $item, et en multipliant ces deux valeurs l’une avec l’autre. Les produits ainsi obtenus sont les membres de la séquence, qui sont ensuite additionnés afin de générer le prix total.
Créer une formule
Pour créer un formule, procéder comme suit :
1.Sélectionnez le nœud pour lequel vous voulez ajouter la formule, soit en tant que frère ou enfant. Cliquez avec la touche droite, et ajoutez le frère ou l’enfant (selon ce que vous voulez). Lorsque vous décidez où vous voulez que la formule apparaisse (en tant que frère ou enfant), n’oubliez pas que le nœud contextuel de l’expression XQuery de la formule sera le nœud parent de la formule. Par exemple, dans l’expression XQuery affichée dans la capture d’écran ci-dessus, le nœud contextuel est le nœud parent de la formule (Prixtotal) et de son frère, l’array des items. Pour créer la formule dans la capture d’écran ci-dessus, un nœud frère a été apposé dans l’array des items (voir la capture d’écran ci-dessous).
2.Changer le type du nœud de la Formule (voir la capture d’écran ci-dessous).
3.Double-cliquez dans la cellule qui contient l’icône f(x) pour saisir le nom de la formule (voir la capture d’écran ci-dessus). Si le document est un document JSON5 ou JSONC, alors une icône de disque est affichée. Vous pouvez cliquer sur l’icône pour enregistrer le résultat de la formule vers le document.
4.Par défaut, l’expression XQuery est le string 'XQuery', donc le résultat sera le string XQuery (affiché dans la cellule ci-dessous sous l’expression). Saisissez votre expression XQuery en double-cliquant dans la cellule de l’expression et tapez l’expression, puis cliquez sur Enter. Ainsi, la formule sera-t-elle évaluée et son résultat affiché. Les autres formules ne seront pas modifiées.
5.Si le document contient de multiples formules, cliquez sur la commande de menu JSON | Tout réévaluer afin de mettre à jour les résultats de toutes les formules. La commande est particulièrement utile si les formules dans le document recherchent des données qui changent de manière dynamique (par exemple, des taux de change).
Résumé des points clés
Notez que les points suivants sur les formules, en particulier les propriétés spéciales des documents JSON5 et JSONC :
•Le nœud du contexte de l’expression XQuery de la formule est le nœud parent du nœud de la formule.
•Pour ajouter une nouvelle ligne dans une expression, appuyez sur Ctrl+Enter. Ceci est utile si vous voulez afficher une expression sur plusieurs lignes pour une meilleure lecture.
•Les expressions XQuery des formules d’un document sont stockées dans un fichier de métadonnées de l’application spéciale dans votre dossier (Mes) Documents : Altova\XMLSpyCommon\json-metadata.json. Les formules seront automatiquement appliquées depuis ce filtre quand le document est réouvert dans le Mode Grille.
•Dans les documents JSON5 et JSONC, vous pouvez enregistrer de plus les formules comme commentaires. Faites ceci en sélectionnant l’option Persistance des Paramètres du Mode Grille (Outils | Options | Aperçu | Paramètres du Mode Grille). Cette option est sélectionnée par défaut.
•Le résultat du calcul d’une formule est affiché dans la cellule en dessous de l’expression XQuery. Dans le cas de JSON5 et JSONC, la sortie peut en plus être stockée dans le document. Si l’option Persistance a été sélectionnée (voir point précédent), alors une icône de disque apparaît à côté de l’expression XQuery. Activez cette icône pour enregistrer le résultat de la formule dans le document.
 | Le résultat de la formule n’est pas enregistré dans le contenu JSON ; cliquez pour l’enregistrer. Uniquement dans JSON5 et JSONC. |
 | Le résultat de la formule est enregistré dans le contenu JSON ; cliquez pour ne pas l’enregistrer. Uniquement dans JSON5 et JSONC |
•Que vous ayez cliquer sur le disque ou non, le résultat de la formule sera calculé et stocké dans les métadonnées du document.
•Quand la sortie est un calcul et est stocké dans le contenu, il est stocké comme propriété qui a le nom que vous avez assigné à la formule. Par exemple, dans la formule Prixtotal décrite ci-dessus, le résultat est stocké comme suit : "totalPrice": 28.
•Notez la différence : Dans les documents en JSON5 et JSONC, les formules sont enregistrées en tant que commentaires JSON, leurs résultats sont enregistrés en tant que propriétés JSON.
| Note : | il n’est pas possible d’enregistrer les formules ou leurs résultats dans les documents JSON qui ne sont pas JSON5 ou JSONC. Toutefois, puisque les formules du Mode Grille de tout document JSON sont toujours stockées dans le fichier de métadonnées de l’application, elles seront toujours appliquées quand le document est affiché dans le Mode Grille. |
| Note : | Puisqu’une formule est basée sur XQuery, elle ne fonctionnera pas dans les documents YAML qui ne sont pas JSON-like. Donc, si, par exemple, vous utilisez des ancres ou alias dans votre document YAML, alors le calcul de la formule résultera en un message d’erreur XQuery. |
Formules dans les tables
Si toutes les cellules d’une colonne de table (in Affichage Table) contiennent la même formule, la formule est affichée une seule fois—dans l’en-tête de la colonne (voir la capture d’écran ci-dessous). Les résultats du calcul de la formule sont, toutefois, affichés dans les cellules respectives. La formule dans l’en-tête de la colonne est une représentation du Mode Grille. Dans le contenu du document JSON/YAML (en Mode Texte), la formule est répétée pour chaque item ligne-table.
Même si une seule formule est différente (telle que dans cellule en surbrillance de la capture d'écran ci-dessous), chaque formule sera affichée dans sa cellule respective.
Réévaluer toutes les formules
Pour mettre à jour les résultats de toutes les formules dans le document, cliquez sur la commande du menu JSON | Tout réévaluer.
Procédures pour les actions pertinentes
•Ajouter une nouvelle colonne vide à la table comme suit : Basculez vers Affichage de la liste depuis l’Affichage de la table, cliquez avec la touche droite sur n’importe quelle paire key:value dans l’affichage de la liste, et apposez ou insérez une nouvelle paire key:valuepar le biais du menu contextuel de l’item. Lorsque vous rebasculez vers l’Affichage de la table, une nouvelle colonne est créée pour la nouvelle key:value paire qui a été apposée/insérée. Vous pouvez désormais éditer la colonne dans le Mode Grid.
•Si toutes les formules d’une colonne de table sont les mêmes pour que la formule apparaisse dans l’en-tête, et vous voulez créer maintenant une formule différente pour une cellule individuelle, basculez vers l’Affichage de la liste et éditer la formule de cette cellule.