Voir la source de Convertisseur XML Pivot - Opérations sur les champs

===Attribut @id===
Identifiant facultatif du champ source dans le XML de données.<br>
Grâce au Wildcard ("*") il est possible de récupérer tous les champs sans devoir les spécifier individuellement : <code><field id="*"/></code>


Exemple :
XML de données :

<syntaxhighlight lang="xml">
<data>
  <field id="site">1234</field>
  <doc type="BL">
    <field id="firstname">Martin</field>
    <field id="lastname">Garrix</field>
  </doc>
</data>
</syntaxhighlight>

XML de paramétrage :

<syntaxhighlight lang="xml">
<param>
  <doc type="BL">
    <field id="*"/>
  </doc>
</param>
</syntaxhighlight> 

Résultat XML "Draw" (Pour le Designer Mapping) :

<syntaxhighlight lang="xml">
<doc>
  <page name="BL">
    <field name="GLOBAL_site">1234</field>
    <field name="firstname">Martin</field>
    <field name="lastname">Garrix</field>
  </page>
</doc>
</syntaxhighlight>


===Attribut @name=== 
Facultatif, cet attribut permet la personnalisation du nom du champ cible pour le Designer en surchargeant le nom initial d'origine défini par l'attribut @id.<br>

===Attribut @data-type===
Facultatif, cet attribut permet de spécifier le type de la donnée provenant du fichier XML de données.

Il permet de forcer le formatage de la donnée, par exemple si la valeur est “000045.65000” et que le type est “number” alors le résultat après transformation sera “45.65” (suppression des zéros non significatifs et application des séparateurs définis par défaut).
Le type est utilisé également en cas de tri, afin de déterminé la méthode de tri (alphanumérique ou numérique)

Valeurs possibles :
* '''"text"''' : Valeur par défaut. Ne provoque aucun traitement de formatage
* '''"number"''' : Supprime tous les zéros non significatifs et applique les séparateurs de milliers et de décimal ainsi que le nombre de chiffres après la virgule par défaut.
* '''"date"''' : permet la conversion d’une date en spécifiant le format en entrée (dans le fichier XML de données) et le format attendu en sortie via les attributs @date-in et @date-out, leurs valeurs par défaut étant "ISO". 

Exemple : data-type="date"

Si cet attribut n’est pas présent, il sera déterminé automatiquement à partir des attributs de mise en forme.<br>
Ainsi, si un attribut @thousands-separator, @nb-decimal ou @decimal-separator est spécifié, il s’agit forcement d'un numérique (number), de même s’il s’agit d’un champ de type résultat de calcul.<br>
Si @date-in ou @date-out est spécifié, il s’agit forcement d’une date.<br>

===Attribut @nb-decimal===
Facultatif.<br>
Nombre fixe de chiffres après la virgule (par arrondi).<br>

Si non spécifié, seuls les chiffres significatifs après la virgule sont conservés.<br>
Par exemple 12,42370000 donnera 12,4237 et 57,140000000 donnera 57,14.<br>

Il est possible de passer 2 valeurs en paramètre afin de spécifier un nombre minimum et un nombre maximum de chiffres après la virgule.

Exemple : nb-decimal="2,4" (min=2, max=4)<br>
4.123456 -> 4.1235
4.1 -> 4.10

En cas d'usage de cet attribut, le champ sera implicitement considéré comme étant numérique (@data-type="number").

===Attribut @decimal-separator===
Facultatif
Chaine de caractères utilisée comme séparateur de décimales
Valeur par défaut : "." ou paramètre du programme si spécifié
Si @data-type n’est pas spécifié, ce dernier est implicitement considéré comme étant "number"

===Attribut @thousands-separator===
Facultatif
Chaine de caractères utilisée comme séparateur de milliers
Valeur par défaut : chaine vide ou paramètre du programme si spécifié
Si @data-type n’est pas spécifié, ce dernier est implicitement considéré comme étant "number"

