Modelio Template Editor Tutorial

Modelio
Tutorials
Document Publisher Template

Editor
Author: Modeliosoft
Version: 1.0
Copyright: Modeliosoft
Modeliosoft
21 avenue Victor Hugo
75016 Paris
www.modeliosoft.com
Document Publisher Template Editor
Sommaire
1 Introduction ................................................................................................................ 3
1.1 Customizing Document Publisher documents ................................................................. 3
1.2 The five customization levels ........................................................................................... 4
2 Designing a template ................................................................................................... 6

2.1 Template design ............................................................................................................... 6
2.2 What is a template ........................................................................................................... 7
2.2.1 The Document Publisher end-user point of view .......................................................... 7
2.2.2 The Document Publisher generator .............................................................................. 8
2.2.3 A template from inside .................................................................................................. 8
3 First steps with the “hello world” template .................................................................13

3.1 STEP 1 – Creating the hello world template .................................................................. 13
3.2 STEP 2 – Adding a production node ............................................................................... 16
3.3 STEP 3 – Testing the Hello world template .................................................................... 18
4 Deeper into the template editor .................................................................................21

4.1 Context and node creation............................................................................................. 21
4.2 Using variables in production......................................................................................... 21
4.3 Production nodes ........................................................................................................... 21
4.4 Navigation nodes............................................................................................................ 23
4.5 Control nodes ................................................................................................................. 24
5 A real example: the “Use case catalog” template .........................................................25

5.1 Dividing into procedures ................................................................................................ 25
5.2 Main sections ................................................................................................................. 26
5.3 Actor & use case tables .................................................................................................. 27
5.4 Use case diagram production......................................................................................... 28
5.5 Detailed use cases .......................................................................................................... 29
5.6 Reference towards a scenario ........................................................................................ 30
5.7 Interaction table ............................................................................................................. 31
5.8 Scenario details .............................................................................................................. 32
6 Extending an existing template ...................................................................................33

6.1 Opening a predefined template ..................................................................................... 33
6.2 Basic extension ............................................................................................................... 33
Copyright Modeliosoft 2009

21 avenue Victor Hugo, 75016 Paris Page 2
1 Introduction
This tutorial presents how to make a Document Publisher Template using the Modelio
Documentation Template Editor.
A Document Publisher Template is an archive file designed and produced by the Modelio
Documentation Template Editor that can be later installed in Modelio where it is used by Document
Publisher to produce documentation.
The template defines which documentation contents have to be produced from the elements of the
user model and how these contents are organized in the output document. The template is therefore
literally driving the documentation generation process when run by the Document Publisher module
to produce documentation.
Templates are one of several available techniques to produce specific documents with Document
Publisher. The chapter “Customizing Document Publisher documents” is a quick overview of these
techniques and a quick guide about the recommended technique in each context.
The chapter “Designing a template” details template design and introduces the concept of “node”,
core of Modelio documentation templates.
The chapter “First steps with the “Hello World” template” details a concrete example of template
design and development.
The chapter “Deeper into the Template Editor” presents advanced concepts about node creation,
and the list of all predefined nodes.
The chapter “A real example: the “Use case catalog” template” details step by step the content of a
predefined template provided by Document Publisher.
The last chapter “Extending the template editor” explains how predefined templates can be modified
and extended.
1.1 Customizing Document Publisher documents
Modelio Document Publisher produces rich documentation from an annotated UML model. The
overall and perceived quality of the produced documentation depends on several factors.
MODEL CONTENTS
The first factor is the quality, pertinence and quantity of the model annotations added by the user to
the model. It should be obvious that a model in which no descriptions are provided for the model
elements will probably result in poor documentation. This factor does not directly depend on
Modelio Document Publisher but rather on the end-user.
DOCUMENT CONTENTS
Not only does the model need to be properly documented, but also the way the model is browsed
must be relevant. This relevance resides in the fact that the actual contents of the produced
document fit the needs of the expected reader. The trick is to remember that the reader’s

