Téléchargement des produits


Version anglaise


 

 

 

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 :

"alpha"

Type Adélia ALPHA ou tableau d'ALPHA.

"bool"

Type Adélia BOOL ou tableau de BOOL. 

"num_bin_2"

Type Adélia NUM_BIN_2 ou tableau de NUM_BIN_2. 

"num_bin_4"

Type Adélia NUM_BIN_4 ou tableau de NUM_BIN_4. 

"num_bin_8"

Type Adélia NUM_BIN_8 ou tableau de NUM_BIN_8.

"num_e"

Type Adélia NUM_E ou tableau de NUM_E.

"num_p"

Type Adélia NUM_P ou tableau de NUM_P.

"date"

Type Adélia DATE ou tableau de DATE.

"time"

Type Adélia TIME ou tableau de TIME.

"timestamp"

Type Adélia TIMESTAMP ou tableau de TIMESTAMP.

"list"

Type Adélia LISTE.

"class"

Type Adélia REF_CLASSE ou tableau de REF_CLASSE.

"image"

Type Adélia IMAGE ou tableau de IMAGE.

"ds"

Type Adélia DS.

 

Optionnellement, il est possible d'ajouter le type d'encodage d'une valeur de type Adélia IMAGE / DATE / TIME / TIMESTAMP :

"image;convimg=0"

Octets encodés en base 64.

"image;convimg=1"

Tableau d'octets.

"date;convdts=0"

Objet Date.

"date;convdts=1"

Horodatage sous la forme d'un nombre correspondant à une durée (en millisecondes) à partir du 1er janvier 1970 à 0 heure (UTC).

"date;convdts=2"

Chaîne alphanumérique au format ISO 8601

"time;convdts=0"

objet Time.

"time;convdts=1"

Horodatage sous la forme d'un nombre correspondant à une durée (en millisecondes) à partir du 1er janvier 1970 à 0 heure (UTC).

"time;convdts=2"

Chaîne alphanumérique au format ISO 8601

"timestamp;convdts=0"

Objet Timestamp.

"timestamp;convdts=1"

Horodatage sous la forme d'un nombre correspondant à une durée (en millisecondes) à partir du 1er janvier 1970 à 0 heure (UTC).

"timestamp;convdts=2"

Chaîne alphanumérique au format ISO 8601

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. 
-3 : La valeur de NomDeCle ne peut être vide que si la valeur associée à ajouter (ValeurDonnee) a le type Adelia REF_CLASSE.
-4 : Le nom du type Adélia de ValeurDonnee (TypeAdelia) n'est pas valide.

     
 

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

 

Cliquez ici pour plus d'informations. 

 


Type simple ALPHA

Exemple

L4G Adelia

NUM_BIN_2 codeRet
ALPHA(15) name
name = 'Mary'
appeler_class 'vatoolbx.dll' 'VaToolBxAPEAddInDataModel' 'myDataModel' 'name' name 'alpha' codeRet

Expression Freemarker

${name}

Résultat dans gabarit

Mary

 

 

Type simple NUM_E(4,2)

Exemple

L4G Adelia

NUM_BIN_2 codeRet
NUM_E(4,2) price
price = 12.56
appeler_class 'vatoolbx.dll' 'VaToolBxAPEAddInDataModel' 'myDataModel' 'key_price' price 'num_e' codeRet

Expression Freemarker

${key_price}

Résultat dans gabarit

12,56

 


Type simple BOOL

Exemple

L4G Adelia

NUM_BIN_2 codeRet
BOOL is_archive
is_archive = *VRAI
appeler_class 'vatoolbx.dll' 'VaToolBxAPEAddInDataModel' 'myDataModel' 'IsArchive' is_archive 'bool' codeRet

Expression Freemarker

${ IsArchive?c }

Résultat dans gabarit

true

↑ Haut de page

 

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
IMAGE dot
appeler_class 'vatoolbx.dll' 'VaToolBxFileToImage' 'c:/dot.png' dot codeRet

* the image is converted to a base 64 encoded string
appeler_class 'vatoolbx.dll' 'VaToolBxAPEAddInDataModel' 'myDataModel' 'dotImg' dot 'image ;convimg=1' codeRet

Expression Freemarker

${ dot }

Résultat dans gabarit

iVBORw0KGgoAAAANSUhEUgAAAAkAAAAJCAMAAADXT/YiAAAAGFBMVEX///9SUlKAgIDr6+uBgYFaWlp9fX1WVlZoulyHAAAAJklEQVQImWNgwAqYWVhZmMEsJkZGRjYwixXIYkcTY2ZiZWLGbgQADREASBTqq5EAAAAASUVORK5CYII=

↑ Haut de page

 

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
DATE orderDate
orderDate = &ALPHA_DATE('*ISO';'2018-10-31')
appeler_class 'vatoolbx.dll' 'VaToolBxAPEAddInDataModel' 'myDataModel' 'orderDate' orderDate 'date' 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
DATE orderDate
orderDate = &ALPHA_DATE('*ISO';'2018-10-31')
appeler_class 'vatoolbx.dll' 'VaToolBxAPEAddInDataModel' 'myDataModel' 'orderDate' orderDate 'date ;convdts=1' 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
DATE orderDate
orderDate = &ALPHA_DATE('*ISO';'2018-10-31')
appeler_class 'vatoolbx.dll' 'VaToolBxAPEAddInDataModel' 'myDataModel' 'orderDate' orderDate 'date ;convdts=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 :
*attributs {
ALPHA(15) name ;
ALPHA(15) lastName ;
NUM_BIN_2 age ;
}

 

