Overview

RTFTemplate is RTF to RTF engine, which is enable to merge RTF model (Template) with data comming from JAVA object (Context). RTFTemplate can generate RTF document, which is the result of merge of RTF model and data.

Since 1.0.1-b8 version, RTFTemplate was re-designed to be more modular. If you are using old version of RTFTemplate you can go to the old documetation here.

To use RTFTemplate you must :

• design your RTF model with MS Word by using merge fields (MERGEFIELD), hyperlink fields (HYPERLINK) and bookmarks (BOOKMARK, to manage start/end loop).
• prepare your context with JAVA objects.
• merge your RTF model (Template) with your JAVA objects (Context) by using RTFTemplate.

After merge step, merge fields (MERGEFIELD) and hyperlink (HYPERLINK) will be replaced by your data comming from your JAVA context. Bookmarks (BOOKMARK) are used to set start/end loop of a list which contains JAVA objects (ex : to generate for instance a RTF table (RTF rows) by iterating on this thist).

To start using RTFTemplate, you can go to user guide.

Generation process

RTFTemplate generation process is executed with 3 steps :

• Step 1 : RTF model source parsing which load RTF model into the RTFDocument structure. RTFDocument is composed with the whole RTF model, and cut RTF elements of the model, which are interpreted by RTFTemplate as fields (RTFField), bookmarks (RTFBookmark)...
• Step 2 : transformation process. The RTFDocument structure is transformed to :
  • replace RTF code with specific macro swith template engine selected (ex : replace bookmark with #foreach macro when RTFTemplate is used with Velocity).
  • remove some RTF code. For merge fields (MERGEFIELD), RTFTemplate remove the character " which include merge fields.

  Result of this step give a new RTFDocument which contains macro of the selected template engine.

• Step 3 : merge the transformed document with JAVA context. This step use the selected template engine to merg etransformed document with JAVA context to give the RTF target document which contains RTF model and the data.

You can find here a schema which explains RTFTemplate process generation.

RTF model sample

Here a RTF model sample designed with MS Word :

After merge of RTF model with context (JAVA object), RTF target document obtained is :

How use RTFTemplate?

Here JAVA code used to obtain the last RTF target document :

  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);

This sample use default configuration of RTFTemplate (ex : Velocity is the default template engine), but it's possible to customize RTFtemplate to use another template engine like Freemarker.

ATTENTION this sample is not the optimal strategy of RTFTemplate using. If you have performance constraint, go to the section how optimize RTFTemplate?

New API

Before 1.0.1-b8 version RTFTemplate was based only on Velocity template engine. Today RTFTemplate can be configured with Spring XML file. Now you can implement your template engine or redefine existing implementation of template engine as you want.

For more informations about RTFTemplate configuration, click here.

By default RTFTemplate implement Velocity et Freemarker templates engines.

The new API is able to separate the different steps of generation process of RTFTemplate. Each step can be too implement as you want.