expectations depend…on the reader. Therefore, it is necessary to provide the right contents to the
right reader. This is where templates are helpful, since they define how the model is exploited and
which data is to be extracted from it.
DOCUMENTATION LOOK
Documents must be pretty (or at least perceived as such). Document Publisher uses style sheets to
format the documents it produces. Customizing the used style sheet is possible.
As a direct consequence of what has been stated so far, the possibility of customizing the appearance
and the contents of the produced documentation is a key feature of document generators like
Modelio Document Publisher. Moreover, the exact nature of the required customization depends on
specific user needs.
Modelio Document Publisher proposes five different levels of customization of the documents it
produces. While the customization capabilities increase with each level, the required effort from the
user and the complexity are kept minimal by Modelio which provides dedicated GUIs, tools and
techniques for each level.
1.2 The five customization levels
LEVEL 1
This level is the simplest to use. It only consists in using one of the standard templates that are
provided by Document Publisher. Just select a template and a couple of model elements and in just
one click you get a document. The standard ‘off the shelf’ templates of Document Publisher cover
most common situations in terms of reader audience and the role of the produced document in the
overall application development process. Note the paradigm: one template for one document.
LEVEL 2
Nothing very complex in level 2 which is similar to level one, being based on Document Publisher
standard templates too. Here, the end-user simply changes some parameters of the chosen
template. For example, the end-user can change the ‘company logo’ of the produced document, he
can ask for ‘a table of contents’ section to be added to the document, place the table of contents at
the top or at the end of the document and so on.
Each template comes with specific parameters which are proposed and documented in the ‘Create a
document’ wizard’s GUI. Again, the one template for one document paradigm is applied.
LEVEL 3
At level 3, Document Publisher can fit specific needs where several templates have to be combined in
order to produce the right document. For example, one might need a section describing use cases,
produced using the “Use case” template along with another part of the document describing the
project class structure based on another template like ‘design’. Document Publisher enables
templates to be combined in such cases. The result is a unique document containing the
concatenated production of both templates. Note that only standard templates are used here.

Moreover, no additional tooling is required, ie Modelio and its Document Publisher are all you need
to benefit from all the possibilities of levels 1, 2 and 3.
LEVEL 4
Level 4 is definitely an advanced level. It consists in designing and developing a specific template,
testing it and delivering it to end-users.
Of course level 4 possibilities are huge, the first limit mainly being the template designer’s
imagination. The template designer uses the Document Publisher Template Editor tool to create new
templates and the important point is that no software development is required. You just have to
assemble so-called “nodes” to describe what has to be done.
This is one of the main objectives of this tutorial: learn how to create a template using the template
editor.
The second limit of level 4 results from the template editor possibilities, ie the standard set of nodes
it features. But this limit can also be overcome… by level 5!
LEVEL 5
Level 5 consists in extending the set of ‘nodes’ that can be used to create templates. It requires Java
programming but is the most powerful means of customizing your documentation. By developing
specific ‘nodes’ (a node = a couple of Java classes), you can enrich the template editor ‘dictionary’
and by assembling these custom nodes in your template you can almost create any document you
might imagine.
This tutorial will now concentrate on the level 4 use case. For information on using Document
Publisher customization features for levels 1, 2 and 3, please refer to Document Publisher
documentation.

