forked from jquery/api.jquery.com
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathend.xml
95 lines (90 loc) · 4.51 KB
/
end.xml
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
<?xml version="1.0"?>
<entry type="method" name="end" return="jQuery">
<title>.end()</title>
<signature>
<added>1.0</added>
</signature>
<desc>End the most recent filtering operation in the current chain and return the set of matched elements to its previous state.</desc>
<longdesc>
<p>Most of jQuery's <a href="http://api.jquery.com/category/traversing">DOM traversal</a> methods operate on a jQuery object instance and produce a new one, matching a different set of DOM elements. When this happens, it is as if the new set of elements is pushed onto a stack that is maintained inside the object. Each successive filtering method pushes a new element set onto the stack. If we need an older element set, we can use <code>end()</code> to pop the sets back off of the stack.</p>
<p>Suppose we have a couple short lists on a page:</p>
<pre><code>
<ul class="first">
<li class="foo">list item 1</li>
<li>list item 2</li>
<li class="bar">list item 3</li>
</ul>
<ul class="second">
<li class="foo">list item 1</li>
<li>list item 2</li>
<li class="bar">list item 3</li>
</ul>
</code></pre>
<p>The <code>end()</code> method is useful primarily when exploiting jQuery's chaining properties. When not using chaining, we can usually just call up a previous object by variable name, so we don't need to manipulate the stack. With <code>end()</code>, though, we can string all the method calls together:</p>
<pre><code>
$('ul.first').find('.foo').css('background-color', 'red')
.end().find('.bar').css('background-color', 'green');
</code></pre>
<p>This chain searches for items with the class <code>foo</code> within the first list only and turns their backgrounds red. Then <code>end()</code> returns the object to its state before the call to <code>find()</code>, so the second <code>find()</code> looks for '.bar' inside <code><ul class="first"></code>, not just inside that list's <code><li class="foo"></code>, and turns the matching elements' backgrounds green. The net result is that items 1 and 3 of the first list have a colored background, and none of the items from the second list do.</p>
<p>A long jQuery chain can be visualized as a structured code block, with filtering methods providing the openings of nested blocks and <code>end()</code> methods closing them:</p>
<pre><code>
$('ul.first').find('.foo')
.css('background-color', 'red')
.end().find('.bar')
.css('background-color', 'green')
.end();
</code></pre>
<p>The last <code>end()</code> is unnecessary, as we are discarding the jQuery object immediately thereafter. However, when the code is written in this form, the <code>end()</code> provides visual symmetry and a sense of completion —making the program, at least to the eyes of some developers, more readable, at the cost of a slight hit to performance as it is an additional function call.</p>
</longdesc>
<example>
<desc>Selects all paragraphs, finds span elements inside these, and reverts the selection back to the paragraphs.</desc>
<code><![CDATA[
jQuery.fn.showTags = function (n) {
var tags = this.map(function () {
return this.tagName;
})
.get().join(", ");
$("b:eq(" + n + ")").text(tags);
return this;
};
$("p").showTags(0)
.find("span")
.showTags(1)
.css("background", "yellow")
.end()
.showTags(2)
.css("font-style", "italic");
]]></code>
<css><![CDATA[
p, div { margin:1px; padding:1px; font-weight:bold;
font-size:16px; }
div { color:blue; }
b { color:red; }
]]></css>
<html><![CDATA[<p>
Hi there <span>how</span> are you <span>doing</span>?
</p>
<p>
This <span>span</span> is one of
several <span>spans</span> in this
<span>sentence</span>.
</p>
<div>
Tags in jQuery object initially: <b></b>
</div>
<div>
Tags in jQuery object after find: <b></b>
</div>
<div>
Tags in jQuery object after end: <b></b>
</div>]]></html>
</example>
<example>
<desc>Selects all paragraphs, finds span elements inside these, and reverts the selection back to the paragraphs.</desc>
<code><![CDATA[$("p").find("span").end().css("border", "2px red solid");]]></code>
<css><![CDATA[p { margin:10px; padding:10px; }]]></css>
<html><![CDATA[<p><span>Hello</span>, how are you?</p>]]></html>
</example>
<category slug="traversing/miscellaneous-traversal"/>
<category slug="version/1.0"/>
</entry>