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:
However, since this operation is needed very often in some applications, a special function was introduced.findElementById ( element.getAttrValue(linkAttrName), elementTypeSpec )
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 theIDREF
-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}