Using the Velocity template engine

Velocity properties file. 2

Variables supported by Ebase. 2

Field variables 2

Table variables 3

Debugging template errors 3

Invoking Velocity from a component 3

Introduction

Ebase provides integration with the Velocity template engine supplied by Apache. This can be used to create complex template-based data formats and inserting form field values and table cell values into the data stream. Examples of where this can be useful include:

Creating HTML email messages, in particular messages that contain tables from the Ebase form.
Creating custom report pages. This can be achieved by creating a form page with a single display only CHAR field and clicking the HTML checkbox on the presentation properties. Then invoke a Velocity template to format the data and output it to the field.
Creating XML documents.

Basically, you supply a template that can contain special statements (VTL) recognized by Velocity. The template is parsed and executed and the result is returned. This is best illustrated by a simple example. If we have a template test1.vm containing the following:

<HTML>

<BODY>

<TABLE>

#foreach( $field in $fields )

#if ( $field.name.startsWith("F") )

<TR>

<TD>$field</TD>

<TD>$field.name</TD>

</TR>

#end

</TABLE>

</BODY>

</HTML>

Then execute this template:

FPL:

API based language (Javascript):

With FPL, the formattemplate function is used:

set RESULT = formattemplate('test1.vm');

var result = VelocityServices.invokeTemplateFromFile("test1.vm");

The result will be an html page containing a table of all form fields beginning with “F” and their values. References to $field are replaced with the field value, and references to $field.name are replaced with the field name.

Anything beginning with a # is recognized as a Velocity VTL statement – the example above illustrates the use of #foreach, #if and #end statements. Anything beginning with a $ represents a variable to be resolved by the Ebase system. Details of all variables and their properties are given below.

Full details of the Velocity template engine and its syntax language VTL are available here. The level of Velocity implemented in Ebase is 1.4.

Invoking Velocity from Ebase Xi

FPL:

API based language (Javascript):

This is done using the formattemplate FPL function. The template to be invoked can be specified either as a file name (the default) or it can be specified as a string. Full syntax for this function is:

Syntax: formattemplate(string1 [ , string2 ] [ , loglevel ] )

Description: Invokes the Velocity template engine and returns a formatted string. Parameters are as follows:

string1 Specifies either the template filename within the template directory (see below) or the template itself depending on the contents of string2.

string2 An optional parameter. If specified it must contain either:

‘FILE’ indicates that string1 specifies a filename within the template directory or…

‘INLINE’ indicates that string1 contains a template string

If omitted, the default for string2 is ‘FILE’.

Loglevel An optional parameter. If specified it is an integer that designates the logging level. Only Velocity messages of the specified logging level or higher will be issued. Logging levels are:

1 Debug

2 Info

3 Warn

4 Error

If omitted, the default for loglevel is 2.

Examples: set RESULT = formattemplate('exampleTemplate.vm');

set RESULT = formattemplate('#foreach ( $field in $fields )<field>$field</field>#end', 'INLINE');

Use one of the methods in VelocityServices.

Examples invoking a Velocity template from a file:

var result = VelocityServices.invokeTemplateFromFile("test1.vm");

var result = VelocityServices.invokeTemplateFromFile("test1.vm", VelocityServices.LOG_LEVEL_DEBUG);

Examples invoking a Velocity template from an inline String:

var template = "<HTML><BODY><TABLE>#foreach( $field in $fields ) .. ";

var result = VelocityServices.invokeTemplateFromInlineString(template);

var result = VelocityServices.invokeTemplateFromInlineString(template, VelocityServices.LOG_LEVEL_DEBUG);

Velocity properties file

Velocity requires a properties file named velocity.properties. This properties file is located in the ebaseConf directory of the web application on the Ebase Xi server e.g. UfsServer/tomcat/webapps/ufs/ebaseConf. This file requires the following property which specifies the location of the template directory:

file.resource.loader.path=../../velocityTemplates

In Tomcat systems, the root directory is UfsServer/tomcat/bin, therefore the specification above refers to directory UfsServer/velocityTemplates.

Variables supported by Ebase

A variable is anything that appears immediately following a $ within a template. Velocity templates within Ebase support variables that refer to elements within the Ebase form. The following variables are supported:

Field variables

Referred to as $fieldname e.g. $ADDRESS_LINE_1, $CITY etc. A reference to a field in this way returns the value for the field. For numeric fields, any formatting commas are removed and the decimal point i.e. comma or point, will be taken from the formatting language used for the system’s default language. For date fields, the value returned is in the format defined in server property data literal format.

All fields in a form can also be referenced using the following syntax (as shown in the introduction):

#foreach( $field in $fields )

……..

#end

In this case, each field is referred to as $field within the loop.

References to Ebase system variables (that begin with a $) should be made as per the following example:

${$LANGUAGE}

Field variables also support a number of additional properties:

$fieldname.formattedValue

Returns the value for the field formatted according to the formatting language in use for the form. For numeric fields, formatting commas are included. Date and time fields are presented in the same format as seen by the end user running the form. This property can be useful when creating information to be viewed by the end user e.g. an email, report page etc. All field values are displayed in the same format as presented to the end user.

$fieldname.unformattedValue

Returns the unformatted value for the field. This is the same as specifying $field.

$fieldname.valueLength

The length of the value for this field. This will be 0 if the field has no value.

$fieldname.name

The form field name.

$fieldname.type

The field type. This will be one of the following:

BOOLEAN

CHAR

CURRENCY

DATE

DATETIME

INTEGER

NUMBER

TIME

$fieldname.presentationType

The field presentation type. This will be one of the following:

BUTTON

CHECKBOX

LABEL

PASSWORD

RADIO

SELECT (for dropdown lists)

TEXT

TEXTAREA

Table variables

Referred to as $tablename e.g. $CUSTOMERS. The only references supported for tables are to loop through all rows or to refer to the single supported property numRows. An example of looping through a table to extract cell values is shown in the example below which creates an HTML table:

Table has $CUSTOMER.numRows rows

<table>

#foreach ( $row in $CUSTOMER )

<tr>

<td>${CUSTOMER-NAME}</td>

<td>${CUSTOMER-NUMBER}</td><td>${CUSTOMER-CREDIT}</td>

<td>${CUSTOMER-PHONE}</td>

</tr>

#end

</table>

Note that this example also shows the formal syntax for referring to variables i.e. as enclosed in {}. See Velocity documentation for details.

Each table row also supports the rowNumber property i.e. $row.rowNumber.

Debugging template errors

All Velocity messages are written to the execution log viewed from the designer View --> Execution Log. When an error occurs, a generic error message is displayed in the browser “Error evaluating expression formattemplate(……)”. The details of the error can only be displayed by looking at the execution log.

Note that a reference to a $ variable that does not exist results in the variable name not being replaced in the output stream.

Invoking Velocity from a component

When a Velocity template is invoked from an event that is part of a component, all field and table name references in the template will be automatically prefixed with the component prefix i.e. the template should be constructed using component field names, not the prefixed form field names that result when a component is inserted into a form. If the resulting fully prefixed name does not exist, the system will then search for the field using the unprefixed name.

However a reference to the name property of a component field will return the fully prefixed name of the field as it appears in the form.