Language: ENCN

Dom7 - Custom DOM Library

Framework7 doesn't use any third party library, even for DOM manipulation. It has its own custom DOM7 - DOM library that utilizes most edge and high-performance methods for DOM manipulation. You don’t need to learn something new, its usage is very simple because it has the same syntax as well known jQuery library with support of the most popular and widely used methods and jQuery-like chaining.

To start use it there is a Dom7 global window function, but we recommend to assign it to some local variable with more handy name, like $$, but not to "$" to prevent confilicts with other libraries like jQuery or Zepto:

//Export DOM7 to local variable to make it easy accessable
var $$ = Dom7;

Usage Example

Just everything you already know:

$$('.something').on('click', function (e) {
    $$(this).addClass('hello').attr('title', 'world').insertAfter('.something-else');
});

Available Methods

All these methods works almost in the same way and with the same arguments as in jQuery or Zepto:

$$(window).trigger('resize');
Classes
.addClass(className) Add class to elements
//Add "intro" class to all paragraphs
$$('p').addClass('intro');
.removeClass(className) Remove specified class
//Add "big" class from all links with "big" class
$$('a.big').removeClass('big');
.hasClass(className) Determine whether any of the matched elements are assigned the given class:
<p class="intro">Lorem ipsum...</p>
$$('p').hasClass('intro'); //-> true
.toggleClass(className) Remove (if class is present) or add (if not) one or more classes from each element in the set of matched elements:
<!-- Before -->
<h1 class="small">This is first title</h1>
<h2>This is subtitle</h2>                
$$('h1, h2').toggleClass('small');
<!-- After -->
<h1>This is first title</h1>
<h2 class="small">This is subtitle</h2>                
Attributes and properties
.prop(propName) Get property value:
var isChecked = $$('input').prop('checked');
.prop(propName, propValue) Set single property value:
//Make all checkboxes checked
$$('input[type="checkbox"]').prop('checked', true);
.prop(propertiesObject) Set multiple properties:
$$('input').prop({
  checked: false,
  disabled: true
})                
.attr(attrName) Get attribute value:
<a href="http://google.com">Google</a>
var link = $$('a').attr('href'); //-> http://google.com
.attr(attrName, attrValue) Set single attribute value:
//Set all links to google
$$('a').attr('href', 'http://google.com');
.attr(attributesObject) Set multiple attributes:
$$('a').attr({
  id: 'new-id',
  title: 'Link to Google',
  href: 'http://google.com'
}) 
.removeAttr(attrName) Remove specified attribute:
//Remove "src" attribute from all images
$$('img').removeAttr('src');
.val() Get the current value of the first element in the set of matched elements
<input id="myInput" type="text" value="Lorem ipsum"/>
var inputVal = $$('#myInput').val(); //-> 'Lorem ipsum'
.val(newValue) Set the value of every matched element
$$('input#myInput').val('New value here');
Data storage
.data(key, value) Store arbitrary data associated with the matched elements
$$('a').data('user', {
    id: '123',
    name: 'John',
    email: '[email protected]'
});  
.data(key) Return the value at the named data store for the first element in the collection, as set by data(key, value) or by an HTML5 data-* attribute
var user = $$('a').data('user'); 
//-> {id: '123', name: 'John', email: '[email protected]'}

or

<p data-id="123">Lorem ipsum...</p>
var id = $$('p').data('id'); //-> 123
.removeData(key) Remove specified data
$$('a').removeData('user')
Data Set
.dataset() Returns element's data set (set of data- attributes) as plain Object
<div id="my-div" data-loop="true" data-animate-pages="false" data-index="0" data-hello="world">
    ...
