forked from netavanza/awesomplete
-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.html
355 lines (301 loc) · 14.5 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
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
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>Awesomplete: Ultra lightweight, highly customizable, simple autocomplete, by Lea Verou</title>
<link rel="stylesheet" href="https://leaverou.github.io/prism/themes/prism.css" />
<link rel="stylesheet" href="awesomplete.css" />
<link rel="stylesheet" href="style.css" />
</head>
<body class="language-markup">
<header>
<h1>Awesomplete</h1>
<a href="#download" class="size"><strong>2KB</strong> minified <span class="amp">&</span> gzipped!</a>
<p>Ultra lightweight, customizable, simple autocomplete widget with zero dependencies, built with modern standards for <abbr title="Verified to work in: IE9 (sorta), IE10+, Chrome, Firefox, Safari 5+, Mobile Safari">modern browsers</abbr>. <a href="http://lea.verou.me/2015/02/awesomplete-2kb-autocomplete-with-zero-dependencies">Because <code><datalist></code> still doesn’t cut it.</a></p>
<nav></nav>
</header>
<section>
<h1>Demo (no JS, minimal options)</h1>
<label>
Pick a programming language:<br />
<input autofocus class="awesomplete" data-list="Ada, Java, JavaScript, Brainfuck, LOLCODE, Node.js, Ruby on Rails" />
</label>
<p>Note that by default you need to type <strong>at least 2 characters</strong> for the popup to show up, though that’s <a href="#customization">super easy to customize</a>. With Awesomplete, making something like this can be as simple as:</p>
<pre class="language-markup"><code><input class="awesomplete"
data-list="Ada, Java, JavaScript, Brainfuck, LOLCODE, Node.js, Ruby on Rails" /></code></pre>
<pre class="language-javascript"><code>// No extra JS needed for basic usage!</code></pre>
</section>
<section id="basic-usage">
<h1>Basic usage</h1>
<p>Before you try anything, you need to include <code>awesomplete.css</code> and <code>awesomplete.js</code> in your page, via the usual <code><link rel="stylesheet" href="awesomplete.css" /></code> and <code><script src="awesomplete.js" async></script></code> tags.</p>
<p>For the autocomplete, you just need an <code><input></code> text field (might work on <code><textarea></code> and elements with <code>contentEditable</code>, but that hasn’t been tested). Add <code>class="awesomplete"</code> for it to be <strong>automatically processed</strong> (you can still specify many options via HTML attributes), otherwise you can instantiate with a few lines of JS code, which allow for more customization.</p>
<p>There are many ways <strong>to link an input to a list of suggestions</strong>. The simple example above could have also been made with the following markup, which provides a nice native fallback in case the script doesn’t load:</p>
<pre class="language-markup"><code><input class="awesomplete" list="mylist" />
<datalist id="mylist">
<option>Ada</option>
<option>Java</option>
<option>JavaScript</option>
<option>Brainfuck</option>
<option>LOLCODE</option>
<option>Node.js</option>
<option>Ruby on Rails</option>
</datalist></code></pre>
<pre class="language-javascript"><code>// None!</code></pre>
<p>Or the following, if you don’t want to use a <code><datalist></code>, or if you don’t want to use IDs (since any selector will work in <code>data-list</code>):</p>
<pre class="language-markup"><code><input class="awesomplete" data-list="#mylist" />
<ul id="mylist">
<li>Ada</li>
<li>Java</li>
<li>JavaScript</li>
<li>Brainfuck</li>
<li>LOLCODE</li>
<li>Node.js</li>
<li>Ruby on Rails</li>
</ul></code></pre>
<pre class="language-javascript"><code>// None!</code></pre>
<p>Or the following, if we want to instantiate in JS:</p>
<pre class="language-markup"><code><input id="myinput" />
<ul id="mylist">
<li>Ada</li>
<li>Java</li>
<li>JavaScript</li>
<li>Brainfuck</li>
<li>LOLCODE</li>
<li>Node.js</li>
<li>Ruby on Rails</li>
</ul></code></pre>
<pre class="language-javascript"><code>var input = document.getElementById("myinput");
new Awesomplete(input, {list: "#mylist"});</code></pre>
<p>We can use an <strong>element reference</strong> for the list instead of a selector:</p>
<pre class="language-markup"><code><input id="myinput" />
<ul id="mylist">
<li>Ada</li>
<li>Java</li>
<li>JavaScript</li>
<li>Brainfuck</li>
<li>LOLCODE</li>
<li>Node.js</li>
<li>Ruby on Rails</li>
</ul></code></pre>
<pre class="language-javascript"><code>var input = document.getElementById("myinput");
new Awesomplete(input, {list: document.querySelector("#mylist")});</code></pre>
<p>We can also directly use an <strong>array of strings</strong>:</p>
<pre class="language-markup"><code><input id="myinput" /></code></pre>
<pre class="language-javascript"><code>var input = document.getElementById("myinput");
new Awesomplete(input, {
list: ["Ada", "Java", "JavaScript", "Brainfuck", "LOLCODE", "Node.js", "Ruby on Rails"]
});</code></pre>
<p>We can even set it (or override it) later and it will just work:</p>
<pre class="language-markup"><code><input id="myinput" /></code></pre>
<pre class="language-javascript"><code>var input = document.getElementById("myinput");
var awesomplete = new Awesomplete(input);
/* ...more code... */
awesomplete.list = ["Ada", "Java", "JavaScript", "Brainfuck", "LOLCODE", "Node.js", "Ruby on Rails"];</code></pre>
</section>
<section id="customization">
<h1>Customize</h1>
<p>All settings discussed in this section are settable via either a <code>data-</code> attribute on the <code><input></code> element or a JS property on the second argument of the <code>Awesomplete</code> constructor, like so:</p>
<pre class="language-javascript"><code>new Awesomplete(inputReference, {
minChars: 3,
maxItems: 15,
...
});</code></pre>
<p>You can of course combine both HTML attributes and JS properties. <strong>In case of conflict</strong> (e.g. you’ve specified both a <code>data-minchars</code> on the text field and a <code>minChars</code> JS property, <strong>the HTML attribute wins</strong>. You can also use the JS properties to change a parameter <strong>after</strong> the object has been created, in which case the change will apply even if there is a conflicting HTML attribute.</p>
<table>
<thead>
<tr>
<th>JS property</th>
<th>HTML attribute</th>
<th>Description</th>
<th>Value</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>list</code></td>
<td><code>data-list</code></td>
<td>Where to find the list of suggestions. Described in more detail in the “<a href="#basic-usage">Basic usage</a>” section above.</td>
<td><ul>
<li>Array of strings</li>
<li>HTML element</li>
<li>CSS selector (no groups, i.e. no commas)</li>
<li>String containing a comma-separated list of items</li>
</ul></td>
<td>N/A</td>
</tr>
<tr>
<td><code>minChars</code></td>
<td><code>data-minchars</code></td>
<td>Minimum characters the user has to type before the autocomplete popup shows up.</td>
<td>Number</td>
<td>2</td>
</tr>
<tr>
<td><code>maxItems</code></td>
<td><code>data-maxitems</code></td>
<td>Maximum number of suggestions to display.</td>
<td>Number</td>
<td>10</td>
</tr>
<tr>
<td><code>autoFirst</code></td>
<td><code>data-autofirst</code></td>
<td>Should the first element be automatically selected? Demo: <input class="awesomplete" data-autofirst data-list="Ada, Java, JavaScript, Brainfuck, LOLCODE, Node.js, Ruby on Rails" xautofocus /></td>
<td>Boolean</td>
<td>false</td>
</tr>
</tbody>
</table>
</section>
<section id="extensibility">
<h1>Extend</h1>
<p>The following JS properties do not have equivalent HTML attributes, because their values are functions. They allow you to completely change the way Awesomplete works:</p>
<table>
<thead>
<tr>
<th>Property</th>
<th>Description</th>
<th>Value</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>filter</code></td>
<td>Controls how entries get matched. By default, the input can match anywhere in the string and it’s a case insensitive match.</td>
<td>Function that takes two parameters, the first one being the current suggestion text that’s being tested and the second a string with the user’s input it’s matched against. Returns <code>true</code> if the match is successful and <code>false</code> if it is not. For example, to only match strings that <strong>start with the user’s input</strong>, <strong>case sensitive</strong>, we can do this:
<pre class="language-javascript"><code>filter: function (text, input) {
return text.indexOf(input) === 0;
}</code></pre> For case-<strong>in</strong>sensitive matching from the start of the word, there is a predefined filter that you can use, <code class="language-javascript">Awesomplete.FILTER_STARTSWITH</code>
</td>
<td><code class="language-javascript">Awesomplete.FILTER_CONTAINS</code>: Text can match anywhere, case insensitive.</td>
</tr>
<tr>
<td><code>sort</code></td>
<td>Controls how list items are ordered.</td>
<td>Sort function (will be passed directly to <code>Array.prototype.sort()</code>) to sort the items after they have been filtered and before they are truncated and converted to HTML elements.</td>
<td>Sorted by length first, order second.</td>
</tr>
<tr>
<td><code>item</code></td>
<td>Controls how list items are generated.</td>
<td>Function that takes two parameters, the first one being the suggestion text and the second one the user’s input and returns a list item.</td>
<td>Generates list items with the user’s input highlighted via <code><mark></code>.</td>
</tr>
<tr>
<td><code>replace</code></td>
<td>Controls how the user’s selection replaces the user’s input. For example, this is useful if you want the selection to only partially replace the user’s input.</td>
<td>Function that takes one parameter, the text of the selected option, and is responsible for replacing the current input value with it.
</td>
<td><pre class="language-javascript"><code>function (text) {
this.input.value = value;
}</code></pre></td>
</tr>
</tbody>
</table>
</section>
<section id="events">
<h1>Events</h1>
<p>Custom events are thrown in several places and are often cancellable. To avoid conflicts, all custom events are prefixed with <code>awesomplete-</code>.</p>
<table>
<thead>
<tr>
<th>Name</th>
<th>Description</th>
<th>event.preventDefault()?</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>awesomplete-select</code></td>
<td>The user has made a selection (either via pressing enter or clicking on an item), but it has not been applied yet.</td>
<td>Yes. The selection will not be applied and the popup will not close.</td>
</tr>
<tr>
<td><code>awesomplete-selectcomplete</code></td>
<td>The user has made a selection (either via pressing enter or clicking on an item), and it has been applied.</td>
<td>No</td>
</tr>
<tr>
<td><code>awesomplete-open</code></td>
<td>The popup just appeared.</td>
<td>No</td>
</tr>
<tr>
<td><code>awesomplete-close</code></td>
<td>The popup just closed.</td>
<td>No</td>
</tr>
</tbody>
</table>
</section>
<section id="api">
<h1>API</h1>
<p>There are several methods on every Awesomplete instance that you can call to customize behavior:</p>
<table>
<thead>
<tr>
<th>Method</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>open()</code></td>
<td>Opens the popup.</td>
</tr>
<tr>
<td><code>close()</code></td>
<td>Closes the popup.</td>
</tr>
<tr>
<td><code>next()</code></td>
<td>Highlights the next item in the popup.</td>
</tr>
<tr>
<td><code>previous()</code></td>
<td>Highlights the previous item in the popup.</td>
</tr>
<tr>
<td><code>goto(i)</code></td>
<td>Highlights the item with index <code>i</code> in the popup (<code>-1</code> to deselect all). Avoid using this directly and try to use <code>next()</code> or <code>previous()</code> instead when possible.</td>
</tr>
<tr>
<td><code>select()</code></td>
<td>Selects the currently highlighted item, replaces the text field’s value with it and closes the popup.</td>
</tr>
<tr>
<td><code>evaluate()</code></td>
<td>Evaluates the current state of the widget and regenerates the list of suggestions or closes the popup if none are available. You need to call it if you dynamically set <code>list</code> while the popup is open.</td>
</tr>
</tbody>
</table>
</section>
<section id="download">
<h1>Download!</h1>
<ul>
<li><strong><a href="https://github.com/LeaVerou/awesomplete/archive/gh-pages.zip">Download everything as a zip file</a></strong></li>
<li><a href="https://github.com/LeaVerou/awesomplete">Fork me on Github</a></li>
<li><a href="https://github.com/LeaVerou/awesomplete/issues/new">File a bug</a> </li>
<li><a href="https://github.com/LeaVerou/awesomplete/issues/new">Suggest a feature</a> </li>
</ul>
<p><strong>Pull requests are very welcome</strong>, as long as you maintain the code style and ask before adding tons of LOCs to the codebase!</p>
</section>
<footer>Made with ♥ by <a href="http://lea.verou.me">Lea Verou</a> • <a href="http://lea.verou.me/2015/02/awesomplete-2kb-autocomplete-with-zero-dependencies">Read the blog post</a> • <a href="http://shop.oreilly.com/product/0636920031123.do">Buy my book!</a> </footer>
<script src="awesomplete.js"></script>
<script src="https://leaverou.github.io/prism/prism.js" defer></script>
<script src="index.js"></script>
<a href="https://twitter.com/share" class="twitter-share-button" data-via="LeaVerou" data-size="large">Tweet</a>
<script async src="//cdn.carbonads.com/carbon.js?zoneid=1673&serve=C6AILKT&placement=leaveroume" id="_carbonads_js"></script>
<script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0],p=/^http:/.test(d.location)?'http':'https';if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src=p+'://platform.twitter.com/widgets.js';fjs.parentNode.insertBefore(js,fjs);}}(document, 'script', 'twitter-wjs');</script>
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-25106441-4', 'auto');
ga('send', 'pageview');
</script>
</body>
</html>