tcb-mod

MOD - Many One DOM

A simple, very lightweight and highly intelligent DOM traversal & manipulation library

MOD is a super slim & lightweight jQuery replacement. It aims to have a very similar & familiar syntax but does differ in many ways.

Why?

MOD hopes to have solved the following 'problems':

1. jQuery is close to 100kb minified. Version 2, which drops lots of legacy support, is (almost impressively) unreduced in size.
2. Jumping between pure DOM Elements and jQuery objects is a true pain. It should simply not be a part of the workflow of modern web development.
3. When working with Angular you only get access to jqLite minus selectors (and selectors is a pretty import to us).

7.7kb Minified But Unzipped

So yeah cant say much more than that.

MOD Does What You Don't Like

MOD solves problem number 2 (above) by doing what you dont like; namely modifying the built-in Node, Document, Element, EventTarget and NodeList prototypes. This creates a much more natural workflow than jQuery or similar. No more need to remember whether the variable you are working with is an element, or a jQuery object. Now it always has the capabilities of both.

Compatibility

MOD seems to work in all modern web browsers. Preliminary tests indicate full functionality in IE9, Firefox 3.6, Chrome 3, Safari 4 and Opera 9 and later. Shitloads of testing left though.

Chainable

Currently MOD is, like jQuery, chainable. However, traverser methods (e.g. next()) will return null if no match is found. In such a situation one would get an error when calling next().css(). To avoid this one would have to do like so:

var next = node.next();
if(next) next.css('unicode-bidi', 'bidi-override');

When working with NodeLists (see below) instead of Nodes, one will never get this error since all traverser methods return empty NodeLists if no matching nodes are found.

Performance

Unfortunately we have not had time to test the performance of MOD against other libraries. But since it always uses native functions, it should be super quick.

Contribute

If you want to contribute, send a mail to [e-mail].

Right now the main thing needed is testing of performance.

Methods

All Methods Are Available On Both Nodes & NodeLists

All methods are added to a specific prototype (e.g. Node or EventTarget), but also to the NodeList prototype. All methods are thus also available on instances of NodeLists. Certain properties (such as Element.children) are actually HTMLCollections, not NodeLists. Since HTMLCollections are currently not extended, do something like M(element.children) to get a (non-live) NodeList. They will probably not be extended either, since they are live lists. And iterating through and manipulating live lists is very tricky.

If a method returns Nodes or NodeLists, the method will return a NodeList when called on a NodeList. If a method returns strings, a concatted string will be returned. If a method returns a boolean (only hasClass), a boolean will be returned.

Traversers

Traversers are methods that traverses the DOM and returns null, a Node or a NodeList.

• childs
• descendants
• closest
• first
• last
• next
• parent
• prev

Manipulators

Manipulators are methods that inserts or removes nodes and returns the current node.

• after
• append
• before
• prepend
• replaceWith
• vanish
• wrap

String Returners

These methods either update a property and returns the current node or returns a string.

• css
• html
• outerHtml
• text

Others

• clone

Method Descriptions

Global Functions

Instead of just $(), MOD uses M(), O() and D(). M as in Many, O as in One and DOM as in D. Read on to see the differences between them...

MOD.assign(prototype || prototypes, func, attachToNodeList)

This is the function MOD uses to extend the prototypes. func will be added to the passed prototype or prototypes. If attachToNodeList is true it will also add the function to the NodeList prototype so you can call the function on all nodes in a NodeList.

M(ufo)

M as in Many. Mostly same as O(ufo) but always returns a NodeList. Returns null if unclassified ufo is passed.

M(htmlString)

Returns a NodeList of all nodes created from the valid HTML string htmlString (by calling document.createFromHtml(htmlString)).

M(selector)

Alias for Document.prototype.M() which is alias for Document.prototype.querySelectorAll().

M(node)

Returns a NodeList only containing node.

M(array || nodeList || htmlCollection)

Returns collection as a (non-live) NodeList.

O(ufo)

O as in One. Mostly same as M(ufo) but always returns a single node. Returns null if unclassified ufo is passed.

