forked from jquery/api.jquery.com
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathend.xml
125 lines (120 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
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
<?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="/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>