domObj.DOM
(Merge only) (As of 3.1.001.17/21)
Find a DOM object by dotted document object name. Document DOM only, not Data DOM.
Syntax
(As of 3.1.001.21) domObj.DOM(dottedName)
domObj._DOM(dottedName)
Returned Value
The document object that was found or null if it was not found.
Parameters
dottedName defines the name of the object which is to be found. This is a literal string or a variable that contains a string. E.g. "Details.Detail.Item".
Usage
This can be a very effective, and safe, way to detect whether an object exists. Scripters often make the mistake of referring to objects in optional panes, causing their script to fail if the referenced pane does not exist.
this._value = this.optionalPane.Item._value ; // will fail if optionalPane does not exist
Some scripters try to protect themselves by using: if (this.optionalPane._count > 0)... but that fails, ending the script if optionalPane does not exist. More wary scripters might use the childNamed(...) or descendant(...) functions and that is good, however, this DOM(...) function is hoped to be easier for scripters to use.
Note that DocOrigin's flexibility in dotted names comes to the fore. You do not need to specify every segment of the object's name. DocOrigin will make intelligent inferences based on the object context (the domObj in domObj.DOM). It checks the siblings of domObj, then the descendants of domObj, then the descendants of the siblings of domObj and continually fans out to find a nearby object that satisfies what was provided in the dotted name argument. Of course, you can supply a full dotted name if you wish. The important thing is that your script will not fail and you can safely check if the result is null.
