_data (The Data DOM)
These properties allow the scripter read-only access to the Data DOM (as opposed to the Form or Document DOM). The Data DOM represents the XML file that is read by Merge and whose data is merged into the document. The _data DOM represents the data for each single document in turn, not the entire data file all at once.
| Property | Description |
|---|---|
_data | This is the root object of the Data DOM. It is not yet populated at Start-of-Job, but is at Start-of-Document. |
| Return the raw (text string) value of a data item in the XML data file. This is the only Data DOM attribute for which one can leave off the leading underscore (_), though that is not recommended as it is quite possible that a data file will have a <value> element in it. |
._name | Return the name of the current Data DOM object, i.e. the tag name of an XML element. |
._fullName | Return the fully qualified name of the current Data DOM object, all the way from _data down to this object's basic name, all in dotted notation. E.g. _data.Document.Invoice.Header.CustomerId. |
._parent, ._firstChild, ._nextSibling, ._prevSibling, ._nextNode | These allow the scripter to walk the Data DOM in a logical fashion. Each function returns a Data DOM object with which one could access ._value, ._name, ._fullName, or one of these traversal functions. |
dataDomObject | (As of 3.2.001.03) Find an ancestor (not necessarily just an immediate parent) of a given name. |
dataDomObject | (As of 3.2.001.03) Find a descendant object with a given name. |
dataDomObject | (As of 3.2.001.03) Find an immediate child (not further down descendant) of a given name. |
dataDomObject | For any Data DOM object one can get the object that represents one of its children by using that child's name or tagName (case-sensitive). |
dataDomObject | Get the value of the named attribute (or "" if it doesn't exist) for this data node. attrName is case-sensitive. |
It's a bit of a philosophical debating point as to whether the above are properties or functions/methods. They certainly act like properties in that they give the appearance of a static value being made available for the asking, even though background processing may have to occur to 'come up with' the answer. The following are definitely functions.
| Function | Description |
|---|---|
| Load up a series of values in the data file and represent them as an array. The optional firstrow is an array of column names for the subsequent data, usually used when loading data for a chart. See _chart Data for an example of its usage. |
| Load up a single structure in the data file and represent it as a JavaScript object. See the example below. |
_loadAsObject Example
Suppose your data file had this construct somewhere in it:
<ShipTo> <CompanyName>Perfect Printers</CompanyName> <Address1>425 Lansing Drive</Address1> <Address2>Moline, Illinois</Address2> <Address3>USA 61265</Address3> <Address4>Tel:800.555.2323 Fax:309.762.4411</Address4> </ShipTo>
You could use: var o = _data._loadAsObject("ShipTo"); to load up that structure into a JavaScript object. We could print it out with: _logf("'%s'\n", o) and we'd see these values (manually split into multiple lines here for display purposes).
'{CompanyName:Perfect Printers, Address1:425 Lansing Drive, Address2:Moline, Illinois,
Address3:USA 61265, Address4:Tel:800.555.2323 Fax:309.762.4411}'
Notes
Notes
1. _data does not exist yet at Start-of-Job. It does by Start-of-Document.
2. If you really want to read the raw XML data file you can always:
var fp = _file.fopen(_job.command.data, "r");
while (true) {
line = fp.fgets();
if (line == null) break; // end-of-file
// do whatever you like
}
fp.fclose();
That's not a recommended course of action, just advising of an available 'port in a storm' if you become desperate. It might be used as a way to get at header/control information that occurs outside of the <Document>...</Document> boundaries. Of course, you could also use the XmlInput Class.
3. In a field's event you can refer to this._dataSource to get the _data DOM object that was used to populate the field. That is a generality that should be taken with a grain of salt. Some fields are populated with script. Some other fields, likely in error, have no associated data file element. Beware of null.