2 Designing a template
2.1 Template design
Creating a template does not require software programming, thanks to the Modelio Document
Publisher Template Editor. So, why would a template require a design?
The reason is that extracting pertinent data from a model and producing it in a readable and
expected way (organization, look and so on…) requires some initial thought. In other words, do not
try to create a template if you do not know exactly (or enough) what you want in your document.
This might seem obvious but it is still worth saying.
How to achieve a good design for your template? There is no universal answer to this question,
probably for the same reasons that forbid the existence of a universal template. In other words it
depends on many things.
However from our experience let us give you some useful tips.
1. Always start with a good model sample: a model of the kind that your template is supposed
to be run on. A template cannot be well-designed for all model types or contents. If you do
not already have an existing realistic model sample, take some time to build one. This will
help you a lot and later enable efficient testing of the template.
2. Your final goal is to produce “good” documents. Here “good” depends on the reader
expectations. Therefore start by manually creating a document sample (ideally documenting
the same model sample as above).
The unique risk here is to create a document structure that might be difficult or costly to
implement as a template. For now, accept this risk.
3. Try to submit both the model sample and the document sample to the expected readers, and
use their feedback to modify the document sample until you get their approval. These
readers are your customers. And by the way, proceed in the same way for the model sample
itself: is it relevant and similar to the kind of models they are used to work with?
4. Only then create your template in the template editor… Last thing, you will need a name for
your template.
WHAT IF MY SAMPLE DOCUMENT STRUCTURE IS HARD TO IMPLEMENT AS A TEMPLATE ?
You will probably have to make a choice here. Reading this part of the tutorial, you are customizing
the produced documentation at level 4, and asking this question means that the level 4 possibilities
do not suffice to fit your needs.
The straight and naïve answer is ‘move to level 5’. In level 5, programming specific extensions in Java
code should allow you to produce anything… However, be aware that level 5 requires more effort,
more testing more development and actually more costs. In such situations, it might be more
efficient to re-negotiate the structure of the document to produce with its intended users. Most

often, a few changes enable you to stick to level 4 and to the standard features of the template
editor.
2.2 What is a template
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.
2.2.1 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.

2.2.2 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.
Template Style sheet
User model Document Output

Data extraction Publisher Production document
generator
2.2.3 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:
Node
Input Result
element execute()
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 nodes, production nodes, control node. These
nodes differ by the nature of the result they produce and by their basic behavior.

2.2.3.1 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.
Production
Input Node HTML/DOCX
element data
execute()
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.
2.2.3.2 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.
Node
Input Set of model
element execute() 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.

E N E0 E1 E2
P1
Execution sequence:
P2
for x in { E0, E1, E2 }
Template P1.execute(x)
structure P2.execute(x)
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.
E N E0 E1 E2
P1
Execution sequence:
P2
for node in { P1, P2 }
Template node.execute(E0)
structure node.execute(E1)
node.execute(E2)
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.
2.2.3.3 Control Nodes

These 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 control nodes.
E X
CALL P
Execution sequence:
Y
X(E)
P1(E)
P2(E)
Y(E)
DEFINE P
P1
P2
Template
structure
2.2.3.4 Main nodes in the template editor

The following table summarizes the main nodes in the template editor. The complete node catalog
can be found in section 4.
Family Name Description
Production Paragraph Produces a text paragraph. The paragraph can contain

arbitrary text or variables which values are extracted from
the model.
Section Produces a section (usually a chapter title). Can be set to

increment the chapter numbering.
List Used to produce a ‘bulleted’ list. The user may choose

between bullet, checks or numbers.
Table Used to produce tables. The number of rows/columns and

their contents is defined by the child nodes.
Navigation Root Set the current element to the root of one of the models
supported by Modelio (UML, requirements, and so on). A
kind of “goto” in the model.
Metamodel This node is used to navigate in the model using the

metamodel associations and metaclasses.
Finder This node finds all the instances of a given metaclass. For
example it is possible to get all the packages of a model.
The result is a flat list of elements.
Filter This node applies a filter to its input element. If the

element matches the filter condition it is processed
otherwise it is ignored.
Control Define procedure Define a node as a callable procedure.
Call procedure Call a node previously defined as a procedure.
Table 1 - Main nodes

3 First steps with the “hello world” template

In order to get familiar with the basics commands and operations of the template editor let’s create
a very simple “Hello world” template. Our requirements are very simple: produce a document in
which a unique section displays the simple text “hello world from element ‘xxx’” where ‘xxx’ is the
name of the model element the template is applied to.
The reader is supposed to be familiar with Modelio basic operations like creating a project, creating
an element, installing a module and so on.
The starting point of this example is:
- An opened Modelio project

