Guide utilisateur - Création des modèles

Création des modèles

La création d'un modèle consiste à :

  • préparer le contexte JAVA attendu par le modèle RTF.
  • générer le fichier XML (*.fields.xml) qui sera utilisé lors de l'intégration de RTFTemplate dans votre application, mais aussi pour vous aider à construire vos modèle RTF.
  • tester le résultat de la fusion du modèle avec le contexte JAVA.

Pour effectuer ces tâches, RTFTemplate fournit une classe abstraite net.sourceforge.rtf.usecases.AbstractRTFUseCase que vous pouvez implémenter. Cette classe permet de :

  • tester rapidement le résultat de la fusion de votre modèle RTF avec votre contexte JAVA.
  • générer le fichier XML (*.fields.xml) à partir de votre contexte JAVA. Ce fichier contient tous les champs accessibles lors du désign de votre modèle RTF en fonction de votre contexte JAVA.

ATTENTION, il n'est pas conseillé d'utiliser l'implémentation de cette classe dans votre application. Veuillez vous reportez à la section intégration de RTFTemplate pour plus d'information.

RTFTemplate fournit une distribution qui contient les cas d'utilisation de RTFTemplate (gérer les images, les sauts de pages...). Pour plus d'informations cliquez ici.

Implementer AbstractRTFUseCase

Avant d'implémenter cette classe vous devez créer votre contexte JAVA, autrement dit créer toutes vos classes JAVA POJO (Plain Old java Object) et collections de POJO. Ces classes définissent des getters/setters sur des types Simples (java.lang.String,...) ou sur d'autres POJO. Le contexte créé sera ensuite fusionné avec votre modèle source RTF.

Classe AbstractRTFUseCase

Voici le code de cette classe et les méthodes principales que vous devez implémenter ou que vous pouvez utiliser : (Il existe d'autres méthodes qui vous permettent de configurer plus finement RTFTemplate.)

  public abstract class AbstractRTFUseCase {
  
    /**
     * Run RTFTemplate for merging rtfSource with the context 
     * putted with the method putContext which be must implement.
     * After execution of this method, files 
     * rtfSource + ".<rtfTemplateImpl>.rtf" (RTF template implementation (vmRTFtemplate,...) and 
     * rtfSource + ".out.rtf" (RTF final with values of the context)
     * will be generate.
     * @param rtfSource RTF source model.
     * @throws Exception
     */throws Exception
     */
    protected final void run(String rtfSource) throws Exception {
      ....
    }

    /**
     * This method must be implement by class
     * wich manage your RTF model. 
     * Put the context of your model
     * (eg : context("date", new Date()); ) 
     * @param context IContext
     */
    protected abstract void putContext(IContext context);
    
    /**
     * Return String XML Mergefields used in your context
     * and Bookmarks (for start and end loop)  
     * @return
     */
    public String getXMLFields() {
      ....
    }
    
    /**
     * Save XML fields available into file.
     * If force parameter is false, the file is 
     * updated with new context (by keeping just 
     * description) otherwise the file is 
     * crushed with new context.
     * @param filename
     * @throws Exception
     */
    protected void saveXmlFields(String filename, boolean force) throws Exception {
      ....
    }
    
    /**
     * set true if RTF with (velocity, freemarker,... macro) file must be generated
     * and false otherwise.
     * @param saveTransformedDocument
     */
    public void saveTransformedDocument(boolean saveTransformedDocument)
      ....
    }
    
    /**
     * This value allow to group by content when there is PageBreak
     * in order to group by content.
     * @param groupByPerPageBreak
     */
    protected void setGroupByPerPageBreak(int groupByPerPageBreak) {
      ...
    }
    
  }

