Finds an element whose XML element ID matches the one specified in elementId parameter.

This function calls directly the W3C DOM method:

org.w3c.dom.Document.getElementById()
and returns the GOMElement object representing the element returned by this method. The document, which is searched for the element, is provided by contextElement (or the generator context element when this parameter is omitted).

Notice that, although the notions of XML element ID and the element unique identifier (the one returned by GOMElement.id property) are related to each other, they are actually different things!

Each XML element ID is a string provided by the value of a certain attribute of type ID contained in the element. In theory, every element in an XML document is supposed to have an attribute of type ID that uniquely identifies that element within the entire XML document.

However, the XML 1.0 standard does not prevent a valid XML document to contain elements with the repeating identifiers as well as without them at all. Therefore, in reality, the notion of XML element ID does not provide a reliable way to uniquely identify the XML elements.

DocFlex/XML uses different means for generating element unique identifiers (actually, they are based on the references to the corresponding org.w3c.dom.Node objects). However, what is supported is that when an element does have an XML element ID, then

toString(element.id) == XML element ID

Parameters:

contextElement

Specifies the context element that provides the XML document to be searched for the requested element.

The XML document may be specified not only directly (as an element of #DOCUMENT type) but also by any other element known to belong to it.

When this parameter is omitted (or null) the generator context element will be used by default.

elementId
The ID value for an XML element.

Returns:

The matching element or null, if no element with such an ID found.

See Also:

getXMLDocument(), findElementById(), GOMElement.id