</div>
var dataset = $$('#my-div').dataset();
/* 
dataset will contain plain object with camelCase keys and with formatted boolean and number types:
{
    loop: true,
    animatePages: false,
    index: 0,
    hello: 'world'
}
*/
CSS transform, transitions
.transform(CSSTransformString) Adds prefixed CSS transform property:
$$('a').transform('rotate(90deg)')
.transition(transitionDuration) Set CSS transition-duration property to collection:
$$('p').transition(300)
Events
.on(eventName, handler, useCapture) Add event handler function to one or more events to the selected elements.
$$('a').on('click', function (e) { 
  console.log('clicked'); 
});
$$('input[type="text"]').on('keyup keydown change', function (e) { 
  console.log('input value changed'); 
});
.on(eventName, delegatedTarget, handler, useCapture) Live/delegated event handler
$$(document).on('click', 'a', function (e) { 
  console.log('link clicked'); 
});
.once(eventName, handler, useCapture) Add event handler function to one or more events to the selected elements that will be executed only once
$$('a').once('click', function (e) { 
  console.log('clicked'); 
});
$$('input[type="text"]').once('keyup keydown change', function (e) { 
  console.log('input value changed'); 
});
.once(eventName, delegatedTarget, handler, useCapture) Live/delegated event handler that will be executed only once
$$(document).once('click', 'a', function (e) { 
  console.log('link clicked'); 
});
.off(eventName, handler, useCapture) Remove event handler
function clickHandler(){
    console.log('clicked');
}
// Add event listener
$$('a').on('click', clickHandler);
// Remove event listener
$$('a').off('click', clickHandler);                  
.off(eventName, delegatedTarget, handler, useCapture) Remove live/delegated event handler
function clickHandler(){
    console.log('clicked');
}
// Add event listener
$$(document).on('click', 'a', clickHandler);
// Remove event listener
$$(document).off('click', 'a', clickHandler);
.trigger(eventName, eventData) Execute all handlers added to the matched elements for the specified event
.transitionEnd(callback, permanent) Adds prefixed transitionEnd event handler to collection:
$$('a').transitionEnd(function(){ /* do something */ })
.animationEnd(callback) Adds prefixed animationEnd event handler to collection:
$$('a').animationEnd(function(){ /* do something */ })
Styles
.width() Get the current computed width for the first element in the set of matched elements
var boxWidth = $$('div#box').width();
.outerWidth([includeMargin]) Get the current computed width for the first element in the set of matched elements, including padding and border, and margin (if includeMargin is true)
var outerWidth = $$('div#box').outerWidth(true);
.height() Get the current computed height for the first element in the set of matched elements
var boxHeight = $$('div#box').height();
.outerHeight([includeMargin]) Get the current computed height for the first element in the set of matched elements, including padding and border, and margin (if includeMargin is true)
var outerHeight = $$('div#box').outerHeight(true);
.offset() Get the current coordinates of the first element relative to the document
var coords = $$('.content').offset(); //-> {top: 100, left: 200}
var top = coords.top; //-> 100
var left = coords.left; //-> 200
.hide() Set "display:none" to the matched elements
//hide all paragraphs
$$('p').hide();
.show() Set "display:block" to the matched elements
//show all paragraphs
$$('p').show();
.css(property) Get value of specified CSS property for the first element:
$$('.content').css('left'); //-> 200px
.css(property, value) Set specified CSS property to the matched elements:
$$('.content').css('left', '100px');
.css(propertiesObject) Set multiple CSS properties to the matched elements:
$$('a').css({
    left: '100px',
    top: '200px',
    color: 'red',
    width: '300px',
    marginLeft: '17px',
    'padding-right': '20px'
});
Scroll
.scrollTop() Get scrollTop position of element
.scrollTop(position, duration, callback) Set scrollTop "position" with animation during "duration" (in ms). Scroll top position will be set immediately if duration is not specified. If you have specified "callback" function, then it will be executed after scrolling completed
.scrollLeft() Get scrollLeft position of element
.scrollLeft(position, duration, callback) Set scrollLeft "position" with animation during "duration" (in ms). Scroll left postion will be set immediately if duration is not specified. If you have specified "callback" function, then it will be executed after scrolling completed
.scrollTo(left, top, duration, callback) Set scroll left and scroll top with animation during "duration" (in ms). Scroll postion will be set immediately if duration is not specified. If you have specified "callback" function, then it will be executed after scrolling completed
Dom Manipulation
.add(elements) Create a new Dom7 collection with elements added to the set of matched elements:
var links = $$('a');
var divs = $$('div');
links.add('p').addClass('blue');
links.add(divs).addClass('red');
.each(callback) Iterate over collection, executing a callback function for each matched element
.html() Get the HTML contents of the first element in the set of matched elements
.html(newInnerHTML) Set the HTML contents of every matched element
.text() Get the text contents of the first element in the set of matched elements
.text(newTextContent) Set the text contents of every matched element
.is(CSSSelector) Check the current matched set of elements against CSS selector
.is(HTMLElement) Check the current matched set of elements against HTML element or Dom7 collection
.index() Return the position of the first element within the Dom7 collection relative to its sibling elements
.eq(index) Reduce the set of matched elements to the one at the specified index
.append(HTMLString) Insert content, specified by the parameter, to the end of each element in the set of matched elements
.append(HTMLElement) Insert specified HTML element to the end of element in the set of matched elements
.appendTo(HTMLElement) Insert content/elements, to the end of element specified in parameter
.prepend(newHTML) Insert content, specified by the parameter, to the beginning of each element in the set of matched elements
.prepend(HTMLElement) Insert specified HTML element to the beginning of element in the set of matched elements
.prependTo(HTMLElement) Insert content/elements, to the beginning of element specified in parameter
.insertBefore(target) Insert every element in the set of matched elements before the target. Target could be specified as CSS selector or HTML element or Dom7 collection
.insertAfter(target) Insert every element in the set of matched elements after the target. Target could be specified as CSS selector or HTML element or Dom7 collection
.next([selector]) Get the immediately following sibling of each element in the set of matched elements. If a selector is provided, it retrieves the next sibling only if it matches that selector
.nextAll([selector]) Get all following siblings of each element in the set of matched elements, optionally filtered by a selector
.prev([selector]) Get the immediately preceding sibling of each element in the set of matched elements, optionally filtered by a selector
.prevAll([selector]) Get all preceding siblings of each element in the set of matched elements, optionally filtered by a selector
.siblings([selector]) Get the siblings of each element in the set of matched elements, optionally filtered by a selector
.parent([selector]) Get the first parent of each element in the current set of matched elements, optionally filtered by a selector
.parents([selector]) Get the ancestors of each element in the current set of matched elements, optionally filtered by a selector
.closest([selector]) For each element in the set, get the first element that matches the selector by testing the element itself and traversing up through its ancestors in the DOM tree
.find(selector) Get the descendants of each element in the current set of matched elements, filtered by a selector
.children(selector) Get the children of each element in the set of matched elements, optionally filtered by a selector
.filter(callback) Filter collection of elements
var redLinks = $$('a').filter(function(index, el) {
    return $$(this).hasClass('red');
})
.remove() Remove/detach matched elements from the Dom
.empty() Remove all child nodes of the set of matched elements from the DOM. Alias for .html('')
Shortcuts
.click() Trigger "click" event on collection
.click(handler) Add "click" event handler to collection
.blur() Trigger "blur" event on collection
.blur(handler) Add "blur" event handler to collection
.focus() Trigger "focus" event on collection
.focus(handler) Add "focus" event handler to collection
.focusin() Trigger "focusin" event on collection
.focusin(handler) Add "focusin" event handler to collection
.focusout() Trigger "focusout" event on collection
.focusout(handler) Add "focusout" event handler to collection
.keyup() Trigger "keyup" event on collection
.keyup(handler) Add "keyup" event handler to collection
.keydown() Trigger "keydown" event on collection
.keydown(handler) Add "keydown" event handler to collection
.keypress() Trigger "keypress" event on collection
.keypress(handler) Add "keypress" event handler to collection
.submit() Trigger "submit" event on collection
.submit(handler) Add "submit" event handler to collection
.change() Trigger "change" event on collection
.change(handler) Add "change" event handler to collection
.mousedown() Trigger "mousedown" event on collection
.mousedown(handler) Add "mousedown" event handler to collection
.mousemove() Trigger "mousemove" event on collection
.mousemove(handler) Add "mousemove" event handler to collection
.mouseup() Trigger "mouseup" event on collection
.mouseup(handler) Add "mouseup" event handler to collection
.mouseenter() Trigger "mouseenter" event on collection
.mouseenter(handler) Add "mouseenter" event handler to collection
.mouseleave() Trigger "mouseleave" event on collection
.mouseleave(handler) Add "mouseleave" event handler to collection
.mouseout() Trigger "mouseout" event on collection
.mouseout(handler) Add "mouseout" event handler to collection
.mouseover() Trigger "mouseover" event on collection
.mouseover(handler) Add "mouseover" event handler to collection
.touchstart() Trigger "touchstart" event on collection
.touchstart(handler) Add "touchstart" event handler to collection
.touchend() Trigger "touchend" event on collection
.touchend(handler) Add "touchend" event handler to collection
.touchmove() Trigger "touchmove" event on collection
.touchmove(handler) Add "touchmove" event handler to collection
.resize(handler) Add "resize" event handler to collection
.scroll(handler) Add "scroll" event handler to collection

