DOM Access from JavaScript
Overview
PTC Arbortext Layout Developer provides DOM Level 2 Core functionality in JavaScript. This allows you to work directly with the XML DOM using a standard mechanism, rather than using proprietary PTC Arbortext Layout Developer methods or XPath. Using DOM functionality you can create, manipulate, and query XML DOMs held by PTC Arbortext Layout Developer. In some cases using DOM is more efficient and quicker than using XPath so there are some performance benefits to using this functionality.
PTC Arbortext Layout Developer creates an XML DOM from XML text streams (either .xm tags or other tags which are instructed to behave as XML) or from XML DOM streams (.xd tags). XML text streams provide a read-only DOM while XML DOM streams provide a read-write DOM.
The Formatting Object Model includes extension objects prefixed by fx. These support PTC Arbortext Layout Developer’s DOM support and provide access to PTC Arbortext Layout Developer functionality not represented in the standard DOM model.
PTC Arbortext Layout Developer’s extensions to DOM
Refer to the Formatting Object Model Reference for full descriptions of PTC Arbortext Layout Developer’s DOM extension objects. They include several useful properties and methods.
The majority of the properties and methods are available on: fxAttribute, fxCDATASection, fxComment, fxDocument, fxDTD, fxElement, fxEntity, fxEntityReference, fxNode, fxNotation, fxProcessingInstruction, fxText
Properties:
• startPosition, endPosition, startContent, endContent —provide the character position in the content stream of the start or end of the node or its content
• hasAugmentation — returns a number describing the type of augmentation applied to the node
The AugmentationType constant describes the number. The number advises whether there is before, after, or reference augmentation applied to the current node.
• withinAugmentation — tests whether the current node is part of DOM augmentation, with a boolean value
The property allows you to determine which type of navigation is needed to keep within the augmented subtree.
• augFirstChild, augLastChild, augPreviousSibling, augNextSibling, augParentNode, augRefererNode — provide augmentation versions of the normal DOM node properties
augRefererNode provides access to the reference node information applied to augmented DOM objects.
• extendedNodeType — returns a number indicating the node type of the current node, as described by the NodeType constant
The extended node types include XInclude, DTD node types, and whitespace.
Methods include:
• getNodePath() — returns a string of the location path to the current node
• evaluateXPath() — provides a means to evaluate an XPath expression relative to the current node
This method returns an XPathResult object.
• getPage() — returns the number of the page on which the current node appeared
• getUserString() and setUserString() — provide access to the user data nodes set on the current node
• augmentBefore(), augmentAfter(), and augmentReference() — provide DOM methods for augmenting the node
• augSerialize() and serialize() — write out the node to a string with, or without, augmentation nodes applied, respectively
Serialization can be pretty printed if required.
Creating a New DOM in PTC Arbortext Layout Developer
A new DOM created in PTC Arbortext Layout Developer must be attached to an XML DOM type tag (.xd). With this tag association PTC Arbortext Layout Developer handles the new DOM correctly, including applying it as the content of frames.
This example code creates a new DOM in PTC Arbortext Layout Developer:
//Create a new DOM
//First create a stream
var stream = template.content.streams["newDOM"];
if (!stream) {
stream = template.content.createStream("newDOM",fTag.TYPE_XML_TREE);
}
//Create DOM and associate it with the stream
stream.xmlDocument=application.domImplementation.createDocument("", "article", null);
//Get the XML DOM
var DOM = stream.xmlDocument;
In this example, the code checks for the existence of the XML DOM stream named newDOM. If it does not exist, it is created.
Then, the DOM is created using the application.domImplementation.createDocument() method, a DOM Level 2 Core method. Using this method the root element of the DOM is specified as article. The first parameter of the method, not declared in this example, can be used to specify the namespace of the root element. The last parameter, set to null in this example, can be used to specify a type of document to be created.
The stream.xmlDocument property provides access to the new DOM, which is attached to the XML DOM tag.