Returns an element linked from the specified IDREF-attribute contained in the specified element.

More exactly, the function finds an element by the unique identifier provided as the value of the specified element attribute. (See also "What is Element Unique Identifier?" below.)

The same result can be also obtained with an expression like:


findElementById (
  element.getAttrValue(linkAttrName),
  elementTypeSpec
)
However, since this operation is needed very often in some applications, a special function was introduced.

Parameters:

element

The element whose attribute is requested. If not specified, the generator context element is assumed, i.e. the same as the call: getElementByLinkAttr(contextElement, linkAttrName, ...)
linkAttrName
The name of the IDREF-attribute.

If the attribute has multiple values, the one will be used which is specified by the index parameter (see below).

index
Specify the index by which the necessary element identifier is obtained from the multi-valued array.

Precisely, the index parameter is treated the same as in the following expression:


findElementById (
  element.getAttrValues(linkAttrName)[index],
  elementTypeSpec
)
When the index is not specified, 0 is assumed by default.
elementTypeSpec
The list of matching Element Types (see "Specifying Matching Element Types" below).

When this parameter is specified, the returned element will always comply (and be resolved) with at least one the matching Element Types. If found element does not comply with any of them, the function will return null.

When this parameter is not specified, the GOMElement object returned by this function will have its element type automatically resolved according to the referenced type information (i.e. the elements of which type are linked from this attribute) provided for this attribute by the DSM Type driver.

Note: You may need to specify the matching Element Type even when the linked element is guaranteed to comply with it. In that case, the returned GOMElement instance will be resolved with that Element Type, which may be needed for further processing. (For details, see "What are Element Types?" below.)

Returns:

The found element or null otherwise (if no element with such an identifier exists or wrong attribute name or incompatible matching Element Types)

See Also:

getAttrValue(), findElementById()

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

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

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