Returns the nearest predecessor of the specified element which complies with one of the specified Element Types.

The element predecessors are other elements by which the given element has been reached as it was retrieved from the data source (DSM). See also "What are element predecessors?" below.

This function, actually, returns the same result as the following expression:


findElementByType (
  element.predecessors,
  elementTypeSpec
)
The difference is that it is more compact and will work much faster (as it iterates directly by the predecessor chain and no intermediate array is allocated).

Parameters:

element

The element whose predecessor is requested.

If not specified, the generator context element is assumed, which is the same as the call:


findPredecessorByType (
  contextElement,
  elementTypeSpec
)
See Also: GOMContext.contextElement

Note: When this parameter is null, the function just returns null as well.

elementTypeSpec
The list of target Element Types (see "Specifying Matching Element Types" below).

The returned element will comply with one of the target Element Types.

Note: When the list contains names of non-existent Element Types, the generator will raise an error.

elementTypes
This parameter provides an alternative way to specify the target Element Types.

In this case, the Element Types are specified via an array of GOMElementType objects representing each Element Type.

The difference from the 'elementTypeSpec' parameter is that, there is no need to parse the Element Type specification (and find the corresponding Element Types) during the function call, which is time-consuming.

Instead, you can prepare/parse the necessary Element Types preliminary using getElementTypes() function, and then just pass them via this parameter.

This should improve performance when the function is called repeatedly with the same target Element Types.

Notes:

  1. If all target Element Types are known, they all should be specified directly in 'elementTypeSpec' parameter. In that case, the Element Type specification will be parsed/prepared only once when parsing the whole expression.
  2. If the passed GOMElementType[] array is null or empty, the function will return null.

See Also:

getElementTypes(), findElementByType(), GOMElement.predecessors

${include ../../../refs/element_predecessors.htm}

${include ../../../refs/matching_ets_spec.htm}