FlexDoc.XYZ - Template Components

  1. Components
  2. Sections
  3. Section Blocks
  4. Area Section
  5. Area Rows
  6. Controls
  7. Container Sections
  8. Stock-Sections
  9. Call Stock-Section
  10. Call Template

1. Components

FlexDoc templates can be considered as a sort of computer programs, which contain instructions interpreted by FlexDoc Generator. Such instructions are subdivided into template components and component properties.

Template components are the template building blocks and visualized in the FlexDoc 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" enabling condition icon 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:

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 something (for instance, a space or new line). Such a separator can be specified in the Control Group properties. Another possibility is a special Separator Control, which allows you to specify the individual separators that are inserted between the output of particular controls.

There are following control types:

Text 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:
  1. Expression

    The value is calculated by a string FlexQuery-expression

  2. Element Attribute

    The value of the specified context element's attribute

  3. Location Path

    The value of a certain element or attribute pointed by the specified Location Path, which is interpreted relatively to the context element

  4. 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 FlexDoc.

Separator Control

Allows you to define an individual separator, 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 Separator 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:
  1. File Image

    The image is specified by the filepath of the source graphics file.

  2. URL Image

    The image is specified by the FlexQuery-expression, which generates the URL of the source graphics file.

  3. 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

  4. Element Image

    A graphic image that somehow depicts (or illustrates) the context element (for example, the element's diagram).

    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.

  5. Element Small Icon

    A small icon representing the context element. The icon image should be provided by the DSM driver.

  6. 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 programming

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 used to

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 forms naturally as elements are 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 the 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:

  1. Enumerated Attributes
  2. Selected Attributes
  3. Selected+Enumerated Attributes
  4. Values of Single Attribute

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 FlexDoc/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:

  1. The declared attributes
  2. 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 FlexDoc 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 in a particular FlexDoc application.

Settings
  1. 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.

  2. Filter Expression

    Allows to include into the resulting AIS only those attributes that satisfy the filter condition specified as the boolean FlexQuery-expression.

Sorting
  1. none – keep original order
  2. by name – sort the AIS by the attribute name
  3. by value – sort the AIS by the attribute value (according to the value data type)
  4. by key expression – sorts the AIS by the key generated for each attribute by the specified FlexQuery-expression

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 FlexDoc 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.

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.

Values of Single Attribute

Enumerates all values of the specified attribute of the context element.
Settings
Filter Expression
Sorting
  1. none (original order)
  2. by value
  3. by key expression

8. Stock-Sections

As in any computer program, some sections of a template can repeat themselves. In those situations FlexDoc 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:

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:
  1. Pass Current Model

    The called template receives the same data source that is being processed by the current template

  2. 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:
  1. 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.

  2. 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:
  1. The parameter name
  2. The FlexQuery-expression calculating the parameter's value