DOM methods

Ojay provides a stack of methods for making DOM (Document Object Model) actions easier. When you create a new Ojay collection using Ojay(selector), that collection has many methods that allow you to retrieve data from and perform actions on the collection of DOM nodes it contains.

Required files

  • http://yui.yahooapis.com/2.7.0/build/yahoo-dom-event/yahoo-dom-event.js
  • http://yui.yahooapis.com/2.7.0/build/selector/selector-beta.js
  • http://yoursite.com/ojay/js-class.js
  • http://yoursite.com/ojay/core.js

node

Ojay collections are array-like objects that contain lists of DOM nodes. So if I call Ojay('p')[0] I will get back a raw HTMLElement paragraph element. Calling Ojay('p').at(0) gives you a single-memeber Ojay collection wrapping that same element.

All Ojay collections have a special property, node that refers to the first native HTMLElement in the collection. So, Ojay('p')[0] is the same as Ojay('p').node and Ojay('p').at(0).node.

How DOM methods work

There are two broad types of methods: getter (accessor) methods, and setter (mutator) methods. Getters return data and information about an object without changing the object, and setters change the object’s state.

In Ojay, all getter methods return data about the first member of the collection. If you want information about some other member, grab it using at().

    style = Ojay('p').getStyle('fontSize');
    style = Ojay('p').at(7).getStyle('fontSize');

All setter methods perform some action, like setting a style or animating the collection, and return the collection. This means that setter methods are chainable, so you can write:

    Ojay('p').setStyle({color: 'red'}).addClass('anim')
        .animate({left: {by: 200}}, 5);

A handful of methods – on(), animate() and wait() – actually return MethodChain objects, but the basic thing to remember is

  • Getter methods return data from the first member
  • Setter methods act on all members and are chainable

Class name methods

Ojay has the following methods for manipulating class names on HTML elements:

  • addClass(className) – adds the given className to all members of the collection.
  • removeClass(className) – removes the given className from all members of the collection.
  • replaceClass(oldClass, newClass) – replaces oldClass with newClass on all members of the collection.
  • setClass(className) – sets the class name on all members to className all previous class names are discarded.
  • hasClass(className) – returns true iff the first member of the collection has the given className.

All except hasClass are chainable. Examples:

    Ojay('a').addClass('popup').removeClass('foo');
    Ojay('#widget').hasClass('bar')   // -> true or false

Attribute methods

Ojay’s set() method alters the attributes of all elements in an Ojay collection. To make all forms on the page perform GET requests when submitted, you could write:

    Ojay('form').set({method: 'get'});

While to change the value of an input field, you could write:

    Ojay('input#first-name').set({value: 'John Smith'});

You can specify multiple attributes together to save you lots of lines of DOM code:

    Ojay('form.contact').set({
        method:   'post',
        target:   'someFrame',
        action:   '/path/to/action.html'
    });

Styling methods

These manipulate CSS styling properties on elements. setStyle() is chainable, getStyle() is not. hide() and show() are chainable.

  • setStyle(properties) – sets the style of all elements to the given values.
  • getStyle(name) – returns the value of the named style from the first member in the collection.
  • hide() – hides all members by setting their display style to "none".
  • show() – unhides all members by setting their display style to "".

Examples:

    Ojay('h1).setStyle({margin: '16px 0', fontSize: '24px'});
    var color = Ojay('#widget').getStyle('color');

Document traversal methods

Ojay gives each collection some methods to find DOM nodes relative to their members. These are:

  • parents()
  • ancestors()
  • children()
  • descendants()
  • siblings()

All these return an Ojay collection containing the elements with the specified relationship to the current collection. Each one takes an optional argument - a CSS selector – to filter the result.

Examples:

    // Get all elements containing links as children
    Ojay('a').parents()

    // Get all an element's descendants with a given class
    Ojay('#something').descendants('.classname')

A couple of related methods are:

  • matches(selector) – returns true iff the first member of the collection matches the given CSS selector.
  • query() – returns the elements of the collection that match the given selector.

wait()

wait() delays execution of a chain for the given length of time. The time can be specified as a number of seconds, or as a function that returns a number based on the position of an element in the collection.

    Ojay('h1').wait(3).animate({
      fontSize: {to: 200, unit: 'px'}
    }, 4.5);

    Ojay('li').wait(function(item, i) { return 0.3*i })
        .setStyle({color: 'red'})
        .children().hide();

Region methods

Ojay provides a wrapper layer around the YAHOO.util.Region class to make it a little easier to work with. To get the region of the first element in a collection just call:

    var region = Ojay('#some-element').getRegion();

This returns an Ojay.Region object, with various methods for getting properties of the region. See the region documentation for more info.

Ojay does provide some shortcuts for getting region properties from an element. These include:

  • getWidth(), getHeight()
  • getTop(), getRight(), getBottom(), getLeft()
  • getCenter()
  • areaIntersects(), areaContains()
  • intersection()

These are shortcuts for:

  • Ojay('#foo').getRegion().getWidth(), etc
  • Ojay('#foo').getRegion().top, etc
  • Ojay('#foo').getRegion().getCenter()
  • Ojay('#foo').getRegion().intersects(), Ojay('#foo').getRegion().contains()
  • Ojay('#foo').getRegion().intersection()