Command Reference CIB jsMerge
Functions
Processing Data within Tables
AllgemeinresetRec(tablealias)
hasRec(tablealias)
nextRec(tablealias)
mergeRec(tablealias)
Characteristics of Dynamically Generated Tables
Allgemein
CIB jsMerge provides the ability to read one or more datasets (e.g. in a while-loop) out of custom tables and merge them into the result documents. This creates a dynamic table in the resulting document. The input-datasets can stem from CSV or XML data sources.
For the purpose of creating dynamic tables from that data a set of special functions has been implemented. A dynamic table is identified by a table alias name. This alias name is defined either via
- Multi nodes in a XML data source or
- the name of the CSV data source (when using a single CSV) or
- The record in the control file of a multi CSV data source
The variable is called via the name defined in the data source („variableName“). To call a variable from a multi-data source the alias name has to be added as prefix to the variable name.
Example:
{# ref(“<tablealias>.<variableName>”)}
As an illustration, the following example shows some of the functions introduced for processing tables:
|
{#while(hasRec(“Persons”)) {‘x
{#nextRec(“Persons”)}}} |
Note
The functions „resetRec()“, „hasRec()“, „nextRec()“ and „mergeRec()“ can be used without “tablealias”(or with “tablealias”=null). In this case, these functions affect all dynamic tables used in the template project. Application examples would be serial letters or copies.
resetRec(tablealias)
The function "resetRec(tablealias)" positions to the first data record in the table "tablealias".
If this function is used without the parameter "tablealias" or with "tablealias"=null, all existing tables will be positioned to the first data record. This also sets all data record counters (=return value of the function "mergeRec(...)") to 1.
hasRec(tablealias)
The function „hasRec(tablealias)“ returns “true” if the current record exists in the table “tablealias”. If the table is empty or the end of the table is reached (e.g. after “nextRec()”) the function returns “false”.
If this function is used without the parameter “tablealias“ or with ”tablealias“=null, the function „hasRec()“ only returns “false” if the end of all tables has been reached. Otherwise the result is “true“.
nextRec(tablealias)
The function “nextRec(tablealias)“ selects the next entry in the table specified by “tablealias“.
This function behaves like “{ next tablealias }“ with the difference that it is necessary to access the variables of the selected dataset using the table alias name, i.e. the variables have to be called with the prefix:{#ref("<tablealias>.<variableName>"))}
Example:
{# text(ref(“Person.CustomerID”));
nextRec(“Person”);
text(ref(“Person.CustomerID”));}
In this example the „customerID“ of the first and the second dataset will be copied to the resulting document.
If the function „nextRec(tablealias)“ reaches the end of the table „tablealias“, it sets all variables of this table to an empty value “” and the function „hasRec(tablealias)“ will return “false” the next time it is called and the counter „mergeRec(tablealias)“ is set to “0”. Any further calls of the function „nextRec(tablealias)“ will not change that state. If the function ”nextRec()“ is used without the parameter „tablealias“ or with „tablealias“=null, all tables will be set to the next record. In this case there is a global internal couter that counts all calls of “nextRec()”. This counter is initialized with 1 and will be reset to 1 by “resetRec()”. The counter will not increase if the end of all available tables has been reached.
mergeRec(tablealias)
The function „mergeRec(tablealias)“ returns the number of the currently selected dataset in the table “tablealias” (starting with 1 for the first selected dataset).
Example:
|
{#while(hasRec(“Persons”)) { if((Number(mergeRec(“Persons”)) % 2) == 0) {‘x
} else {‘x
} nextRec(“Persons”);}} |
If this example is executed without the parameter “tablealias” or with “tablealias”=0, the function returns the state of the internal global counter used in the function “nextRec()”.If there is a table-overflow, „mergeRec(tablealias)“ is set to „0“.
Characteristics of Dynamically Generated Tables
The following special characteristics have to be considered when working with dynamically generated tables in LibreOffice:
to realize hidden paragraphs in LibreOffice there has to be a minimum of one character in the paragraph (an "x" in our examples here). This character then has to be formatted as "hidden". Paragraph markers cannot be set as "hidden" like in MS Word.
Note:
In the resulting document, every data record will be written in a separate
table. In the input document, de paragraphs before the table have to be
formatted as hidden so the optical representation in the output document looks
like one table:
|
{#while(hasRec(“Persons”)) {‘x
{#nextRec(“Persons”)}}} |
(please
also see the example in chapter mergeRec(tablealias))
In contrast to MS Word, LibreOffice does not interpret these table rows as one table.
That also means that a defined table heading is not repeated on following pages if the table spans several pages.