DocFlex Technology - FlexQuery Reference - Generator Object Model

The Generator Object Model (GOM) exposes some inner working of the DocFlex Generator in the form of hierarchy of objects which represent some of the generator's components and the data the generator processes. Currently, there are following GOM object types:

Those objects and their properties can be accessed within FlexQuery expressions in templates in order to control the interpretation of template components and the output they produce.

At any particular moment, the generator may be processing one or several templates (which, in that case, are those called one from another).

For each template, the generator maintains a special GOMContext object which holds information about the template's current processing state.

The GOM starts from the GOMContext object associated with the given template. The properties of that object are accessible within the FlexQuery scripts in the same way as variables. Those properties presented in the form of predefined variables are called generator variables.

The values of generator variables are references to other GOM objects which in turn hold their own properties and in such a way provide access to other GOM objects.

Example:

contextElement.id
This expression returns an identifier of the generator's current context element.

DSM

Represents DSM (Data Source Model).

Some DSM Types may introduce their own extended properties associated with the whole data source which are accessible via this object (for instance, the name of an XML file which supplies all the data processed by the template).

DSMAttr

Represents the DSM attribute on the level of the DSM Driver which is the one who provides data from the DSM (Data Source Model), a representation of the current data source. Each DSMAttr object is the DSM Driver's encapsulation of the corresponding DSM attribute.