===Attribut @date-in===
Factultatif
Valeur par défaut (si une conversion de date est requise) : "ISO"
Le formatage en entrée peut également être véhiculé par le paramètre de l’attribut @data-type=date(xxxxx)
Chaine de caractères permettant de spécifier le format de la date en entrée en vue de sa conversion
Valeurs :
Concaténation de texte “en dur” et de variables
[D] : numéro du jour dans le mois sur 1 chiffre
[DD] : numéro du jour dans le mois sur 2 chiffres
[M] : numéro du mois sur 1 ou 2 chiffres (1 pour janvier , 10 pour octobre)
[MM] : numéro du mois sur 2 chiffres
[YY] : année sur 2 chiffres
[YYYY] : année sur 4 chiffres
Autres chaines de caractères : conservée telle quelle
"ISO" : date au format ISO, équivalent à "[YYYY]-[MM]-[DD]"
Exemples pour le 23 octobre 2020 :
date-in="[YYYY][MM][DD]" signifie que la date est fournie sous la forme "20201023"
date-in="[DD]/[MM]/[YYYY]" signifie que la date est fournie sous la forme "23/10/2020"
data-type="date([DD]-[MM]-[YY])" signifie que la date est fournie sous la forme "23-10-20"
Si @data-type n’est pas spécifié, ce dernier est implicitement considéré comme étant "date"

===Attribut @date-out===
Factultatif
Valeur par défaut (si une conversion de date est requise) : [DD]/[MM]/[YYYY] ou utiliser @culture si spécifié
Syntaxe inspirée de la norme ISO 8601
Chaine de caractères permettant de spécifier le format de la date attendu après conversion
Valeurs :
Concaténation de texte “en dur” et de variables
[D] : numéro du jour dans la semaine (1 pour lundi et 7 pour dimanche)
[DD] : numéro du jour dans le mois sur 2 chiffres (01, 02, 03, …, 30, 31)
[DD-short] : numéro du jour dans le mois sur 1 ou 2 chiffres (1, 2, 3, …, 30, 31)
[DDD] : numéro du jour dans l’année
[weekday-name-short] : nom du jour abrégé de la semaine (“Sun” pour Sunday, “Mon” pour Monday …). “dotw”=day(s) of the week, qui est différent de weekdays qui ne comprend ni le samedi ni le dimanche.
[weekday-name] : nom du jour de la semaine (“Monday”, “Thuesday”, “Wednesday” …)
[MM] : numéro du mois dans l’année sur 2 chiffres (01, 02, …, 12)
[MM-short] : numéro du mois dans l’année sur 1 ou 2 chiffres (1, 2, …, 12)
[month-name-short] : diminutif du nom du mois (Jan, Feb, Mar, Apr etc…)
[month-name]: nom du mois (January, February, March etc…)
[YY] : année sur 2 chiffres
[YYYY] : année sur 4 chiffres
[WW] : numéro de la semaine dans l’année sur 2 chiffres (01, 02, … , 52)
[WW-short] : numéro de la semaine dans l’année sur un ou 2 chiffres (1, 2, …, 52)
Autres chaines de caractères : conservée telle quelle
"ISO" : [YYYY]-[MM]-[DD]
Exemples pour le 23 octobre 2020 :
date-out="[weekday-name], [month-name] [DD] [YYYY]" → "Thursday, October 23 2020"
date-out="[DD]-[month-name]-[YY]" → "23-Oct-20"
Si @data-type n’est pas spécifié, ce dernier est implicitement considéré comme étant "date"

===Attribut @culture===
Facultatif
Valeur par défaut : "en-UK"
Chaine de caractère permettant de spécifier les types de conversion numériques ou de date
Exemples : "fr-FR" , "en-US" , "en-UK" etc…
Impact sur le séparateur de décimales (virgule ou point) , séparateur de milliers (virgule ou point), langue pour les noms de jours et de mois, formatage des dates

