dom

The dom plugin handles DOM navigation and manipulation with a focus on navigating and manipulating the spirits associated to DOM elements. It is less suited for general DOM navigation, so you might want to compliment Spiritual GUI with some like jQuery for that.

Queries

The spirit can lookup elements and other spirits using CSS selectors. The selector is required, the type, is optional.

this.dom.q(selector, type); // first descendant
this.dom.qall(selector, type); // all descendants
this.dom.qdoc(selector, type); // first in document
this.dom.qdocall(selector, type); // all in document

Given a single argument, the CSS selector, the methods return either a DOM element or an array of elements.

this.dom.q('a'); // [object HTMLAnchorElement]
this.dom.qall('a').length; // 23

The second argument type is a spirit constructor. When specified, the methods return either a spirit or an array of spirits. You can use gui.Spirit to find any kind of spirit.

this.dom.q('a', gui.Spirit); // [object MyLinkSpirit]
this.dom.qall('a', MyLinkSpirit).length; // 23

The two methods qdoc and qdocall work the same way, except they search from the document node instead of the spririts DOM subtree.

The dom plugin also features more traditional methods for navigating back and forth in the DOM structure. The type argument is optional.

this.dom.parent(type); // parent element or spirit of type
this.dom.child(type); // first child element (or spirit)
this.dom.children(type); // all children
this.dom.ancestor(type); // first ancestor
this.dom.ancestors(type); // all ancestors
this.dom.descendant(type); // first descendant
this.dom.descendants(type); // all descendants
this.dom.next(type); // next sibiling (of type)
this.dom.previous(type); // previous sibling
this.dom.following(type); // all following siblings
this.dom.preceding(type); // all preceding siblings
this.dom.first(type); // first child (or spirit of type)
this.dom.last(type); // last child (or spirit of type)

If you omit the type argument, these methods will return either a DOM element or an array of elements. In this case, some methods become redundant. For example, parent() and ancestor() always return the same element.

If you add a second argument in the form of a spirit constructor, the methods can be used to lookup spirits. Use gui.Spirit to lookup all kinds of spirits.

this.dom.descendants(gui.Spirit).length; // 23
this.dom.ancestor(TopMenuSpirit); // [object TopMenuSpirit]
this.dom.last(ButtonSpirit); // [object ButtonSpirit]

We'll save the detailed walkthrough of these methods for a more convenient time. Let's talk about DOM manipulation.

Manipulation

The following methods can be used to insert things inside-of, instead-of or next-to the spirit. They share the same signature.

this.dom.append(things); // append element(s) or spirit(s)
this.dom.prepend(things); // prepend thing(s)
this.dom.before(things); // insert thing(s) before
this.dom.after(things); // insert things(s) after
this.dom.replace(things); // replace with thing(s)

The things argument is complicated. It can be either:

There's also this method.

this.dom.appendTo(thing); // append to element or spirit

It goes along with some methods that are still under development.

Add methods insertBefore and so on + add a note on second-step navigation (stuff only works in spirits).