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
|
<!DOCTYPE html>
<html lang='en'><head><meta http-equiv='content-type' content='text/html; charset=UTF-8' /></head><body>
<div class="entry-content">
<div class="entry-title roundTop">
<h1 class="jq-clearfix">.filter()</h1>
<div class="entry-meta jq-clearfix">
Categories:
<span class="category"><a href="http://api.jquery.com/category/traversing/" title="View all posts in Traversing">Traversing</a> > <a href="http://api.jquery.com/category/traversing/filtering/" title="View all posts in Filtering">Filtering</a></span>
</div>
</div>
<div id="filter1" class="entry method">
<h2 class="jq-clearfix roundTop section-title">
<span class="name">.filter( selector )</span> <span class="returns">Returns: <a class="return" href="http://api.jquery.com/Types/#jQuery">jQuery</a></span>
</h2>
<div class="jq-box roundBottom entry-details">
<p class="desc"><strong>Description: </strong>Reduce the set of matched elements to those that match the selector or pass the function's test. </p>
<ul class="signatures">
<li class="signature" id="filter-selector">
<h4 class="name">
<span class="versionAdded">version added: <a href="/category/version/1.0/">1.0</a></span>.filter( selector )</h4>
<p class="arguement"><strong>selector</strong>A string containing a selector expression to match the current set of elements against.</p>
</li>
<li class="signature" id="filter-functionindex">
<h4 class="name">
<span class="versionAdded">version added: <a href="/category/version/1.0/">1.0</a></span>.filter( function(index) )</h4>
<p class="arguement"><strong>function(index)</strong>A function used as a test for each element in the set. <code>this</code> is the current DOM element.</p>
</li>
<li class="signature" id="filter-element">
<h4 class="name">
<span class="versionAdded">version added: <a href="/category/version/1.4/">1.4</a></span>.filter( element )</h4>
<p class="arguement"><strong>element</strong>An element to match the current set of elements against.</p>
</li>
<li class="signature" id="filter-jQuery object">
<h4 class="name">
<span class="versionAdded">version added: <a href="/category/version/1.4/">1.4</a></span>.filter( jQuery object )</h4>
<p class="arguement"><strong>jQuery object</strong>An existing jQuery object to match the current set of elements against.</p>
</li>
</ul>
<div class="longdesc">
<p>Given a jQuery object that represents a set of DOM elements, the <code>.filter()</code> method constructs a new jQuery object from a subset of the matching elements. The supplied selector is tested against each element; all elements matching the selector will be included in the result.</p>
<p>Consider a page with a simple list on it:</p>
<p>We can apply this method to the set of list items:</p>
<pre>
$('li').filter(':even').css('background-color', 'red');
</pre>
<p>The result of this call is a red background for items 1, 3, and 5, as they match the selector (recall that <code>:even</code> and <code>:odd</code> use 0-based indexing).</p>
<h4 id="using-filter-function">Using a Filter Function</h4>
<p>The second form of this method allows us to filter elements against a function rather than a selector. For each element, if the function returns <code>true</code> (or a "truthy" value), the element will be included in the filtered set; otherwise, it will be excluded. Suppose we have a somewhat more involved HTML snippet:</p>
<pre>
<ul>
<li><strong>list</strong> item 1 -
one strong tag</li>
<li><strong>list</strong> item <strong>2</strong> -
two <span>strong tags</span></li>
<li>list item 3</li>
<li>list item 4</li>
<li>list item 5</li>
<li>list item 6</li>
</ul>
</pre>
<p>We can select the list items, then filter them based on their contents:</p>
<pre>
$('li').filter(function(index) {
return $('strong', this).length == 1;
}).css('background-color', 'red');
</pre>
<p>This code will alter the first list item only, as it contains exactly one <code><strong></code> tag. Within the filter function, <code>this</code> refers to each DOM element in turn. The parameter passed to the function tells us the index of that DOM element within the set matched by the jQuery object.</p>
<p>We can also take advantage of the <code>index</code> passed through the function, which indicates the 0-based position of the element within the unfiltered set of matched elements:</p>
<pre>
$('li').filter(function(index) {
return index % 3 == 2;
}).css('background-color', 'red');
</pre>
<p>This alteration to the code will cause the third and sixth list items to be highlighted, as it uses the modulus operator (<code>%</code>) to select every item with an <code>index</code> value that, when divided by 3, has a remainder of <code>2</code>.</p>
</div>
<h3>Examples:</h3>
<div class="entry-examples" id="entry-examples">
<div id="example-0">
<h4>Example: <span class="desc">Change the color of all divs; then add a border to those with a "middle" class.</span>
</h4>
<pre class="prettyprint"><code class="example demo-code"><!DOCTYPE html>
<html>
<head>
<style>
div { width:60px; height:60px; margin:5px; float:left;
border:2px white solid;}
</style>
<script src="http://code.jquery.com/jquery-1.7rc2.js"></script>
</head>
<body>
<div></div>
<div class="middle"></div>
<div class="middle"></div>
<div class="middle"></div>
<div class="middle"></div>
<div></div>
<script>
$("div").css("background", "#c8ebcc")
.filter(".middle")
.css("border-color", "red");
</script>
</body>
</html></code></pre>
<h4>Demo:</h4>
<div class="demo code-demo"></div>
</div>
<div id="example-1">
<h4>Example: <span class="desc">Change the color of all divs; then add a border to the second one (index == 1) and the div with an id of "fourth."</span>
</h4>
<pre class="prettyprint"><code class="example demo-code"><!DOCTYPE html>
<html>
<head>
<style>
div { width:60px; height:60px; margin:5px; float:left;
border:3px white solid; }
</style>
<script src="http://code.jquery.com/jquery-1.7rc2.js"></script>
</head>
<body>
<div id="first"></div>
<div id="second"></div>
<div id="third"></div>
<div id="fourth"></div>
<div id="fifth"></div>
<div id="sixth"></div>
<script>
$("div").css("background", "#b4b0da")
.filter(function (index) {
return index == 1 || $(this).attr("id") == "fourth";
})
.css("border", "3px double red");
</script>
</body>
</html></code></pre>
<h4>Demo:</h4>
<div class="demo code-demo"></div>
</div>
<div id="example-2">
<h4>Example: <span class="desc">Select all divs and filter the selection with a DOM element, keeping only the one with an id of "unique".</span>
</h4>
<pre class="prettyprint"><code class="example">$("div").filter( document.getElementById("unique") )</code></pre>
</div>
<div id="example-3">
<h4>Example: <span class="desc">Select all divs and filter the selection with a jQuery object, keeping only the one with an id of "unique".</span>
</h4>
<pre class="prettyprint"><code class="example">
$("div").filter( $("#unique") )</code></pre>
</div>
</div>
</div>
</div>
</div>
</body></html>
|
