-
Notifications
You must be signed in to change notification settings - Fork 23
/
index.html
299 lines (275 loc) · 15.1 KB
/
index.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
<!DOCTYPE html>
<html lang="en">
<head>
<title>jQuery Nearest Element plugin</title>
<meta charset="utf-8">
<link rel="stylesheet" type="text/css" href="http://fonts.googleapis.com/css?family=Raleway" />
<link rel="stylesheet" type="text/css" href="../shared/docs/theme-v2/docs-common.css" />
<style>
#wrapper {
position: relative;
}
.demo-overlay {
background-color: #D4E9F2;
opacity: 0;
pointer-events: none;
position: absolute;
top: 0;
bottom: 0;
left: 0;
right: 0;
z-index: 1;
-webkit-transition: opacity 1s;
-moz-transition: opacity 1s;
-ms-transition: opacity 1s;
-o-transition: opacity 1s;
transition: opacity 1s;
}
.demo-enabled .demo-overlay {
opacity: 0.8;
}
.demo-set {
position: relative;
z-index: 2;
}
.demo-nearest {
outline: 2px dashed blue;
}
</style>
</head>
<body>
<div id="wrapper">
<div id="details">
<h1>jQuery Nearest Element plugin <span class="version">v1.4.0</span></h1>
<h2>Quick Links</h2>
<ul>
<li><a href="https://github.com/gilmoreorless/jquery-nearest">Github project</a></li>
<li><a href="https://github.com/gilmoreorless/jquery-nearest/raw/master/jquery.nearest.js">Raw source code</a></li>
<li><a href="https://github.com/gilmoreorless/jquery-nearest/raw/master/jquery.nearest.min.js">Minified source code</a></li>
<li><a href="demo/">Interactive demonstration #1 – Options and mouse movement</a></li>
<li><a href="demo/edges.html">Interactive demonstration #2 – Percentage parameters</a></li>
</ul>
<p>Available on <a href="https://www.npmjs.com/package/jquery-nearest">npm</a> (<code>npm install jquery-nearest</code>)
and <a href="http://bower.io/">Bower</a> (<code>bower install jquery-nearest</code>).</p>
<h2>Intro</h2>
<p>
This plugin finds the elements in a page that are closest to a particular point or element, based on pixel dimensions.
This is not to be confused with jQuery's own <a href="http://api.jquery.com/closest">.closest()</a> method,
which is based on the DOM tree, not pixels.
</p>
<p>
There are also helper methods to find elements that are the furthest away from or touching a point or element.
</p>
<h2>Reference</h2>
<h3>Methods</h3>
<p>
There are three main methods:
</p>
<ul>
<li><code>.nearest()</code> returns the elements that have the <strong>shortest</strong> pixel distance to a point or element.</li>
<li><code>.furthest()</code> returns the elements that have the <strong>longest</strong> pixel distance to a point or element.</li>
<li><code>.touching()</code> returns the elements that are <strong>touching</strong> a point or element (ie. their pixel distance is 0).</li>
</ul>
<h3>Usage</h3>
<p>
Each of the three methods has a utility function on the global jQuery object and a jQuery prototype function for working with element sets.
The following examples all use <code>nearest</code> as the method, but <code>furthest</code> and <code>touching</code> work in the same way.
</p>
<h4 id="utility">Utility Function</h4>
<pre><code>$.nearest(<em>pointObject</em>, <em>selector</em>[, <em>options</em>]);</code></pre>
<p>
Finds the DOM elements matching <code>selector</code> that are closest to a point or region on the page.
</p>
<p>
<code>pointObject</code> is an object with <code>x</code> and <code>y</code> (numeric) properties that define a point on the page (relative to the top left corner of the page, not the screen).<br>
Optionally, you can also specify <code>w</code> and <code>h</code> properties to define the width and height respectively of a region in the page instead of a single point – in this case the x and y properties define the top left corner of the region.
</p>
<p>
The <code>x</code>, <code>y</code>, <code>w</code> and <code>h</code> properties can also be defined as a percentage string, relative to the <code>container</code> option (defined in the <a href="#options">options</a> section).
</p>
<p>
<code>selector</code> is any valid jQuery selector or object that defines an element set to be filtered by the function.
</p>
<p>
<code>options</code> is an optional collection of parameters to pass to the function. More details can be found in the <a href="#options">options</a> section.
</p>
<h5>Example</h5>
<pre><code><span class="comment">// Find the image(s) closest to a point 300px in and 100px down from the top left corner</span>
var $closestToPoint = $.nearest({x: 300, y: 100}, 'img');
<span class="comment">// Find the elements with class 'floating' closest to a particular region in the page</span>
var $elemSet = $('.floating');
var $closestToRegion = $.nearest({x: 300, y: 100, w: 200, h: 200}, $elemSet);
<span class="comment">// Find the elements with class 'floating' closest to the right-hand side of the document</span>
var $closestToRightEdge = $.nearest({x: '100%', y: 0, h: '100%'}, '.floating');
</code></pre>
<h4 id="single">Single Element Operation</h4>
<pre><code>$(elem).nearest(<em>selector</em>[, <em>options</em>]);</code></pre>
<p>
Finds the DOM elements matching <code>selector</code> that are closest to <code>elem</code>.
If more than one element is in <code>$(elem)</code> then only the first member will be used as a point of reference.
</p>
<p>
<code>selector</code> is any valid jQuery selector or object that defines an element set to be filtered by the function.
</p>
<p>
<code>options</code> is an optional collection of parameters to pass to the function. More details can be found in the <a href="#options">options</a> section.
</p>
<h5>Example</h5>
<pre><code>var $basicExample = $('#something').nearest('.surrounding');
<span class="comment">// Only the first element in this set will be used for matching</span>
var $set = $('.middle');
<span class="comment">// Selector can be any jQuery object</span>
var $convolutedExample = $set.nearest($set.siblings());
</code></pre>
<h4 id="multi">Multiple Element Filter</h4>
<pre><code>$(elemSet).nearest(<em>pointObject</em>[, <em>options</em>]);</code></pre>
<p>
Filters <code>elemSet</code> to return only the members that are closest to the point or region defined by <code>pointObject</code>.
</p>
<p>
This is effectively the same as calling <code>$.nearest(pointObject, elemSet)</code> but with the benefit of not breaking method chains – see <a href="#chaining">chaining</a> for more details.
</p>
<p>
<code>pointObject</code> is an object as defined in the <a href="#utility">Utility Function</a> reference.
</p>
<p>
<code>options</code> is an optional collection of parameters to pass to the function. More details can be found in the <a href="#options">options</a> section.
</p>
<h5>Example</h5>
<pre><code>var $set = $('.filterme');
<span class="comment">// Filter the set by distance to a point</span>
var $closestToPoint = $set.nearest({x: 300, y: 100});
<span class="comment">// Filter the set by distance to a region</span>
var $closestToRegion = $set.nearest({x: 300, y: 100, w: 200, h: 200});
</code></pre>
<h3 id="options">Options</h3>
<p>
All methods take an optional <code>options</code> object to further refine the results.
The object can have the following parameters:
</p>
<dl>
<dt><code>includeSelf</code></dt>
<dd class="type">Boolean – default <code>false</code> <em>(not used by the utility methods)</em></dd>
<dd>If true, the reference element used in a <a href="#single">Single Element Operation</a> will also
be included in the distance calculations.<br>
Example: <code>$(elem).nearest('.droppable', {includeSelf: true});</code></dd>
<dt><code>onlyX</code></dt>
<dd class="type">Boolean – default <code>false</code> <em>(not used by <code>.touching()</code>)</em></dd>
<dd>If true, the function will ignore the Y axis and only the X distance from the reference point will be used.</dd>
<dt><code>onlyY</code></dt>
<dd class="type">Boolean – default <code>false</code> <em>(not used by <code>.touching()</code>)</em></dd>
<dd>If true, the function will ignore the X axis and only the Y distance from the reference point will be used.</dd>
<dt><code>sameX</code></dt>
<dd class="type">Boolean – default <code>false</code> <em>(not used by <code>.touching()</code>)</em></dd>
<dd>If true, the function will not check for elements along the X axis,
meaning only elements directly above or below the reference point will be matched.<br>
This will override <code>onlyX: true</code> if both are provided.</dd>
<dt><code>sameY</code></dt>
<dd class="type">Boolean – default <code>false</code> <em>(not used by <code>.touching()</code>)</em></dd>
<dd>If true, the function will not check for elements along the Y axis,
meaning only elements directly to the left or right of the reference point will be matched.<br>
This will override <code>onlyY: true</code> if both are provided.</dd>
<dt><code>tolerance</code></dt>
<dd class="type">Integer – default <code>1</code></dd>
<dd>Number of pixels to allow for when calculating distances, to account for fractional pixel values.<br>
For example, a tolerance of 1 would match distances of 23px, 23.45px and 24px as being closest, but not 24.1px.</dd>
<dt><code>container</code></dt>
<dd class="type">DOM node or jQuery selector – default <code>document</code></dd>
<dd>Acts as a root node, so that only elements within the container will be matched.<br>
Also used with percentage options for <code>x</code>, <code>y</code>, <code>w</code> and <code>h</code> – the top left corner of the container is 0%, the bottom right corner is 100%.</dd>
<dt><code>directionConstraints</code></dt>
<dd class="type">String array – default <code>empty</code></dd>
<dd>A list of directions to limit the search. Available values:
<code>"left"</code>, <code>"right"</code>, <code>"top"</code>, <code>"bottom"</code><br/>
For example, <code>["left", "top"]</code> will only match elements to the top left of the reference point.</dd>
<dt><code>sort</code></dt>
<dd class="type">String – default <code>empty</code></dd>
<dd>Sorts results based on distance, defaults to no sorting (results are returned in DOM order).<br/>
Available values: <code>"nearest"</code> or <code>"furthest"</code></dd>
</dl>
<dl class="deprecated">
<dt><code>checkHoriz</code></dt>
<dd class="type">Boolean – default <code>true</code> – <strong>Deprecated</strong> in 1.3</dd>
<dd>The <code>checkHoriz: false</code> option is deprecated and will be removed in a future version. Use <code>sameX: true</code> instead (they are equivalent).</dd>
<dt><code>checkVert</code></dt>
<dd class="type">Boolean – default <code>true</code> – <strong>Deprecated</strong> in 1.3</dd>
<dd>The <code>checkVert: false</code> option is deprecated and will be removed in a future version. Use <code>sameY: true</code> instead (they are equivalent).</dd>
</dl>
<p>
A example of using different options can be found on the <a href="demo.html">demonstration page</a>.
</p>
<h2 id="notes">Notes</h2>
<ul>
<li>
The <code>selector</code> parameter is technically optional in all methods, and will default to <code>div</code> if not present.
However, it is <strong>strongly recommended</strong> that you pass in a selector,
otherwise the method will loop through every single div element on the page, which –
apart from being slow and computationally expensive – will most likely produce false positives
by matching a reference element's parent nodes.
</li>
<li>
Only set one of the <code>sameX</code> and <code>sameY</code> options to true in a single call, not both.
If you set both to true, the <code>.nearest()</code> and <code>.furthest()</code> methods will fail to work (it is exactly the same as calling <code>.touching()</code> instead).
</li>
</ul>
<h3 id="changelog">Changelog</h3>
<dl class="changelog">
<dt class="minor" id="v1.4.0">1.4.0</dt>
<dd><ul>
<li>New <code>directionConstraints</code> option
(<a href="https://github.com/gilmoreorless/jquery-nearest/pull/29">PR #29</a>).</li>
<li>New <code>sort</code> option
(<a href="https://github.com/gilmoreorless/jquery-nearest/pull/29">PR #29</a>).</li>
</ul></dd>
<dt class="point" id="v1.3.1">1.3.1</dt>
<dd><ul>
<li>No code changes. Metadata updates only
(<a href="https://github.com/gilmoreorless/jquery-nearest/issues/15">#15</a>,
<a href="https://github.com/gilmoreorless/jquery-nearest/issues/16">#16</a>,
<a href="https://github.com/gilmoreorless/jquery-nearest/issues/25">#25</a>).</li>
</ul></dd>
<dt class="minor" id="v1.3.0">1.3.0</dt>
<dd><ul>
<li>New <code>onlyX</code> and <code>onlyY</code> options
(<a href="https://github.com/gilmoreorless/jquery-nearest/pull/7">PR #7</a>).</li>
<li>New <code>sameX</code> and <code>sameY</code> options as the inverse replacement for <code>checkHoriz</code> and <code>checkVert</code>
(<a href="https://github.com/gilmoreorless/jquery-nearest/issues/9">#9</a>).</li>
<li><strong>Deprecated</strong> the <code>checkHoriz</code> and <code>checkVert</code> options.</li>
<li>Bug fix for filtering on empty sets.</li>
<li>Better calculation of dimensions for percentage-based options.</li>
</ul></dd>
<dt class="point" id="v1.2.2">1.2.2</dt>
<dd><ul>
<li>Bug fix to find only children of the <code>container</code> element if the option is present.
(<a href="https://github.com/gilmoreorless/jquery-nearest/pull/5">PR #5</a>).</li>
</ul></dd>
<dt class="point" id="v1.2.1">1.2.1</dt>
<dd><ul>
<li>Added to <a href="http://plugins.jquery.com/project/nearest">plugins.jquery.com</a>.</li>
</ul></dd>
<dt class="minor" id="v1.2.0">1.2.0</dt>
<dd><ul>
<li>Added to <a href="http://bower.io/">Bower</a>
(<a href="https://github.com/gilmoreorless/jquery-nearest/issues/4">#4</a>).</li>
<li>New <code>container</code> option and the ability to use percentage-based strings for <code>x</code>, <code>y</code>, <code>w</code> and <code>h</code> options
(<a href="https://github.com/gilmoreorless/jquery-nearest/issues/2">#2</a>).</li>
</ul></dd>
<dt class="minor" id="v1.1.0">1.1.0</dt>
<dd><ul>
<li>Added <code>tolerance</code> option to account for fractional pixel values and “close enough” situations
(<a href="https://github.com/gilmoreorless/jquery-nearest/issues/1">#1</a>).</li>
</ul></dd>
<dt class="major" id="v1.0.0">1.0.0</dt>
<dd><ul>
<li>First stable release.</li>
</ul></dd>
</dl>
</div><!-- #details -->
</div><!-- #wrapper -->
<!-- <a class="forkme" href="https://github.com/gilmoreorless/jquery-nearest">Fork me on GitHub</a> -->
<script src="../shared/docs/theme-v2/docs-common.js"></script>
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js" ></script>
<script src="src/jquery.nearest.min.js"></script>
<script src="inc/index.js"></script>
</body>
</html>