aQuery

jQuery for the Arbortext Object Model (AOM)

aQuery is a new way to work with XML and XUI dialogs in Arbortext Editor. It makes your code shorter, easier to read, and more fun to write. It's a port of the popular jQuery library.

The current version of aQuery is 0.7. It has been tested on Arbortext 5.3 and 5.4.

The best documentation on how to use aQuery is the jQuery documentation itself. Most methods that make sense to use in an XML-only environment have been ported; a full list is below under API.

For an example of aQuery in action, load Arbortext with the custom folder provided with the source, and set the variable aQueryDir in initProject.js to the location where you've saved the aQuery scripts.

How To Use

Add aquery.js and aquery_utils.acl to your APTCUSTOM/scripts/ folder. Source them both on Arbortext start up.

To try it out, open a document and type the following on the Javascript command line (to activate the Javascript command line, place your cursor in the command line and press F5). For example, to select all titles in the active document:

var titles = $("title");

The variable titles is now a aQuery object that contains references to all of the <title/>s in the active document. For more powerful ways to select elements, see Selectors below. If you do this:

titles.text("Howdy!");

The content of every <title/> in the document is replaced with the text "Howdy!".

If you want to work with a document that is not the active document (for example, a XUI dialog), then you can use the $$ function, passing it a reference to a DOM document object:

var $dialog = $$(XUIDoc);

Now, you can select all the list items in that dialog:

var listitems = $dialog("listitem");

Note that $ and $$ are simply convenient abbreviations for aQuery and aQueryCreate respectively; you can use those instead if you prefer.

Selectors

Instead of using jQuery's CSS 3 selector syntax, aQuery uses XPath 1.0 in the form of XSLT match expressions. For example, to select all the section paragraphs in a document:

$("section/p")

To select an element with a given id, you can use the #id syntax. For example, to select the element with the id "topic-1":

$("#topic-1")

Or you can use an OID:

$("(259,1,44)")

To create a new element, you can pass the aQuery constructor a markup string. For example:

$("<section id='newsect'><title>New Section!</title><p/></section>")

returns an aQuery object containing a new <section /> element. You can also pass a DOM element to the aQuery constructor, and get an aQuery object representing that element:

$(Application.activeDocument.getElementById("topic-1"));

API

In addition to the default jQuery methods, aQuery supports the .oid() method, which returns the OID of the first element in the set of matched elements.

Virtually all traversing- and manipulation-related methods have been ported from jQuery. Event support is still weak, although bind() is provided. This is a summary of the jQuery API methods available in aQuery:

Events

• .bind() (first two overloads only)

Manipulation

• .after()
• .append()
• .appendTo()
• .attr()
• .before()
• .clone()
• .detach()
• .empty()
• .xml() (.html() in jQuery)
• .insertAfter()
• .insertBefore()
• .prepend()
• .prependTo()
• .remove()
• .removeAttr()
• .replaceAll()
• .replaceWith()
• .text()
• .unwrap()
• TODO: val()
• .wrap()
• .wrapAll()
• .wrapInner()

Miscellaneous

• .get()
• .index()
• .size()
• .toArray()

Traversing

• .add()
• .andSelf()
• .children()
• .closest()
• .contents()
• .each()
• .end()
• .eq()
• .filter()
• .find()
• .first()
• .has()
• .is()
• .last()
• .map()
• .next()
• .nextAll()
• .nextUntil()
• .not()
• .parent()
• .parents()
• .parentsUntil()
• .prev()
• .prevAll()
• .prevUntil()
• .siblings()
• .slice()

Utilities

• aQuery.contains()
• aQuery.each()
• aQuery.extend()
• aQuery.grep()
• aQuery.inArray()
• aQuery.isArray()
• aQuery.isEmptyObject()
• aQuery.isFunction()
• aQuery.isPlainObject()
• aQuery.makeArray()
• aQuery.map()
• aQuery.merge()
• aQuery.noop()
• aQuery.trim()
• aQuery.type()
• aQuery.unique()

Internals

• .context
• aQuery.error()
• .pushStack()
• .selector

Thanks

Much credit goes to John Resig and the entire jQuery team for such a great library. Thanks also to Samah Abu-Mahmeed for her feedback and for putting aQuery through its paces.

License

aQuery (like jQuery, from which it is based) can be used either under the MIT license or GPL license. For most projects, the MIT license is best, since it places almost no restrictions on what you can do with the code.