Document templates

Templates allow the automatic generation of PDF documents, or printouts

Document templates in agileBase are typically used to create output that needs to be printed or emailed, for example form letters and especially anything that needs to be branded. They can be used for some quite complex and large documents, for example one customer uses them to create branded multi-page reports that are sold to customers, complete with custom fonts, layouts, images and colours.

The same templating system is used for both generating documents (which can be done automatically with a workflow or manually) and displaying output to be printed.

Each template is attached to a view and given a name.

Creating a template

Templates can be created using the built-in WYSIWYG editor, which allows simple presentation controls, like adding tables, headings and text formatting.

Alternatively and for complex needs, templates can be created manually. The templating language is Apache Velocity, which allows concepts such as variables, loops etc. to be used, i.e. simple programming features. The output format is HTML.

  1. Find or create a view which contains the data to be included in your output document. The idea is that each row in the view will correspond to one document, with the data from that row being merged in.
  2. Press the Print button in the toolbar, then the manage button
  3. You will then be prompted to create a template using the WYSIWIG editor, or upload one created outside the system.

Existing templates can also be edited or downloaded. Manually created templates with complex features such as variable setting and looping can’t be edited using the WYSIWYG editor

Including data

Each field in the view (included calculations), or parent table, can be merged in to the template by referencing the field name, preceded by a dollar sign. For convenience, a list of available fields is listed below the WYSIWYG editor, for easy copying and pasting into the template.

For those manually creating templates, a field name becomes a variable to reference by

  • writing it in lower case
  • replacing spaces with underscores (_)
  • removing all characters that are neither letters nor numbers

Here’s an example of a template being updated in the WYSYWIG editor:

Template editing

Using templates

Templates can be used when generating documents, manually or using an automated workflow.

They can also be used as printout templates to let users print data from the system formatted as you wish.

Advanced templating

Convenience features

As well as data, various convenience features are available for insertion into a template.

Here are some of the most commonly used utility functions.

Code Description
$viewTools.getCalendar() Return a Java Calendar object representing the current date and time
Also useful: $viewTools.getCalendarConstant(String name), e.g.
#set($dayOfWeek = $viewTools.getCalendar().get($viewTools.getCalendarConstant("DAY_OF_WEEK")))
$viewTools.getDatestampString() Output the current date in the format 31/01/2023
$viewTools.getDatestampString(“format”) Output the current date/time in a custom format e.g. $viewTools.getDatestampString("EEE, d MMM yyyy HH:mm:ss")
$viewTools.getDatestampString(calendar, “format”) Output the given date/time (as returned by $viewTools.getCalendar() in a custom format
$viewTools.getMathTool() Return a MathTool for doing maths
$viewTools.getNumberTool() Return a NumberTool for formatting and converting numbers
$viewTools.getRandomInt(bound) Return a random number >=0 and <bound
$viewTools.spelloutCurrencyFromString(“number”) Convert e.g. “12.50” into “Twelve pounds 50 pence”
$viewTools.spelloutNumber(number) Convert e.g. 1,200 into “One thousand, two hundred”

Complex data merging

Here are some of the most commonly used data retrieval / formatting functions.

Code Description
$view.getReportDataRows() Return all rows in the current view e.g.
#set($rows = $view.getReportDataRows())
#foreach($row in $rows)
$view.getReportDataRows(view) Return all rows in the specified view e.g.
#set($myView = $view.getReport("my view"))
#set($rows = $view.getReportDataRows($myView))
$view.getReportDataRows(view, n) Return the top n rows in the specified view
$view.htmlTable() Output a HTML table containing the rows of the current session view (the last one the user opened), with session filters applied
$view.htmlTable(view, rows) Given a list of rows as returned by getReportDataRows, from the specified view, format them as a HTML table e.g.
#set($myView = $view.getReport("my view"))
#set($rows = $view.getReportDataRows($myView))
$view.htmlTable($myView, $rows)
$view.htmlTable(“table name”, “child view name”) For the given table, find the record being edited by the user. Filter the given view (which must contain the ID field for the table) by the ID of that record and output the rows as a HTML table. e.g.
$view.htmlTable("organisations", "all contacts")
might output the contacts belonging to the current organisation in the user’s session
$view.htmlTable(“table name”, “child view name”, true/false) As above, but if true is added, include any columns which are empty for all records (they are excluded by default)
$view.htmlTableTransverse(view, rows) As per $view.htmlTable(view, rows) above, but swap the axes in the table, i.e. field names will appear down the left, each row will be output as a column
$view.htmlTableTransverse(“table name”, “child view name”) As per $view.htmlTable(“table name”, “child view name”) but again with swapped axes

…and here are some of the most commonly used session functions. Each user gets a new session when they log in, it stores information about the system’s current state for them.

Code Description
$sessionData.getReport() Return the last view the user looked at
$sessionData.getTable() Return the last table the user looked at
$sessionData.getRowId() Return the ID of the record last loaded
$sessionData.getTile() Return the open tile

There are many more functions than these available, indeed the whole of the agileBase user interface is created with templates including functions of these three types.

The entire templating API is beyond the scope of this documentation but if you do wish to create any template functionality not covered by the above, it’s probably possible. Please get in touch with us to discuss your needs and be pointed in the right direction.

Using Apache Velocity features

In the examples above are some uses of simple programming code. A full reference for what you can do with the Apache Velocity language is here:

Last modified June 22, 2021: Tag all docs pages (c49ef8f)