- The Document Publisher and Document Publisher Template Editor modules are installed
- There is a “Document folder” in your model.
3.1 STEP 1 – Creating the hello world template
Let’s start by creating our new “Hello world” template.
Right-click on the document folder in the UML Navigator

Choose the “Create a Template Editor element->Template” command in the popup menu
This pops up the template editor window shown below:

1 4
2 5
Let’s detail the Template Editor window contents.
 THE TEMPLATE TREE
The template tree shows the nodes that build the template. Here there is only one node, which is a
special node: the root node. The root node represents the template itself. By default the root node is
named “root”, you can rename it directly in the tree using the F2 key. Obviously, in this example we
renamed it “HelloWorld”. Don't forget that we should rename any nodes in this tree to indicate their
use in no time at all.
 THE NODE DESCRIPTION
In the node description field, the user can enter a description for the selected node. This description
will be available only in the TemplateEditor, mainly for template maintenance purpose. We
recommend that you add a comment to this field to indicate missing parts of the template, or to
explain complex node assembly.
 THE RAILWAY
This indicator shows the model navigation context of the selected node as a three elements
sequence.

The type of the selected node
The ‘kind’ of the input The ‘kind’ of the output

element element
Here the selected node is the HelloWorld node whose type is “root”.
The “input element” is the model element that is passed to the current node when it is executed.
Here the input element type is simply Element, the most general metaclass of Modelio. However the
root node representing the whole template itself, this value has no real signification except may be
that the Document Publisher end-user can indeed select any kind of elements as target for his
Document.
The “output element” kind is the metaclass of the elements produced by the navigation node. Root
node is indeed a navigation node as it will loop on the targets elements of the Document being
produced and pass these target elements to its children node. This is the definition of a navigation
node. Because we set the root node metaclass property to ‘Package’, we are guaranteed that the
root node will only pass package instances to its child nodes. This is why the railway indicates
‘Package’ here for the output element kind.
 THE NODE PROPERTIES
The template editor displays the properties or parameters of the node currently selected in the
template tree. In our example the HelloWorld node being selected, its properties are displayed.
Node properties are specific to each kind of node and are used to configure the node behavior. For
the root node, properties like version, creation date are obvious. However, the metaclass property
requires some details.
At runtime, the template is executed against some model elements that might be of various kinds
(the list of these elements is freely composed by the end-user when creating a Document and no
assumption can be made about his choices). By specifying a metaclass in the root node property, we
can somewhat “claim” that the template is supposed to be run only on this particular kind of model
elements. Here we chose Package, meaning that elements which are not packages in the Document
definition list of targets will be ignored by the template1.
Action: set the metaclass property value to ‘Package’
1
Warning: no misunderstanding here! This does not mean that the template will not be able to process
elements which are not packages, it only means that the template can only be launched/started on a package.
While running, the template can perfectly process the package owned classes, diagrams, and so on.

 THE TEMPLATE DESCRIPTION
Another node property for the root node is the template description field. The user can enter a
description for the template, which will be made available to the Document Publisher end-user when
selecting a particular template. It is recommended to indicate here the purpose of the template, the
kind of document it produces and the type of model element it is supposed to be run on.
3.2 STEP 2 – Adding a production node
Let’s continue with our HelloWorld example. Remember that what we are supposed to do it simply
to produce a text displaying “hello world from element ‘xxx’” where ‘xxx’ is the name of the model
element the template is applied to.
For this purpose a “Paragraph” production node from the explorer tree contextual menu sounds
good.
Let’s run this menu command to obtain the result shown below

