ullamlaboriosam
Version:
Lightweight and intuitive javascript library
939 lines (907 loc) • 79.4 kB
HTML
<!DOCTYPE html><html><head><title>Documentation - Umbrella JS</title><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="keywords" content="javascript, js, library, umbrella, html, html5, light"><meta name="description" content=" Lightweight and intuitive javascript library"><meta property="og:url" content="http://umbrellajs.com/"><meta property="og:title" content="Umbrella JS"><meta property="og:image" content="http://umbrellajs.com/umbrella.png?1"><meta property="og:description" content="Lightweight and intuitive javascript library to speed up your web development"><link href="fontello.css" rel="stylesheet"><link href="picnic.css" rel="stylesheet"><link href="style.css" rel="stylesheet"><link href="https://fonts.googleapis.com/css?family=Dosis" rel="stylesheet" type="text/css"><link rel="icon" href="umbrella.svg" type="image/svg+xml"></head><body><nav><div class="brand"><img src="umbrella.svg" alt="Logo" class="logo"><a href="/">Umbrella JS</a></div><div class="menu"><a href="https://github.com/franciscop/umbrella" class="pseudo button icon-g"><span class="text">Github</span></a><a href="documentation" class="button icon-doc"><span class="text">Documentation</span></a></div></nav><main id="home" class="documentation"><section class="flex five"><aside class="full fifth-1000"><h2>Contents</h2><div class="links flex two three-500 five-800 one-1000"></div><a href="#home" tabindex="-1" class="top pseudo button">▲ Up you go ▲</a></aside><article class="full four-fifth-1000"><h1 id="documentation">Documentation</h1>
<p>Find nodes from the HTML with a CSS selector:</p>
<pre><code class="lang-js">u('ul#demo li')
u(document.getElementById('demo'))
u(document.getElementsByClassName('demo'))
u([ document.getElementById('demo') ])
u( u('ul li') )
u('<a>')
u('li', context)
</code></pre>
<h3 id="parameters">Parameters</h3>
<p>The first parameter can be:</p>
<ul>
<li>A text CSS selector</li>
<li>A single HTML Node. This is specially useful in events where you can just pass <code>this</code></li>
<li>A NodeList or other similar objects that can be converted to an array</li>
<li>An array of nodes*</li>
<li>Another Umbrella instance</li>
<li>An HTML fragment as a string</li>
<li>Nothing</li>
</ul>
<p>The second parameter is only for the CSS selector, which indicates a portion of the DOM where the selector is applied. For example, with <code>u('li', u('ul').first())</code> it will find all of the <code>li</code> from the first <code>ul</code>.</p>
<p>* actually it can be an array of anything you want as in <code>["a", "b"]</code>, however this is not officially supported and might change at any moment</p>
<blockquote>
<p>You <em>should</em> use <code>u('#demo')</code> instead of <code>u(document.getElementById('demo'))</code>, internally it's optimized to do this in a fast way. That was only an example of what's possible.</p>
</blockquote>
<h3 id="return">Return</h3>
<p>An instance of Umbrella JS so you can chain it to any of the other methods.</p>
<h3 id="examples">Examples</h3>
<p>Select all of the list elements that are children of <code>ul</code></p>
<pre><code class="lang-js">var lis = u('ul > li'); // Same as u('ul').children('li');
</code></pre>
<p>Find all of the headers from the page to create a Table of Contents:</p>
<pre><code class="lang-js">var headers = u('h1, h2, h3, h4, h5, h6');
</code></pre>
<p>Generate a link on the fly:</p>
<pre><code class="lang-js">var link = u('<a>').addClass('main').attr({ href: '/hello' });
</code></pre>
<p>You can use this to generate many kind of elements on the fly. For example, for a simple grocery list (using ES6 for simplicity):</p>
<pre><code class="lang-js">var fruits = ['apple', 'strawberry', 'pear', 'banana'];
var list = u('<ul>').append(fruit => `<li>${ fruit }</li>`, fruits);
u('body').append(list);
</code></pre>
<p>It plays well with other libraries, including jquery. For example, with <a href="http://github.com/franciscop/pagex">pagex.js</a>:</p>
<pre><code class="lang-js">// When we are on the page "/login"
page(/^login/, function(){
function done(err, res){
if (err) return alert("There was an error");
window.location.href = "/user/" + res.id;
};
// Find the form and handle it through ajax when it's submitted
u("form.login").ajax(done);
});
</code></pre>
<h3 id="native-methods">Native methods</h3>
<blockquote>
<p>This section is inspired by <a href="http://blissfuljs.com/docs.html#vanilla">Bliss.js' vanilla methods</a></p>
</blockquote>
<p>There are many native methods and properties that you can use. These can be called straight in the <code>.first()</code> or <code>.last()</code> elements, a <code>.nodes</code> element or you can loop every element to call them. For example:</p>
<pre><code class="lang-js">// Single element from .nodes
u('h1').nodes[0].classList.add('vanilla');
// Single element
u('h1').first().classList.add('vanilla', 'test');
// Multiple elements. Note that the order is different from jquery
u('h2').each(function(el){
el.classList.add('vanilla', 'test');
});
</code></pre>
<p>And for the arrays it's similar, you can call any array method on <code>u().nodes</code> since this is literally an array:</p>
<pre><code class="lang-js">u('h2').nodes.forEach();
var mapped = u('h2').nodes.map();
var filtered = u('h2').nodes.filter();
var good = u('h2').nodes.some();
</code></pre>
<p>However, there are also some advantages of using Umbrella's methods instead of native methods. For example, with <code>.addClass()</code> vs native <code>classList.add()</code>:</p>
<ul>
<li><strong>error prevention</strong>: if nodes.length = 0, the single-element way will fail in the above implementation (since first() and nodes[0] are null)</li>
<li><strong>cross-browser</strong>: the classList.add() with multiple elements <a href="http://caniuse.com/#search=classList">is not compatible with IE10-11 & Android 4.3-</a></li>
<li><strong>chainable</strong>: <code>u('<div>').each(...).addClass(...);</code></li>
<li><strong>more flexibility</strong>: there are many ways to specify multiple classes with addClass, and only one way to specify them on the native way. Imagine that you have an array of classes, with the native method this becomes a nightmare. This is what it means to be flexible:</li>
</ul>
<pre><code class="lang-js">u('h2').addClass('vanilla', 'test'); // It accepts multiple parameters
u('h2').addClass(['vanilla', 'test']); // Also accept an array
u('h2').addClass(['vanilla'], ['test']); // Or multiple arrays
u('h2').addClass('vanilla, test'); // Strings with space and/or comma
u('h2').addClass('vanilla', ['test'], 'one, more' ); // Or just whatever
</code></pre>
<p>So it's convenient that you know these limitations and act accordingly. Try to use native methods where it makes sense, then Umbrella's methods where it's better suited or then create your own methods when you need it.</p>
<h2 id="-length">.length</h2>
<p>You can check how many elements are matched with <code>.length</code>:</p>
<pre><code class="lang-js">// Check how many <a> are in the page
alert(u('a').length);
</code></pre>
<h2 id="-addclass-">.addClass()</h2>
<p>Add html class(es) to all of the matched elements.</p>
<pre><code class="lang-js">.addClass('name1')
.addClass('name1 name2 nameN')
.addClass('name1,name2,nameN')
.addClass('name1', 'name2', 'nameN')
.addClass(['name1', 'name2', 'nameN'])
.addClass(['name1', 'name2'], ['name3'], ['nameN'])
.addClass(function(){ return 'name1'; })
.addClass(function(){ return 'name1'; }, function(){ return 'name2'; })
</code></pre>
<h3 id="parameters">Parameters</h3>
<p><code>name1</code>, <code>name2</code>, <code>nameN</code>: the class name (or variable containing it) to be added to all of the matched elements. It accepts many different types of parameters (see above).</p>
<h3 id="return">Return</h3>
<p><code>u</code>: returns the same instance of Umbrella JS</p>
<h3 id="examples">Examples</h3>
<p>Add the class <code>main</code> to all the <code><h2></code> from the page:</p>
<pre><code class="lang-js">u("h2").addClass("main");
</code></pre>
<p>Add the class <code>toValidate</code> and <code>ajaxify</code> to all the <code><form></code> present in the page:</p>
<pre><code class="lang-js">u("form").addClass("toValidate", "ajaxify");
</code></pre>
<h3 id="related">Related</h3>
<p><a href="#hasclass">.hasClass()</a> finds if the matched elements contain the class(es).</p>
<p><a href="#removeclass">.removeClass()</a> deletes class(es) from the matched elements.</p>
<p><a href="#toggleclass">.toggleClass()</a> adds or removes the class</p>
<h2 id="-after-">.after()</h2>
<p>Add some html as a sibling after each of the matched elements.</p>
<pre><code class="lang-js">.after(html)
.after('<div>')
.after(u('<div>'))
.after(u('<div>').first()) // Same as document.createElement('div')
.after(u('<div></div><div></div>'))
.after(function(){})
.after(function(el){}, elements)
.after(function(el){}, 10)
</code></pre>
<h3 id="parameters">Parameters</h3>
<p><code>html = ""</code>:</p>
<ul>
<li>Any of these elements:<ul>
<li><strong>string</strong> containing the html that is going to be inserted</li>
<li><strong>instance of Umbrella</strong></li>
<li><strong>HTML node</strong></li>
<li><strong>array</strong> containing HTML nodes</li>
</ul>
</li>
<li>A callback that returns any of the previous. It gets passed these parameters:<ul>
<li><strong>el</strong>: the current element from the elements parameter, {} if none is specified and i if elements is number</li>
<li><strong>i</strong>: the index of the current element</li>
</ul>
</li>
</ul>
<p><code>elements = [{}]</code> (optional): It can be any of the following:</p>
<ul>
<li>An array of elements that will be passed to the callback. The callback is executed once per element, and all of them are added consecutively.</li>
<li>A css selector, so the function will be executed once per matched element.</li>
<li>A number, in which case the function will be executed that number of times</li>
</ul>
<h3 id="return">Return</h3>
<p><code>u</code>: returns the same instance of Umbrella JS</p>
<h3 id="examples">Examples</h3>
<p>Add a separator <code><hr></code> after each of the main titles h1:</p>
<pre><code class="lang-js">u("h1").after("<hr>");
</code></pre>
<p>Add three elements after the link. All of these methods are equivalent:</p>
<pre><code class="lang-js">// Add them all like a single string
u("a.main").after("<a>One</a><a>Two</a><a>Three</a>");
// Add them in a chain
u("a.main").after("<a>Three</a>").after("<a>Two</a>").after("<a>One</a>");
// Add them with a function parameter
var cb = function(txt){ return "<a>" + txt + "</a>" };
u("a.main").after(cb, ["One", "Two", "Three"]);
// Same as the previous one but with ES6
u("a.main").after(txt => `<a>${ txt }</a>`, ["One", "Two", "Three"]);
</code></pre>
<p>They all result in:</p>
<pre><code class="lang-html"><!-- previous data -->
<a class="main"></a>
<a>One</a>
<a>Two</a>
<a>Three</a>
</code></pre>
<p>You can also add some events to them by creating an html node:</p>
<pre><code class="lang-js">function greeting(){ alert("Hello world"); }
u("a.main").after(function(){
return u('<a>').addClass('hi').on('click', greeting).html("Greetings!");
});
</code></pre>
<h3 id="related">Related</h3>
<p><a href="#before">.before()</a> Add some html before each of the matched elements.</p>
<p><a href="#append">.append()</a> Add some html as a child at the end of each of the matched elements</p>
<p><a href="#prepend">.prepend()</a> Add some html as a child at the beginning of each of the matched elements.</p>
<h2 id="-ajax-">.ajax()</h2>
<p>Make all of the matched forms to be submitted by ajax with the same action, method and values when the user submits the form.</p>
<blockquote>
<p>Note: this method does NOT submit the form, it just handles it when it's submitted (from the user or with .trigger())</p>
</blockquote>
<pre><code class="lang-js">.ajax(done, before);
</code></pre>
<h3 id="parameters">Parameters</h3>
<p><code>done</code> [optional]: A function to be called when the request ends. The first argument is the error, if any. The second is the body, which is parsed to JSON if it's a JSON string or just the body as a string if it's not JSON. The third is the request object itself.</p>
<pre><code class="lang-js">var done = function(err, body, xhr){};
</code></pre>
<p><code>before</code> [optional]: A function to be called before the request is sent. Useful to manipulate some data in real-time.</p>
<pre><code class="lang-js">var before = function(xhr){};
</code></pre>
<h3 id="return">Return</h3>
<p><strong>Undefined</strong>. Please don't use the returned value for anything (it might be a promise in the future).</p>
<h3 id="examples">Examples</h3>
<p>Handle the newsletter through ajax</p>
<pre><code class="lang-js">u('.newsletter').ajax(function(err){
if (err) return alert("Error");
alert("Thank you for subscribing, awesome!");
});
</code></pre>
<p>Actually send a form through ajax:</p>
<pre><code class="lang-js">u('form.edit').ajax(function(){ console.log('Sent!'); }).trigger('submit');
</code></pre>
<h3 id="why-not-jquery-">Why not jquery?</h3>
<p>This was created because this pattern is quite common in jquery:</p>
<pre><code class="lang-js">$('form').on('submit', function(e){
e.preventDefault();
$.post($(this).attr('action'), $(this).serialize(), function(data){
alert("Done! Thanks, " + data.name);
}, 'json');
});
</code></pre>
<p>After repeating that many times, I found out that it's better if we just make that the default. The same code on Umbrella JS:</p>
<pre><code class="lang-js">u('form').ajax(function(err, data){
if (!err) alert('Done! Thanks, ' + data.name);
});
</code></pre>
<p>Of course you have freedom and you can use a similar method to jquery, but I think it's a bit pointless for this specific situation:</p>
<pre><code class="lang-js">u('form').on('submit', function(e){
e.preventDefault();
var options = { method: u(this).attr('method'), body: u(this).serialize() };
ajax(u(this).attr('action'), options, function(err, data){
if (!err) alert("Done! Thanks, " + data.name);
});
});
</code></pre>
<h3 id="related">Related</h3>
<p><a href="#ajaxfn">ajax()</a>: perform ajax requests</p>
<h2 id="-append-">.append()</h2>
<p>Add some html as a child at the end of each of the matched elements</p>
<pre><code class="lang-js">.append(html)
.append('<div>')
.append(u('<div>'))
.append(u('<div>').first()) // Same as document.createElement('div')
.append(u('<div></div><div></div>'))
.append(function(){})
.append(function(el){}, elements)
.append(function(el){}, 10)
</code></pre>
<h3 id="parameters">Parameters</h3>
<p><code>html = ""</code>:</p>
<ul>
<li>Any of these elements:<ul>
<li><strong>string</strong> containing the html that is going to be inserted</li>
<li><strong>instance of Umbrella</strong></li>
<li><strong>HTML node</strong></li>
<li><strong>array</strong> containing HTML nodes</li>
</ul>
</li>
<li>A callback that returns any of the previous. It gets passed these parameters:<ul>
<li><strong>el</strong>: the current element from the elements parameter, {} if none is specified and i if elements is number</li>
<li><strong>i</strong>: the index of the current element</li>
</ul>
</li>
</ul>
<p><code>elements = [{}]</code> (optional): It can be any of the following:</p>
<ul>
<li>An array of elements that will be passed to the callback. The callback is executed once per element, and all of them are added consecutively.</li>
<li>A css selector, so the function will be executed once per matched element.</li>
<li>A number, in which case the function will be executed that number of times</li>
</ul>
<h3 id="return">Return</h3>
<p><code>u</code>: returns the same instance of Umbrella JS</p>
<h3 id="examples">Examples</h3>
<p>Add a footer to each of the articles</p>
<pre><code class="lang-js">u("article").append("<footer>Hello world</footer>");
</code></pre>
<p>Add three elements to the list. All of these methods are equivalent:</p>
<pre><code class="lang-js">// Add them all like a single string
u("ul").append("<li>One</li><li>Two</li><li>Three</li>");
// Add them in a chain
u("ul").append("<li>One</li>").append("<li>Two</li>").append("<li>Three</li>");
// Add them with a function parameter
var cb = function(txt){ return "<li>" + txt + "</li>" };
u("ul").append(cb, ["One", "Two", "Three"]);
// Same as the previous one but with ES6
u("ul").append(txt => `<li>${ txt }</li>`, ["One", "Two", "Three"]);
</code></pre>
<p>They all result in:</p>
<pre><code class="lang-html"><ul>
<!-- previous data -->
<li>One</li>
<li>Two</li>
<li>Three</li>
</ul>
</code></pre>
<p>You can also add some events to them by creating an html node:</p>
<pre><code class="lang-js">function greet(){ alert("Hello world"); }
u("a.main").append(function(){
return u('<a>').addClass('hi').on('click', greet).html("Hey!");
});
</code></pre>
<h3 id="related">Related</h3>
<p><a href="#prepend">.prepend()</a> Add some html as a child at the beginning of each of the matched elements.</p>
<p><a href="#before">.before()</a> Add some html before each of the matched elements.</p>
<p><a href="#after">.after()</a> Add some html as a sibling after each of the matched elements.</p>
<h2 id="-array-">.array()</h2>
<p>Extract structured data from the DOM.</p>
<pre><code class="lang-js">.array()
.array(callback)
</code></pre>
<h3 id="parameters">Parameters</h3>
<p><code>callback = function(node, i){ return node.innerHTML }</code>: a callback to be called on each node. The returned value is the one set on the final version. If an array is returned then these elements are added to the set. However, if nothing or null is returned it removes them.</p>
<h3 id="return">Return</h3>
<p>A simple javascript array consisting on the elements returned by the callback</p>
<h3 id="example">Example</h3>
<pre><code class="lang-html"><ul>
<li>Peter</li>
<li>Mery</li>
<li>John</li>
</ul>
</code></pre>
<p>Javascript (by default):</p>
<pre><code class="lang-js">u('ul li').array();
// ['Peter', 'Mery', 'John']
</code></pre>
<p>Javascript (with custom callback):</p>
<pre><code class="lang-js">u('ul li').array(function(node){
return { name: u(node).text() };
});
// [{ name: 'Peter' }, { name: 'Mery' }, { name: 'John' }]
</code></pre>
<h2 id="-attr-">.attr()</h2>
<p>Handle attributes for the matched elements</p>
<pre><code class="lang-js">// GET
.attr('name');
// SET
.attr('name', 'value');
.attr({ name1: 'value', name2: 'value2' });
</code></pre>
<h3 id="parameters">Parameters</h3>
<p><em>GET</em></p>
<p><code>name</code>: the attribute that we want to get from the first matched element</p>
<p><em>SET</em></p>
<p><code>name</code>: the attribute that we want to set for all of the matched elements</p>
<p><code>value</code>: what we want to set the attribute to. If it's not defined, then we get the name</p>
<h3 id="return">Return</h3>
<p><em>GET</em></p>
<p><code>string</code>: the value of the attribute</p>
<p><em>SET</em></p>
<p><code>u</code>: returns the same instance of Umbrella JS</p>
<h3 id="important">Important</h3>
<p>You must understand that <code>.attr()</code> will only retrieve the attributes, not the properties like <code>checked</code>. To understand it better, check <a href="http://api.jquery.com/prop/">jquery's attr() vs prop()</a>.</p>
<p>Each property is different so you should consult each case. For example, if you wanted to get the property <code>checked</code> you could do:</p>
<pre><code class="lang-js">u('.terms-os-service').is(':checked');
</code></pre>
<h3 id="examples">Examples</h3>
<p>Get the alt of an image:</p>
<pre><code class="lang-js">u('img.hero').attr('alt');
</code></pre>
<p>Set the src of all of the images:</p>
<pre><code class="lang-js">u('img').attr({ src: 'demo.jpg' });
</code></pre>
<h3 id="related">Related</h3>
<p><a href="#data">.data()</a> handle data-* attributes for the matched elements</p>
<h2 id="-before-">.before()</h2>
<p>Add some html before each of the matched elements.</p>
<pre><code class="lang-js">.before(html)
.before('<div>')
.before(u('<div>'))
.before(u('<div>').first()) // Same as document.createElement('div')
.before(u('<div></div><div></div>'))
.before(function(){})
.before(function(el){}, elements)
.append(function(el){}, 10)
</code></pre>
<h3 id="parameters">Parameters</h3>
<p><code>html = ""</code>:</p>
<ul>
<li>Any of these elements:<ul>
<li><strong>string</strong> containing the html that is going to be inserted</li>
<li><strong>instance of Umbrella</strong></li>
<li><strong>HTML node</strong></li>
<li><strong>array</strong> containing HTML nodes</li>
</ul>
</li>
<li>A callback that returns any of the previous. It gets passed these parameters:<ul>
<li><strong>el</strong>: the current element from the elements parameter, {} if none is specified and i if elements is number</li>
<li><strong>i</strong>: the index of the current element</li>
</ul>
</li>
</ul>
<p><code>elements = [{}]</code> (optional): It can be any of the following:</p>
<ul>
<li>An array of elements that will be passed to the callback. The callback is executed once per element, and all of them are added consecutively.</li>
<li>A css selector, so the function will be executed once per matched element.</li>
<li>A number, in which case the function will be executed that number of times</li>
</ul>
<h3 id="return">Return</h3>
<p><code>u</code>: returns the same instance of Umbrella JS</p>
<h3 id="examples">Examples</h3>
<p>Add a header to each of the articles</p>
<pre><code class="lang-js">u("article").after("<header>Hello world</header>");
</code></pre>
<p>Add three elements before the link. All of these methods are equivalent:</p>
<pre><code class="lang-js">// Add them all like a single string
u("a.main").before("<a>One</a><a>Two</a><a>Three</a>");
// Add them in a chain
u("a.main").before("<a>One</a>").before("<a>Two</a>").before("<a>Three</a>");
// Add them with a function parameter
var cb = function(txt){ return "<a>" + txt + "</a>" };
u("a.main").before(cb, ["One", "Two", "Three"]);
// Same as the previous one but with ES6
u("a.main").before(txt => `<a>${ txt }</a>`, ["One", "Two", "Three"]);
</code></pre>
<p>They all result in:</p>
<pre><code class="lang-html"><a>One</a>
<a>Two</a>
<a>Three</a>
<a class="main"></a>
<!-- previous data -->
</code></pre>
<p>You can also add some events to them by creating an html node:</p>
<pre><code class="lang-js">function greeting(){ alert("Hello world"); }
u("a.main").before(function(){
return u('<a>').addClass('hi').on('click', greeting).html("Greetings!");
});
</code></pre>
<h3 id="related">Related</h3>
<p><a href="#after">.after()</a> Add some html as a sibling after each of the matched elements.</p>
<p><a href="#append">.append()</a> Add some html as a child at the end of each of the matched elements</p>
<p><a href="#prepend">.prepend()</a> Add some html as a child at the beginning of each of the matched elements.</p>
<h2 id="-children-">.children()</h2>
<p>Get the direct children of all of the nodes with an optional filter</p>
<pre><code class="lang-js">.children(filter);
</code></pre>
<h3 id="parameters">Parameters</h3>
<p><code>filter</code>: a string containing a selector that nodes must pass or a function that return a boolean. See <a href="#filter">.filter()</a> for a better explanation</p>
<h3 id="return">Return</h3>
<p><code>u</code>: returns an instance of Umbrella JS with the new children as nodes</p>
<h3 id="examples">Examples</h3>
<p>Get the first <code><li></code> of every <code><ul></code></p>
<pre><code class="lang-js">u("ul").children('li:first-child');
</code></pre>
<h3 id="related">Related</h3>
<p><a href="#parent">.parent()</a> get all of the direct parents</p>
<p><a href="#find">.find()</a> get all of the descendants of the matched nodes</p>
<p><a href="#closest">.closest()</a> get the first ascendant that matches the selector</p>
<h2 id="-clone-">.clone()</h2>
<p>Create a deep copy of the set of matched elements. Includes matched element node and <strong>all of its events</strong> as well as its children <strong>and all of their events</strong> by <strong>default</strong>.</p>
<pre><code class="lang-js">u('.elementToClone').clone()
</code></pre>
<h3 id="extensions">Extensions</h3>
<ul>
<li>The following extensions are enabled by default:<ul>
<li><strong>select</strong> select input node values are copied to all cloned nodes. To disable globally, add <code>u.prototype.mirror.select = false;</code> to your code.</li>
<li><strong>textarea</strong> textarea input node values are copied to all cloned nodes. To disable globally, add <code>u.prototype.mirror.select = false;</code> to your code.</li>
</ul>
</li>
</ul>
<h3 id="return">Return</h3>
<p><code>u</code>: returns the same instance of Umbrella JS</p>
<h3 id="examples">Examples</h3>
<p>Clone a node and append to another.</p>
<pre><code class="lang-html"><div class="container">
<div class="testClone1">Hello</div>
<div class="cloneDestination"></div>
</div>
</code></pre>
<pre><code class="lang-js">var clone = u("testClone1").clone();
u(".cloneDestination").append(clone);
</code></pre>
<p>Result:</p>
<pre><code class="lang-html"><div class="container">
<div class="testClone1">Hello</div>
<div class="cloneDestination">
<div class="testClone1">Hello</div>
</div>
</div>
</code></pre>
<h3 id="related">Related</h3>
<p><a href="#append">.append()</a> add some html as a child at the end of each of the matched elements.</p>
<h2 id="-closest-">.closest()</h2>
<p>Find the first ancestor that matches the selector for each node</p>
<pre><code class="lang-js">.closest(filter);
</code></pre>
<h3 id="parameters">Parameters</h3>
<p><code>filter</code>: a string containing a selector that nodes must pass or a function that return a boolean. See <a href="#filter">.filter()</a> for a better explanation</p>
<h3 id="return">Return</h3>
<p><code>u</code>: returns an instance of Umbrella JS with the new ancestors as nodes</p>
<h3 id="examples">Examples</h3>
<p>Get the ul of every li</p>
<pre><code class="lang-js">u("li").closest('ul');
</code></pre>
<h3 id="related">Related</h3>
<p><a href="#find">.find()</a> get all of the descendants of the matched nodes</p>
<p><a href="#parent">.parent()</a> get all of the direct parents</p>
<p><a href="#children">.children()</a> get the direct children of all of the nodes with an optional filter</p>
<h2 id="-data-">.data()</h2>
<p>Handle data-* attributes for the matched elements</p>
<pre><code class="lang-js">// GET
.data('name');
// SET
.data('name', 'value');
.data({ name1: 'value', name2: 'value2' });
</code></pre>
<h3 id="parameters">Parameters</h3>
<p><em>GET</em></p>
<p><code>name</code>: the data-* attribute that we want to get from the first matched element</p>
<p><em>SET</em></p>
<p><code>name</code>: the data-* attribute that we want to set for all of the matched elements</p>
<p><code>value</code>: what we want to set the attribute to. If it's not defined, then we get the name</p>
<h3 id="return">Return</h3>
<p><em>GET</em></p>
<p><code>string</code>: the value of the data-* attribute</p>
<p><em>SET</em></p>
<p><code>u</code>: data-* returns the same instance of Umbrella JS</p>
<h3 id="examples">Examples</h3>
<p>Get the value for data-id:</p>
<pre><code class="lang-html"><ul>
<li data-id='0'>First</li>
<li data-id='1'>Second</li>
<li data-id='2'>Third</li>
</ul>
</code></pre>
<pre><code class="lang-js">u('ul li').first().data('id'); // 0
</code></pre>
<p>Set the data-id of an element:</p>
<pre><code class="lang-js">u('ul li').first().data({ id: '1' }); // <li data-id='1'>First</li>
u('ul li').first().data('id', '2'); // <li data-id='2'>First</li>
</code></pre>
<h3 id="related">Related</h3>
<p><a href="#attr">.attr()</a> handle attributes for the matched elements</p>
<h2 id="-each-">.each()</h2>
<p>Loop through all of the nodes and execute a callback for each</p>
<pre><code class="lang-js">.each(function(node, i){});
</code></pre>
<h3 id="parameters">Parameters</h3>
<p><code>callback</code>: the function that will be called. It accepts two parameters, the node and the index. <code>this</code> is Umbrella's instance so other methods like <code>this.args()</code> and <code>this.slice()</code> are available.</p>
<h3 id="return">Return</h3>
<p><code>u</code>: returns an instance of Umbrella JS with the same nodes</p>
<h3 id="examples">Examples</h3>
<p>Loop through all of the links and add them a <code>target="_blank"</code>:</p>
<pre><code class="lang-js">u('a').each(function(node, i){
u(node).attr({ target: '_blank' });
});
</code></pre>
<h2 id="-empty-">.empty()</h2>
<p>Remove all child nodes of the matched elements.</p>
<pre><code class="lang-js">.empty();
</code></pre>
<h3 id="parameters">Parameters</h3>
<p>This method doesn't accept any parameters</p>
<h3 id="return">Return</h3>
<p><code>u</code>: Returns an instance of Umbrella JS with the empty nodes.</p>
<h3 id="examples">Examples</h3>
<p>Removes all child nodes from all containers:</p>
<pre><code class="lang-js">u("div.container").empty();
</code></pre>
<h3 id="related">Related</h3>
<p><a href="#remove">.remove()</a> Removes the matched elements.</p>
<h2 id="-filter-">.filter()</h2>
<p>Remove all the nodes that doesn't match the criteria</p>
<pre><code class="lang-js">.filter('a')
.filter(u('a'))
.filter(function(node, i){ return u(node).is('a'); })
</code></pre>
<h3 id="parameters">Parameters</h3>
<p><code>filter</code>: it can be:</p>
<ul>
<li>css selector that each of the nodes must match to stay</li>
<li>instance of umbrella with the elements to keep (the intersection will be kept)</li>
<li>function that returns a boolean with true to keep the element. It accepts two parameters, <code>node</code> and <code>index</code>, and the context of <code>this</code> is the instance of umbrella so methods like <code>this.slice()</code> are available</li>
</ul>
<h3 id="returns">Returns</h3>
<p>An instance of Umbrella with the nodes that passed the filter.</p>
<h3 id="examples">Examples</h3>
<p>Get only the active links</p>
<pre><code class="lang-js">var links = u('a').filter('.active');
</code></pre>
<p>Get all of the paragraphs with a link:</p>
<pre><code class="lang-js">var paragraphs = u('p').filter(function(node){
return u(node).find('a').length > 0;
});
</code></pre>
<p>Get only the inputs with an answer above 5 and show an error:</p>
<pre><code class="lang-js">u('input').filter(function(node, i){
if (parseInt(u(node).first().value) > 5) {
return true;
}
}).addClass('error');
</code></pre>
<h3 id="related">Related</h3>
<p><a href="#is">.is()</a> check whether one or more of the nodes is of one type</p>
<p><a href="#not">.not()</a> remove all the nodes that match the criteria</p>
<h2 id="-find-">.find()</h2>
<p>Get all of the descendants of the nodes with an optional filter</p>
<pre><code class="lang-js">.find(filter);
</code></pre>
<h3 id="parameters">Parameters</h3>
<p><code>filter</code>: a string containing a selector that nodes must pass or a function that return a boolean. See <a href="#filter">.filter()</a> for a better explanation</p>
<h3 id="return">Return</h3>
<p>An instance of Umbrella with the new children as nodes</p>
<h3 id="examples">Examples</h3>
<p>Get all of the links within all the paragraphs</p>
<pre><code class="lang-js">u("p").find('a');
</code></pre>
<p>Get the required fields within a submitting form:</p>
<pre><code class="lang-js">u('form').on('submit', function(e){
var required = u(this).find('[required]');
});
</code></pre>
<h3 id="related">Related</h3>
<p><a href="#closest">.closest()</a> get the first ascendant that matches the selector</p>
<p><a href="#parent">.parent()</a> get all of the direct parents</p>
<p><a href="#find">.children()</a> get the direct child of the matched nodes</p>
<h2 id="-first-">.first()</h2>
<p>Retrieve the first of the matched nodes</p>
<pre><code class="lang-js">.first();
</code></pre>
<h3 id="parameters">Parameters</h3>
<p>This method doesn't accept any parameters</p>
<h3 id="return">Return</h3>
<p>The first html node or false if there is none.</p>
<h3 id="examples">Examples</h3>
<p>Retrieve the first element of a list:</p>
<pre><code class="lang-js">var next = u("ul.demo li").first();
</code></pre>
<h3 id="related">Related</h3>
<p><a href="#last">.last()</a> retrieve the last matched element</p>
<h2 id="ajax-fn">ajax() fn</h2>
<p>Function (not method) that allows performing ajax requests. The implementation is somewhat similar to <a href="https://github.com/yanatan16/nanoajax">nanoajax</a>:</p>
<pre><code class="lang-js">var action = '/save';
var options = { body: 'a=b' };
var after = function(err, data){ console.log(data); };
var before = function(xhr){};
ajax(action, options, after, before);
</code></pre>
<h3 id="parameters">Parameters</h3>
<p><code>action</code>: the place where to send the ajax request</p>
<p><code>options</code>: an object that sets the options to be passed. These are:</p>
<ul>
<li><code>method = 'GET'</code>: the way to send the request. It can be GET or POST</li>
<li><code>body = ''</code>: a string on the <code>a=b&c=d</code> format or a simple object that will be converted</li>
<li><code>headers = {}</code>: an object with <code>{ key: value }</code> headers to be manually set</li>
</ul>
<p><code>after</code>: the callback to be called when the request has been sent and parsed. The first parameter is an error that can be null, and the second one the parsed data in JSON or the unparsed data as an string.</p>
<p><code>before</code>: a callback that can be called just before sending the request. It receives the XHR object as the first parameter.</p>
<h3 id="return">Return</h3>
<p>Returns the already sent XHR object.</p>
<h3 id="tips">Tips</h3>
<p>You can modify the XHR object straight by using the <em>before</em> callback. It is called just before sending the request, after setting all its parameters:</p>
<pre><code class="lang-js">ajax('/save', {}, after, function(xhr){
xhr.responseType = 'json';
});
</code></pre>
<h2 id="-handle-">.handle()</h2>
<p>This function is the same as <a href="#on"><code>on()</code></a>, but it executes the <code>e.preventDefault()</code> so you don't need to do it. So these two are exactly the same:</p>
<pre><code class="lang-js">u('form.login').on('submit', function(e){
e.preventDefault();
// logic
});
</code></pre>
<pre><code class="lang-js">u('form.login').handle('submit', function(e){
// logic
});
</code></pre>
<h3 id="related">Related</h3>
<p><a href="#on">.on()</a> Calls a function when an event is triggered</p>
<p><a href="#trigger">.trigger()</a> calls an event on all of the matched nodes</p>
<p><a href="#off">.off()</a> Removes an event from matched nodes</p>
<h2 id="-hasclass-">.hasClass()</h2>
<p>Find if any of the matched elements contains the class passed:</p>
<pre><code class="lang-js">.hasClass('name1');
.hasClass('name1 name2 nameN');
.hasClass('name1,name2,nameN');
.hasClass('name1', 'name2', 'nameN');
.hasClass(['name1', 'name2', 'nameN']);
.hasClass(['name1', 'name2'], ['name3'], ['nameN']);
.hasClass(function(){ return 'name1'; });
.hasClass(function(){ return 'name1'; }, function(){ return 'name2'; });
</code></pre>
<p>If more than one class is passed, they are checked <strong>with the AND condition</strong> similar to:</p>
<pre><code class="lang-js">u("a").hasClass("button") && u("a").hasClass("primary");
</code></pre>
<h3 id="parameters">Parameters</h3>
<p><code>name1</code>, <code>name2</code>, <code>nameN</code>: the class name (or variable containing it) to be matched to any of the matched elements. It accepts many different types of parameters (see above).</p>
<h3 id="return">Return</h3>
<p><strong><code>boolean</code></strong>: returns true if all of the passed classes are found in any of the matched elements and false if they couldn't be found.</p>
<h3 id="example">Example</h3>
<p>You can also check manually if it has several classes with the OR parameter with:</p>
<pre><code class="lang-js">u('a').is('.button, .primary');
</code></pre>
<p>And with the AND parameter:</p>
<pre><code class="lang-js">u('a').is('.button.primary');
</code></pre>
<p>Toggle the color of a button depending on the status</p>
<pre><code class="lang-html"><a class="example button">Click me</a>
<script src="//umbrellajs.com/umbrella.min.js"></script>
<script>
u(".example").on('click', function() {
if(u(this).hasClass("error")) {
u(this).removeClass("error").html("Click me");
} else {
u(this).addClass("error").html("Confirm");
}
});
</script>
</code></pre>
<h3 id="related">Related</h3>
<p><a href="#addclass">.addClass()</a> adds html class(es) to each of the matched elements.</p>
<p><a href="#removeclass">.removeClass()</a> deletes class(es) from the matched elements.</p>
<h2 id="-html-">.html()</h2>
<p>Retrieve or set the html of the elements:</p>
<pre><code class="lang-js">// GET
.html();
// SET
.html(html);
</code></pre>
<h3 id="parameters">Parameters</h3>
<p><em>GET</em>
should pass no parameter so it retrieves the html.</p>
<p><em>SET</em>
<code>html</code>: the new value that you want to set. To remove it, pass an empty string: <code>""</code></p>
<h3 id="return">Return</h3>
<p><em>GET</em>
<code>string</code>: the html of the first node</p>
<p><em>SET</em>
<code>u</code>: returns the same instance of Umbrella JS</p>
<h3 id="examples">Examples</h3>
<p>Get the main title:</p>
<pre><code class="lang-js">var title = u('h1').html();
</code></pre>
<p>Set the main title:</p>
<pre><code class="lang-js">u('h1').html('Hello world');
</code></pre>
<h3 id="related">Related</h3>
<p><a href="#attr">.text()</a> Retrieve or set the textContent of the elements</p>
<p><a href="#attr">.attr()</a> Handle attributes for the matched elements</p>
<h2 id="-is-">.is()</h2>
<p>Check whether any of the nodes matches the selector</p>
<pre><code class="lang-js">.is('a')
.is(u('a'))
.is(function(){ return Math.random() > 0.5 })
</code></pre>
<h3 id="parameters">Parameters</h3>
<p><code>filter</code>: it can be two things:</p>
<ul>
<li>css selector to check</li>
<li>instance of umbrella with the elements to check</li>
<li>function that returns a boolean to check for each of the nodes. If one of them returns true, then the method <code>is()</code> returns true. It accepts two parameters, <code>node</code> and <code>index</code>, and the context of <code>this</code> is the instance of umbrella so methods like <code>this.slice()</code> are available.</li>
</ul>
<h3 id="return">Return</h3>
<p><em>boolean</em>: <em>true</em> if any of the nodes matches the selector or the function returns true, false otherwise.</p>
<h3 id="examples">Examples</h3>
<p>Check if the current form needs to be valdated</p>
<pre><code class="lang-js">u('form.subscribe').ajax(false, function() {
// Same as u('form.subscribe').hasClass('validate')
if (u('form.subscribe').is('.validate')) {
validate();
}
});
</code></pre>
<h3 id="related">Related</h3>
<p><a href="#filter">.filter()</a> remove unwanted nodes</p>
<p><a href="#not">.not()</a> remove all the nodes that match the criteria</p>
<h2 id="-last-">.last()</h2>
<p>Get the last element from a list of elements.</p>
<pre><code class="lang-js">.last();
</code></pre>
<h3 id="parameters">Parameters</h3>
<p>This method doesn't accept any parameters</p>
<h3 id="return">Return</h3>
<p>The last html node or false if there is none.</p>
<h3 id="examples">Examples</h3>
<p>Retrieve the last element of a list:</p>
<pre><code class="lang-js">var next = u("ul.demo li").last();
</code></pre>
<h3 id="related">Related</h3>
<p><a href="#first">.first()</a> retrieve the first matched element</p>
<h2 id="-map-">.map()</h2>
<p>Change the content of the current instance by looping each element</p>
<pre><code class="lang-js">.map(function(){});
</code></pre>
<h3 id="parameters">Parameters</h3>
<p>A single callback that returns the element(s) that are going to be kept:</p>
<pre><code class="lang-js">var links = u('.special li').map(function(node, i){
if (parseInt(node.innerHTML) > 10) {
return '<a>' + u(node).data('id') + '</a>';
}
}).addClass('expensive');
</code></pre>
<p>It can return a value that evaluates to false, a single element, an string, an array or an Umbrella instance. It will <strong>remove duplicated nodes</strong> from the result.</p>
<blockquote>
<p>Note: Umbrella JS is made to manipulate HTML nodes so it will consider the string "" and 0 as false and remove them. Return an HTML node or an HTML string to keep the elements.</p>
</blockquote>
<h3 id="return">Return</h3>
<p>An instance of Umbrella with the nodes passed</p>
<h3 id="examples">Examples</h3>
<p>Get the parent elements (see <a href="#parent">.parent()</a>):</p>
<pre><code class="lang-js">var lists = u('li').map(function(node){ return node.parentNode });
</code></pre>
<h3 id="related">Related</h3>
<p><a href="#each">.each()</a> loop all the elements without changing them</p>
<h2 id="-not-">.not()</h2>
<p>Remove known nodes from nodes</p>
<pre><code class="lang-js">.not('a')
.not(u('a'))
.not(function(node){ return Math.random() > 0.5; })
</code></pre>
<h3 id="parameters">Parameters</h3>
<p><code>not</code>: it can be two things (in order):</p>
<ul>
<li>css selector that each of the nodes must <strong>not</strong> match to stay</li>
<li>instance of umbrella with the element to remove</li>
<li>function that returns <code>true</code> to remove the element. It accepts <strong>one parameter</strong>, and the context of <code>this</code> is the instance of umbrella so methods like <code>this.slice()</code> are available</li>
</ul>
<pre><code class="lang-js">.not(function(node){
// your code
});
</code></pre>
<h3 id="examples">Examples</h3>
<pre><code class="lang-html"><ul class="menu">
<li><a class="active">Menu item 1</a></li>
<li><a>Menu item 2</a></li>
<li><a>Menu item 3</a></li>
</ul>
</code></pre>
<p>Get only the non-active links on paragraphs</p>
<pre><code class="lang-js">var nonactive_links = u('.menu a').not('.active');
</code></pre>
<p>Get all of the active:</p>
<pre><code class="lang-js">active_links = u('.menu a').not(nonactive_links);
</code></pre>
<h3 id="related">Related</h3>
<p><a href="#is">.is()</a> check whether one or more of the nodes is of one type</p>
<p><a href="#filter">.filter()</a> Remove unwanted nodes</p>
<h2 id="-off-">.off()</h2>
<p>Remove event handler from matched nodes</p>
<pre><code class="lang-js">.off('event1')
.off('event1 event2 eventN')
.off('event1,event2,eventN')
.off(['event1', 'event2', 'eventN'])
</code></pre>
<h3 id="parameters">Parameters</h3>
<p><code>event</code>:
Any number of events (such as click, mouseover)</p>
<p><code>listener</code>:
Function reference to remove from the events</p>
<h3 id="examples">Examples</h3>
<pre><code class="lang-html"><ul>
<li class="off-single-test">1</li>
<li class="off-multiple-test">2</li>
<li class="off-multiple-test">3</li>
</ul>
</code></pre>
<pre><code class="lang-js">const listener = function() {
alert('called');
}
//Add listener
u('.off-multiple-test').on('click', listener);
//Trigger event
u('.off-multiple-test').trigger('click'); //Alert appears
//Remove listener
u('.off-multiple-test').off('click', listener);
//Trigger event
u('.off-multiple-test').trigger('click'); //No alert
</code></pre>
<h3 id="related">Related</h3>
<p><a href="#on">.on()</a> Attaches an event to matched nodes</p>
<p><a href="#handle">.handle()</a> Same as <code>.on()</code>, but it prevents the default action</p>
<p><a href="#trigger">.trigger()</a> Triggers an event on all of the matched nodes</p>
<h2 id="-on-">.on()</h2>
<p>Calls a function when an event is triggered</p>
<pre><code class="lang-js">.on('event1', callback)
.on('event1 event2 eventN', callback)
.on('event1,event2,eventN', callback)
.on(['event1', 'event2', 'eventN'], callback)
.on('event1', 'selector', callback)
</code></pre>
<h3 id="parameters">Parameters</h3>
<p><code>event1</code>, <code>event2</code>, <code>eventN</code>: the name(s) of the events to listen for actions, such as <code>click</code>, <code>submit</code>, <code>change</code>, etc.</p>
<p><code>callback</code>: function that will be called when the event is triggered. The parameters it accepts are <code>function(e, data1, data2, ..., dataN)</code>:</p>
<ul>
<li><p><code>e</code>: the event that was triggered. It has some interesting properties:</p>
<ul>
<li><code>e.currentTarget</code>: Contains the element that triggered the event.</li>
<li><code>e.preventDefault()</code>: Avoids the browser from performing the default action.</li>
<li><code>e.details</code>: an array of the argument data passed to <code>trigger()</code> if it was passed with that function. See other arguments:</li>
</ul>
</li>
<li><p><code>data1</code>, <code>data2</code>, <code>dataN</code>: the arguments that were passed to <code>trigger()</code> if it was called with that function.</p>
</li>
</ul>
<p>Another way is doing event delegation, for which the parameters are:</p>
<p><code>event1</code>, <code>event2</code>, <code>eventN</code>: same as before</p>
<p><code>selector</code>: a css selector that matches the nodes that will trigger it</p>
<p><code>callback</code>: same as before</p>
<h3 id="return">Return</h3>
<p>Umbrella instance</p>
<h3 id="examples">Examples</h3>
<p>An auto-save feature that submits the form through ajax every 10 seconds</p>
<pre><code class="lang-js">// Show 'test' when the button test is clicked
u('button.test').on('click', function(e) {
alert("Test");
});
// This example is very similar to .ajax() implementation
u('form.tes