La configuration d'Apache FreeMarker se fait à partir du fichier freemarker.properties.
Pour pouvoir faire fonctionner FreeMarker avec vos propres templates, cette configuration est obligatoire.
La première étape consiste à récupérer un exemplaire de ce fichier. Consultez la page MergeTransformMicroService pour plus de détails.
Ce fichier est un fichier .properties Java (syntaxe clé = valeur).
La seconde étape consiste à modifier ou renseigner les clés en fonction des besoins.
La seule clé qui doit être obligatoirement modifiée est la clé "template_loader", permettant de définir le chargeur de templates.
Les clés du fichier freemarker.properties
Clé | Description | ||||||||||||||||||||||||||||||||||||||||
| template_loader | |||||||||||||||||||||||||||||||||||||||||
Chargeur de template. Valeur par défaut : freemarker.cache.MultiTemplateLoader( \ [com.hardis.adelia.mergedocengine.freemarker.conf.ClassTemplateLoader(com.hardis.adelia.mergedocengine.ProcessTemplate.CLASS_FOR_OBJECT_BUILDER_EXPRESSION, "/com/hardis/adelia/mergedocengine/freemarker/lib")]) Le caractère "\" indique un saut de ligne dans la valeur d'une clé. Il faut rajouter votre propre chargeur au chargeur par défaut de l'APE. Vous avez à votre disposition plusieurs types de chargeur, suivant le format de livrable de l'ensemble de vos templates, à savoir :
Chargeur com.hardis.adelia.mergedocengine.freemarker.conf.FileTemplateLoaderLes paramètres sont les suivants :
Par exemple, si vos templates utilisateur sont dans les répertoires "c:\billingTemplates" et "c:\reportingTemplates" :
Chargeur com.hardis.adelia.mergedocengine.freemarker.conf.ClassTemplateLoaderLes paramètres sont les suivants :
Par exemple, si vos templates utilisateur sont dans un fichier JAR localisé dans le package "/myTemplates" (le fichier JAR doit être présent dans le CLASSPATH Java) :
Chargeur com.hardis.adelia.mergedocengine.freemarker.conf.ZipFileTemplateLoaderLes paramètres sont les suivants :
Par exemple, si vos templates utilisateur sont dans les fichiers "c:\billingTemplates.zip" (accessibles depuis la racine du fichier) et "c:\reportingTemplates.zip" (accessibles depuis le sous-répertoire "year2019") :
| |||||||||||||||||||||||||||||||||||||||||
default_encoding | |||||||||||||||||||||||||||||||||||||||||
Encodage par défaut des templates lus à partir d'une locale n'ayant pas d'encodage associé. Valeur par défaut : UTF-8 | |||||||||||||||||||||||||||||||||||||||||
template_update_delay | |||||||||||||||||||||||||||||||||||||||||
Définit le délai en millisecondes devant s'écouler avant que le module de gestion de cache des templates vérifie s'il existe une version plus récente d'un template que celui en cache. La valeur par défaut est 5 s. En phase de mise au point de templates, cette valeur indique quelle est la durée minimale d'attente entre l'instant de sauvegarde d'un template (sauvegarder une modification par exemple) et sa disponibilité à être traité (pour tester le résultat de la modification) par le moteur FreeMarker. Il faut donc indiquer une valeur de l'ordre de la seconde. En phase de production, il peut être intéressant d'avoir une valeur très grande pour ne pas impacter les performances du moteur lors de fortes charges. | |||||||||||||||||||||||||||||||||||||||||
locale | |||||||||||||||||||||||||||||||||||||||||
Définit la locale utilisée par défaut si aucune locale n'est spécifiée dans les paramètres des services Web. | |||||||||||||||||||||||||||||||||||||||||
template_exception_handler | |||||||||||||||||||||||||||||||||||||||||
Définit la stratégie de remonté d'erreur lors du traitement d'un template. Valeur par défaut: "rethrow" | |||||||||||||||||||||||||||||||||||||||||
boolean_format | |||||||||||||||||||||||||||||||||||||||||
Définit les valeurs alphanumériques utilisées pour convertir une valeur booléenne FreeMarker en chaîne alphanumérique dans l'interpolation ${ booleanValue }. Valeurs par défaut : yes, no ("yes" pour True et "no" pour False) | |||||||||||||||||||||||||||||||||||||||||
extSharedVariables | |||||||||||||||||||||||||||||||||||||||||
Permet de définir une ou plusieurs variables partagées par tous les templates. La syntaxe doit être une Map. Par exemple : extSharedVariables = { "sharedNumberVar": 10, \
Ces variables peuvent être manipulées dans les templates en utilisant des interpolations ${ sharedNumberVar }, ${sharedSequenceVar[1]} , ${sharedHashVar.subVar1}, etc. Attention : si une variable de premier niveau dans le data model porte le même nom qu'une variable partagée, la variable du data model va "cacher" la variable partagée. | |||||||||||||||||||||||||||||||||||||||||
Injection de variables d'environnement dans freemarker.properties
L'APE offre la possibilité d'injecter des variables dans le fichier freemarker.properties. Celles-ci peuvent apparaître uniquement dans les valeurs des clés (et non comme nom de clé) du fichier .properties Java.
Déclaration d'une variable
La syntaxe d'une variable doit être la suivante :
/*<nom de variable>*/ (sans espaces), où <nom de variable> est constitué d'une suite d'un ou plusieurs caractères parmi les suivant : "a" à "z", "A" à "Z", "0" à "9" ou "_".
Lors de l'exécution de l'APE, chaque variable identifiée dans le fichier freemarker.properties est remplacée par sa valeur (la déclaration d'une variable /*<nom de variable>*/ est remplacée par sa valeur).
Définition d'une variable
Une variable peut être :
- soit une variable d'environnement,
- soit une propriété système définie au lancement de l'APE.
Variable d'environnement
Une variable d'environnement est une variable utilisateur partagée par un ou plusieurs processus. Son mode de définition est propre à chaque système d'exploitation.
Propriété système
En Java, une propriété système est définie par la syntaxe suivante :
-D<nom de variable>=<valeur de variable>
Remarques :
- La propriété système est prioritaire sur la variable d'environnement. Si une même variable est définie à la fois comme variable d'environnement et comme propriété système, alors la valeur de la propriété système sera prise en compte,
- Lors de l'exécution de l'APE, si une variable n'est pas définie, sa déclaration est laissée telle quelle.
Exemple
Voici un exemple de clé template_loader d'un fichier freemarker.properties qui déclare :
- un chargeur de templates de type FileTemplateLoader dont le paramètre "baseDir" est défini par une variable d'environnement TEST_ENV_VAR1 et
- un autre chargeur de templates dont la valeur est définie par une variable d'environnement TEST_ENV_VAR2.
template_loader=freemarker.cache.MultiTemplateLoader( \
[com.hardis.adelia.mergedocengine.freemarker.conf.FileTemplateLoader(java.io.File ("/*TEST_ENV_VAR1*/")), \
/*TEST_ENV_VAR2*/, \
com.hardis.adelia.mergedocengine.freemarker.conf.ClassTemplateLoader(com.hardis.adelia.mergedocengine.ProcessTemplate.CLASS_FOR_OBJECT_BUILDER_EXPRESSION, "/com/hardis/adelia/mergedocengine/freemarker/lib"), \
com.hardis.adelia.mergedocengine.freemarker.conf.ClassTemplateLoader(com.hardis.adelia.mergedocengine.ProcessTemplate.CLASS_FOR_OBJECT_BUILDER_EXPRESSION, "/com/hardis/adelia/apeexternallibs/freemarker/lib")])
L'utilisateur définit la variable TEST_ENV_VAR1 comme variable d'environnement et la variable TEST_ENV_VAR2 comme propriété système. Voici la syntaxe de lancement de l'APE en Windows et Linux :
Windows
set TEST_ENV_VAR1=./templatesDir1
ape-dev.bat -Dmanagement.endpoint.shutdown.enabled=true -Dserver.port=8080 -DTEST_ENV_VAR2=com.hardis.adelia.mergedocengine.freemarker.conf.FileTemplateLoader(java.io.File(\"d:/ape/templatesDir2\"))"
Linux
export TEST_ENV_VAR1=./templatesDir1
↑ Haut de pagesh ape-dev.sh -Dmanagement.endpoint.shutdown.enabled=true -Dserver.port=8080 -DTEST_ENV_VAR2='com.hardis.adelia.mergedocengine.freemarker.conf.FileTemplateLoader(java.io.File(\"/home/userape/ape/templatesDir2\"))'