TEMPLATE TREE
In the template tree, a “Paragraph” node has appeared, just below our HelloWorld node. The right
side of the template editor is now displaying the new Paragraph node properties because this node is
the current selected node in the template tree. Don't forget that we should rename nodes in this
tree to indicate their use in no time at all.
RAILWAY
Let’s have a look at the new railway contents. The current selected node is now of type “Paragraph”
(middle icon). The input element type (left icon) is indicating “Package” because our paragraph node
is child of our root node and because our root node produces only package instances. Finally the
output element kind (right icon) is also “Package” because our Paragraph node being a production
node, it will not navigate in the model and consequently will not change the type of the model
element being processed. Practically, if we add another child node to our root, a brother node of our
Paragraph node, this brother will receive a “Package” as input element.
NODE PROPERTIES
The important field for our example is the “text” field where we can enter the text we what the node
to produce in the output document. By default the text value is $Name . This $ notation indicates a
variable value that will be replaced by the name of the element being produced, in our case a

Package (remember the railway input element type). There are several possible variables available
and depending on the type of the input element. These possible variables can be chosen in the
bottom combo box field of the property area called ‘Available attributes for current element’.
In order to fulfill our requirements for our displayed text we need to modify the text contents as
follows:
Action: set the text as shown above.
3.3 STEP 3 – Testing the Hello world template
In order to test our template we need to carry out the following operations:
1. Compile and package the template

2. Create a test Document bound to our template
3. Generate the test Document (it will immediately be displayed after generation)
COMPILE AND PACKAGE THE TEMPLATE
Execute the “Package template” command from the template tree left toolbar. This command
will pop up a file chooser dialog box and prompt for a file name for the template. The proposed
default options should be fine without any changes: the template file is created in the proper
directory for testing and the file name is the template name completed by a .jar extension. So you
simply have to validate the dialog box to package your template. That’s it.

CREATE A TEST DOCUMENT
Close the template editor. Back to the modeler, create a Document named ‘test’ in the UML browser
for example.
Enter the document name
Chose the document directory
Select the HelloWorld template
Drag and drop the project root

package from the UML
Navigator into this field.

From the newly created document, launch the ‘Generate Documentation’ command of Document
Publisher (right-click on the document, Document Publisher menu -> Generate Documentation).
The ‘test’ document is then generated and displayed in Word. It should look like this:

4 Deeper into the template editor
4.1 Context and node creation
According to the node selected in the template tree, the nodes available for creation may vary.
Navigation nodes only depend on the navigation context displayed in the railway. For example you
can create an “Opposite Association End” node only if the output element kind is AssociationEnd.
Production nodes depend on the navigation context. For example, a diagram production can be
inserted only if the output element kind is a diagram. However, several production nodes also
depend on the parent production nodes (“Table Cell” only on “Table”, “List item” only on “List”…).
4.2 Using variables in production

By default, the text value of almost all production nodes is $Name. This $ notation indicates a
variable value that will be replaced by the name of the element being produced. There are several
possible variables available depending on the type of the input element (remember to look the
railway). These possible variables can be chosen in the bottom combo box field of the property area
called “Available attributes for current element”.
Once a variable is chosen in the combo box, it can be added in the text value area of the production
node using the “+” button on the right of the combo box.
4.3 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 the addition of some document data
to the document content.
The following table summarizes the available production nodes in the template editor.
Name Context Description
Character On a paragraph, a list Adds content in an already open paragraph. Useful for
item or a table cell. building a line with information coming from several
model elements.
Comma On a paragraph, a list Adds content in an already open paragraph. Applied on

Separated List item or a table cell. several model elements, separators can be inserted
before, between or after them.

Ex: parameters in a method signature (parameter1,

parameter2).
Diagram On the root or a Used to insert the current diagram into the generated
section. document.
The current model In HTML mode, diagrams are automatically clickable if

element must be a the corresponding elements exist in the generated
diagram. documentation.
File Insertion On the root or a Produces a hyperlink or a file insertion from the file
section. contained in the artifact.
The current model When the element is a valid document, its content is
element must be an automatically generated and inserted.
artifact or a
document.
List On the root or a Used to produce a “bulleted” list. The user may choose
section. between bullets, ticks or numbers.
List item Only on a list. Adds a text list entry, on a single line only.
The level of the list item can be specified to produce

items on several levels.
Paragraph On the root, a Produces a text paragraph. The paragraph can contain
section, a table cell arbitrary text or variables whose values are extracted
or a list. from the model.
The user may indicate if an empty paragraph is to be

