README
Lean DOM Manipulation
This isn't a drop-in replacement for jQuery, but rather a different implementation. Dominus is jQuery minus the cruft, with a footprint of ~4kB minified and gzipped, vs the ~33kB in jQuery. Dominus uses sektor
as its selector engine of choice, which is a drop-in replacement for Sizzle, but tens of times smaller in exchange for a more limited feature-set.
Just like with jQuery, Dominus exposes a rich API that's chainable to the best of its ability. The biggest difference with jQuery at this level is that the Dominus
wrapper is a real array. These arrays have been modified to include a few other properties in their prototype, but they don't change the native DOM array. See poser
for more details on that one. All of this means you can .map
, .forEach
, .filter
, and all of that good stuff that you're used to when dealing with JavaScript collections, and at the same time you get some extra methods just like with jQuery.
Install
Using Bower
bower install -S dominus
Using npm
npm install -S dominus
API
The API in Dominus begins with the methods listed below, which allow you to grab an object instance.
Static Methods
These are the static methods provided by Dominus. Consider these the entry point, just like the methods exposed by jQuery on $
.
dominus()
Returns an empty Dominus
collection.
dominus(HTMLElement)
Wraps the HTMLElement
object in a Dominus
collection.
dominus(Dominus)
Returns the Dominus
collection, as-is.
dominus(Array)
Returns a Dominus
collection with the HTMLElement
objects found in the provided array.
dominus('<{tag-name}>')
Returns a Dominus
collection after creating an element of the provided tag type name.
dominus(selector, context?)
See dominus.find
below.
dominus.find(selector, context?)
Queries the DOM for the provided selector, using sektor
. Returns a Dominus
collection with HTMLElement
objects. If context
is provided then the search is restricted to children of context
. The context
can be either a DOM element, a selector string, or a Dominus object (the first DOM element in the group is used).
dominus.findOne(selector, context?)
Queries the DOM for the provided selector, using sektor
. Returns the first matching HTMLElement
object, if any. If context
is provided then the search is restricted to children of context
. The context
can be either a DOM element, a selector string, or a Dominus object (the first DOM element in the group is used).
dominus.custom(name, type, filter)
See Custom Event Filters below.
Instance Methods
Once you've gotten yourself a Dominus
collection, there's a few more methods you'll get access to. I'll denote array instances as a
, where possible.
First off, there's the selection methods.
Navigation API
These methods let you search the DOM for the nodes that you want to manipulate.
a.prev(selector?)
Returns the previous sibling, optionally filtered by a selector
.
a.next(selector?)
Returns the next sibling, optionally filtered by a selector
.
a.parent(selector?)
Returns the first parent element, optionally filtered by a selector
.
a.parents(value?)
Returns all parent elements, optionally filtered by another Dominus collection, a DOM element, or a selector.
a.children(value?)
Like .find
, but only one level deep. Optionally filtered by another Dominus collection, a DOM element, or a selector.
a.find(selector)
Queries the DOM for children of the elements in the array, using the provided selector. Returns a single Dominus
collection containing all of the results.
a.findOne(selector)
Queries the DOM for children of the elements in the array, using the provided selector. Returns the first matching HTMLElement
object, if any.
a.where(selector)
Returns a subset of the elements in the array that match the provided selector.
a.is(selector)
Returns whether at least one of the elements in the array match the provided selector.
Then there's also the attribute manipulation API.
Attribute Methods
These methods let you modify DOM element attributes or properties.
a.html(value?)
If a value
is provided then every element in the Dominus
collection gets assigned that HTML value
, then a
is returned for chaining. If you don't provide a value
, you get the HTML contents of the first node in the Dominus
collection back.
a.text(value?)
If a value
is provided then every element in the Dominus
collection gets assigned that plain text value
, then a
is returned for chaining. If you don't provide a value
, you get the plain text contents of the first node in the Dominus
collection back. In the case of elements that can be checked
, the native value
property is used instead.
a.value(value?)
If a value
is provided then every element in the Dominus
collection gets assigned that input value
, then a
is returned for chaining. If you don't provide a value
, you get the input value of the first node in the Dominus
collection back. In the case of elements that can be checked
, the native checked
property is used instead.
a.attr(name)
The name
attribute's value is returned, for the first element in the collection.
a.attr(name, value)
Every element in the collection gets assigned value
to the attribute property name
. Passing null
or undefined
as the value
will remove the attribute from the DOM element entirely.
a.attr(attributes)
The attributes
map is used to assign every property-value pair to the attributes in every element.
a.addClass(value)
Adds value
to every element in the collection. value
can either be a space-separated class list or an array.
a.removeClass(value)
Removes value
from every element in the collection. value
can either be a space-separated class list or an array.
a.setClass(value)
Sets value
for every element in the collection. value
can either be a space-separated class list or an array.
a.hasClass(value)
Returns true
if at least one of the elements in the collection matches every class in value
. value
can either be a space-separated class list or an array.
a.css(prop)
Gets the CSS property value for prop
from the first element in the set of matched elements. camelCase
gets converted into hyphen-case
.
a.css(prop, value)
Sets the CSS property value for prop
to value
for every element in the set of matched elements. camelCase
gets converted into hyphen-case
.
a.css(props)
Sets the CSS property values for every element in the set of matched elements using the provided props
map. camelCase
gets converted into hyphen-case
.
Example:
dominus('body').css({ color: 'blue', width: 600 });
You can physically alter the DOM, using the methods listed in the next category.
DOM Manipulation
a.on(type, filter?, fn)
Attaches the event handler fn
for events of type type
on every element in the Dominus
collection. You can also pass in a list of event types, such as click dragstart
, and both events get the event listener attached to them.
The filter?
argument is optional, and you can use it to provide a selector that will filter inputs. This is known as event delegation. The example below will bind a single event listener that will fire only when child nodes matching the .remove
selector are clicked.
dominus('.products').on('click', '.remove', removeProduct);
a.once(type, filter?, fn)
Meant for when you want to listen for an event only once. This method is identical to a.on(type, filter?, fn)
, except the event listener will be removed right before your fn
callback is executed.
a.off(type, filter?, fn)
Turns off event listeners matching the event type
, the filter
selector (if any), and the event handler.
a.emit(type)
Fabricates a synthetic event of type type
and dispatches it for each element in the collection. Note that these events are even accessible outside of Dominus.
var el = document.getElementById('dollars');
el.addEventListener('dollarsigns', function () {
alert('$