Table Generation Handlers allow to create dynamic datasets-derived tables inside Open Office documents. In order to use this type of handler, it should be 'placed' just above a skeleton-table, which will be expanded and populated with data, as shown below.

Sample Table Generation Handler usage

The attached TableHandlers Inforama project contains few letters that shows how to use them.

Currently there are four types of supported Table Geneation Handlers. Each of them is described below.

$iterateRows

This is the most basic handler that allows to iterate the underlying data set on a row-by-row basis.

It should be used in one of the following forms:

 $iterateRows{[dataSetName]} 

Fills the entire content of the first table below the handler occurrence with all data from the specified data set.

 $iterateRows{[dataSetName], [startRowIdx]} 

Fill the content of the first table below the handler occurrence starting at the specified table's row. One possible usage of this handler is to specify a custom table header and populate the remaining part of the table with data. The screenshot below illustrates it.

Sample iterateRows handler usage

 $iterateRows{[dataSetName], [startRowsIdx]-[numRows]} 

Fill the content of the table below handler occurrence starting at the specified table's row and populating the data to the specified number of following rows. The screenshot below shows a usage of this form of the handler that willl create a table with every other row filled with data and the footer (last row) preserved.

Sample iterateRows handler usage

Sample Letters using $iterateRows handler

• ratedFilms - lists all filmes that have a rating specified by the $P{rating} parameter.

• categories - lists all categories, within each category lists first $P{numInCategory} films belonging to this category.

• rentals - lists all rentals of the customer specified by the $P{customerId} parameter.

$iterateCells

This handler allows to create a table with an arbitrary number of columns and fill it with data from the underlying data set's specified column. It should be used in the form:

 $iterateCells{[dataSetName], [numCols]} 

The handler task is to fill the content of the table below handler occurrence. The second arguments specifies the number of columns in the result table.

Sample iterateCells handler usage

Sample Letters using $iterateCells handler

• filmActors - lists all films from the category specified by the parameter $P{category}, and for each film lists its actors. The number of columns of the actor's table is specified by the $P{colsActor} parameter.

$createTable

This handler is the most flexible way of creating dynamic tables inside Open Office documents. It should be used in the following form:

 $createTable{[dataSetName], [subHandler1], [subHandler2], ...} 

The first argument specifies the data set while the following arguments define a list of subhandlers providing hints to the table formatting, etc. In most cases a single subhandler specifies one 'property' of the result table by providing a groovy expression which, after being evaluated, is interpreted by the Table Generation Engine.

List of supported subhandlers:

• $numCols{...} - defines the number of columns that should appear in the result table. The content of this handlers is expected to evaluate to a numeric value. If this handler isn't provided the result table will have the same number of columns as the data set.

• $include{...} - indicates that the current data set's field should be included in the result table or not. The content is expected to evaluate to a true/false value. If the tag isn't provided then all data fields from the data set will be shown in the result table.

• $value{...} - defines a value that should appear in the current cell (the value can be XSL-FO block container element). If this handlers isn't provided the value from a table below will be used.

• $hasData{...} - if the content of this handler evaluates to false then the table creation process stops. By default (when the tag isn't provided) the process stops when there are no more data in the underlying data set. The content of this tag should evaluate to true/false value.

• $cellTemplate{...} - the tag should return a cell style template that will be applied to the current cell. Cell style templates can be referred to by using the syntax: template_name.cel(column, row), for example: myTemplate.cell(0,0) will get the style of the left-corner cell from the template named "myTemplate";

• $includeCell{...} - indicates whether the current cell should be included in result table or not. The tag is similiar to the "$include", the difference is that it allows to ommit the whole XSL-FO cell element. It should evaluate to true/false. If the tag isn't provided each cell is included.

• $step{...} - when the content of this tag evaluates to true then the underlying data set "internal state of iteration" is moved to the next data field for each cell of the result table. The default behaviour (when the tag isn't provided) is the same as $step{true}

The screenshot below shows the sample usage of this handler.

Sample createTable handler usage

Sample Letters using $createTable handler

• rentals2 - lists all rentals of the customer specified by the $P{customerId} parameter. All overdue rentals are highlighted (red colour).

• subFilms - allows to specify a sub-table that will appear for each film.