kept or removed at generation.
Reference On a paragraph, a list Used to insert a hyperlink on the current element. The
item or a table cell. target must be a production node producing its content
on the same model element.
Link resolution takes place upon generation: if no

anchor can be found, the hyperlink is replaced by the
name of the element.
Section On the root or Produces a section (usually a chapter title). Can be set
another section. to increment chapter numbering. A section can be
removed if it contains nothing, or replaced by a default
text (such as N/A).
Table On the root or a Used to produce tables. The number of rows/columns

section. is indicated, but their content is defined by the child
nodes.

The process of new lines/columns is automatically

managed by the generation engine.
Table Cell Only on a table. Adds a new cell to the current table, at the same index
as its position in the template. (i.e. the second cell in
the template will be column 2 in the document)
A table cell usually contains an embedded paragraph,

which can be ignored if necessary.
4.4 Navigation nodes

Navigation nodes are used to navigate in the model (in other words, get elements from other
elements however you want). A navigation node can’t add data to the document content on its own,
but is usually combined with some production nodes.
The following table summarizes the available navigation nodes in the template editor.
Filter Everywhere. Applies a filter to its input element. If the element

matches the filter condition, it is processed. Otherwise
it is ignored.
Finder Everywhere. Finds all the instances of a given metaclass. For

example it is possible to get all the packages of a
model. The result is a flat list of elements.
Metamodel Everywhere. Browses the model using metamodel associations and

metaclasses.
Note Only on a model From a model element, gets all notes which have the
element. given type.
The node type list is computed from the project where

the template is edited. Therefore, before using a
module-specific type, the module must be installed in
the project to make the note type available in the
template.
Opposite Only on an From an association end, gets all other association ends
Association End association end. from the same association.
Predefined Only on a model Gathers the commoner navigations available according

element. to the current navigation element.
It might hide several navigations on the model itself,

like in getting the parent classes of a class.

Root Everywhere. Sets the current element to the root of one of the
models supported by Modelio (UML, requirements, and
so on). A kind of “goto” in the model.
Tagged Value Only on a model From a model element, gets all tagged values which
element. have the given type.
The tag type list is computed from the project where

the template is edited. Therefore, before using a
module-specific type, the module must be installed in
the project to make the tag type available in the
template.
4.5 Control nodes
The following table summarizes the available control nodes in the template editor.
Call Everywhere. Calls a node previously defined as a procedure.

procedure
Define N/A Defines a node as a callable procedure.

procedure
Root N/A Represents the template itself, and enables its name
and description to be set.

5 A real example: the “Use case catalog” template

In order to get familiar with template building, let’s examine one of the predefined templates, the “Use case catalog” template. In our template
classification, this template is meant to be an overview analysis template, like “Requirements” or “Process”, as opposed to technical reference guides like
“Class Reference” or “Diagram Reference”.
The “Use case catalog” template can be applied to Packages, and provides an overview of all the actors and use cases of the system. For each use case, a
detailed description of its content is added. Interactions contained in use cases are described as scenarios.
5.1 Dividing into procedures

When creating a template, it is important to think about the different parts of the document you want to generate, and to break down your template
according to those parts, in order to make the template development and maintenance easier.
Let’s start with our example’s main organization, procedures.
1. The root node shows the name of the template, and contains the mains section as well as calls towards the procedures.
2. The first procedure, “ProcGetActors”, produces a table showing all actors involved in the system.
3. The “ProcGetUseCases” procedure produces a table showing all use cases involved in the system.
4. The “ProcGetUseCasesDiagrams” procedure generates the use case diagrams.
5. The “ProcDetailledUseCases” procedure is used to generate all information about use cases and references towards scenarios.
6. The last procedure, “ProcGetSequenceDiagram”, is used to add a list of scenarios and details about each scenario.

