-
-
Notifications
You must be signed in to change notification settings - Fork 1.2k
/
Autocomplete.vue
279 lines (258 loc) · 11.5 KB
/
Autocomplete.vue
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
<example src="./examples/AutocompleteStatic.vue" />
<example src="./examples/AutocompleteTrigger.vue" />
<example src="./examples/AutocompleteSearch.vue" />
<example src="./examples/AutocompleteBox.vue" />
<example src="./examples/AutocompleteTemplate.vue" />
<example src="./examples/AutocompleteAsync.vue" />
<template>
<page-container centered :title="$t('pages.autocomplete.title')">
<div class="page-container-section">
<p>Input text can be used with autocomplete to help users who have limited literacy or who write in a foreign language. For example, autocomplete can suggest input as it’s typed (refreshing suggestions with each keystroke).</p>
<p>Vue Material autocomplete is really simple, yet powerfull. With simple options you can create great suggestions with async feedbacks.</p>
<p>Autocomplete works like <code>md-field</code>. This means that you can pass labels, validation messages, helper texts and even icons:</p>
</div>
<div class="page-container-section">
<h2 id="staticData">Static Data</h2>
<p>If you have a small amount of data or if it's static, you can pass the options to <code>md-autocomplete</code> in a simple and intuitive way:</p>
<code-example title="Normal and Dense" :component="examples['autocomplete-static']" />
</div>
<div class="page-container-section">
<h2 id="trigger">Trigger</h2>
<p>By default the suggestions will appear along with a focus trigger. If you want something less intrusive, you can disable this behaviour by canceling the focus event. If this, the suggestions will appear right after a keystroke:</p>
<code-example title="Focus vs Input" :component="examples['autocomplete-trigger']" />
</div>
<div class="page-container-section">
<h2 id="boxLayout">Box Layout</h2>
<p>Autocomplete have types two layouts: Default with floating labels and a boxed layout with inline labels. The box layout will apply a boxed layout with a small elevation, that also works really great as search bar inside a toolbar. Gorgeous:</p>
<code-example title="Works with dense variant too!" :component="examples['autocomplete-box']" />
</div>
<div class="page-container-section">
<h2 id="customTemplate">Custom Template</h2>
<note-block alert>This section will assume that you have knowledge of <a href="https://vuejs.org/v2/guide/components.html#Scoped-Slots" target="_blank">Vue Scoped Slots</a>. This will allow you to customize the option list.</note-block>
<p>Autocomplete also accepts a custom template, flexible to accept any HTML element and with an 'empty state' built in. You can also highlight the search term inside the matches, to give a feedback on why that item has been in the results. Awesome:</p>
<code-example title="With highlight text" :component="examples['autocomplete-template']" />
<note-block tip>Although the <code>md-highlight-text</code> component is most used with autocomplete, you can use it anywhere.</note-block>
</div>
<div class="page-container-section search-algorithms">
<h2 id="search-algorithms">Search Algorithms</h2>
<p>Vue Material autocomplete comes with 2 ways of search: <a href="https://en.wikipedia.org/wiki/Approximate_string_matching" target="_blank">Fuzzy search</a> and search by whole term. The fuzzy search tries to match the results by approximation, finding patterns inside the available options. This will help with accidental type errors and improve the results. If you think that this may be confusing, you can disable this. Example:</p>
<div class="md-layout md-gutter">
<div class="md-layout-item md-size-40">
<p>
<strong>Fuzzy search</strong> - search term: <code>pam</code>
</p>
<div>
Matches:
<ul>
<li>
<md-highlight-text md-term="pam">Pam Beesly</md-highlight-text>
</li>
<li>
<md-highlight-text md-term="pam">Meredith Palmer</md-highlight-text>
</li>
</ul>
</div>
</div>
<div class="md-layout-item md-size-40">
<p>
<strong>Normal Search</strong> - search term: <code>pam</code>
</p>
<div>
Matches:
<ul>
<li>
<md-highlight-text md-term="pam" :md-fuzzy-search="false">Pam Beesly</md-highlight-text>
</li>
</ul>
</div>
</div>
</div>
<code-example title="Fuzzy or Normal" :component="examples['autocomplete-search']" />
</div>
<div class="page-container-section">
<h2 id="async-options">Async Options</h2>
<p>Sometimes the options are inside a database in a remote server. Instead of giving a static data, we can provide a <code>Promise</code> that will resolve with the data from a backend servide, for example. This is great to save Bandwidth on the initial load and to improve the performance. Look at this example:</p>
<code-example title="Spinner Loading" :component="examples['autocomplete-async']" />
<api-item title="API - md-autocomplete">
<p>All the following options can be used on any autocomplete:</p>
<api-table :headings="autocomplete.props.headings" :props="autocomplete.props.props" slot="props" />
<api-table :headings="autocomplete.slots.headings" :props="autocomplete.slots.props" slot="scoped-slots" />
<api-table :headings="autocomplete.events.headings" :props="autocomplete.events.props" slot="events" />
</api-item>
<api-item title="API - md-highlight-text">
<p>The following options can be used with highlight text:</p>
<api-table :headings="highlight.props.headings" :props="highlight.props.props" slot="props" />
</api-item>
</div>
</page-container>
</template>
<script>
import examples from 'docs-mixins/docsExample'
export default {
name: 'DocAutocomplete',
mixins: [examples],
data: () => ({
autocomplete: {
slots: {
headings: ['Name', 'Description', 'Values'],
props: [
{
name: 'md-autocomplete-item',
description: 'Creates a custom autocomplete result item',
options: [
{
name: 'item',
description: 'Will receive each item of the matched options.'
},
{
name: 'term',
description: 'The current input search term.'
}
],
usage: '<template slot="md-autocomplete-item" slot-scope="{ item, term }"> ... </template>'
},
{
name: 'md-autocomplete-empty',
description: 'Creates a empty state in case of zero matches',
options: [
{
name: 'term',
description: 'The current input search term.'
}
],
usage: '<template slot="md-autocomplete-empty" slot-scope="{ term }"> ... </template>'
}
]
},
props: {
headings: ['Name', 'Description', 'Default'],
props: [
{
name: 'v-model',
type: 'String|Number|Boolean|Array',
description: 'The model variable to bind the autocomplete value',
defaults: 'null'
},
{
name: 'md-options',
type: 'Array|Promise',
description: 'The available options to be searched. If <code>Array</code>, the autocomplete will use a inner search engine. If <code>Promise</code>, you will need to implement the search by yourself (this is commonly made by a backend service).',
defaults: '[]'
},
{
name: 'md-input-name',
type: 'String',
description: 'The input name attribute',
defaults: 'null'
},
{
name: 'md-input-id',
type: 'String',
description: 'The input id attribute',
defaults: 'a random string'
},
{
name: 'md-input-max-length',
type: 'Number',
description: 'Enables a character count, based on the given value.',
defaults: 'null'
},
{
name: 'md-input-placeholder',
type: 'Number',
description: 'Sets a optional placeholder on autocomplete.',
defaults: 'null'
},
{
name: 'md-dense',
type: 'Boolean',
description: 'Enable the dense layout for options',
defaults: 'false'
},
{
name: 'md-layout',
type: 'String',
description: 'Sets the input layout. The floating variant is the default. See below the detailed description of each layout.',
defaults: 'floating'
},
{
offset: true,
name: 'md-layout="floating"',
type: 'String',
description: 'Sets the input layout to floating. This is the default.',
defaults: '-'
},
{
offset: true,
name: 'md-layout="box"',
type: 'String',
description: 'Sets the input layout to a boxed layout.',
defaults: '-'
},
{
name: 'md-open-on-focus',
type: 'Boolean',
description: 'Disable/enable the on focus event. If <code>false</code>, the options will show the results right after a keystroke.',
defaults: 'true'
},
{
name: 'md-fuzzy-search',
type: 'Boolean',
description: 'Disable/enable the fuzzy search algorithm. If <code>false</code>, the search will match the whole search term. This option do not take any effects if the <code>md-options</code> is a Promise',
defaults: 'true'
}
]
},
events: {
headings: ['Name', 'Description', 'Value'],
props: [
{
name: 'md-changed',
description: 'Triggered when the user types on the input field',
value: 'The search term'
},
{
name: 'md-selected',
description: 'Triggered when the user selects an option',
value: 'The selected value'
},
{
name: 'md-opened',
description: 'Triggered when the options panel is opened',
value: 'null'
},
{
name: 'md-closed',
description: 'Triggered when the options panel is closed',
value: 'null'
}
]
}
},
highlight: {
props: {
headings: ['Name', 'Description', 'Default'],
props: [
{
name: 'md-term',
type: 'String',
description: 'The search term to highlight',
defaults: 'null'
},
{
name: 'md-fuzzy-search',
type: 'Boolean',
description: 'Disable/enable the fuzzy highlight algorithm. If <code>false</code>, the highlight will match the whole search term.',
defaults: 'true'
}
]
}
}
})
}
</script>
<style lang="scss">
.search-algorithms .md-highlight-text-match {
color: #448aff;
}
</style>