What are Location Paths?

Location Paths are special expressions similar to the expression of XML XPath. Such expressions are used to specify the search of element or attributes reachable from a given (context) element.

Each Location Path has the following structure:

Step1 / Step2 / ... / StepN
The Location Paths that specify the search of only elements are called Element Location Paths. They consist of only Element Location Steps.

Those Location Paths specifying the search of attributes are called Attribute Location Paths. In them, the steps from Step1 to StepN-1 are also Element Location Steps. However, the last step must be an Attribute Location Step (see below).

Each Element Location Step may have the following structure:

axis :: ETs [filter]
where

axis

Specifies the search axis. This determines a subset of the element tree from which the elements are collected during interpretation of the given step. DocFlex supports the following axes:
Axis Description
child Includes children of the step's context node. This axis is used by default (i.e. when no axis:: prefix is specified at the location step).
self Includes only the step's context node itself
child-or-self Includes the step's context node and all its children
descendant Includes all descendants of the step's context node (i.e. its children, children of the children and so on)
descendant-or-self Includes the step's context node and all its descendants
attribute^ This is the link-axis, which is an extension of XPath introduced in DocFlex. It contains those elements of the whole DSM (Data Source Model) whose IDs (unique identifiers) are the values of the specified attribute of the step's context node.

See Also: GOMElement.id

{ expr } This axis, called formula-axis, is another extension of XPath introduced in DocFlex. It covers functionally all other axes and is, probably, the ultimate axis imaginable.

The elements included in that axis are produced by the FlexQuery expression specified between the curly brackets. The expression should return the enumeration of new elements, which it may produce from the step's context node (the element) passed to the expression as the generator context element.

For example, the step:

child::Person
will do the same as the step:
{ findChildren (
"Person")
}::Person
The real power of the formula-axis is that you can program within the embedded expression any method of finding elements (including finding them using element maps). That profoundly transforms capabilities of the entire search possible to organize using location paths!

Note: The expression specified in formula-axis should always return the Enumeration type. Otherwise, the generator will raise an error.

The returned enumeration should contain objects of GOMElement or DSMElement types (objects of other types will be ignored).

The null value returned by the expression will be interpreted as an empty enumeration.

ETs
Specifies one or several matching Element Types. Each element, to be included in the step's result set, should comply with at least one of the specified matching Element Types. The list of the matching Element Types can be defined as:
filter
This is a boolean FlexQuery-expression which defines the subquery for the location step filter.

When specified this subquery is executed for each element to be included in the step's result set. An element is included in the result set only when the subquery returns true.

The tested element is accessible within the subquery as the generator context element (via the contextElement variable). The previous context element is overshadowed (it is restored again after the Location Path processing is finished).

Note: The filtering subquery is compiled dynamically within the implementation of this function. Thus, there is no way to check it before execution. Syntax errors within the subquery will cause an exception during the processing of the Location Path.

Each Attribute Location Step has the following structure:

@attribute
where attribute is the name of the searched attribute. The Attribute Location Paths are normally used to collect values of the same attribute by a number of elements at once.

Compound Location Paths

You may join several Location Paths using '|' delimiter into a single expression:

lpath1 | lpath2 | ... | lpathN
Such an expression, called Compound Location Path, is interpreted by consecutive interpretation of the Location Paths contained in it. The result is a union of elements or attributes produced by each constituent Location Path.