===Attribut @case===
Facultatif
Permet de spécifier la casse
Valeur par défaut : vide (pas de modification de la casse)
Valeurs :
"upper" : conversion en majuscule
"lower" : conversion en minuscule
"first-upper" : forcer la première lettre en majuscule, ne pas modifier le reste
"first-upper-then-lower" : "forcer la première lettre en majuscule puis le reste en minuscules
Exemples si le champ d’origine contient "hello World!"
case="upper" → "HELLO WORLD!"
case="lower" → "hello world!"
case="first-upper" → "Hello World!"
case="first-upper-then-lower" → "Hello world!"

===Attribut @math===
Facultatif
Application d’une opération arithmétique sur un champ
Syntaxe : math="<opération>" avec utilisation du caractère “.” pour représenter la valeur du champ avant calcul.
Exemple : <field id="volume" math="./1000"/>   Permet de diviser le volume par 1000 afin de convertir des millilitres en litres. 
Dans un premier temps seul ./xxxx .*xxxxx  .-xxxxx .+xxxxx et .%xxxxxx doivent être mis en oeuvre
Si @data-type n’est pas spécifié, ce dernier est implicitement considéré comme étant "number"

===Attribut @prefix===
Facultatif
Chaine de caractère ajoutée en préfixe devant le champ
Syntaxe : prefix="abcdefg"
Exemple : 
<field id="volume" prefix="Volume : "/>    avec volume=1000
Permet d’obtenir <field name="volume">Volume : 1000</field> 
Le prefix doit être appliqué uniquement si le contenu du champ n’est pas vide afin de ne jamais obtenir un champ ne contenant que le préfixe et/ou le suffixe. Exemple : si prefix="Montant : " et suffix="€", en cas d’absence de valeur (null ou chaine vide), le résultat ne doit surtout pas être "Montant : €"

===Attribut @suffix===
Facultatif
Chaine de caractère ajoutée en suffixe après le champ
Syntaxe : suffix="abcdefg"
Exemple : 
<field id="volume" suffixe=" L"/>    avec volume=1000
Permet d’obtenir <field name="volume">1000 L</field> 
Même principe et contraintes que l’attribut @prefix 

