HTML-Templates

The LIMBAS form/report editors are a good way of designing forms or reports with pixel precision using drag & drop. However, individual elements such as continuous text or data content are separated from each other and could previously only be combined with each other by the administrator using php scripts.

For newsletters, letters, invoices etc., however, it is often necessary to integrate data content such as customer names or prices directly into the body text. Since version 3.6, the new HTML template engine in LIMBAS allows this to be done conveniently with the Wysiwyg editor.

How it works

Normal text can be written in the new template element in the form/report editor, but html can also be written directly. The special feature compared to the text block element is that the template element recognizes various placeholders in the text, which are automatically replaced by the template engine for the user. For example, data content can be integrated.

Some texts, such as company data, are often used in several reports and should not be re-entered in each report. The template engine allows a modular structure of the forms/reports: text modules can be defined in a separate table of the type “Report templates” and integrated into other template elements with a sub-template element placeholder. The table must be selected when creating the template element.

It makes sense to define the report content in a data record name of this table and to reference this in the template element of the report editor: ${name}

Placeholder syntax

There are two ways to insert placeholders: Either with the ${…}-syntax or as an <lmb /> HTML element. Both (equivalent) variants are always shown in the following examples. Placeholders can also be inserted in the Wysiwyg editor via the “LIMBAS Templates” context menu. The <lmb /> variant is inserted in the background.

${Introduction}
// or<lmb type="template" name="Introduction" />// (always displayed)

${form: Introduction}
// or<lmb type="template" name="Introduction" target="form" />// (only displayed in the form)

${report: Introduction}
// or<lmb type="template" name="Introduction" target="report" />// (only displayed in the report)

After the opening bracket or as a “target” attribute, you can optionally specify a medium (form/report) for which the element is to be displayed. If no medium is specified, it is displayed for all media.

Data content

${->Name}
// or<lmb type="data" src="->Name" />

Recognizable by the arrow (->). For example, the content of the Name field is inserted here. The data comes from the data record for which the form is opened or for which the report is printed.

${=>Orders->Name}
// or<lmb type="data" src="=>Orders->Name" />

The table is implicitly specified by the data record, but it can also be specified explicitly with the double arrow (=>) for greater clarity. The same syntax can be used to query fields of a 1:1 linked table.

${->Customers->Name}
// or<lmb type="data" src="->Customers->Name" />

Link fields are also supported. The example above, for example, shows the name of the linked customer. Customer is the name of the link field in the current table.

${->Customer->Name|"No customer linked!"}
// or<lmb type="data" src="->Customer->Name" alt="No customer linked!" />

A default value can also be specified in the event that no value is entered for the field in the data record.

${->Name[key=value]} ${->Name[flag]}
// or<lmb type="data" src="->Name" data-key="value" /> <lmb type="data" src="->Name" data-flag />

Further options can be transferred in square brackets. These are supported/handled differently depending on the medium (form/report).

${->Name} // => "Alfred"
${->Name[show=description]} // => "First name"
${->Name[show=title]} // => "First name of the customer"
// or<lmb type="data" src="->Name" data-show="description" /> // => "First name"
// etc

Furthermore, the description or title of the field can also be displayed instead of the data (see table field settings).

Predefined options

There are predefined options for various field types.

Sub-element

${Introduction}
// or<lmb type="template" name="Introduction" />

Instead of this placeholder, for example, the report template with the name Introduction is inserted. The name of a report template must be unique. However, the report template table can also be filtered (e.g. according to the language of the logged-in user) so that the name is unique during the evaluation.

Dynamic data content

See reports.

Template groups

See reports.

Function call

${=FunctionName()}
// or<lmb type="func" name="FunctionName" />

Recognizable by the equal sign (=). The server evaluates the report_FunctionName function for reports and the form_FunctionName function for forms. This can be implemented in the script extensions. The report_/form_ prefix ensures that no system functions can be called directly.

Any number of parameters can be passed to the function (separated by commas). The number of parameters passed should match the number of parameters of the implemented function in order to avoid errors. There are 4 types of parameters:

Texts

${=FunctionName("Any string")}
// bzw
<lmb type="func" name="FunctionName"><lmb type="value" value="Any string" /></lmb>

Numbers

${=FunctionName(-42.5)}
// bzw
<lmb type="func" name="FunctionName"><lmb type="value" value="-42.5" /></lmb>

Data content (arrow ->)

${=FunctionName(->Customer->Name)}
// bzw
<lmb type="func" name="FunctionName"><lmb type="data" src="->Customer->Name" /></lmb>

Function call (equal sign =)

${=FunctionName(=OtherFunctionName())}
<lmb type="func" name="FunctionName"><lmb type="func" name="OtherFunctionName" /></lmb
// The inner function can again have the same types of parameters

The result of the function should be valid html that is inserted at the location. If the function returns an object of the TemplateElement class (extra/template/base/TemplateElement.php) instead, this is inserted at the position.

If/Else/Endif

