fivetanley/dom

DOM traversal, manipulation and events aggregate library (like jQuery)

dom

jQuery inspired DOM traversal / manipulation component. Aggregates the following components to create a more familiar experience when you need the combined functionality of:

• domify to convert HTML to DOM nodes
• classes to add, remove, and toggle classes
• delegate for event delegation
• event for event binding
• type for type checking

Installation

$ component install component/dom

Example

var dom = require('dom');

dom('li').select(function(el){
  return el.text() == 'Maru';
}).addClass('amazing');

API

... not even remotely done, feel free to fork and help ...

API

• dom(id)
• dom(html)
• .length()
• .get(i)
• .at(i)
• .first()
• .last()
• .addClass(name)
• .removeClass(name)
• .toggleClass(name)
• .hasClass(name)
• .find(selector)
• .each(fn)
• .forEach(fn)
• .map(fn)
• .select(fn)
• .filter(fn)
• .css(prop, value)
• .css(prop)

dom(id)

should return an element by id.

var list = dom('<ul><li id="one">foo</li><li id="two">bar</li></ul>');
list = dom('#two', list);
assert(1 == list.length(), 'expected length of 1');
assert('bar' == list.get(0).textContent);

dom(html)

should return a dom List of elements.

var list = dom('<em>Hello</em>');
assert('Hello' == list.get(0).textContent);

.length()

should return the number of elements.

var list = dom('<em>Hello</em>');
assert(1 == list.length());

.get(i)

should return the element at i.

var list = dom('<em>Hello</em>');
assert('Hello' == list.get(0).textContent);

.at(i)

should return the element at i as a List.

var list = dom('<em>Hello</em>');
assert('Hello' == list.at(0).get(0).textContent);

.first()

should return the first element in the List.

var list = dom('<ul><li>foo</li><li>bar</li></ul>').find('li');
assert('foo' == list.first().text());

.last()

should return the last element in the List.

var list = dom('<ul><li>foo</li><li>bar</li></ul>').find('li');
assert('bar' == list.last().text());

.addClass(name)

should add the given class name.

var list = dom('<em>Hello</em>');
list.addClass('foo').addClass('bar');
assert('foo bar' == list.get(0).className);

.removeClass(name)

should remove the given class name.

var list = dom('<em>Hello</em>');
list.addClass('foo').addClass('bar').removeClass('foo');
assert('bar' == list.get(0).className);

.toggleClass(name)

should toggle the given class name.

var list = dom('<em>Hello</em>');

list.toggleClass('show');
assert('show' == list.get(0).className);

list.toggleClass('show');
assert('' == list.get(0).className);

.hasClass(name)

should return true when the classname is present.

var list = dom('<em>Hello</em>').addClass('show');
assert(true === list.hasClass('show'));

should return false when the classname is not present.

var list = dom('<em>Hello</em>').addClass('show');
assert(false === list.hasClass('hide'));

.find(selector)

should return descendants matching the selector.

var list = dom('<ul><li>foo</li><li>bar</li></ul>');
list = list.find('li');
assert(2 == list.length());

.each(fn)

should iterate passing (list, i).

var list = dom('<ul><li>foo</li><li>bar</li></ul>').find('li');

var indexes = [];
var values = [];
var ret = list.each(function(el, i){
  indexes.push(i);
  values.push(el);
});

assert(ret == list, 'should return self for chaining');
assert(0 == indexes[0]);
assert(1 == indexes[1]);
assert(values[0] instanceof dom.List, 'values should be dom lists');
assert(list.get(0) == values[0].get(0));
assert(list.get(1) == values[1].get(0));

.forEach(fn)

should iterate passing (el, i).

var list = dom('<ul><li>foo</li><li>bar</li></ul>').find('li');

var indexes = [];
var values = [];
var ret = list.forEach(function(el, i){
  indexes.push(i);
  values.push(el);
});

assert(ret == list, 'should return self for chaining');
assert(0 == indexes[0]);
assert(1 == indexes[1]);
assert(!(values[0] instanceof dom.List), 'values should be elements');
assert(list.get(0) == values[0]);
assert(list.get(1) == values[1]);

.map(fn)

should map passing (list, i).

var list = dom('<ul><li>foo</li><li>bar</li></ul>').find('li');

var ret = list.map(function(el, i){
  return el.text();
}).join('|');

assert('foo|bar' == ret);

.select(fn)

should filter passing (list, i).

var list = dom('<ul><li>foo</li><li>bar</li></ul>').find('li');

var selected = list.select(function(el){
  return el.text() == 'bar';
});

assert(1 == selected.length(), 'invalid length');
assert(selected.get(0) == list.get(1));

.filter(fn)

should alias .select.

assert(dom.List.prototype.filter == dom.List.prototype.select);

.css(prop, value)

should set a style value.

var list = dom('<em>Hello</em>');
list.css('display', 'none');
assert('none' == list.get(0).style.display);

.css(prop)

should get a style value.

var list = dom('<em>Hello</em>');
list.css('display', 'none');
assert('none' == list.css('display'));

Notes

It is recommended that you do not depend on this library directly when creating public components, unless you require most or all of the functionality provided. Otherwise it is preferred that you use the smaller more specific components.

This lib will not include any XHR support, that is out of scope, this library is for DOM manipulation, traversal, and events only.

License

MIT