21 avenue Victor Hugo, 75016 Paris
Page 25
5.2 Main sections
Section nodes in the template define the organization of the generated document, visible in the table of contents.
Each section node indicates its own style, therefore generating the proper section level.
An “anchor” for links is also created automatically for each section, allowing reference nodes producing hyperlinks to target the proper area.
Please note that nodes have been renamed to show their use instantly without selecting them.

Page 26
5.3 Actor & use case tables
In this part of the template, we see two similarly built procedures, generating the tables presenting all the actors and use cases.
Creating a table in a template requires:
A table node ( “ListOfActors” in this example) indicating the number of columns and their titles
One or several navigation nodes, to gather the elements to be produced in the table (in this example, a node finder producing actors)
A table cell for each column, producing the content of the table (in this example, “NameOfActor” and “DescriptionOfActors”)
Putting the navigation node between table and table cells allows the creation of those cells for each actor.
Please note that in the example above, the “DescriptionOfActor” cell is created only when the current actor has a description, due to the second
navigation node.

Page 27
5.4 Use case diagram production
This procedure is used to generate the use case diagrams in the document, in a specific section.
In all predefined templates, diagram generation is always preceded by the generation of the diagram’s description, as this is meant to describe
what is presented in this diagram.
Diagram production requires:
A navigation node, to gather the diagrams

In this example, a section node is created for each diagram
A navigation node to get the diagram’s description, here it is a finder called “Find All UseCase Diagrams”
A paragraph to produce this description
A diagram node to insert the image, named “PictureOfDiagram” in this example

Page 28
5.5 Detailed use cases
This procedure groups the content of the detailed use case section. The pattern for each part is simple:
Insert a subtitle (“Pre-Conditions”, “Description”…)
Get a specific note (“Description”, “PreCondition”…)
Generate the note content in a paragraph
The only exception is the actor part:

Gather all associated actors with a predefined navigation node
Generate them with a comma separated to keep them on the same line

Page 29
5.6 Reference towards a scenario
At the end of the detailed use case section, a scenario subsection is created when interactions are found in the use case.
As before, a subtitle is added for each scenario, containing the description of the interaction.
The interesting part is the “See Also”, which creates a hyperlink reference towards another section in the document containing the sequence
diagrams from this interaction.
To create a reference, you have to:
Navigate on an element, here a sequence diagram (the example uses a metamodel navigation, “Foreach Sequence Diagram”)
Create a paragraph like in this example (“SeeAlso”), or another container like a table cell, or a list entry
Create the reference inside
In the reference property page, on the right part of the template editor, add the production node to reference, usually a section node
The hyperlink will be created upon generation only when an “anchor” can be found for this model element. Otherwise only the element name is
produced. “Anchors” are automatically created for section nodes, but you can manually add an “Anchor” in several other production nodes,
using the “added to index” checkbox.
Please note that if a single element has several possible anchors in the same document, only the first one will be used upon generation.

Page 30
5.7 Interaction table
This procedure of the ”Use Case catalog” template generates the scenarios, created in the model as interactions in use cases.
The first part presents all use cases and their scenarios, with links towards the details of each scenario.
The interesting part is the “Scenario of Use Case” table cell. Unlike the actor table (see paragraph 5.3) described earlier, there are navigation
nodes before and after the cell:
“Find All Use Cases” enables the creation of two cells for each use case.
The two other navigation nodes, “Foreach Interaction” and “Foreach SequenceDiagram”, before the paragraph creation, are meant to
create content inside the current cell rather than creating a new cell.
Please note that when a table cell has nothing to produce directly from the current element, but only in child nodes, the embedded paragraph
should be deactivated. Otherwise, a useless empty line will be added in the cell before its real content.

Page 31
5.8 Scenario details
The second part of the procedure generates the

detailed scenarios. This is similar to use case diagram
production:
Navigation nodes to gather sequence diagrams

In this example, a section node is created for
each of them
Another navigation node to get the diagram’s
description
A paragraph to produce this description
A diagram node to insert the image

Page 32
6 Extending an existing template
6.1 Opening a predefined template