Utilities

Dom7.each

A generic iterator function, which can be used to seamlessly iterate over both objects and arrays. Arrays and array-like objects with a length property (such as a function's arguments object) are iterated by numeric index, from 0 to length-1. Other objects are iterated via their named properties

$$.each(object/array, callback) - iterate through object or array

  • object/array - object or array - to iterate over. Required.
  • callback - function - callback function that will be executed on every object property, or on every array element. Required.
var fruits = ['Apple', 'Orange', 'Pineapple', 'Bannana'];
$$.each(fruits, function (index, value) {
    alert(index + ': ' + element); 
});          
 
//This produces 4 alerts:
0: Apple
1: Orange
2: Pineapple
3: Bannana
var person = {
    firstName: 'John',
    lastName: 'Doe',
    age: 25,
};
$$.each(person, function (key, value) {
    alert(key + ': ' + value);
});
 
//This produces 3 alerts:
firstName: John
lastName: Doe
age: 25          

Dom7.parseUrlQuery

$$.parseUrlQuery(url) - parse url query get parameters

  • url - string - url with GET parameters. Required.

Method returns object with query parameters

var query = $$.parseUrlQuery('http://google.com/?id=5&foo=bar');
console.log(query); //-> {id: 5, foo: 'bar'}

Dom7.isArray

$$.isArray(obj) - Determine whether the argument is an array

  • obj - object - Object to test whether or not it is an array

returns a Boolean indicating whether the object is a JavaScript array

var fruits = ['Apple', 'Orange'];
console.log($$.isArray(fruits)); //-> true

Dom7.unique

$$.unique(array) - Remove duplicates in passed array

  • obj - array - Array to remove duplicates

returns a new unique array

var fruits = ['Apple', 'Orange', 'Apple'];
console.log($$.unique(fruits)); //-> ['Apple', 'Orange'];

Dom7.serializeObject

$$.serializeObject(object) - Create a serialized representation of a plain object suitable for use in a URL query string

  • object - object - Object to serialize

returns a new unique array

var params = {foo: 'bar', id: 5};
console.log($$.serializeObject(params)); //-> 'foo=bar&id=5'

Dom7.toCamelCase

$$.toCamelCase(string) - Convert hypens-case string to camelCase string

  • string - string - hypens-case string

returns a new camelCase string

var hypensCaseString = 'hello-my-world';
var camelCaseString = $$.toCamelCase(hypensCaseString);
console.log(camelCaseString); //helloMyWorld

Dom7.dataset

$$.dataset(el) - Get element's data set (set of data- attributes) as plain Object

  • el - HTMLElement or string (with CSS selector) - element with data- attributes to get dataset from

returns a new plain object with dataset

<div id="my-div" data-loop="true" data-animate-pages="false" data-index="0" data-hello="world">
    ...
</div>
var dataset = $$.dataset('#my-div');
/* 
dataset will create plain object with camelCase keys and with formatted boolean and number types:
{
    loop: true,
    animatePages: false,
    index: 0,
    hello: 'world'
}
*/          

Dom7.requestAnimationFrame

$$.requestAnimationFrame(callback) - Cross-browser implementation on requestAnimationFrame

  • callback - function - A parameter specifying a function to call when it's time to update your animation for the next repaint

returns animation request id, that uniquely identifies the entry in the callback list

var animId;
function anim() {
  var left = parseInt($$('#anim').css('left'), 10) + 1;
  $$('#anim').css({left: left + 'px'})
  animId = $.requestAnimationFrame(anim);
}
animId = $.requestAnimationFrame(anim);

Dom7.cancelAnimationFrame

$$.cancelAnimationFrame(requestID) - Cancels an animation frame request

  • requestID - number - The ID value returned by the call to $$.requestAnimationFrame() that requested the callback
$.cancelAnimationFrame(animId);

Dom7.removeDiacritics

$$.removeDiacritics(text) - Replace diacritics in specified text string with standard latin characters

  • text - string - Text string
var text = $$.removeDiacritics('ÁÓL');
console.log(text); //-> 'AOL'

Ajax

$$.ajax(parameters)- Load data from the server

  • parameters - object - Request parameters

returns plain XHR object

Let's look at the list of available parameters

Parameter Type Default Description
async boolean true If you need synchronous requests, set this option to false
method string 'GET' Request method (e.g. "POST", "GET", "PUT")
cache boolean true If set to false, it will force requested pages not to be cached by the browser. Setting cache to false will only work correctly with HEAD and GET requests. It works by appending "_nocache={timestamp}" to the GET parameters
contentType string 'application/x-www-form-urlencoded' Content type. Also could be 'multipart/form-data' and 'text/plain'. For cross-domain requests, setting the content type to anything other than application/x-www-form-urlencoded, multipart/form-data, or text/plain will trigger the browser to send a preflight OPTIONS request to the server
crossDomain boolean undefined If you wish to force a crossDomain request (such as JSONP) on the same domain, set the value of crossDomain to true. When true additional "X-Requested-With: XMLHttpRequest" header will not be added to request
data Object or String or Array Data to be sent to the server. It is converted to a query string, if not already a string. It's appended to the url for GET-requests. See processData option to prevent this automatic processing. For POST requests could be FormData type
processData boolean true By default, data passed in to the data option as an object (technically, anything other than a string) will be processed and transformed into a query string, fitting to the default content-type "application/x-www-form-urlencoded". If you want to send a DOMDocument, or other non-processed data, set this option to false
dataType string 'text' The type of data that you're expecting back from the server. Could be 'text' or 'json'
headers object An object of additional header key/value pairs to send along with requests using the XMLHttpRequest transport
xhrFields object An object of fieldName-fieldValue pairs to set on the native XHR object
username string A username to be used with XMLHttpRequest in response to an HTTP access authentication request
password string A password to be used with XMLHttpRequest in response to an HTTP access authentication request
timeout number 0 Set a timeout (in milliseconds) for the request
Callbacks
beforeSend function (xhr) A pre-request callback function that can be used to modify the XHR object before it is sent. Use this to set custom headers, etc
error function (xhr, status) A function to be called if the request fails
success function (data, status, xhr) A function to be called if the request succeeds
complete function (xhr, status) A function to be called when the request finishes (after success and error callbacks are executed)
statusCode object An object of numeric HTTP codes and functions to be called when the response has the corresponding code. For example, the following will alert when the response status is a 404:
$$.ajax({
  url: 'somepage.html',
  statusCode: {
    404: function (xhr) {
      alert('page not found');
    }
  }
})

Ajax Events

Each Ajax request produces global Ajax events on document, so you can always intercept and handle them:

Event Target Description
ajax:start document A pre-request event that can be used to modify the XHR object before it is sent. Use this to set custom headers
ajax:error document Event to be triggered if the request fails
ajax:success document Event to be triggered if the request succeeds
ajax:complete document Event to be triggered when the request finishes (after success and error events are executed)

For example:

$$(document).on('ajax:complete', function (e) {
  var xhr = e.detail.xhr;
  console.log('request performed');
});

Shorthand Methods

Dom7.get

$$.get(url, data, success, error) - Load data from the server using a HTTP GET request

  • url - string - Request url
  • data - object - A plain object or string that is sent to the server with the request. Optional
  • success - function (data, status, xhr) - A callback function that is executed if the request succeeds. Optional
  • error - function (xhr, status) - A callback function that is executed if the request fails. Optional

returns plain XHR object

$$.get('blog-post.php', {foo:'bar', id:5}, function (data) {
  $$('.articles').html(data);
  console.log('Load was performed');
});

Dom7.post

$$.post(url, data, success, error) - Load data from the server using a HTTP POST request

  • url - string - Request url
  • data - object - A plain object or FormData or string that is sent to the server with the request. Optional
  • success - function (data, status, xhr) - A callback function that is executed if the request succeeds. Optional
  • error - function (xhr, status) - A callback function that is executed if the request fails. Optional

returns plain XHR object

$$.post('auth.php', {username:'foo', password: 'bar'}, function (data) {
  $$('.login').html(data);
  console.log('Load was performed');
});

Dom7.getJSON

$$.getJSON(url, data, success, error) - Load JSON-encoded data from the server using a GET HTTP request

  • url - string - Request url
  • data - object - A plain object or FormData or string that is sent to the server with the request. Optional
  • success - function (data, status, xhr) - A callback function that is executed if the request succeeds. Optional
  • error - function (xhr, status) - A callback function that is executed if the request fails. Optional

returns plain XHR object

$$.getJSON('items.json', function (data) {
  console.log(data);
});

Ajax Setup

$$.ajaxSetup(parameters)- Set default values for future Ajax requests. Its use is not recommended

  • parameters - object - Default requests parameters
// After the following setup all XHR requests will have additional 'Autorization' header
$$.ajaxSetup({
    headers: {
        'Authorization': 'sometokenvalue'
    }
})

Original Request Parameters

Each of Ajax methods returns plain XHR object, which is also available in callbacks. This default XHR object extended with the following properties:

Properties
xhr.requestParameters Object with passed XHR request parameters
xhr.requestUrl String with request URL

Animation

.animate(properties, parameters)- Perform a custom animation of a set of CSS properties

  • properties - object - CSS properties to animate
  • parameters - object - animation parameters

returns Dom7 collection

$$('#animate-me').animate(
    /* CSS properties to animate, e.g.: */
    {
        'margin-left': 100,
        'width': 200,
        'height': 300,
        'opacity': 0.5
    },
    /* Animation parameters */
    {
        // Animation duraion in ms, optional (default to 300)
        duration: 300,
        // Animation easing, optional (default to 'swing'), can be also 'linear'
        easing: 'swing',
        /* Callbacks */
        // Animation begins, optional
        begin: function (elements) {
            console.log('animation began');
        },
        // Animation completed, optional
        complete: function (elements) {
            console.log('animation completed');
        },
        // Animation in progress, optional
        progress: function (elements, complete, remaining, start) {
            /* Where
            complete - The call's completion percentage (as a decimal value)
            remaining - How much time remains until the call completes (in ms)
            start - The absolute time at which the call began (in ms)
            */
            console.log('animation in progress');
        }
    }
);

It also supports chaining que:

$$('#animate-me')
    .animate(
        {
            'margin-left': 100,
            'width': 200,
            'height': 300,
            'opacity': 0.5
        }
    )
    .animate(
        {
            'width': 50,
            'height': 50
        }
    );