Les méthodes qui doivent être obligatoirement implémentées sont :

  • putContext : cette méthode vous permet de poser dans le contexte tous les objets JAVA que votre modèle RTF peut utiliser. Concernant les collections ou les objets complexes (avec graphes d'objets), il est très important d'instancier la collection et de lui ajouter au moins UN objet Java, afin que RTFTemplate puisse générer les macros de boucles (#foreach pour Velocity, #list pour freemarker,...), mais aussi qu'il puisse générer correctement le fichier XML des champs disponibles (*.fields.xml).

Une fois que vous avez implémenté ces méthodes, vous pouvez utiliser les méthodes :

  • run : pour lancer le test de votre modèle RTF. Cette méthode attend le nom du fichier modèle RTF à utiliser. Ce fichier est obligatoire. Même si vous n'avez pas encore commencer à désigner votre modèle, vous devez créer un fichier vide RTF pour lancer le test. Selon la configuration (voir ci dessous), cette méthode générera le fichier RTF transformé (avec les macros du moteur de template), les champs XML disponibles (*.fields.xml),...
  • getXMLFields : pour obtenir les champs XML disponibles (*.fields.xml) pour votre modèle. La String XML retournée peut ensuite être utilisé pour désigner votre modèle RTF.
  • saveXmlFields : pour sauver les champs XML disponibles (*.fields.xml) de votre modèle dans un fichier XML.
  • saveTransformedDocument : passer la valeur true, si vous souhaiter générer le fichier RTF qui contient les macros du moteur de template sélectionné (Velocity, Freemarker,...). Par défaut, AbstractRTFUseCase ne génère pas ce fichier.
  • setGroupByPerPageBreak : pour générer tous les groupByPerPageBreakème d'un item de la première liste que RTFTemplate détecte dans votre modèle RTF, un saut de page.
  • setApplicationContext : cette méthode vous permet d'indiquer la configuration Spring à utiliser avec RTFTemplate.

Exemple d'implémentation

Voici un exemple de code d'implémentation de AbstractRTFUseCase :

  public class RTFProjectTest extends AbstractUseCase {
        
    protected void putContext(IContext context) {
      /**
       * Context of simply POJO
       */      
      context.put("date", new Date());
      context.put("project", new Project("Jakarta Velocity"));
      
      /**
       * Context of list of POJO
       */
      List developers = new ArrayList();
      Developer developer = new Developer("Will Glass-Husain", "wglass@apache.org");
      developer.addRole("Java Developer");
      developer.addRole("Release Manager");
      ....
      context.put("developers", developers );
    }
        
    public static void main( String[] args ) throws Exception {
        RTFProjectTest usecase = new RTFProjectTest();
        usecase.run("usecases/project/project_model.rtf");
        usecase.saveRTFVelocity(true); // Save RTF file with velocity macro
        // Display the XML fields 
        System.out.println(usecase.getXMLFields()); 
        // Save XML fields into project_model.fields.xml file with update description
        usecase.saveTransformedDocument("usecases/project/project_model.fields.xml" ,false);
    }
}  

Une fois le test lancé, le fichier XML qui contient les champs XML disponibles (*.fields.xml) project_model.fields.xml se générera.

Ce fichier XML peut être ensuite utilisé pour modéliser votre modèle RTF. ATTENTION ce fichier doit se terminer par fields.xml pour que vous puissiez l'utiliser avec MS Word.

XML fields available

Les noms des champs de fusion MERGEFIELD et de liens hypertextes HYPERLINK doivent respecter une certaine syntaxe. Ces noms de ces champs sont contenues dans le fichier XML des champs disponibles.

<?xml version="1.0" encoding="ISO-8859-1"?>
<fields>
        <description><![CDATA[]]></description>
        <!-- Bookmark Pattern -->
        <bookmark>
                <type>START_LOOP</type>
                <name>START_LOOP_{i}</name>
                <description><![CDATA[]]></description>
        </bookmark>
        <bookmark>
                <type>END_LOOP</type>
                <name>END_LOOP_{i}</name>
                <description><![CDATA[]]></description>
        </bookmark>        
        ...
        <mergefield>
                <list>true</list>
                <listInfo>$[developers].Email</listInfo>
                <name>$developers.Email</name>
                <description><![CDATA[]]></description>
        </mergefield>
        <mergefield>
                <list>true</list>
                <listInfo>$[developers].Name</listInfo>
                <name>$developers.Name</name>
                <description><![CDATA[]]></description>
        </mergefield>
        ....
        <mergefield>
                <list>false</list>
                <listInfo>$project.Name</listInfo>
                <name>$project.Name</name>
                <description><![CDATA[]]></description>
        </mergefield>
        <mergefield>
                <list>false</list>
                <listInfo>$date</listInfo>
                <name>$date</name>
                <description><![CDATA[]]></description>
        </mergefield>        
        ....
</fields>

Ce fichier XML contient les élements XML suivants :

  • description : cet élément est uniquement utilisé par la macro MS Word pour afficher la description du modèle.
  • bookmark : décrit le pattern à utiliser pour nommer les signets début/fin boucle :
    • type : START_LOOP pour identifier le début d'une boucle et END_LOOP pour identifier la fin d'une boucle.
    • name : le pattern à utiliser pour le nom d'un signet. {i} doit être utilisé dans le pattern . En effet un signet à un nom unique dans le modèle RTF.
    • description : cet élément est uniquement utilisé par la macro MS Word pour afficher la description du signet.
  • mergefield : décrit le champs à utiliser dans le modèle :
    • list : true si le champs est associé à un objet d'une liste (ex : objet JAVA qui est contenu dans une collection de type java.util.List) et false dans les autres cas (associé à un object JAVA POJO).
    • listInfo : qui est utilisé par RTFTemplate pour identifier les listes dans le cas de graphes d'objets.
    • name : nom du champs qui utilise la syntaxe.
    • description : cet élément est uniquement utilisé par la macro MS Word pour afficher la description du champs sélectionné.