_document
This is the Document Object Model (DOM) object for the current document being processed. It enables access to field data and form field attributes. It contains a hierarchy that reflects the design's nested structure of Pages, Containers, Panes and Groups with their Fields and Text Labels, and it also reflects the various instances of those objects created as a result of merging data into the form design. For example:
_document.main_pane.header_pane.customer_name._value
The DOM is specific to the current combination of form design and data, and it reflects the current design's structure. _document reflects the top-level object in the document, i.e. the Form object.
One thing to be careful of is that if a Pane is optional and the data stream does not force its instantiation, then a reference to that Pane or to objects within that Pane will result in a runtime error. When scripting, you should keep the possibility of 'non-existence' of Panes in mind. See domObj.DOM and domObj.DOMValue.
Another thing is that you will have multiple instances of the same Pane and in those cases you must take care to specify which occurrence you wish to reference. Remember that when pagination occurs (and for all events after that), there is an even greater likelihood of multiple occurrences of Panes, even ones not marked as being Allow Multiple. This occurs because page headers and footers may have been injected multiple times. Multiple instances of a Pane can also occur if it had to be split across pages. In that case, the Pane object will exist in the DOM on both (or more) pages, with a part of the Pane on each page. Typical error messages in such cases are ScriptExtendedSyntax and DJ-GetResolveValName.
Use of this._parent, this._ancestor() and this._descendant() can relieve a lot of the "have to know the occurrence number" headaches. Another technique is to stuff a value of interest, using a local reference, like this._value, into an _cache variable and then later referencing that _cache variable.
The following script can help you understand the current document structure:
for (var o=_document; o; o=o._nextNode) {
if (pn._type == "Pane") _logf("%s\n", o._fullName);
}
Note that the results of that will not be the same at all events so be sure to explore the document structure in the event where you are puzzling out an issue.
Dom Object Attributes
Fields and Text Labels have values and attributes (font, color, margins, and so on) which can be accessed and modified in script by specifying the name of the Field or Label followed by a dot followed by the attribute name. The value of the Field or Label is accessed as just another attribute named _value. The DOM properties topic (See DOM Properties) identifies the many, many properties that are available for reference. In that list the attributes are marked as return or set. return indicates that the attribute value may be accessed from script, while set indicates that it may be modified using script. There are versions of these attributes which do not have the leading underscore(_) in their names. However, the use of the leading underscore is highly recommended so as to avoid potential conflict with the object names in a document.
Other DOMs
See also the _page DOM. It is rarely used and reflects only a page subset of the overall _document DOM.
Note that the _data DOM is a completely different DOM, reflecting the XML data that is applied to the form design.