O(htmlString)

Returns the first (or only) node after creating DOM Nodes from htmlString (by calling document.createFromHtml(htmlString)).

O(selector)

Alias for Document.prototype.O() which is alias for Document.prototype.querySelector().

O(array || nodeList || htmlCollection)

Returns the first node in the collection.

D(func)

Does the same as $(document).ready(func).

Document Prototype Methods

Document.prototype.M()

M as in Many. Alias for querySelectorAll(). Returns a NodeList.

Document.prototype.O()

O as in One. Alias for querySelector(). Returns an Element.

Document.prototype.createFromHtml(htmlString)

The method sets the innerHTML property of a fictional DIV element to htmlString. It then turns all of that elements child nodes (even text nodes if that's what the htmlString created) into a non-live NodeList and returns it.

EventTarget Prototype Methods

EventTarget.prototype.bind(eventString, listener, thisArg, params)

Creates an event and binds the this value in listener to that of thisArg. If params (should be an array) is provided then those will be passed to listener after the event object.

EventTarget.prototype.off(eventString, listener)

Not implemented yet.

EventTarget.prototype.on(eventString, listener, params)

Same as bind() but without the possibility of binding the this parameter.

EventTarget.prototype.onOne(eventString, listener, params)

Same as on() except the listener is removed after it is called the first time.

EventTarget.prototype.bindOne(eventString, listener, thisArg, params)

Same as bind() except the listener is removed after it is called the first time.

Node Prototype Methods

Node.prototype.after(node)

Inserts node after the current node.

Node.prototype.ancestors(node)

Recursive closest().

Node.prototype.append(ufo)

append(node)

Inserts node as last child of the current node.

append(nodeList)

Inserts the nodes nodeList at the end of the current node.

Node.prototype.before(ufo)

before(node)

Inserts node before the current node.

before(nodeList)

Inserts the nodes in nodeList before the current node.

Node.prototype.clone(isDeep)

Returns a clone of the current node. The clone is shallow unless isDeep is true.

Node.prototype.closest(selector, stop)

Traverses the DOM upwards until an element that matches selector is found. If no selector is passed it returns this.papa().

If stop is provided, closest will iterate up through the DOM until stop is encountered. Without stop it will iterate until it reaces the document.

Node.prototype.descendants(ufo, levels) {

Returns descendant nodes to the current node. If levels is set it only returns a set amount of levels (e.g. to only get children, call with 1 level).

Ignores text nodes that only contain whitespaces and are adjacent to block Elements.

descendants(null || undefined || 1, levels)

Returns (as a NodeList) all descendant nodes that are instance of Element.

descendants(nodeType, levels)

Returns (as a NodeList) all descendant nodes that are of nodeType. If nodeType === 0, then it returns all descendants.

descendants(selector, levels)

Returns all descendant nodes that matches the selector. If all levels are wanted then M(selector) would be a better option.

Node.prototype.each(func) {

Calls func with this parameter set to current node. Mainly used for NodeLists.

Node.prototype.empty()

Remove all child nodes of the current node.

Node.prototype.first(ufo, dontIterate) {

Retrieves the first child node according to criterias in ufo.

If dontIterate is true, then it will only check the very first child node. Otherwise returns the first child node that matches the criteria, or null if none.

Ignores text nodes that only contain whitespaces and are adjacent to block Elements.

first(dontIterate)

Returns first child that is an Element.

first(nodeType, dontIterate)

Return first of nodeType. If nodeType === 0, then it returns the first node of any type.

first(selector, dontIterate)

Return first that matches selector.

html(ufo)

Returns innerHTML or textContent, or sets innerHTML depending on ufo.

This method is attached to Node.prototype so that instances of Document, DocumentFragment and Element all get access to it.

html()

Returns this.innerHTML if possible, otherwise this.textContent.

html(htmlString)

Sets innerHTML if possible.

Node.prototype.last(ufo, iterate)

Opposite of first(). Otherwise identical.

Node.prototype.offspring(ufo)

Calls descendants(ufo, 1).

offspring()

Returns (as a NodeList) all child nodes that are instance of Element.

offspring(true)

Returns (as a NodeList) all child nodes (both Nodes & Elements).

offspring(nodeType)

Returns (as a NodeList) all child nodes that are of nodeType.

offspring(selector)

Returns (as a NodeList) all child nodes that match selector.

Node.prototype.outerHtml = function(htmlString) {

Same as html(), but affects the outerHTML property.

NOTE: Will not work for Elements not in the 'visible' DOM because they have no parents. Unless they are present in a DocumentFragment.

Node.prototype.next(ufo, dontIterate) {

Retrieves the next sibling node according to criterias in ufo.

If dontIterate is true, then it will only check the very first sibling. Otherwise it iterates first of the following sibling nodess that match the criteria, or null if none.

Ignores text nodes that only contain whitespaces and are adjacent to block Elements.

next(dontIterate)

Returns the next node that is an Element.

next(nodeType, dontIterate)

Return next of nodeType. If nodeType === 0, then it retrieves the next of any type.

next(selector, dontIterate)

Return next that matches selector.

Node.prototype.papa(selector) {

Returns the parent node. If selector is present it only returns it if it matches it; otherwise null.

Node.prototype.prepend(ufo) {

Identical to append(), but inserts ufo at the beginning of the current node.

Node.prototype.prev(ufo, iterate)

Same as next() but the opposite.

Node.prototype.vanish()

Removes the current node and all of its children from the DOM.

Node.prototype.replaceWith(node)

Replaces the current node and all of its children with node.

Node.prototype.text(textString)

Sets or returns this.textContent depending on whether textString is a string.

Node.prototype.wrap(ufo)

Wraps the current node with an element generated from ufo. The wrapping is done by inserting the new element before the current node, and then appending the node to the element.

wrap(element)

Wraps the current node by creating an element with `element.clone()` (shallow).

wrap(htmlString)

Wraps the current node by creating an element with `O(htmlString)`.

Element Prototype Methods

Element.prototype.matches(selector)

Element.prototype.matches = Element.prototype.matches || Element.prototype.matchesSelector ||
  Element.prototype.msMatchesSelector || Element.prototype.mozMatchesSelector ||
  p.webkitMatchesSelector || p.oMatchesSelector;

Element.prototype.M(selector)

Same as for Document.prototype.M().

Element.prototype.O(selector)

Same as for Document.prototype.M().

Element.prototype.addClass(classString)

Takes a space seperated string of classes and adds them if they are not already present.

Element.prototype.attr(ufo1, ufo2, prefix)

Append prefix to all attribute names of the current element. Note that to return an attribute using the prefix one must call attr(attributeName, undefined, prefix).

attr(attributeName)

Return the attribute attributeName.

attr(attributeName, null)

Remove the attribute attributeName

attr(attributeName, value)

Set the attribute attributeName to value.

attr(attributes)

attributes is an object of attribute-value pairs to set. If the value of the pair is set to null, then the attribute will be removed.

Element.prototype.css(ufo1, ufo2)

css(styleName)

Return the value of `styleName`.

css(styleName, value)

Set `styleName` to `value`.

css(styles)

`styles` is an object of style-value pairs to set.

Element.prototype.data(ufo1, ufo2)

Basically just does the same thing as attr(), but with the prefix parameter always set to 'data'.

Element.prototype.hasClass(classString)

Returns wheter any of the space separated classes in classString are present on the current element.

Element.prototype.prop()

Not implemented yet.

Element.prototype.removeClass(classString) {

Remove all of the space separated classes in classString if present on the current element.

Element.prototype.toggleClass(classString)

Toggle all of the space separated classes in classString.

NodeList Prototype Methods

NodeList.prototype.toArray()

Returns the current NodeList as an array.

NodeList.prototype.indexOf(node)

Returns indexOf node in current NodeList.

NodeList.prototype.includes(ufo)

includes(node)

Check if the current NodeList contains node.

includes(selector)

Checks if any of the nodes in the current NodeList matches selector.