Cette fonction est fournie dans le cadre de l'utilisation de l' Adélia Print Engine.
Elle permet d'ajouter une donnée (paramètre "ValeurDonnee", de tout type Adélia) dans un modèle de données.
Cette donnée est référencée dans le modèle par une clé (paramètre "NomDeCle", de type Adélia ALPHA).
Un modèle de données est un ensemble de couples clé/donnée. Ce modèle est identifié par un nom unique (paramètre "NomModele"). Il est automatiquement créé lors du premier ajout d'un couple.
Pour chaque ajout, il est nécessaire d'indiquer le type Adélia (paramètre "TypeAdelia") de la donnée à ajouter.
Dans le cas d'une variable tableau, il faut indiquer le type Adélia sous-jacent.
De plus, il est possible d'indiquer pour les types Adélia IMAGE / DATE / TIME / TIMESTAMP le mode d'encodage de la valeur dans le modèle de données.
Par exemple, "image ;convimg=0" indique que la variable à ajouter est de type IMAGE et que sa valeur sera stockée sous la forme de tableau d'octets.
Ce mode d'encodage peut aussi être ajouté lors de l'ajout d'une variable de type complexe (REF_CLASSE ou LISTE).
Dans ce cas, il est pris en compte si la variable contient des attributs (pour le type REF_CLASSE) ou des colonnes (pour le type LISTE) de type IMAGE / DATE / TIME / TIMESTAMP.
Par exemple, "class ;convdts=1 ;convimg=1" indique que la variable à ajouter est de type REF_CLASSE et que, si celle-ci contient des attributs de type DATE / TIME / TIMESTAMP ou IMAGE, ils seront stockés respectivement sous la forme de numériques (horodatage) et de tableau d'octets.
Rappel : la dll VaToolBx doit être déjà chargée (ordre CHARGER_DLL ) au moment de l'appel de cette fonction et doit rester chargée au moment de l'appel des fonctions VaToolBxAPEClearDataModel, VaToolBxAPEMergeDoc, VaToolBxAPETransformDoc ou VaToolBxAPEMergeAndTransformDoc.
Domaine d'application
- Client Java,
- Serveur Java,
- Client Adélia Web,
- Client Adélia Cloud.
Paramètres
ALPHA(n) |
NomModele |
Nom du modèle de données. |
||||||||||||||||||||||||||||||||||||||||||||||||||
ALPHA(n) |
NomDeCle |
Nom de la clé permettant d'accéder à la valeur ajoutée |
||||||||||||||||||||||||||||||||||||||||||||||||||
Tout type |
ValeurDonnee |
Valeur de la donnée à ajouter |
||||||||||||||||||||||||||||||||||||||||||||||||||
ALPHA(n) |
TypeAdelia |
Nom du type Adélia de ValeurDonnee. Les types Adélia doivent être indiqués de la manière suivante :
Optionnellement, il est possible d'ajouter le type d'encodage d'une valeur de type Adélia IMAGE / DATE / TIME / TIMESTAMP :
|
||||||||||||||||||||||||||||||||||||||||||||||||||
NUM_BIN_2 |
CodeRetour |
Code retour de l'opération : 0 : L'opération s'est déroulée correctement. -1 : Le nom du modèle de données ne peut être vide. -2 : Erreur lors de l'ajout dans le modèle de données d'une valeur de type Adélia LISTE. |
||||||||||||||||||||||||||||||||||||||||||||||||||
Lors de l'ajout de la donnée dans le modèle, celle-ci est ajouté par copie.
Par exemple, une donnée de type LISTE sera dupliquée (par copie de liste), et cette copie sera ajoutée au modèle.
De plus, si deux appels à cette fonction utilisent la même valeur de clé, l'ancienne donnée associée à cette clé (lors du premier appel) sera remplacée par la donnée passée lors du deuxième appel.
Enfin, il n'est pas possible de supprimer unitairement un couple clé/donnée du modèle de données (il est toutefois possible de vider complétement le modèle de données via la fonction VaToolBxAPEClearDataModel).
Il est possible, dans la même chaîne d'appel de programmes, de compléter le même modèle de données.
Le modèle de données ainsi construit est la source de données Freemarker (le "data-model" ; cliquez ici pour plus de détails) lors du traitement d'un gabarit (le "template") par la fonction VaToolBxAPEMergeDoc.
Le data-model est une table de hachage (ou tableau associatif).
Chaque donnée ajoutée n'est accessible que par sa clé. Une clé ne peut représenter qu'une seule donnée.
Pour accéder à une valeur du data-model dans Freemarker, on utilise, dans la source de données, la variable ayant pour nom la valeur de la clé (attention : sensible à la casse).
Par exemple, si le couple ("name"/"Mary") fait partie de la source de données , alors l'expression Freemarker ${name} a pour valeur la chaîne alphanumérique "Mary".
Chaque variable issue de la source de données a un type Freemarker déduit du type Adélia de la donnée associée :
| Types simples | |||
Type Adélia |
Type Java dans le modèle de données |
Type Freemarker dans la source de données |
|
|
ALPHA / DS |
String |
String |
|
NUM_BIN_2 / NUM_BIN_4 / NUM_BIN_8 / NUM_E / NUM_P |
Short (NUM_BIN_2) / Integer (NUM_BIN_4) / Long (NUM_BIN_8) / Integer, Long, Double, BigDecimal (NUM_E, NUM_P) |
Number |
|
BOOL |
Boolean |
Boolean |
|
IMAGE |
byte[] / String |
Sequence / String |
|
DATE |
java.sql.Date / Long / String |
Date / Number / String |
|
TIME |
java.sql.Time / Long / String |
Time / Number / String |
|
TIMESTAMP |
java.sql.Timestamp / Long / String |
Date-time / Number / String |
Types complexes |
|||
| Type Adélia | Type Java dans le modèle de données | Type Freemarker dans la source de données | |
|
REF_CLASSE |
Map<String, Object> |
Hash |
|
LISTE |
List<Map<String, Object>> |
Sequence (d'objets de type Hash) |
|
TABLEAU |
LinkedList<Object> |
Sequence |
|
|||
Type simple ALPHA
Exemple
L4G Adelia |
NUM_BIN_2 codeRet |
Expression Freemarker |
${name} |
Résultat dans gabarit |
Mary |
Type simple NUM_E(4,2)
Exemple
L4G Adelia |
NUM_BIN_2 codeRet |
Expression Freemarker |
${key_price} |
Résultat dans gabarit |
12,56 |
Type simple BOOL
Exemple
L4G Adelia |
NUM_BIN_2 codeRet |
Expression Freemarker |
${ IsArchive?c } |
Résultat dans gabarit |
true |
Type simple IMAGE
Lors de l'ajout dans le modèle de données d'une variable Adélia de type IMAGE, il est possible de choisir le type Java utilisé pour le stockage de la donnée dans le modèle de données :
Valeur du paramètre TypeAdelia |
Description |
Type Java dans le modèle de données |
image |
Par défaut, la variable Adélia de type IMAGE est stockée sous la forme d'une chaîne alphanumérique représentant le contenu de l'image, encodé en base 64. |
String |
image;convimg=0 |
Identique au comportement par défaut : la variable Adélia de type IMAGE est stockée sous la forme d'une chaîne alphanumérique représentant le contenu de l'image, encodé en base 64. |
String |
image;convimg=1 |
La variable Adélia de type IMAGE est stockée sous la forme d'un tableau d'octets |
byte[] |
Exemple
L4G Adelia |
NUM_BIN_2 codeRet * the image is converted to a base 64 encoded string |
Expression Freemarker |
${ dot } |
Résultat dans gabarit |
iVBORw0KGgoAAAANSUhEUgAAAAkAAAAJCAMAAADXT/YiAAAAGFBMVEX///9SUlKAgIDr6+uBgYFaWlp9fX1WVlZoulyHAAAAJklEQVQImWNgwAqYWVhZmMEsJkZGRjYwixXIYkcTY2ZiZWLGbgQADREASBTqq5EAAAAASUVORK5CYII= |
Types simples DATE / TIME / TIMESTAMP
Lors de l'ajout dans le modèle de données d'une variable Adélia de type DATE ou TIME ou TIMESTAMP, il est possible de choisir le type Java utilisé pour le stockage de la donnée dans le modèle de données :
Valeur du paramètre TypeAdelia |
Description |
Type Java dans le modèle de données |
date |
Par défaut, la variable Adélia de type DATE est stockée sous la forme d'un objet Java Date. |
java.sql.Date |
date;convdts=0 |
Identique au comportement par défaut : la variable Adélia de type DATE est stockée sous la forme d'un objet Java Date. |
java.sql.Date |
date;convdts=1 |
La variable Adélia de type DATE est stockée sous la forme d'un horodatage, sous la forme d'un nombre correspondant à une durée (en millisecondes) à partir du 1er janvier 1970 à 0 heure (UTC). |
Long (ex : 1546214400000 pour la date 31 décembre 2018 avec une heure forcée à 00:00:00) |
date;convdts=2 |
La variable Adélia de type DATE est stockée sous la forme d'une chaîne alphanumérique au format ISO 8601. |
String (ex : "2018-12-31" pour la date 31 décembre 2018) |
time |
Par défaut, la variable Adélia de type TIME est stockée sous la forme d'un objet Java Time |
java.sql.Time |
time;convdts=0 |
Identique au comportement par défaut : la variable Adélia de type TIME est stockée sous la forme d'un objet Java Time. |
java.sql.Time |
time;convdts=1 |
La variable Adélia de type TIME est stockée sous la forme d'un horodatage, sous la forme d'un nombre correspondant à une durée (en millisecondes) à partir du 1er janvier 1970 à 0 heure (UTC). |
Long (ex : 51782000 pour l'heure 15:23:02 avec une date forcée au 1er janvier 1970) |
time;convdts=2 |
La variable Adélia de type TIME est stockée sous la forme d'une chaîne alphanumérique au format ISO 8601. |
String (ex : "15:23:02") |
timestamp |
Par défaut, la variable Adélia de type TIMESTAMP est stockée sous la forme d'un objet Java Timestamp |
java.sql.Timestamp |
timestamp;convdts=0 |
Identique au comportement par défaut : la variable Adélia de type TIMESTAMP est stockée sous la forme d'un objet Java Timestamp |
java.sql.Timestamp |
timestamp;convdts=1 |
La variable Adélia de type TIMESTAMP est stockée sous la forme d'un horodatage, sous la forme d'un nombre correspondant à une durée (en millisecondes) à partir du 1er janvier 1970 à 0 heure (UTC). |
Long (ex : 151400107765451782000 pour l'horodatage 2017-12-23 à 04:51:17 et 654 millisecondes) |
timestamp;convdts=2 |
La variable Adélia de type TIMESTAMP est stockée sous la forme d'une chaîne alphanumérique au format ISO 8601. |
String (ex : "2017-12-23T04:51:17.654" pour l'horodatage 2017-12-23 à 04:51:17 et 654 millisecondes) |
Exemples : Type simple DATE
Exemple 1
L4G Adelia |
NUM_BIN_2 codeRet * orderDate is seen like a Freemarker Date in template |
Expression Freemarker |
${ orderDate } |
Résultat dans gabarit |
31 oct. 2018 |
Exemple 2
L4G Adelia |
NUM_BIN_2 codeRet * orderDate is seen like a Freemarker Number in template |
Expression Freemarker |
${ orderDate?number_to_date?date } |
Résultat dans gabarit |
31 oct. 2018 |
Exemple 3
L4G Adelia |
NUM_BIN_2 codeRet * orderDate is seen like a Freemarker String (ISO 8601 format) in template |
Expression Freemarker |
${ orderDate?date.iso } |
Résultat dans gabarit |
31 oct. 2018 |
Le data-model est un modèle arborescent : chaque couple clé/donnée est ajouté à une racine nommée ".data_model".
La variable spéciale Freemarker .data_model représente la source de données. Elle est de type Hash (table de hachage) et référence les "sous-variables" ayant pour nom la valeur de la clé de chaque couple ajouté.
Pour distinguer une variable Freemarker issue d'un gabarit d'une variable issue de la source de données, il est préférable d'utiliser l'expression ${.data_model.name} plutôt que ${name}.
De plus, si une variable est de type complexe (hash ou sequence), elle permet de référencer d'autres "sous-variables", qui elles-mêmes pourraient être de type complexe (imbrication à plusieurs niveaux).
↑ Haut de page
Type complexe REF_CLASSE
Dans le data-model, une donnée Adelia de type REF_CLASSE (instance d'un objet CLASSE Adélia) est référencé par une variable Freemarker de type Hash.
L'accès aux valeurs d'attributs définis dans la classe se fait au travers des "sous-variables" de même nom que les noms d'attributs.
Le type des "sous-variables" (simple ou complexe) dépendra du type Adélia de l'attribut de classe associé.
Lorsque la valeur de la clé vaut *BLANK, les sous-variables sont ajoutées directement sous la racine ".data_model".
Exemple 1
L4G Adelia |
CLASSE Personne : |
|
NUM_BIN_2 codeRet |
Modèle de données |
|
Expression Freemarker |
My name is ${ .data_model.client.name } ${ .data_model.client.lastName } |
Résultat dans gabarit |
My name is Mary Smith |
Exemple 2
L4G Adelia |
CLASSE Personne : |
|
NUM_BIN_2 codeRet |
Modèle de données |
|
Expression Freemarker |
My name is ${ .data_model.name } ${ .data_model.lastName } |
Résultat dans gabarit |
My name is Mary Smith |
Exemple 3
L4G Adelia |
CLASSE Personne : |
CLASSE Couple : |
|
NUM_BIN_2 codeRet
|
|
Modèle de données |
|
|
Expression Freemarker |
${ .data_model.weddingCouple.person1.name } ${ .data_model.weddingCouple.person1.lastName } and ${ .data_model.weddingCouple.person2.name } ${ .data_model.weddingCouple.person2.lastName } are just married!
|
|
Résultat dans gabarit |
Mary Smith and Bob Starr are just married!
|
|
Type complexe LISTE
Dans le data-model, une donnée Adelia de type LISTE est référencée par une variable Freemarker de type Sequence.
Une Sequence Freemarker est une liste ordonnée de valeurs.
Dans le cas d'une LISTE Adélia, la variable est une séquence d'objets Hash. Chaque objet Hash contient les valeurs des colonnes de la LISTE pour chaque ligne.
L'accès aux valeurs des colonnes se fait au travers des "sous-variables" de même nom que les noms des colonnes Adelia de la LISTE (attention : les noms des colonnes sont forcés en minuscules).
Le type des "sous-variables" (simple ou complexe) dépendra du type Adélia de la colonne associée.
Exemple 1
L4G Adelia |
NUM_BIN_2 codeRet |
Modèle de données |
|
Expression Freemarker |
Number of students: ${ .data_model.studentList?size} |
Résultat dans le gabarit |
Number of students: 3 |
Exemple 2
L4G Adelia |
CLASSE Personne : |
|
NUM_BIN_2 codeRet |
Modèle de données |
|
Expression Freemarker |
Number of students: ${ .data_model.studentList?size} |
Résultat dans le gabarit |
Number of students: 3 |
