Template expression
Template expressions within a document template start with a template header (similar to the function header for OSI functions). For the template header line (1) OSITemplate has to be assigned as paragraph style. The end of the template is indicated by an end statement. The paragraph style OSIEnd has to be assigned to the end (2) statement.
Any text outside template definitions will be ignored and does not become part of the generated document. Text after the template header line and before the end line becomes part of the generated document.
Document templates have to start with a main template or expression. The name of the main template has to be the same name as the template document name (without extension). Hence, template document name must not contain spaces or other special characters. One may also refer to a different entry point, which is defined as template in the template document. When referring to another entry point name, the entry point to the template must be declared when calling the template.
Template expressions may refer to option variables, which have been set in the configuration or ini-file or by the calling program. Option variables are referred to by name enclosed in %...%.
In order to support function variables, template variables (3) may be defined similar to OSI function variables in the VARIABLES section. In contrast to OSI functions, template variables do not require a special section, but the paragraph style OSIVariables. Variables have to be defined immediately after the template header. Variables must not be defined after first text or code line. As long as variables are not defined as global variables, those are defined in the scope of the template expression, i.e. between header and end, only.
After variable definitions template text, text references and template code may be defined. Defined fixed text (4) will be copied to the document with text formatting as being defined in the template (what you see is what you get). In order to invoke text from the database, operation paths (5) may be defined enclosed in $...$. For displaying the text provided via the operation path the current text formatting as being used for the operation path will be used. Any paragraph style except reserved OSI... styles may be assigned to fixed text and operation path references
Code lines (6) within the template function have to be defined with paragraph style OSICode. When defining code lined, no text will be generated from the code line. In order to generate text
Several specific types of template expressions are supported in addition:
- Template function - describes a function within document template
- Table template - describes a table with several rows
- Row template - describes a row in a composed table
(1) void SampleTemplate ()
(3) global int count = 0;
(3) SET<HierarchyTopic> &topics = HierarchyTopic(%ItemName%);
(4) This is my fixed text
(5) $topic(0).definition.definition.characteristic$
(6) topic.SubTopicTable();
(2) end
Changing text formatting within an operation path reference may cause errors in the generated document.
When writing a document template, all text outside OSI template expressions will be ignored, except header and footer. Variables will be replaced when being referenced within a template body. In order to define variables for header or footer, document variables (fields) have to be defined (in LibreOffice Insert/Fields). One cannot directly refer to OSI text variables enclosed in $...$ within header or footer sections.
In order to define document variables, one may define a field in LibreOffice (set variable) within an OSI template section (text part). The value assigned to the variable may be refer to a database property or OSI expression enclosed in $...$. After assigning the variable, the current value will be displayed in all places, which refer to the defined field (show variable). In order not to show variable settings within the document, "set variable" areas as in the example below should be hidden.
set variable my_date=$Date&
Template expressions are used for executing a number of OSI statements. Often, template functions are used for calling subordinated template expressions or for calculating derived values.
Template functions start with a function header line, which requires the OSIExpression paragraph style. Template expressions are terminated with an end statement, which requires an OSIEnd paragraph style.
Any spaces or text within a template function will be ignored. Code lines within the template function have to be defined with paragraph style OSICode.
collection void DSC_Topic::SubTopicTable()
if ( tryGet(0) )
if ( sub_topics.count > 0 )
sub_topics.SubTopic1Table();
end
Usually, page formatting as being defined for the default page format is used. In order to change the page format, it is suggested to change the default page format rather than assigning a different format. When using a page format different from the default page format, the first element within the document template should be a paragraph. In this case, the page formatting defined for the document is copied to the generated document. Otherwise, the generated document used the default page format.
In order to start a page with a different page format in the document, the page break together with the new page format has to be defined within a valid document template expression, e.g. as manual page break immediately after the document template headline. Page breaks defined outside OSI template expressions do not affect the generated document.
Table templates are used for displaying instances of a collection in table rows. Table templates (1) start with a table template header line, which requires the OSITable paragraph style. Table templates are terminated with an end statement (2), which requires an OSIEnd paragraph style.
Table templates are collection templates and will iterate for the last row found in the table definition. Table headlines (2) can be defined as first row(s) in the table. All table lines except the last (3) one are considered as static lines and will appear only once in the table. No text replacement will be done in static table lines, i.e. static table lines may refer to fixed text, only. The last table line (3) will be repeated for each instance of the collection referenced by the calling object.
A table template may contain an initial section before table begin, which will not iterate. Since no object instance is selected in the initial section (paragraph, headline), those may contain global, static or parameter data, only.
Code lines may be inserted before the first and after the last table row as well as in table cells. Code lines within the table template have to be defined with paragraph style OSICode. Code lines (4) immediately before and after the table will be executed for each table row generated for the last table row. Thus, this code can be used for calling other table row templates in order to create complex tables. Table templates may contain the table definition and expression code, but should not contain text paragraphs or multiple tables.
In case of defining multiple row table templates, all rows are created for each instance in the collection. Conditional rows can be created by using expression (see example below)
(1) collection void DSC_Topic::SubTopic1Table()
(2) Title 1 Title 2
(3) §definition.name$ $definition.definition.characteristic$
(4) if ( definition.definition.example.count )
(4) DSC_Topic::Example();
(4) sub_topics()->SubTopic2Table();
(2) end
Table templates should be marked as collection functions. Otherwise, template call may fail, when no instance is selected in the calling property handle.
Usually, all instances will be printed to the table. In order to restrict the number of lines to be printed, a filter might be set for the collection. One also may pass a count (__count) to the table template. The parameter has to be defined an integer (INT) in the table template headline and has to be set by the calling template.
When defining a __count parameter in the template head line, generating table lines starts with the instance currently selected in the collection. The __count parameter contains the number of instances to be processed.
When the table template returns, the next/previous instance after the last printed to the table is positioned. When the end of the collection had been reached, no instance is positioned in the collection.
persons.first(); // position first instance in collection
while ( persons.positioned() )
persons.Table2(10); // print next ten lines as long as table returns true
...
collection void Person::Table2(int __count) // table template header
...
Usually, table rows are ordered according according to selected order key (ascending sort order). In order to achieve a descending table row order, the function header needs a __descending parameter. Data type and passed value does not matter, because the existence of the parameter is checked when generating the template code, i.e. at a time point, where no parameter value is available.
Row templates are usually called from within a table template in order to add additional rows for the selected object instance. This allows creating complex tables with different row formats. Row templates (1) start with a row template header line, which requires the OSIRow paragraph style. Row templates are terminated with an end statement (2), which requires an OSIEnd paragraph style.
The row (3) defined in the row template should fit into the table definition calling the row template. Row templates are used for creating tables with different generic rows. A row template should contain only one row, which fits into the table calling the row template. Only the first row specification in the template will be considered as row template. Additional rows or paragraphs will be ignored.
In order to call further row templates, code lines may be inserted before and after the row as well as in row cells. Code lines (4) within the table template have to be defined with paragraph style OSICode. Code lines (4) may be used for calling subsequent row templates.
(1) void DSC_Topic::SubTopic2Table()
(3) $definition.name$ $definition.definition.characteristic$
(4) if ( definition.definition.example.count )
(4) DSC_Topic::Example();
(2) end