NUM_BIN_2 codeRet
REF_CLASSE(Personne) aPerson
aPerson = new Personne()
aPerson.setname('Mary')
aPerson.setlastName('Smith')
aPerson.setage(18)
appeler_class 'vatoolbx.dll' 'VaToolBxAPEAddInDataModel' 'myDataModel' 'client' aPerson 'class' codeRet

Modèle de données

Expression Freemarker

My name is ${ .data_model.client.name } ${ .data_model.client.lastName }
My name is ${ client.name } ${ client.lastName }

Résultat dans gabarit

My name is Mary Smith
My name is Mary Smith

 

 

Exemple 2

L4G Adelia

CLASSE Personne :
*attributs {
ALPHA(15) name ;
ALPHA(15) lastName ;
NUM_BIN_2 age ;
}

 

NUM_BIN_2 codeRet
REF_CLASSE(Personne) aPerson
aPerson = new Personne()
aPerson.setname('Mary')
aPerson.setlastName('Smith')
aPerson.setage(18)
appeler_class 'vatoolbx.dll' 'VaToolBxAPEAddInDataModel' 'myDataModel' *BLANK aPerson 'class' codeRet

Modèle de données

Expression Freemarker

My name is ${ .data_model.name } ${ .data_model.lastName }
My name is ${ name } ${ lastName }

Résultat dans gabarit

My name is Mary Smith
My name is Mary Smith

 

 

Exemple 3

 

L4G Adelia

CLASSE Personne :
*attributs {
ALPHA(15) name ;
ALPHA(15) lastName ;
NUM_BIN_2 age ;
}

CLASSE Couple :
*attributs {
REF_CLASSE(Personne) person1 ;
REF_CLASSE(Personne) person2;
}

 

NUM_BIN_2 codeRet
REF_CLASSE(Couple) aCouple
REF_CLASSE(Personne) aPerson
aCouple = new Couple()
aPerson = new Personne()
aPerson.setname('Mary')
aPerson.setlastName('Smith')
aPerson.setage(18)
aCouple.setperson1(aPerson)

aPerson = new Personne()
aPerson.setname('Bob')
aPerson.setlastName('Starr')
aPerson.setage(20)
aCouple.setperson2(aPerson)

appeler_class 'vatoolbx.dll' 'VaToolBxAPEAddInDataModel' 'myDataModel' 'weddingCouple' aCouple 'class' 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!

 

↑ Haut de page

 

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
ALPHA(30) NAME
NUM_BIN_2 Age
LISTE studentList NAME Age

NAME = 'Franck Hunter'
Age = 18
Inserer_elt studentList
NAME = 'Theresa Black'
Age = 17
Inserer_elt studentList
NAME = 'Alexander Faye'
Age = 19
Inserer_elt studentList

appeler_class 'vatoolbx.dll' 'VaToolBxAPEAddInDataModel' 'myDataModel' 'studentList' studentList 'list' codeRet

Modèle de données

Expression Freemarker

Number of students: ${ .data_model.studentList?size}
First student: ${ .data_model.studentList[0].name} , ${ .data_model.studentList[0].age}
Second student: ${ .data_model.studentList[1].name} , ${ .data_model.studentList[1].age}
Third student: ${ .data_model.studentList[2].name} , ${ .data_model.studentList[2].age}

Résultat dans le gabarit

Number of students: 3
First student: Franck Hunter, 18
Second student: Theresa Black, 17
Third student: Alexander Faye, 19


Exemple 2

L4G Adelia

CLASSE Personne :
*attributs {
ALPHA(15) name ;
ALPHA(15) lastName ;
NUM_BIN_2 age ;
}

 

NUM_BIN_2 codeRet
REF_CLASSE(Personne) aPerson
NUM_P(4,2) avgGrade
LISTE studentList aPerson avgGrade

aPerson = new Personne()
aPerson.setname('Franck')
aPerson.setlastName('Hunter')
aPerson.setage(18)
avgGrade = 9.8
Inserer_elt studentList

aPerson = new Personne()
aPerson.setname('Theresa')
aPerson.setlastName('Black')
aPerson.setage(17)
avgGrade = 12.05
Inserer_elt studentList

aPerson = new Personne()
aPerson.setname('Alexander')
aPerson.setlastName('Faye')
aPerson.setage(19)
avgGrade = 14
Inserer_elt studentList

appeler_class 'vatoolbx.dll' 'VaToolBxAPEAddInDataModel' 'myDataModel' 'studentList' studentList 'list' codeRet

Modèle de données

Expression Freemarker

Number of students: ${ .data_model.studentList?size}
First student: ${ .data_model.studentList[0].aperson.name} ${ .data_model.studentList[0].aperson.lastName} , ${ .data_model.studentList[0].aperson.age}; ${ .data_model.studentList[0].avggrade}
Second student: ${ .data_model.studentList[1].aperson.name} ${ .data_model.studentList[1].aperson.lastName} , ${ .data_model.studentList[1].aperson.age}; ${ .data_model.studentList[1].avggrade}
Third student: ${ .data_model.studentList[2].aperson.name} ${ .data_model.studentList[2].aperson.lastName} , ${ .data_model.studentList[2].aperson.age}; ${ .data_model.studentList[2].avggrade}

Résultat dans le gabarit

Number of students: 3
First student: Franck Hunter, 18; 9,8
Second student: Theresa Black, 17; 12,05
Third student: Alexander Faye, 19; 14

↑ Haut de page

  • Aucune étiquette