Document Publisher comes with a vast catalog of predefined templates. As a Template Editor user, it
you can easily extend these templates, either to add the content of your choice, or to modify the way
in which some parts of the model are generated.
The XML definition of all predefined templates can be found in the Template Editor’s installation
directory (<Project_Path>/mda/TemplateEditor/res/templates/<language>).
6.2 Basic extension
Let’s take an example of a predefined template extension, starting from the “Use case catalog”
presented earlier.
Let’s assume we want to replace the table of actors with a list, in order to distinguish it from the use
case table generated in the same part of the document.
For this, carry out the steps illustrated in the following screenshot.

1. Load the default template’s XML file (“UseCase.xml”) from the resources in the Template
Editor.
2. Go to the point you want to modify (in this example, the procedure where the actor table is
generated).
3. Create the new nodes:
a. Create a list node, and set its type to “bullet”. Name it “ListOfActors”.
b. Add the same navigation node as “FindAllActors” in the table (it is a smart finder
producing all actors).
c. Add the list item producing the name of the actor. Name it “NameOfActor”.
4. Just delete the former “ListOfActors”, this will delete all its children.
5. Package the extended template.

Now, let’s take a look at the result of generating this template on the same example as in the
previous chapter.


Modelio Template Editor Tutorial

Загружено:

Сведения о документе

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

Modelio Template Editor Tutorial

Загружено:

Авторское право:

Доступные форматы

Modelio

Document Publisher Template

2 Designing a template ................................................................................................... 6

3 First steps with the “hello world” template .................................................................13

4 Deeper into the template editor .................................................................................21

5 A real example: the “Use case catalog” template .........................................................25

6 Extending an existing template ...................................................................................33

Copyright Modeliosoft 2009

1.1 Customizing Document Publisher documents

Copyright Modeliosoft 2009

1.2 The five customization levels

Copyright Modeliosoft 2009

Copyright Modeliosoft 2009

2.1 Template design

WHAT IF MY SAMPLE DOCUMENT STRUCTURE IS HARD TO IMPLEMENT AS A TEMPLATE ?

Copyright Modeliosoft 2009

2.2 What is a template

2.2.1 The Document Publisher end-user point of view

Copyright Modeliosoft 2009

2.2.2 The Document Publisher generator

Template Style sheet

User model Document Output

2.2.3 A template from inside

The general pattern of a node behavior is shown in the figure below:

Copyright Modeliosoft 2009

2.2.3.1 Production Nodes

2.2.3.2 Navigation Nodes

Copyright Modeliosoft 2009

Note that ‘standard loop’ mode is used by default.

2.2.3.3 Control Nodes

Copyright Modeliosoft 2009

The following figure illustrates the use of control nodes.

2.2.3.4 Main nodes in the template editor

Family Name Description

Production Paragraph Produces a text paragraph. The paragraph can contain

Section Produces a section (usually a chapter title). Can be set to

List Used to produce a ‘bulleted’ list. The user may choose

Table Used to produce tables. The number of rows/columns and

Metamodel This node is used to navigate in the model using the

Copyright Modeliosoft 2009

metamodel associations and metaclasses.

Filter This node applies a filter to its input element. If the

Control Define procedure Define a node as a callable procedure.

Call procedure Call a node previously defined as a procedure.

Table 1 - Main nodes

Copyright Modeliosoft 2009

3 First steps with the “hello world” template

The starting point of this example is:

- An opened Modelio project

3.1 STEP 1 – Creating the hello world template

Let’s start by creating our new “Hello world” template.

Right-click on the document folder in the UML Navigator

This pops up the template editor window shown below:

Copyright Modeliosoft 2009

Let’s detail the Template Editor window contents.

 THE TEMPLATE TREE

 THE NODE DESCRIPTION

Copyright Modeliosoft 2009

The type of the selected node

The ‘kind’ of the input The ‘kind’ of the output

 THE NODE PROPERTIES

Action: set the metaclass property value to ‘Package’

Copyright Modeliosoft 2009

 THE TEMPLATE DESCRIPTION