FlexDoc.XYZ - Template Components
- Section Blocks
- Area Section
- Area Rows
- Container Sections
- Call Stock-Section
- Call Template
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.
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:
There are following section types: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.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.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:
- 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.
- Generates a paragraph with thehorizontal rule.
- Generates an empty paragraph with the specified height or a vertical spacing added before the following paragraph.
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:
- Generates a fragment of the predefined text with the specified formatting
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:
The value is calculated by a string FlexQuery-expression
The value of the specified context element's attribute
- Location Path
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.
- 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.
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:
- 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.
- 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.
imagessubdirectory near the document) or stored directly within the document file itself.
- File Image
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)
- 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).
The container sections are: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
- The generation of some main output
- When the main output exists, framing it with the header and footer
- In case of no main output, inserting instead of it some alternative content
Folder Sections may be used to
- Dynamically switch on/off large parts of a template
- Add a common header/footer to the total output produced by a series of sections in case that such an output is not empty.
- Specify a series of sections to generate a single formatted object, e.g. table or list. In that case, each of those sections will produce some part of the object: a table row or a list item.
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.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.
There are following methods to specify collecting of the AIS:
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:
- The declared attributes
- The unknown attributes (whose number may vary for different elements)
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.
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.
Allows to include into the resulting AIS only those attributes that satisfy the filter condition specified as the boolean FlexQuery-expression.
- none – keep original order
- by name – sort the AIS by the attribute name
- by value – sort 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
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.
- Filter Expression
- 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.
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.
Enumerates all values of the specified attribute of the context element.
- Filter Expression
- none (original order)
- by value
- by key expression
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.
- Call Stock-Section – the template section version
- Call Stock-Section Control – the version of a control
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:
- Specifies the filepath of the called template
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
- Pass Current Model
Specifies what sort of output the called template will produce.
There are two options:
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
- This Document
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