forked from franciscop/umbrella
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathdocumentation.html
1356 lines (1309 loc) · 76.9 KB
/
documentation.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html><html><head><title>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/web/umbrella.png?1"><meta property="og:description" content="Lightweight and intuitive javascript library to speed up your web development"><link href="web/fontello.css" rel="stylesheet"><link href="web/picnic.css" rel="stylesheet"><link href="web/style.css" rel="stylesheet"><link href="https://fonts.googleapis.com/css?family=Dosis" rel="stylesheet" type="text/css"><link rel="icon" href="web/umbrella.svg" type="image/svg+xml"></head><body><nav><div class="brand"><img src="web/umbrella.svg" alt="Logo" class="logo"><a href="/">Umbrella JS</a></div><div class="menu"><a href="tests" class="pseudo button icon-ok"><span class="text">Tests</span></a><a href="https://github.com/umbrellajs/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="row"><aside><a href="#home" tabindex="-1" class="top pseudo button">▲ Up you go ▲</a><h2>Contents</h2></aside><article><h1 id="umbrella-js-documentation">Umbrella JS - 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 understad 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="-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.test').on('submit', function(e){
// Avoid submitting the form normally
e.preventDefault();
// Submit the form through ajax
ajax(u(this).attr('action'), u(this).serialize());
});
// Better 'onchange':
u('input').on('change click blur paste', function(){
console.log("Maybe changed");
});
</code></pre>
<h3 id="related">Related</h3>
<p><a href="#off">.handle()</a> Same as <code>.on()</code>, but it prevents the default action</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="-parent-">.parent()</h2>
<p>Retrieve each parent of the matched nodes, optionally filtered by a selector</p>
<pre><code class="lang-js">.parent()
.parent('p')
.parent(u('p'))
.parent(function(node, i){})
</code></pre>
<h3 id="parameters">Parameters</h3>
<p><code>selector</code>: Optional filter argument for the parents</p>
<h3 id="examples">Examples</h3>
<p>Retrieve all of the parents of <code><li></code> in the page:</p>
<pre><code class="lang-js">u('li').parent();
</code></pre>
<p>Retrieve all the paragraphs that have a link as a direct child</p>
<pre><code class="lang-js">u('a').parent('p');
</code></pre>
<h3 id="related">Related</h3>
<p><a href="#parent">.children()</a> get all of the direct children</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="-prepend-">.prepend()</h2>
<p>Add some html as a child at the beginning of each of the matched elements.</p>
<pre><code class="lang-js">.prepend(html)
.prepend('<div>')
.prepend(u('<div>'))
.prepend(u('<div>').first()) // Same as document.createElement('div')
.prepend(u('<div></div><div></div>').nodes)
.prepend(function(){})
.prepend(function(el){}, elements)
.prepend(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>