Some DSM Type may introduce their own extended properties which are accessible via this object. (That's why it is exposed in the Generator Object Model.)

See Also:

GOMAttribute

DSMElement

Represents the DSM element on the level of the DSM Driver, which is the one who provides data from the DSM (Data Source Model), a representation of the current data source.

Some DSM Type may introduce their own extended element properties which are accessible via this object. (That's why it is exposed in the Generator Object Model.)

Note: Each DSMElement object is the DSM Driver's encapsulation of the corresponding DSM element. It is not necessary that such an encapsulation is unique for a particular DSM element. To distinguish the exact elements, use GOMElement.id property.

See Also:

GOMElement

DSMElementType

Provides the information about an Element Type.

Note: The information about a particular Element Type may be obtained using function findElementType().

See Also:

findElementType(), instanceOf(), resolveElementType(), GOMElement.elementType

Properties

String name

The Element Type name.

This name is used for all references to this Element Type.

String displayName

The Element Type display name.

This may be a more user-friendly name which is used only for displaying or printing (in particular, it is used by the Template Designer).

If not provided by the DSM Driver, the display name is the same as the Element Type's main name.

String printName

A yet another user-friendly name for the Element Type provided by the DSM Driver.

Rather than the display name, which is more oriented for showing in the Template Designer, this name may be a somewhat shorter version that is more suitable for inserting in the generated documentation.

If the print name is not provided by the DSM Driver, the property returns the Element Type's main name.

String bigIconName

The name of the image resource file containing a big icon associated with the Element Type.

If no such an icon provided, the property returns an empty string.

String smallIconName

The name of the image resource file containing a small icon associated with the Element Type.

If no such an icon provided, the property returns an empty string.

GOMAttribute

Provides the most complete information about a particular attribute. This information is obtained dynamically both from the DSM (Data Source Model) representing the current data source and the DSM Type providing the data type information about the whole class of data sources this template was designed for.

See Also:

getAttr()

Properties

String name

The attribute name.

String displayName

The attribute display name.

This is a more user-friendly name which may be provided by the DSM Type in addition to the main name.

String valueType

The attribute value type (as string with the type name).

Possible types:

Type Name Implementing Java Class
"string" java.lang.String
"number" java.lang.Number
"boolean" java.lang.Boolean
"date" java.util.Date
"dateTime" java.util.Date
"binary" com.docflex.api.util.Binary
"id" java.lang.Object
"idref" java.lang.Object
"object" java.lang.Object

Note: Attributes under some DSM Type may have multiple (list) values. Such values are represented as arrays of objects of a particular value type, which is returned by this property.

In various dialogs and treeviews in the Template Designer, the list value types are shown with the square brackets (e.g. idref[]).

Within a FlexQuery-expression, you can use the multiValued property to test whether the attribute provides a list value.

To access all items of the list value, use multiValued property.

Boolean multiValued

If true, indicates that the element has a multiple (list) value.

To access all value items, use values property.

Object value

The attribute value.

If the attribute has multiple values, this property returns the first one.

Object[] values

An array of all values associated with this attribute (a vector value).

In the case of a single value, this property returns a single element array containing it.

DSMAttr dsmAttr

Returns an object representing the attribute on the level of the underlying DSM (Data Source Model). Some DSM Types may introduce their own extended attribute properties which are accessible via this object.

GOMContext

Represents a template being processed by the generator.

This object provides the dynamic information associated with the template's current processing state.

Properties

GOMElement contextElement

Represents the generator's context element.

During processing of a template, the generator always maintains some current context element around which most of the data processing occurs.

GOMElement rootElement

The root element received by this template.

GOMElement imgMapElement

This property is used when generating a hypertext imagemap for the context element's image. It represents an element associated with a certain area of the image where a hyperlink should be placed.

GnrIterator iterator

Describes the state of the current iterator (i.e. Element Iterator or Attribute Iterator).

Please note, this property points to a given iterator section only within its body-, header- and footer-blocks.

Within all the iterator section's setting expressions as well as its else-block, the iterator property always refers to the parent iterator.

GOMSectionBlock sectionBlock

Provides information about the currently executed section block.

GOMStockSection stockSection

Provides information about the stock-section call (such as parameters, etc.)

Note: This property is valid only within a stock-section body.

GOMOutputInfo output

Information about the generated output.

GOMContext rootContext

Represents the root template associated with the document being generated by the given template. If this template produces only a piece of the whole document, the GOMContext object associated with it is different from the root one.

GOMContext mainContext

Represents the main template whose processing was initially launched by the user (or from API). This template may be different from the root template in the event when the generated documentation consists of multiple documents (e.g. a framed HTML documentation).

GOMIterator

Describes the state of an iterator (such as Element Iterator or Attribute Iterator).

Properties

GOMElement contextElement

The context element received by the iterator. Normally, all iterated items (elements / attributes / attribute values) are produced from it.

Note: This property is valid within the iterator's body-, header- and footer-blocks. It remains unchanged and is not the same as the generator's current context element.

GOMIterator parentIterator

When the iterator is processed within another iterator, this property represents the parent one.

Note: The propery is valid within the iterator's body-, header- and footer-blocks.

Number numItems

The total number of items (elements / attributes / attribute values) for iteration.

Note: This property is valid within the iterator's body-, header- and footer-blocks.

Boolean isFirstItem

Indicates, if the current item is the first one.

Note: This property is valid only within the iterator's body-block.

Boolean isLastItem

Indicates, if the current item is the last one.

Note: This property is valid only within the iterator's body-block.

GOMElement element

The current element item (in the case of an Element Iterator).

Note: This property is valid only within the iterator's body-block.

GOMAttribute attr

The current attribute item (in the case of an Attribute Iterator).

Note: This property may be valid only within the iterator's body-block.

Object value

The current attribute value item (in the case of an Attribute Iterator).

Note: This property may be valid only within the iterator's body-block.

GOMElement

Represents an information about an element of the Data Source Model (a DSM element) on the level of generator.

The instances of this class are dynamically created by the generator to encapsulate the information about a particular element relevant to the current generation context.

Any DSM element at the same time may be represented by different GOMElement objects. To distinguish which DSM element is represented by a GOMElement object, use id property, which provides a unique identifier of the DSM element.

Properties

String name

The element name.

The particular meaning depends on the underlying DSM Type which represents the data source. Normally, this is the name of the Element Type associated with this element.

Object id

The element's unique identifier.

This is an object (normally String) which uniquely identifies the element within the DSM (Data Source Model). For instance, in the case of an XML-file data source, this would be the value of an element's attribute with the ID type.

See Also:

findElementById(), findElementsByIds(), getElementIds()
String valueType

The element value type (as string with the type name).

Possible types:

Type Name Implementing Java Class
"void" null
"string" java.lang.String
"number" java.lang.Number
"boolean" java.lang.Boolean
"date" java.util.Date
"dateTime" java.util.Date
"binary" com.docflex.api.util.Binary
"id" java.lang.Object
"idref" java.lang.Object
"object" java.lang.Object
If an element has no value, this property returns "void".

Note: Elements under some DSM Type may have multiple (list) values. Such values are represented as arrays of objects of a particular value type, which is returned by this property.

In various dialogs and treeviews in the Template Designer, the list value types are shown with the square brackets (e.g. idref[]).

Within a FlexQuery-expression, you can use the multiValued property to test whether the element provides a list value.

To access all items of the list value, use multiValued property.

Boolean multiValued

If true, indicates that the element has a multiple (list) value.

To access all value items, use values property.

Object value

The element value.

If the element has no value, this property returns null.
In the case, the element has multiple values, this property returns the first one.

Object[] values

An array of all values associated with this element (a list value).

In the case of a single value, this property returns a single-element array containing it. If the element has no value, an empty array is returned.

DSMElement dsmElement

Returns an object representing the DSM element on the level of the DSM Driver.

DSMElementType elementType

Returns the Element Type associated with this element.

For some DSMs (Data Source Models), there is no direct inherent association between elements and Element Types. Even though the exact association always exists, finding it may take some resources. Because of this, the association between an element and its Element Type is established dynamically and may be refined during processing of the template (in the case, the element suits to several Element Types having inheritance relationship).

This property always returns the exact Element Type associated with the given element.

Accessing this property for the first time per an element may evoke some internal calculations. So, use it only in necessary situations!

GOMElement parent

When the element was produced during execution of an Element Iterator or as a result of interpretation of a Location Path, this property returns the immediate predecessor of this element (i.e. the one from which the given element was reached).

For example, if an Element Iterator is specified to iterate by children of the received context element, all iterated elements within the iterator will have the parent property set to the iterator's context element.

If the element was not originated from processing of an Element Iterator or a Location Path, this property returns null.

GOMElement[] ancestors

This property returns an array produced from the given element as the following:

{ parent,
  parent->parent,
  parent->parent->parent,
  ... }

The sequence repeats until reaching null.

As example, let's assume an Element Iterator is specified to iterate by descendants of the received context element. Then, the ancestors property of each iterated element will provide the chain of all the element's ancestors until the iterator's context element, the context element itself, plus all ancestors of the context element.

GOMOutputInfo

Information about the generated output.

Properties

OutputFormat format

Information about the output format.

String type

Indicates what sort of output is being generated by this template.

Possible values:

"document"
the template generates a separate document file.
"included"
the template has been called from a different one to generate a piece of the document being generated by the caller.
String dir

The absolute pathname of the current output directory (i.e. where the template's output document is located).

Note: The returned pathname always ends with the name-separator character.

String file

The absolute pathname of the output document file.

Note: This is the output document whose entire or partial content is being generated by this template.

String docName

The name of the template's output document file without extension.

Note: This is the output document whose entire or partial content is being generated by this template.

String filesDir

The absolute pathname of the directory where the files associated with the template's current output document are stored (for instance, this might be a doc-files directory with the document's images).

Note: The returned pathname always ends with the name-separator character.

String inputFilesPath

The absolute pathname of the default directory where some input files associated with the currently generated output are searched.

For instance, this pathname is used during generation of the RTF output, when interpreting of embedded HTML (i.e. HTML tags embedded in doc-comments). In that case, when an <img> tag is processed, the image source specified with a relative local URL will be resolved against the default directory provided by this property.

For example, if an image tag looks like this:

<img src="doc-files/image.gif">
the actual image file will be searched at the following location:
output.inputFilesPath + "doc-files/image.gif"

Note: The pathname returned by this property always ends with the name-separator character.

Boolean estimationPhase

Returns true, if the documentation output is currently being estimated by the generator.

The generation of the whole documentation consists of two phases -- the estimation phase and the generation phase.

In the estimation phase, the generator quickly passes over all the source data and partially interprets the involved templates. During that, it collects the names and location of all documentation files to be created and all possible hypertarget locations within them. It also makes an estimation of the total generation time in order to graduate the progress bar.

During the generation phase, all template components are being fully interpreted and the real output generated.

Normally, this property is not necessary to be used in any settings of template components. The only situation when this may be required is when using one of the following functions:

GOMSectionBlock

Describes the execution state of a section block.

Properties

Number execSecCount

Returns the number of sections that have been already executed during the current pass through the section block.

A section is executed only when

  1. Its enabling condition (when specified) is true
  2. Its Matching Element Types suit to the context element

Using this property in conjunction with the enabling conditions of sections allows to specify processing of the sections in a way similar to

if (condition1)
...
elseif (condition2)
...

construction.

Let's consider, the first section has an enabling condition condition1 and the section following it should be processed alternatively to the first one when a condition2 is satisfied. To program this, the enabling condition for the second section might be the following:

sectionBlock.execSecCount == 0 && condition2

GOMStockSection

Describes a stock-section call.

Properties

String name

The stock-section name.

Object param

Returns the first parameter passed to the stock-section. If no parameters have been passed, null is returned.

Effectively, this property is the same as the following expression:

stockSection.params.length() > 0 ?
   stockSection.params.elementAt(0) : null
Object[] params

The array of parameters passed to the stock-section.

If no parameters have been passed, the empty array is returned.

GOMElement contextElement

The context element received by the stock-section.

Note: This is not the same as the generator's current context element.

OutputFormat

Describes an output format.

Properties

String name

The output format name. Possible values: "HTML", "RTF", "TXT".

String encoding

The canonical name of the character encoding used to generate the plain text output.

In the case of a non-plain text output format (e.g. HTML, RTF), this property returns the name of the Java machine's default encoding which is still used when such a format is plain-text based.

Boolean supportsPagination

Indicates if the output format supports pagination (e.g. for RTF, this is true).


Copyright© 2003-2009 Filigris Works, Leonid Rudy Softwareprodukte. All rights reserved.
To contact us, please visit www.filigris.com or e-mail to: contact@filigris.com