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"
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:
There are following section types:
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.
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.
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:
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:
The value is calculated by a string FlexQuery-expression
The value of the specified context element's attribute
The value of a certain element or attribute pointed by the specified Location Path, which is interpreted relatively to the context element
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.
The image is specified by the filepath of the source graphics file.
The image is specified by the FlexQuery-expression, which generates the URL of the source graphics file.
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
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.
A small icon representing the context element. The icon image should be provided by the DSM driver.
A big icon representing the context element. The icon image should be provided by the DSM driver.
images subdirectory near the document) or
stored directly within the document file itself.
Panel Control can be especially useful for
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 Sections may be used to
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 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:
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:
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.
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.
Allows to include into the resulting AIS only those attributes that satisfy the filter condition specified as the boolean FlexQuery-expression.
This method works only with the declared attributes. So, its interpretation is always the same in all FlexDoc application.
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.
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:
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:
The called template receives the same data source that is being processed by the current template
The new data source is initialized
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.
The called template creates a new document