The Velocity Template plug-in can be used to generate complex text using the Velocity template engine syntax. The templates can contain loops, if-then-else blocks, and other expressions defined in the Velocity Template Language (VTL). For more information on Velocity and VTL, refer to the Velocity documentation, available at the following URL address: http://velocity.apache.org/?
A typical use of the Velocity plug-in is to substitute variables in a template. The syntax used by Velocity for a variable is $VAR or ${VAR}. For example, if you want to use the Velocity plug-in to generate a message to a user, you can define the template as follows:
Hello ${USER}: Your account was activated on ${DATE}.
You can click the Extract Variables button (in the Velocity Template tab of the File Adapter Configurator dialog box) to display a list of variables used in the template. If necessary, you can edit this list. Each variable will then be represented as an adapter input, available for mapping to a dataslot, or as a constant.
You can use the Velocity Template plugin for File Managed Adapters and Email Managed Adapters:
To configure Velocity Template plug-in:
1. For a File Managed Adapter, open the File Adapter Configurator dialog box, select the Mode as Write or Append and enter the file name. Select the Data Format as Velocity Template. After you have selected Velocity Template, the generic File Format tab is enabled and renamed to a format-specific tab called Velocity Template.
For an Email Managed Adapter, open the Email Adapter Configurator dialog box (refer to Configuringthe Email Adapter). Click Add to add a new part to the message. Select Velocity Template from the options in the enabled cell in the Format Plugin column. Open the Message Body tab.
2. Click the Velocity Template tab. The File Adapter Configurator dialog box for the Velocity Template plug-in appears:
3. In the top text area, enter the text of the template. Refer to the Velocity documentation for help on VTL. If you already have a file with the prepared template, you can load it by clicking Load Template.
This template generates a file in the following format:
Product list for <CompanyName>:
--> <Product1>
--> <Product2>
--> ...
We recommend using the ${varname} notation for the Velocity plugin. The company name and the list of products are defined in the variables ${company} and ${products} respectively. The ${company} is a scalar variable, while ${products} is a list.
4. The Velocity Template plug-in needs a list of variables, whose values will be set from dataslots. You can either enter the names of all such variables in the bottom text area, or click Extract Variables to build such a list automatically. In our example, clicking Extract Variables generates the list of variables shown below:
The Velocity plug-in configurator listed all the variables present in the template. Note, however, that the ${product} variable is used only to iterate through the ${products} list, so it should not receive its value from a dataslot as an adapter input. Edit the variable list, removing the ${product} variable.
Depending on the complexity of your template and the types of variables you are using, you may need to add or remove more variables.
5. The configuration of the Velocity Template plug-in is now complete. Click OK to close the File Adapter Configurator, which also opens the Dataslot Mapping dialog box for the File Adapter workstep.
You have one input parameter for each Velocity variable you listed. Map the "company" input to a CHARACTER dataslot, containing the company name ("@CompanyName"). Map the "products" input to a LIST dataslot, containing the list of products for the given company ("@CompanyProducts").
This process is ready to be published and executed. A sample output of the Velocity Template plug-in is shown below:
Product list for Fruit Co:
--> Apples
--> Oranges
--> Peaches
You can use the Velocity Template plug-in to also generate XML, HTML, Postscript, and other files. The example above shows only a small part of the Velocity template engine functionality. For more information on Velocity and the VTL syntax, refer to the Velocity documentation.