${if =FunctionName()}...${endif}
// or<lmb type="if"><lmb condition="func" name="FunctionName" /></lmb> ... <lmb type="endif" />

${if ->ADataField}...${endif}
// bzw
<lmb type="if"><lmb condition="data" src="ADataField" /></lmb>...<lmb type="endif" />

${if =FunctionName()}...${elseif ->ADataField}...${else}...${endif}
// or
<lmb type="if"><lmb condition="func" name="FunctionName" /></lmb>
... 
<lmb type="elseif"><lmb condition="data" src="->ADataField" /></lmb>
...
<lmb type="else" />
...
<lmb type="endif" />

Evaluates the function report_FunktionsName/form_FunktionsName or the field ADataField. If the value evaluates to true, the part between if and endif is output in the report, otherwise not. Between the two, ${elseif …} and ${else} are also supported.

${Invoice}

${PersonData}
Invoice Text Blabla

${->Salutation} ${->First_name} ${->Last_name}, born ${=formatDate(->BirthDate,"d.m.Y")}

function report_formatDate($date, $format) {
    $stamp = strtotime($date);
    return date($format, $stamp);
}

Tables

You often want to display not just one linked data record in reports, but a table in which all of them are listed. The customer list or the list of items in the invoice are some examples of this in the demo.

The repetition is defined per table row. This means that several lists can be displayed one after the other in a table. You must also define which link is to be iterated over.

Use the Wysiwyg editor to select a field in the desired row and define the link via the Table->Data row menu item. The row is now displayed with a dashed border at the top and bottom.

If you are not working with the Wysiwyg editor, the repetition can be defined with the data-lmb-data-row attribute. The value of the attribute is the link field, in arrow notation (see data content). In the following example, all positions of the data set are iterated over:

<tr data-lmb-data-row="->Positions">...</tr>

It is also possible to iterate over “more distant” link fields, e.g. over the addresses of the first linked contact:

<tr data-lmb-data-row="->Contacts->Address">...</tr>

It is possible to nest repeated rows within each other, i.e. to create another table in a field of a repeated table in which rows are repeated again.

Data fields in the repeated row are then resolved correctly for each row.

If you want to iterate over the base table in list forms, the following syntax can be used:

<tr data-lmb-data-row="=>BasicTableName">...</tr>

Filter

The link that is iterated over can be filtered with an extension. For example, only a maximum of 5 data records can be displayed, or only all data records that have a specific field content.
A filter function, defined in an extension (see script extensions), returns an array with the optional entries gsr, filter and extension. These correspond to the parameters of the get_gresult function:

function report_filterTable() {
  $gsr = array();
  $gsr[tableID]...
  
  $filter = array();
  ...

  $extension = array();
  ...
  return array('gsr' => $gsr, 'filter' => $filter, 'extension' => $extension);
}

To enter a filter function, place the cursor in the corresponding row in the Wysiwyg editor and select the function via the menu item Table -> Repeat row filter. In HTML, the function can alternatively be set via the attribute data-lmb-data-row-filter. The notation of the function is the same as for the function placeholder.

Function calls

Function calls are normally only executed once, the result is output again in each row. If you want a function to be executed again for each row, one of its parameters must be a function call of the index or tableRowData functions (see below).

Utility functions

LIMBAS provides a range of functions for using the data from the repeated table in your own extensions.

Row index

The index($startFrom=0, $depth=0) function specifies the index of the current line.

If no parameter is passed, the index is 0-based. However, if you want to output the index in the first column of the report, for example, it should start at 1. To do this, the first parameter ($startFrom) can be set to 1.

If several repeated table rows are nested within one another, the second parameter ($depth) can be used to differentiate between the rows. By default ($depth=0), the index of the “closest” table row is returned. If, for example, you want the index of an outer table, $depth can be set to 1. The behavior is therefore similar to PHP’s continue or break commands.

Column index

The function colIndex($startFrom=0, $depth=0) is like index, except that the index of the column is returned.

Data record ID

The datid($depth=0) function returns the ID of the current data record. This is always defined by the data record for which the form/report is printed. In repeated table rows, the record ID of the linked record is returned.

The $depth parameter behaves in the same way as for index. The basic data record ID is saved as the “greatest” depth. If you are not currently in a repeated table row, you can get this using datid(0) or simply datid(). If you are in a repeated table row, you can get it with datid(1).

Table data

You often want to display a value in/under the table that is calculated from the previous entries in the table, e.g. a sum of the prices in the table.

The tableRowData() function can be used for this. If it is called within a repeated row, it contains the values of the row so far, i.e. all cells. All elements are listed within the cell:

$data[<Column-Index>][<Element-Index>]: mixed

If the function is called after a repeated line, it contains the values of all previous repeated lines. These are saved under the arrow syntax:

$data[<Link arrow syntax>][<Row-Index>][<Column-Index>][<Element-Index>]: mixed

For example, you add up all the values that appear as the 1st element in the 3rd column of the item list:

foreach ($data[->Positions] as $row) {
    $sum += intval($row[2][0]);
}