 DocFlex Technology - Documentation - Template Components
- Components
- Sections
- Section Blocks
- Area Section
- Area Rows
- Controls
- Container Sections
- Stock-Sections
- Call Stock-Section
- Call Template
1. Components
DocFlex templates can be considered as a sort of computer programs,
which contain instructions interpreted by
DocFlex Generator.
Such instructions are subdivided into template components
and component properties.
Template components are the template's building blocks and visualized in the
DocFlex Template Designer.
Component properties allow adjusting the component's look and behavior.
In the template designer, they can be specified in the component property dialogs and inspectors.
When interpreting a component the generator produces by it a piece
of the output document, which is called the component output.
For each template component, an enabling condition can be defined.
(In the Template Designer, it is normally indicated with the "question"
 icon).
Once defined, the enabling condition is checked by the generator each time before interpreting
the component. If the enabling condition is not satisfied the generator normally passes it over
without generating any output. The enabling condition can be specified in the component properties
simultaneously in two ways:
- in the form of a boolean FlexQuery-expression
- in the form of the list of Element Types. In this case, the component
is processed only when the context element's
type is compatible with the one of the types specified in the list.
There are three types of template components:
2. Sections
Sections are the basic template components.
They provide the control of the data flow (i.e.
the flow of elements and attributes)
and generate consecutive fragments of the result
document.
There are following section types:
3. Section Blocks
In a template, sections
are grouped in section blocks,
where they follow one another in the order defined during the template design.
At any particular moment, when executing a template, the generator processes
some section block. It passes through the block and interprets the contained
sections, according to the order they follow in the block.
As a result of a single pass, the generator produces some document
part called the block output.
When processing a section block the generator always maintains
some current element called generator context element.
During a single pass, the context element is not changed and used
as a parameter for every section being interpreted.
The context element is one of the generator variables
and accessible within the FlexQuery-expressions.
Almost all data processing specified in a template normally is linked
to the context element. At the same time, all elements iterated
by the generator at some moments get assigned to the context element.
In such a way, the elements constitute a specific flow in which
they are being processed.
In similar way, the flow of attributes is organized,
for which purpose the generator maintains yet another variables:
context attribute and context attribute value.
For more details, see Attribute Iterator.
Each template contains the root section block, from which
the generator starts processing this template.
The context element is initially set to the root element
passed to the template together with the
DSM.
4. Area Section
Area Sections are the primary
template components to define
and produce the content of the output documents.
Each time the generator interprets an Area Section it appends
a new fragment to the output document. The fragment is filled with
the data produced from the
context element
as well as from the current values of other generator's variables.
Each output document is built of the sequence of fragments produced by some
of the Area Sections defined in the template. The role of the
sections
of other types is mainly to control the data flow and to dispatch the queue
in which the Area Sections are invoked and processed.
Each Area Section contains a template area,
which, in turn, is a container of Area Rows.
The template area is not a separate component by itself. Instead, it is a special
part of both Area Section and Panel Control
– another template component containing it.
5. Area Rows
Area Rows are the
template components in many ways
similar to sections.
However, unlike sections their purpose is to generate document's informative content
and its formatting rather than controlling the flow of data and processing of the other
components.
Area Rows can be defined only within a
template area where they follow one another
in the order specified during template design.
There are three Area Row types:
Control Group
The container of Controls.
Depending on its settings, an interpretation of the Control Group may
produce a paragraph, a list item, or a table row.
Horizontal Rule
Generates a paragraph with thehorizontal rule.
Vertical Spacer
Generates an empty paragraph with the specified height or
a vertical spacing added before the following paragraph.
6. Controls
Controls are the template components which generate
the minimal pieces of the informative and formatting content
added to the output documents (such are the text fragments
with the individual formatting, graphic images, table cells and so on).
Controls can be defined only within a
Control Group and follow one another
in the order specified during template design.
When a Control Group represents a table row, each control defines one of the table cells.
In this case, if the control is blocked by an enabling condition the table cell is eliminated
by merging it with the neighboring one.
When a Control Group is designed to generate paragraphs or list items,
the output of each control is consecutively added to the
flow that forms a paragraph.
In this case, the output generated by the different controls
can be separated with a delimiter (for instance, a space or a new line).
Such delimiter can be specified in the Control Group properties.
Another possibility is a special Delimiter Control
which allows to specify the individual delimiters that are inserted between the output
of particular controls.
There are following control types:
Label Control
Generates a fragment of the predefined text
with the specified formatting
Data Control
Generates either a fragment of the text data or a document field (RTF) with the specified formatting.
The data source can be selected as one of the following:
- Location Path
The value of a certain element or attribute
pointed by the specified Location Path,
which is interpreted relatively to the context element
- Element Attribute
The value of the specified context
element's attribute
- Formula
The value is calculated by a string FlexQuery-expression
- Document Field
The document field (RTF), for example:
page number, number of pages, table of contents.
The value of the field is calculated by the application rendering the document (for
example, Microsoft® Word). However, the field's formatting is generated by DocFlex.
Delimiter Control
Allows to define an individual delimiter, which is inserted after the
output of the preceding
controls.
The actual delimiter is generated only when there is anything to divide,
i.e. there are both the output of the controls preceding this Delimiter Control
and the output of the following ones.
Image Control
Inserts the graphic image in the document.
The image can be specified as one of the following:
- File Image
The image is specified by the filepath
of the source graphics file.
- URL Image
The image is specified by the FlexQuery-expression,
which generates the URL of the source graphics file.
- Resource Image
The image is specified by the FlexQuery-expression,
which generates the Java-resource name of the source graphics file,
for example: package1/package2/image.gif
- Element Image
A graphic image that somehow depicts (or
illustrates) the context element
(for example, the element's diagram).
This type is supported only for non-XML-file data sources (i.e. those with the custom
written DSM driver). The image should be provided by the DSM driver.
In addition, the driver can pass the hypertext map of the image
that allows to specify generation of the hypertext links from the certain elements
of the image to the appropriate fragments of the generated documentation.
- Element Small Icon
A small icon representing the context
element. The icon image should be provided
by the DSM driver.
- Element Big Icon
A big icon representing the context
element. The icon image should be provided
by the DSM driver.
Depending on the selected output format and the specified generator options, the image can
be either inserted into the document in the form of a reference to the external graphics
file (which is copied into the images subdirectory near the document) or
stored directly within the document file itself.
Panel Control
This control, as well as the Area Section,
contains a template area and generates
the output produced by it.
Panel Control can be especially useful for
- defining a complex content of the table
cells (such as the sequence of paragraphs with the different formatting,
formatted lists, nested tables)
- assigning the common formatting properties
for the series of text fragments generated by the different
controls
(e.g. generating of a common text border)
Call Stock-Section Control
Is similar to Panel Control, but
the control's output is generated by the
called stock-section. Practically,
this allows, for example, to insert into a table cell an output with the arbitrary
content and formatting (including the nested tables).
7. Container Sections
Some template sections
can contain other section blocks.
Such sections are called container sections.
When interpreting a container section, the generator switches to processing
one or several of the section blocks contained in it. Following this, the generator
returns back and continues processing the previous section block with
the initial context element.
The container sections are:
Each container section may contain the following
section blocks:
The body-block is presented in every container
section. When a container section is interpreted, its body-block may be iterated
any number of times depending on a particular section type and parameters.
During these iterations, the main section output is produced.
Each time, as a new pass through the body-block starts, the generator's
context element may be changed.
This depends on the section's type and settings.
It may also occur that during a single interpretation of the container section,
its body-block is never processed at all, or at those times it is run
all the nested sections contained in it produce no
output by themselves (for example,
because of all enabling conditions defined
in those sections are not satisfied and, therefore, the sections are blocked).
In such a case, the main section output
is said to be empty.
The header-block and footer-block
are optional. If defined, they are processed only when the
section main output is not empty.
In that case, the output of the header-block is inserted in the generated document just before
the section's main output, whereas the output of the footer-block – after.
The header- and footer-blocks are always processed with the initial
context element received by the section.
The else-block is yet another optional block of container section.
However, on the contrary to the header- and footer-blocks, if defined,
it is processed only when the section main output is empty. During this,
the context element remains the same received by the section.
Thus, the structure of the container sections allows
- to generate some main output
- when the main output exists, to frame it with the header and footer
- in the case no main output generated, to insert instead of it an alternative content
Folder Section
Folder Section is the simplest variant of
container section.
During its interpretation, the body-block
is processed always and only once. The
context element remains the same as in the parent
section block.
Folder Sections may be useful to
- dynamically switching on/off the large parts of a template
- adding a common header/footer to the total
output
produced by the series of sections
in the case that such an output is not empty
- assigning a series of sections
to generate a single formatted object, e.g.
a table or a list. In this case, each section
will produce a table row or a list item.
Element Iterator
Element Iterator is another kind of
container section.
Element Iterators are the primary
template components
to specify and control the flow of the elements.
Receiving the context element,
an Element Iterator produces from it a set of other elements, which become the
Element Iteration Scope (EIS). Then, the generator
switches to the Element Iterator's body-block
and iterate it for every element from the EIS, each time setting the new element as the
generator context element. The order in which the elements are processed is determined by
the sorting order of the EIS.
In this way, the Element Iterator's main output
is generated. It may occur that the EIS is empty. In such an event, the iterator's
body-block is not processed at all and the section's
main output will be empty as well.
By default, the EIS is sorted in the original order
which is forming naturally when the elements being added to the EIS during its generation.
However, a
different
sorting order can be imposed. In that case, before iterations start the EIS is sorted according
to the sorting order specified in the Element Iterator's properties.
For detailed description of the Element Iterator's features and settings, see chapter
Element
Iterator (details).
Attribute Iterator
Attribute Iterator is the third variety of
container sections.
Attribute Iterators are organized similarly to
Element Iterators, but unlike the former,
instead of the elements, they iterate through the set of the attributes (or the multiple values
of a single attribute).
When an Attribute Iterator is interpreted, depending on its settings it produces from the
context element either a set of its attributes or
an array of the values of a single attribute. In both cases the
Attribute Iteration Scope (AIS) is formed.
Then, the generator switches to the Attribute Iterator's body-block
and inteprets it for every item from the AIS, each time adjusting to it the generator variables:
context attribute and context attribute value.
The order, in which the AIS items are processed, depends on the sorting of the AIS.
In this way, the Attribute Iterator's main output is generated.
When the AIS is empty, the iterator's body-block
is not processed at all and the section's main output is empty too.
There are following methods to specify collecting of the AIS:
- Enumerated Attributes
- Selected Attributes
- Selected+Enumerated Attributes
- Values of Single Attribute
1. Enumerated Attributes
Enumerates attributes of the context element.
This method may have different interpretations for different
DSM Types.
Here's the explanation:
Some DSM Types (like 'Together RWI' in
DocFlex/Together)
may associate with a certain element an undefined number of attributes.
The reason of this is that the same notion of "element attribute" may be applied
to quite different data entities provided by the underlying data source.
That's because some features of those entities relevant to their processing
(like having a certain name and a certain value) are well fit to
the notion of attribute, which makes them convenient to treat in a universal way.
For that reason, all attributes generally associated with a given element
are subdivided into two types:
- The declared attributes
- The unknown attributes (whose number may vary for different elements)
For each declared attribute, it is always known the attribute's name, the data type of
its value and how the value can be obtained from the data source (which allows it to be
requested by the name when needed).
The unknown attributes are always obtained dynamically and returned by the
DSM Driver
in the form of an enumeration, which in turn is provided by a call to some
data source's native API.
When the 'Enumerated Attributes' method is processed, the generator actually asks the
DSM Driver to provide for the
given element the enumeration of its unknown attributes. The DSM Driver, in turn, calls some
data source's native API to provide such an enumeration.
The native API, however, has no information which attributes are declared in the
DSM Type and which are not.
(Since the DSM Type itself is just some approximation of the original data source,
which is introduced by a DocFlex implementation and exists independently on
the application providing the data source.)
Because of this, the returned enumeration of attributes may contain both unknown attributes
and some of the declared ones (but not necessary all the declared attributes, since some of
them may be obtained only using some specific methods known to the
DSM Driver).
Thus, the 'Enumerated Attributes' method provides some general framework and should
be treated accordingly to a particular DocFlex application.
Settings
- Exclude already iterated attributes
If selected, forces the generator to exclude
from the AIS those attributes of the context
element, which have been already processed
in one of the Attribute Iterators interpreted before.
- Filter Expression
Allows to include into the resulting AIS
only those attributes that satisfy the filter
condition specified as the boolean FlexQuery-expression.
Sorting
- none (original order)
- by name
Sorts the AIS by the attribute name
- by value
Sorts the AIS by the attribute value (according
to the value data type)
- by key expression
Sorts the AIS by the key generated for each
attribute by the specified FlexQuery-expression
2. Selected Attributes
Enumerates only those attributes of the context element
which are specified in the list defined in the section's properties.
This method works only with the declared attributes. So, its interpretation is always
the same in all DocFlex application.
Settings
- Filter Expression
Sorting
The order in which the attributes are iterated can be assigned arbitrary and depends
on the position of each attributes in the list where they are specified.
3. Selected+Enumerated Attributes
This method represents a composition of the previous two methods.
It should be used when it is necessary to include in the iteration scope as some selected
declared attributes as the enumerated ones.
If no sorting specified, the selected attributes will appear the first (before the enumerated
ones). The selected attributes will not be duplicated in the event some of them emerge
among the enumerated attributes as well.
4. Values of Single Attribute
Enumerates all values of the specified attribute of the
context element.
Settings
- Filter Expression
Sorting
- none (original order)
- by value
- by key expression
8. Stock-Sections
As in any computer program, some sections
of a template can repeat themselves. In those situations DocFlex provides the possibility
to design such repeating sections only once and store them into the special template part
called Stock, in the form of stock-sections.
When storing into the Stock, each stock-section is assigned with the special unique name.
Then, by this name, the stock-section can be called many times from the different locations of
the template (including the other stock-sections and even from within this stock-section itself).
This can be done using some template components
specifically designed for that purpose.
Each stock-section call produces the same document fragment, as would be generated by the stock-section
itself if it was on the place of its call. In this way, stock-sections can be considered as an equivalent
of the procedures in a typical programming language.
Besides their main use of eliminating duplications in templates, stock-sections allow:
- to generate an arbitrary content of a table
cell. Using the Call
Stock-Section Control, it is possible
to fill any table cell with the output representing
any complexity of the data and formatting.
- using recursive stock-section calls, to
generate document fragments with the complex recurrent structure.
Stock-sections can be one of the following section types:
There are two template components used to insert a stock-section call:
9. Call Stock-Section
This is a template section that just calls the particular stock-section
using its name. The effect of this template section is the same
as if the called stock-section was presented on its place by itself.
10. Call Template
This section type allows to spawn from the current template the processing of some another
template (a subtemplate).
Each time the Call Template section is interpreted, the new instance of the generator is created,
by which the called template is processed. During this, the processing of the current template
is suspended, while the called template, depending on the section's settings, may generate either
a new fragment of the common document (which is being generated by the current template) or
the completely new separate document.
The following section settings determine how this is done:
Template
Specifies the filepath of the called template
Data Source
Specifies which data source should be passed to the called template.
There are two possibilities:
- Pass Current Model
The called template receives the same data source that is being processed
by the current template
- Init New Model
The new data source is initialized
Output Type
Specifies what sort of output the called template will produce.
There are two options:
- This Document
The called template produces a piece of the common document being generated by the
current template. In this case, the behaviour of this section is similar to that of the
Call Stock-Section section.
- Separate Document
The called template creates a new document
Passed Parameters
The list of parameters passed to the called template.
Each parameter is specified by the following settings:
- The parameter name
- The FlexQuery-expression calculating the parameter's value
| 
