Before describing how to practically create a template using the template editor, it is probably helpful to introduce some basic concepts which templates are based on.
The Document Publisher end-user point of view
From the Document Publisher user point of view, a template is an entry in a combo-box which has to be chosen when creating a document in Modelio. See the figure below.
The chosen template will actually define the contents of the produced document and its look along with the chosen style sheet.
The Document Publisher generator
When producing the document, the Document Publisher generator uses the template to output the resulting document from the model. Note that the end-user does not need to cope with this aspect. See the figure below.
A template from inside
A template is composed of a set of nodes. Nodes are the atomic processing units of a template; this means that the real production work is actually carried out by the nodes.
The set of nodes is structured as a tree. This simply means that nodes may have children nodes.
The general pattern of a node behavior is shown in the figure below:
The Document Publisher calls the execute() method of each node of the template, passing it an element of the model. On return, the node produces its result. The ordering of the node calling sequence is defined by the structure of the template, this will be detailed later.
Nodes can be of three different kinds: navigation, production or special. These nodes differ by the nature of the result they produce and by their basic behavior.
Production Nodes
Production nodes are used to produce document data. As with any other node a model element is passed to their execution method. The result of this execution is some document data that will be added to the document content.
Document publisher can produce DOCX (Word Open XML) or HTML documents. Production nodes will therefore produce DOCX or HTML fragments. Once concatenated by the Document Publisher generator, these fragments will compose the final document.
The template editor proposes several production nodes covering different needs, from producing plain text to building tables. This set of available production nodes is detailed later in this document.
Navigation Nodes
Navigation nodes are used to navigate in the model.
Their main characteristic is that they produce a set of elements and a means of looping on this set of elements.
Navigation nodes may have child nodes. These child nodes are typically production nodes but any kind of node is possible.
A navigation node will execute all its child nodes for each model element of its resulting set of elements. Let’s see this in the following example.
This navigation behavior is the standard one for a navigation node. The loop is run on the model elements obtained by the navigation node "N", and each child node ("P1" & "P2") is executed for each iteration. This navigation mode is called ‘standard loop’
Navigation nodes may be configured in the template so that they first loop on child nodes, calling the execute method on each element obtained by the navigation mode. This navigation mode is called ‘switched loop’. It is illustrated by the figure below.
In the ‘switched loop’ mode, the child nodes "P1" and "P2" are first executed in sequence on the first element, then on the second and so on.
Note that ‘standard loop’ mode is used by default.
Special Nodes
Special nodes provide a mean of controlling the execution flow of the template. They mainly allow a mechanism similar to defining a procedure and calling a procedure. Procedures nodes are a very efficient way of re-using some parts of a template within a template, they also allow recursion.
The following figure illustrates the use of special nodes.