===Attribut @from=== 
Facultatif
Alias : @xfrom - les 2 syntaxes étant équivalentes
Permet de récupérer la valeur d'un champ situé dans une autre branche du XML
Cet attribut doit contenir le chemin, absolu ou relatif, de la branche contenant l'élément <field> à récupérer
Si une collection est récupérée :
si l’attribut @function est spécifié, cette fonction est appliquée sur la collection
dans le cas contraire, c’est la valeur du 1er élément trouvé qui doit être récupéré
3 fonctions permettent de faciliter les requêtes relatives :
global-data() : permet de pointer vers la racine du XML de données (/data ou plus généralement /* )
Exemple : from="global-data()"
Il s’agit d’un chemin absolu
current-doc() : permet de pointer à la racine de l'élément <doc> courant
Exemple : from="current-doc()/list[@id='products']/item" pour récupérer la valeur d’un champ se trouvant dans la liste “product” du document courant.
Il s’agit d’un chemin absolu
parent-list() : Permet de remonter à la liste parent lorsque l’on se trouve dans une sous-liste
Exemple : from="parent-list()/item" , ce qui revient en fait à from="../../item" mais plus intuitif
Il s’agit d’un chemin relatif
En cas d’absence de l’attribut @id sur le champ, on s’attend à ce que la requête XPATH spécifiée par le @from retourne une valeur, ou une collection de valeurs. Cela peut-être opportun en cas de requête XPATH complexe comprenant l’utilisation de fonctions XPATH appliquées sur les valeurs retournées.
En cas de chemin absolu commençant par “/param” , la requête XPATH doit être appliquée non pas au XML de données mais au XML de paramétrage lui même. Cela permet de renseigner des données directement dans le fichier de param.
Dans ce cas, la structure des données présente dans le XML de param est libre, mais en cas d’utilisation de l’attribut @id, il faut considérer que la valeur à récupérer provient d’un élément <field> possédant un attribut @id.

Exemple : 

<field name="COMPTE" id="IBAN"  from="/param/mydata/banque[id='CIC']" />
ou
<field name="COMPTE"  from="/param/mydata/banque[id='CIC']/field[id='IBAN']" />



1<param ……>
2  <doc … >
3    …    
4  </doc>
5
6  <mydata>
7    <banque id="CIC">
8      <field id="IBAN">FR76 4377 2347 7653 1235 8754 23</field>
9    </banque>
10    <banque id="CIC">
11      <field id="IBAN">FR76 4377 2347 7653 1235 8754 23</field>
12    </banque>
13  </mydata>
14</param>

===Attribut @keep-empty-if-void=== 
Facultatif
Booleen
Si sa valeur est à "true", ce flag permet de créer un élément <field> vierge en sortie si l'origine de la donnée n'existe pas.
somme de champs d'une "collection vide" (aucun élément retournée)
champ <field> d'origine absent ou vide
Le champ <field> créé doit alors est complètement vierge 
En effet, par défaut, la somme de rien retourne 0
Exemple : 
<field id="montant_ht" from="list[@id='frais']/item" function="sum()" nb-decimal="2">Montant : </field>
-->
<field name="montant_ht">Montant : 0,00</field>
 
<field id="montant_ht" from="list[@id='frais']/item" function="sum()" nb-decimal="2" keep-empty-if-void="true">Montant : </field>
-->
<field name="montant_ht"></field>
 
Illustration sur un cas concret : 
Les échéances 2, 3 et 4 sont vides (pas de montant à 0,00) malgré un formatage numérique avec 2 chiffres après la virgule.

===Attribut @where===
Facultatif, en complément de l’usage de l’attribut @from ou @xfrom
L'attribut where permet d'appliquer un filtre sur la requête passée via l’attribut @from, par comparaison de valeurs avec le symbole "=" comme en SQL.
Plusieurs comparaisons peuvent être effectuées, séparées par le mot clé “or” ou “and”.
Exemple : 
where="((total < 1000) and (nom = 'foo') and (Condition 3)) or (Condition 4)"
Dans cet exemple, les champs total et nom correspondent respectivement aux éléments <field id="total"> et <field id="nom"> frères de l'élément <field> à récupérer.
La valeur 1000 implique une comparaison numérique, alors que la valeur 'foo' une comparaison alphanumérique grâce à la présence des quotes (simples ou doubles).
Si la valeur du champ recherché contient une quote, il suffit de la doubler dans la recherche (comme en syntaxe SQL). Exemple : where="(nom='abc''defg')" si la valeur recherchée est abc'defg

===Attribut @function===
Facultatif
Il s’agit d’une fonction d’agrégation permettant de réduire une collection de champs à une seule valeur.
Applicable sur une collection de champs <field> enfants (champ composé) ou sur une collection de champs issus d’une requête via l’usage de l’attribut @from ou @xfrom.
Attention : il y a des petites différences de comportement selon le cas d’usage (champ composé ou requête xpath)
Valeurs possibles :
sum() : somme → tout élément non numérique doit être considéré comme étant égal à 0
mul('default') : multiplication → en cas de présence d’un champ non numérique, le résultat doit être une chaine vide, ou la chaine “default” si cette dernière est spécifiée
div('default') : division → en cas de présence d’un champ non numérique, ou de tentative de division par 0, le résultat doit être une chaine vide, ou la chaine “default” si cette dernière est spécifiée
Cette fonction n’est pas applicable dans le cas de l’utilisation de l’attribut @function pour une collection de valeurs récupérées via l’usage de @from ou @xfrom
A la place d’une valeur, spécifiée entre simples quotes, prévoir un mot clé permettant de retourner le calcul. Exemple : "5/0"
Ce mot clé pourrait être : operation

Exemples : 



1<field name="nb-colis-par-palette"  function="div(operation)">
2  <field id="nb-palettes"/>
3  <field id="nb-colis"/>
4</field>
Ainsi, si nb-palettes=10 et nb-colis=0 alors le résultat nb-colis-par-palette sera "10/0"




1<field name="nb-colis-par-palette"  function="div('N/A')">
2  <field id="nb-palettes"/>
3  <field id="nb-colis"/>
4</field>
Ainsi, si nb-palettes=10 et nb-colis=0 alors le résultat nb-colis-par-palette sera "N/A"

avg() : moyenne (somme des valeurs des champs divisée par la quantité de valeurs trouvées) → tout élément non numérique doit être considéré comme étant égal à 0
min(field id ou xpath , data-type) : valeur du champ ayant la plus petite valeur. 
ATTENTION
Fonctionnement à débattre….
Les paramètres de la fonction “min” sont facultatifs. Il s’agit soit l'identifiant d'un élément frère, soit une requête xpath relative au chemin spécifiée dans la requête XPATH. S’il n’y a pas de paramètres, c'est le champ spécifié par l'attribut @id qui sera utilisé (c’est à dire le champ lui même).
Un second paramètre facultatif permet de spécifier explicitement le type de comparaison à effectuer : 'number' , 'text' , 'date'
Par défaut, la comparaison doit être numérique, mais peut être alphanumérique si le champ possède un attribut @data-type="text" ou si le contenu n’est pas numérique, ou alors une comparaison de date si @data-type="date".
Le paramètre field id ou xpath est utilisable uniquement en cas d’usage de l’attribut @from ou @xfrom, permet de spécifier un élément frère ou relatif de l'élément recherché.
La requête xpath est obligatoirement relative au chemin définit par l’attribut @from.
Exemples : 
Recherche du numéro de colis ayant la plus petite date de livraison
<field id="NUM_COLIS" from="list[@id='COLIS']/item" function="min(DAT_LIV,date([DD]/[MM]/[YYYY]))"/>

Recherche de la date de livraison la plus ancienne (plus petite)
<field id="DATE_LIV" from="list[@id='COLIS']/item" function="min()" data-type="date([DD]/[MM]/[YYYY])"/>

Rercherche la palette dans laquelle se trouve le colis contenant le plus d’articles 
<field id="NUM_PALETTE" from="list[@id='PALETTES']/item" function="max(list[@id='COLIS']/item/field[@id='QTE_ARTICLES'])"/>

max(field id ou xpath , data-type) : valeur du champ ayant la plus grande valeur.
Mêmes contraintes que pour min()
concat('séparateur') : concaténation des champs en utilisant le séparateur spécifié. Ce dernier peut être aussi bien une chaine vide qu'une chaine d’un ou plusieurs caractères. Ce séparateur est appliqué uniquement entre 2 chaines non vides afin de ne pas obtenir une chaine de caractère comportant plusieurs séparateurs à la suite.
first()
last()
count()
Valeur par défaut :
Dans le cadre d’un champ composé : concat(' ')
Dans le cadre d’un résultat de requête via usage de l’attribut @from : first()
Si @data-type n’est pas spécifié, ce dernier est implicitement considéré comme étant "number" (@data-type="number")  dans le cas où la fonction utilisée retourne un numérique (sum, mul, count, avg etc…)

===Noeud text()===
Facultatif
On ne les retrouve avec du contenu qu’en tant qu’enfant des éléments <field>
S'il n'y a pas d'attribut @id, cela permet de créer un champ texte avec un contenu fixe (en dur). Cet usage implique obligatoirement l’utilisation de l’attribut @name
S'il y a un attribut @id, la valeur renvoyée par ce dernier est préfixée par le contenu "text()" de l'élément <field>
Exemple 1 : <field id="num_colis">Numéro de colis : </field> 
devient <field name="num_colis">Numéro de colis : 123456789</field>
Exemple 2 : <field name="titre">Facture</field> 
devient <field name="titre">Facture</field>