Préambule

RTFTemplate est un moteur RTF vers RTF, qui permet de fusionner un modèle RTF (Template) avec des données provenant d'objets JAVA (Contexte). Il permet de générer un document RTF qui est le résultat de la fusion du modèle RTF et de données.

Depuis la version 1.0.1-b8, RTFTemplate à été reconçu pour être plus modulaire. Si vous utilisez une version antérieur à celle-ci, vous pouvez accédez à l'ancienne documentation ici.

Pour utiliser RTFTemplate vous devez :

• désigner votre modèle RTF avec MS Word en utilisant les champs de fusions (MERGEFIELD), les liens hyper textes (HYPERLINK) et les signets (BOOKMARK, pour gérer les débuts/fins de boucles).
• préparer votre contexte avec des objets JAVA.
• fusionner votre modèle RTF (Template) avec vos objets Java (Contexte) en utilisant RTFTemplate.

Après l'étape de fusion, les champs de fusions (MERGEFIELD) et les liens hyper textes (HYPERLINK) seront remplacés par vos données provenant du contexte JAVA. Les signets (BOOKMARK) sont utilisés pour indiquer les débuts/fins boucle d'une liste contenant des objets JAVA (ex : pour générer par exemple une table RTF (lignes RTF) en itérant sur cette liste).

Pour commencer à utiliser RTFTemplate référer vous au Guide utilisateur.

Processus de génération

Le processus de génération avec RTFTemplate nécéssite trois étapes essentielles :

• Etape 1 : parsing du modèle RTF source qui permet de charger le modèle RTF dans une structure RTFDocument. Cette structure qui contient l'ensemble du modèle RTF, découpe les élements RTF du modèle interprété par RTFTemplate comme les champs (RTFField), les signets (RTFBookmark)...
• Etape 2 : processus de transformation. La structure RTFDocument est transformée pour :
  • remplacer le code RTF avec les macros spécifiques selon le moteur de template sélectionné (ex : remplacer les signets par la macro #foreach dans le cas ou RTFTemplate est utilisé avec Velocity).
  • supprimer certaine partie du code RTF, comme celui des champs de fusions (MERGEFIELD) pour enlever les caractères " qui englobent les champs de fusions.

  Le résulat de cette étape donne une structure RTFDocument qui contient les macros du moteur de template sélectionné.

• Etape 3 : fusion du document transformé avec le contexte JAVA. Cette étape utilise le moteur de template sélectionné pour fusionner le document transformé avec le contexte pour donner le document RTF cible qui contient le modèle RTF fusionné avec les données.

Vous trouverez ici un schéma qui explique le processus de génération utilisé par RTFTemplate.

Exemple de modèle RTF

Voici un exemple de modèle RTF désigner à l'aide de MS Word :

Après fusion du modèle RTF source et du contexte (objet JAVA), le document RTF cible obtenu est le suivant :

Comment utiliser RTFTemplate?

Voici le code JAVA utilisé pour obtenir le document RTF cible précédant :

  String rtfSource = "usecases/models/jakartavelocityproject/jakarta-velocity-model.rtf";
  String rtfTarget = "jakarta-velocity-model.rtf.rtf";

  // 1. Get default RTFtemplateBuilder
  RTFTemplateBuilder builder = RTFTemplateBuilder.newRTFTemplateBuilder();            
    
  // 2. Get RTFtemplate with default Implementation of template engine (Velocity) 
  RTFTemplate rtfTemplate = builder.newRTFTemplate();    
  
  // 3. Set the RTF model source 
  rtfTemplate.setTemplate(new File(rtfSource));  
  
  // 4. Put the context           
  rtfTemplate.put("project", new Project("Jakarta Velocity project"));
  
  rtfTemplate.put("header_developer_name", "Name");
  rtfTemplate.put("header_developer_email", "Email");
  rtfTemplate.put("header_developer_roles", "Roles");
  
  List developers = new ArrayList();
  Developer developer = new Developer("Will Glass-Husain",
          "wglass@apache.org");
  developer.addRole("Java Developer");
  developer.addRole("Release Manager");
  developers.add(developer);  
  rtfTemplate.put("developers", developers);  
  ...
  
  List dependencies = new ArrayList();
  Dependency dependency = new Dependency("commons-collection", "jar",
          "1.0", "http://jakarta.apache.org/commons/collection/");
  dependencies.add(dependency);
  ...
  rtfTemplate.put("dependencies", dependencies);  
  ...    
  
  // 5. Merge the RTF source model and the context  
  rtfTemplate.merge(rtfTarget);

Cet exemple utilise la configuration par défaut de RTFTemplate (notemment le moteur de template Velocity), mais il est possible de configurer RTFtemplate pour pouvoir utilisé d'autres moteur de template comme Freemarker (qui est aussi implementé).

ATTENTION, cet exemple n'est pas la stratégie optimale d'utilisation de RTFTemplate. Si vous avez des contraintes de performances veuillez vous référer à la section comment optimiser RTFTemplate?

Nouvelle API

Avant la version 1.0.1-b8, RTFTemplate était basé uniquement sur le moteur de template Velocity. Aujourd'hui, RTFTemplate peut être configuré à l'aide d'un descripteur XML Spring, ce qui vous permet d'implémenter votre propre moteur de template ou encore ré-implémenter les moteurs existants pour configurer ceux-ci comme vous le souhaitez.

Pour plus d'information sur la configuration de RTFTemplate cliquez ici.

Par défaut RTFtemplate implémente les moteurs de templates Velocity et Freemarker.

La nouvelle API permet de séparer les différents étapes du processus de génération de RTFTemplate. Chacune des étapes peut être ausi ré-implémentée.