Customizing Arbortext using the Arbortext Object Model (AOM)
What is the Arbortext Object Model?
One of Arbortext Editor's biggest strengths is the flexibility it offers for customizing the editing interface to suit your specific authoring process. If you've been implementing and supporting Arbortext for a while, you are probably familiar with the built-in Arbortext Command Language (ACL) scripting framework. This is a powerful script language and library of functions for navigating and modifying structured document content as well as the Editor user interface.
For those who may be new to Arbortext customization, who are accustomed to an object-oriented approach to software development, there is another framework for developing Arbortext features. This framework is known as the Arbortext Object Model, or AOM for short.
The Arbortext Object Model is a set of object-oriented interfaces for developing Arbortext custom features. It extends the W3C Document Object Model (DOM), which you will probably be familiar with if you've done any web development. The standard DOM provides basic methods for getting document nodes, iterating over an element's children, accessing and modifying attribute values, removing existing nodes or creating new nodes, and so on.
The AOM extends this model by adding and extending interfaces to handle features that are specific to the editing and publishing of XML-based documents. The next section provides an overview of the most important Arbortext extensions in the AOM.
One of the biggest advantages of using the AOM is that the implementation is accessible from a variety of development platforms, including:
- Any other environment that supports Microsoft's COM technology
So an AOM approach to developing customizations can let you leverage your development staff's expertise with these mainstream development platforms.
What's In the AOM?
The Arbortext Object Model consists of three general categories of interfaces:
- Standard W3C DOM interfaces
This would include the familiar objects and method found in any web application, such as Document, Node, and Range.
- Arbortext Extensions to the DOM interfaces
These are interfaces that extend DOM objects to add editing-oriented methods and properties to DOM objects. These interfaces generally have the same name as the original DOM interface with an "A" prefix, for example ADocument, ANode, and ARange.
- Custom interfaces for controlling the Arbortext software
This would include interfaces for modifying the user interface, setting program preferences, invoking ACL code, composing documents, working with tables in documents, and controlling a Content Management System (CMS) adapter.
var docname = doc.name;
would be written like this in Java:
String docname = ((ADocument) doc).getName();
Standard DOM Interfaces
All the standard level 1 DOM interfaces, most of the level 2 interfaces, and many level 3 interfaces are supported in the AOM. This means that the standard techniques you would use in a web application for navigating the document structure will also work here. For example, you can use Document.getElementById() to find an element with the a specific ID, or you can use Node.childNodes to iterate over the child nodes of a particular node.
The standard interfaces are described at the W3C web site. The Arbortext Help Center includes descriptions for these interfaces, including annotations about specific methods or properties that may not be fully supported in Arbortext.
Arbortext Extensions to DOM Interfaces
To facilitate editing, Arbortext provides some additional interfaces that add new capabilities to the objects defined in the standard DOM. Some of the more useful Arbortext extensions include:
- ADocument: extends the Document interface with methods and properties unique to an editing environment, including:
- insertionPoint property: returns a Range object representing the location of the caret
- textSelection property: returns a Range object representing the document content selected (highlighted) in the editor window
- save() method: serializes the updated version of the document to the file system or the CMS
- undo() method: undoes the previous operation, similar to the user pressing Ctrl-Z
- ANode: extends the Node interface. Useful members include:
- firstOID property: the ACL OID of the node, which you can pass as a parameter value when you call ACL code via the Acl object (see below)
- tableObject property: if the node is inside a table structure, this will return the lowest-level table object corresponding to the node. For example, if node is an <entry> element in an OASIS table, node.tableObject will return a TableCell object
- contextPath method: returns a list of context strings indicating the structure needed to validly insert this node inside the target node
- distanceTo method: returns a measure of the distance between two nodes in the document
- AElement: extends the Element interface. Useful members include:
- getElementsByAttribute method: returns a list of descendant elements that have a specific attribute, or that have a specific value for a specific attribute
- ARange: extends the Range interface. Useful members include:
- insertParsedString method: parses a string of XML markup into a document fragment and inserts it at the beginning of the range
- toMarkupString method: returns the content of the range as a string of XML markup
Custom Arbortext Interfaces
These interfaces are unique to Arbortext, and are not extensions of existing DOM interfaces. They include:
- Acl: provides a mechanism for accessing ACL features from AOM-based code. Useful members include:
- eval method: executes a string of ACL code and returns the value returned by the ACL code
- execute method: executes a string of ACL commands where a return value isn't required
- DOMOID property: converts an ACL object identifier (OID) to an AOM Node or ANode object
- getVar method: returns the value assigned to an ACL variable
- Application: represents the main Arbortext Editor application. This serves a similar purpose to the Window object in HTML web application development. Useful members include:
- alert and print methods: generate a popup window (alert) or a message in the Arbortext messages window (print) to provide some feedback or information to the user
- openDocument method: opens a document from a file or CMS, or creates a new file with a specified doctype
- activeDocument property: returns a Document object corresponding to the XML document currently open in the Editor window
- activeWindow property: returns a Window object representing the Arbortext Editor window with current focus
- CMS* Interfaces: a set of interfaces for managing the adapter between Arbortext Editor and a content management system such as Arbortext Content Manager. Useful interfaces include:
- CMSAdapter: the main interface for controlling the adapter at a high level
- CMSSession: interface for accessing properties and methods of the current CMS session
- CMSObject: interface for managing an object stored in the CMS, such as an XML object or a graphic file
- Composer: represents the composition framework for publishing XML-based documents. Useful members include:
- isParamRequired method: returns a boolean value representing whether or not a specified parameter needs to be specified for a publishing operation
- runPipeline method: executes the composition process to publish the document. Parameters are passed as a PropertyMap.
- Table* Interfaces: a set of interfaces for managing table operations. Because of the complexities of tables, it is often easier and more reliable to handle tables using these specialized interfaces rather than trying to modify the underlying markup directly. Useful interfaces include:
- TableGrid interface: this represents a table grid, corresponding to a <tgroup> element in an OASIS table
- TableColumn, TableRow, TableCell interfaces: represent the corresponding structures in a table. Note that the TableColumn interface provides a way to interact directly with a table column, which is difficult to do via direct modifications to the underlying markup.
The AOM also provides some custom events to give you the capability to handle certain editing-specific operations. In most cases, the event names are self-explanatory. The event object generated has properties to let you access the associated content and do something useful with it, as well as canceling or otherwise modifying the standard event handling.
- AEdit events: these are events triggered by editing operations, including:
- ADocument events: events triggrered by document operations, including:
TerraXML has extensive experience developing Arbortext applications using both ACL and the AOM framework. If you need help developing an application, or would like specialized training to get your own development staff started with Arbortext application development, contact us to discuss options to get you on your way.