Show last authors
1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc start="2"/}}
3 {{/box}}
4
5 The suggest widget is implemented using [[Selectize.js>>http://selectize.github.io/selectize.js/]] with its Bootstrap skin and is bundled by default in XWiki platform.
6
7 == Predefined Suggesters ==
8
9 A couple of suggesters are available by default in XWiki. Each suggester provides:
10
11 * dedicated helper Velocity macros (to import required resources and to output the required HTML)
12 * a jQuery plugin to activate the suggest behavior on any input or select element
13 * a CSS class that activates the suggest behavior automatically
14
15 The dedicated Velocity macros are in fact loading a JavaScript code that calls the dedicated jQuery plugin on all the elements (input or select) that are marked with the dedicated CSS class. Here's the list of available suggesters:
16
17 |=Data|=Velocity Macros|=jQuery Plugin|=CSS Class
18 |Pages|pagePicker, pagePicker_import|suggestPages|suggest-pages
19 |Attachments|attachmentPicker, attachmentPicker_import|suggestAttachments|suggest-attachments
20 |Users|userPicker, userPicker_input, userPicker_import|suggestUsers|suggest-users
21 |Groups|groupPicker|suggestGroups|suggest-groups
22 |Property Values|xpropertySuggestInputDisplayer|suggestPropertyValues|suggest-propertyValues
23
24 === Usage ===
25
26 There are 3 ways in which you can activate a predefined suggester:
27
28 * from Velocity (by calling the dedicated Velocity macro)
29 * from JavaScript (by calling the dedicated jQyery plugin)
30 * from HTML (by marking form fields with the dedicated CSS class)
31
32 Use the one that suits you the best.
33
34 ==== From Velocity ====
35
36 You can do this by putting the following code in the content of a wiki page. Here we're calling the dedicated ##pagePicker## Velocity macro. Note that you can pass configuration options. Most of these settings are translated into HTML attributes (of the generated suggest input element) read by the dedicated jQuery plugin. You can use the ##data-xwiki-selectize## parameter to pass configuration options to the [[Selectize.js>>https://github.com/selectize/selectize.js/blob/master/docs/usage.md#configuration]] widget. Each predefined suggester might also have custom parameters you can set, check their documentation below.
37
38 {{code language="none"}}
39 {{velocity}}
40 {{html}}
41 #set ($pagePickerParams = {
42 'name': 'targetPages',
43 'value': ['Path.To.Alice', 'Path.To.Bob'],
44 'multiple': 'multiple'
45 })
46 #pagePicker($pagePickerParams)
47 {{/html}}
48 {{/velocity}}
49 {{/code}}
50
51 ==== From JavaScript ====
52
53 You can do this from a JavaScript Skin extension. First you need to configure the path to the suggester you want to use and then you need to call the dedicated jQuery plugin (##suggestAttachments##) from a require block. Note that you can pass configuration options when activating the suggester. These configuration options are either generic (for the [[Selectize>>https://github.com/selectize/selectize.js/blob/master/docs/usage.md#configuration]] widget) or specific to each suggester (see below).
54
55 {{code language="js"}}
56 require.config({
57 paths: {
58 'xwiki-suggestAttachments': "$xwiki.getSkinFile('uicomponents/suggest/suggestAttachments.js', true)" +
59 "?v=$escapetool.url($xwiki.version)"
60 }
61 });
62
63 require(['jquery', 'xwiki-suggestAttachments'], function($) {
64 $('input[name="logo"]').suggestAttachments({
65 accept: 'image/,.mp4,.pdf',
66 uploadAllowed: true
67 });
68 });
69 {{/code}}
70
71 Of course, you still need to load your skin extension code (from the content of a wiki page):
72
73 {{code language="none"}}
74 {{velocity}}
75 {{html}}
76 #set ($discard = $xwiki.jsx.use('Path.To.Your.JSX'))
77 <input type="text" name="logo" value="Sandbox.WebHome@XWikiLogo.png"/>
78 {{/html}}
79 {{/velocity}}
80 {{/code}}
81
82 ==== From HTML ====
83
84 Put the following code in the content of a wiki page. First you need to import the resources required by the suggester and then you need to mark the form fields you wish to enhance (using the dedicated CSS class, ##suggest-users## here). Note that you can use the ##data-xwiki-selectize## attribute to pass configuration options in JSON format to the [[Selectize.js>>https://github.com/selectize/selectize.js/blob/master/docs/usage.md#configuration]] widget. Each predefined suggester might also have custom attributes you can set, check their documentation below.
85
86 {{code language="none"}}
87 {{velocity output="false"}}
88 #userPicker_import
89 {{/velocity}}
90
91 {{html}}
92 <input type="text" name="manager" value="XWiki.mflorea" class="suggest-users"/>
93 {{/html}}
94 {{/code}}
95
96 === Suggest Pages ===
97
98 This suggester displays the page rendered title and the page location. The value that is saved in the end is the page reference. The hidden page user preference is taken into account.
99
100 {{code language="none"}}
101 {{velocity}}
102 {{html}}
103 #set ($pagePickerParams = {
104 ...
105 })
106 #pagePicker($pagePickerParams)
107 {{/html}}
108 {{/velocity}}
109 {{/code}}
110
111 {{image reference="pagePicker.png"/}}
112
113 Custom configuration parameters:
114
115 |=Name|=Description|=Default Value
116 |data-document-reference|The document where the selected values are saved. Stored document references will be relative to this document.|Current page
117 |data-search-scope|(((Where to look for pages. The following is supported:
118 * "wiki:wikiName" look for pages in the specified wiki
119 * "space:spaceReference" look for pages in the specified space)))|Current wiki
120
121 === Suggest Attachments ===
122
123 This suggester displays the attachment (file) name and the attachment location. The suggestion icon is either a preview, if the attachment is an image or an icon that depends on the attachment media type. The value that is saved in the end is the attachment reference. The hidden page user preference is taken into account (e.g. attachments from hidden pages are not displayed by default).
124
125 {{code language="none"}}
126 {{velocity}}
127 {{html}}
128 #set ($attachmentPickerParams = {
129 ...
130 })
131 #attachmentPicker($attachmentPickerParams)
132 {{/html}}
133 {{/velocity}}
134 {{/code}}
135
136 {{image reference="attachmentPicker.png"/}}
137
138 It supports local file upload, either by selecting the files from the file browser or by dropping them on the suggest input. It also supports drag and drop of attachment links from the Attachment tab at the bottom of the wiki page.
139
140 Custom configuration parameters:
141
142 |=Name|=Description|=Default Value
143 |data-document-reference|The document where the selected values are saved and where new files are being uploaded. Stored attachment references will be relative this document.|Current page
144 |data-search-scope|(((Where to look for attachments. The following is supported:
145 * "wiki:wikiName" look for attachments in the specified wiki
146 * "space:spaceReference" look for attachments in the specified space
147 * "document:documentReference" look for attachments in the specified document)))|Current wiki
148 |data-upload-allowed|Whether to allow the user to upload files|false
149 |data-accept|(((Indicates the type of files that can be selected or uploaded. The value is a comma separated list of:
150 * file name extensions (e.g. .png,.pdf)
151 * complete or partial media types (e.g. image/,video/mpeg)
152
153 If nothing is specified then no restriction is applied.)))|None
154
155 === Suggest Users ===
156
157 This suggester displays the user avatar and their name. The value that is saved in the end is the user reference (the reference of the user profile page).
158
159 {{code language="none"}}
160 {{velocity}}
161 {{html}}
162 #set ($userPickerParams = {
163 ...
164 })
165 #userPicker($userPickerParams)
166 {{/html}}
167 {{/velocity}}
168 {{/code}}
169
170 {{image reference="userPicker.png"/}}
171
172 Custom configuration parameters:
173
174 |=Name|=Description|=Default Value
175 |data-userScope|Where to retrieve the user suggestions from. Supported values are: LOCAL_ONLY, GLOBAL_ONLY, LOCAL_AND_GLOBAL|User scope of the current wiki
176
177 === Suggest Groups ===
178
179 The suggester displays the group logo and its name. The group logo is the first image attachment found on the group page. The value that is saved in the end is the group reference (the reference of the group page).
180
181 {{code language="none"}}
182 {{velocity}}
183 {{html}}
184 #set ($groupPickerParams = {
185 ...
186 })
187 #groupPicker($groupPickerParams)
188 {{/html}}
189 {{/velocity}}
190 {{/code}}
191
192 {{image reference="groupPicker.png"/}}
193
194 Custom configuration parameters:
195
196 |=Name|=Description|=Default Value
197 |data-userScope|Where to retrieve the group suggestions from. Supported values are: LOCAL_ONLY, GLOBAL_ONLY, LOCAL_AND_GLOBAL. Note that GLOBAL_ONLY has the same effect as LOCAL_AND_GLOBAL because a wiki with only global users can have local groups|User scope of the current wiki
198
199 === Suggest Property Values ===
200
201 This suggester displays the label assocaited with a property value and saves the raw property value. The following property types are supported by this suggester: Static List and Database List. Note that these property types have default custom displayers associated that load the suggest widget when the "Use suggest" meta property is on. So normally the only thing you need to do is to display the property.
202
203 {{code language="none"}}
204 {{velocity}}
205 $doc.display('myDatabaseListProperty')
206 {{/velocity}}
207 {{/code}}
208
209 {{image reference="propertyValuePicker.png"/}}
210
211 If you don't have a property to display then you can also enable this suggester by calling the generic ##suggestInput## macro like this:
212
213 {{code language="none"}}
214 {{velocity}}
215 {{html}}
216 #set ($discard = $xwiki.jsfx.use('uicomponents/suggest/suggestPropertyValues.js',
217 {'forceSkinAction': true, 'language': $xcontext.locale}))
218 #set ($suggestParams = {
219 'class': 'suggest-propertyValues',
220 'placeholder': 'Select the movie director',
221 'data-className': 'Help.Applications.Movies.Code.MoviesClass',
222 'data-propertyName': 'databaseList1'
223 })
224 #suggestInput($suggestParams)
225 {{/html}}
226 {{/velocity}}
227 {{/code}}
228
229 If you need tag suggestions then you can use this configuration:
230
231 {{code language="none"}}
232 #set ($suggestParams = {
233 'class': 'suggest-propertyValues',
234 'multiple': 'multiple',
235 'data-className': 'XWiki.TagClass',
236 'data-propertyName': 'tags'
237 })
238 {{/code}}
239
240 Custom configuration parameters:
241
242 |=Name|=Description|=Default Value
243 |data-className|The class where the property is defined|None
244 |data-propertyName|The property whose values are to be retrieved as suggestions|None
245 |data-freeText|Whether free text is allowed or forbidden. Possible values are: allowed, forbidden|None
246
247 == Custom Suggesters ==
248
249 === Suggest from Static Data ===
250
251 Let's see how you can use the suggest widget with static data (i.e. data that is available when the web page is loaded).
252
253 {{html wiki="true"}}
254 <div>
255 <ul class="nav nav-tabs" role="tablist">
256 <li role="presentation" class="active">
257 <a href="#staticDataV1" aria-controls="staticDataV1" role="tab" data-toggle="tab">V1: The Basics</a>
258 </li>
259 <li role="presentation">
260 <a href="#staticDataV2" aria-controls="staticDataV2" role="tab" data-toggle="tab">V2: Separate Data</a>
261 </li>
262 <li role="presentation">
263 <a href="#staticDataV3" aria-controls="staticDataV3" role="tab" data-toggle="tab">V3: Helper Macros</a>
264 </li>
265 <li role="presentation">
266 <a href="#staticDataV4" aria-controls="staticDataV4" role="tab" data-toggle="tab">V4: Reusable Code</a>
267 </li>
268 </ul>
269
270 <div class="tab-content">
271 <div role="tabpanel" class="tab-pane active" id="staticDataV1">
272 <p>The following code:</p>
273
274 * loads the resources (JavaScript and CSS) needed by the suggest widget
275 * outputs the HTML (select element) needed by the suggest widget
276
277 <p>Note that the select element is marked with the ##xwiki-selectize## CSS class which activates the suggest widget.</p>
278
279 {{code language="none"}}
280 {{velocity}}
281 #set ($discard = $xwiki.linkx.use($services.webjars.url('selectize.js', 'css/selectize.bootstrap3.css'),
282 {'type': 'text/css', 'rel': 'stylesheet'}))
283 #set ($discard = $xwiki.ssfx.use('uicomponents/suggest/xwiki.selectize.css', true))
284 #set ($discard = $xwiki.jsfx.use('uicomponents/suggest/xwiki.selectize.js', true))
285 {{/velocity}}
286
287 {{html}}
288 <select class="xwiki-selectize">
289 <option value="">Select the country</option>
290 <option value="fr">France</option>
291 <option value="de">Germany</option>
292 <option value="ro">Romania</option>
293 </select>
294 {{/html}}
295 {{/code}}
296
297 </div>
298
299 <div role="tabpanel" class="tab-pane" id="staticDataV2">
300 <p>In this version we separate the code that generates the data used to provide suggestions. The data is usually retrieved from the database.</p>
301
302 {{code language="none"}}
303 {{velocity}}
304 {{html}}
305 #set ($discard = $xwiki.linkx.use($services.webjars.url('selectize.js', 'css/selectize.bootstrap3.css'),
306 {'type': 'text/css', 'rel': 'stylesheet'}))
307 #set ($discard = $xwiki.ssfx.use('uicomponents/suggest/xwiki.selectize.css', true))
308 #set ($discard = $xwiki.jsfx.use('uicomponents/suggest/xwiki.selectize.js', true))
309 #set ($countries = [
310 {'name': 'France', 'code': 'fr'},
311 {'name': 'Germany', 'code': 'de'},
312 {'name': 'Romania', 'code': 'ro'}
313 ])
314 ## See https://github.com/selectize/selectize.js/blob/master/docs/usage.md#configuration
315 #set ($selectizeSettings = {})
316 <select class="xwiki-selectize" data-xwiki-selectize="$escapetool.xml($jsontool.serialize($selectizeSettings))">
317 <option value="">Select the country</option>
318 #foreach ($country in $countries)
319 <option value="$!escapetool.xml($country.code)">$!escapetool.xml($country.name)</option>
320 #end
321 </select>
322 {{/html}}
323 {{/velocity}}
324 {{/code}}
325
326 </div>
327
328 <div role="tabpanel" class="tab-pane" id="staticDataV3">
329 <p>In this version we use some helper Velocity macros: ##picker_import## and ##suggestInput##. Notice the way we specify the selected value and the placeholder by passing parameters to the ##suggestInput## macro.</p>
330
331 {{code language="none"}}
332 {{velocity output="false"}}
333 #set ($countries = [
334 {'name': 'France', 'code': 'fr'},
335 {'name': 'Germany', 'code': 'de'},
336 {'name': 'Romania', 'code': 'ro'}
337 ])
338
339 #macro (countryPicker_displayOptions $selectedValues)
340 #foreach ($country in $countries)
341 <option value="$!escapetool.xml($country.code)"#if ($selectedValues.contains($country.code)) selected="selected"#end
342 >$!escapetool.xml($country.name)</option>
343 #end
344 #end
345 {{/velocity}}
346
347 {{velocity}}
348 {{html}}
349 #picker_import
350 #set ($discard = $xwiki.jsfx.use('uicomponents/suggest/xwiki.selectize.js', true))
351 ## See https://github.com/selectize/selectize.js/blob/master/docs/usage.md#configuration
352 #set ($selectizeSettings = {})
353 #set ($suggestInputAttributes = {
354 'name': 'country',
355 'class': 'xwiki-selectize',
356 'data-xwiki-selectize': $selectizeSettings,
357 'value': 'ro',
358 'placeholder': 'Select the country'
359 })
360 #suggestInput($suggestInputAttributes 'countryPicker_displayOptions')
361 {{/html}}
362 {{/velocity}}
363 {{/code}}
364
365 </div>
366
367 <div role="tabpanel" class="tab-pane" id="staticDataV4">
368 <p>In this last version we make the code reusable by creating the ##countryPicker## and ##countryPicker_import## Velocity macros.</p>
369
370 {{code language="none"}}
371 {{velocity output="false"}}
372 #set ($countries = [
373 {'name': 'France', 'code': 'fr'},
374 {'name': 'Germany', 'code': 'de'},
375 {'name': 'Romania', 'code': 'ro'}
376 ])
377
378 #macro (countryPicker_displayOptions $selectedValues)
379 #foreach ($country in $countries)
380 <option value="$!escapetool.xml($country.code)"#if ($selectedValues.contains($country.code)) selected="selected"#end
381 >$!escapetool.xml($country.name)</option>
382 #end
383 #end
384
385 #macro (countryPicker_import)
386 #picker_import
387 #set ($discard = $xwiki.jsfx.use('uicomponents/suggest/xwiki.selectize.js', true))
388 #end
389
390 #macro (countryPicker $parameters)
391 #countryPicker_import
392 #if ("$!parameters" == "")
393 #set ($parameters = {})
394 #end
395 #set ($discard = $parameters.put('class', "$!parameters.get('class') xwiki-selectize suggest-countries"))
396 #if (!$parameters.containsKey('placeholder'))
397 #set ($parameters.placeholder = 'Select the country')
398 #end
399 #suggestInput($parameters 'countryPicker_displayOptions')
400 #end
401 {{/velocity}}
402
403 {{velocity}}
404 {{html}}
405 #set ($countryPickerParams = {
406 'name': 'country',
407 'value': 'ro'
408 })
409 #countryPicker($countryPickerParams)
410 {{/html}}
411 {{/velocity}}
412 {{/code}}
413
414 </div>
415 </div>
416 </div>
417 {{/html}}
418
419 === Suggest from Remote Data ===
420
421 Most of the time you will want to retrive suggestions when the user types rather than loading all the suggestions on page load. Let's see how you can do this.
422
423 {{html wiki="true"}}
424 <div>
425 <ul class="nav nav-tabs" role="tablist">
426 <li role="presentation" class="active">
427 <a href="#remoteDataV1" aria-controls="remoteDataV1" role="tab" data-toggle="tab">V1: The Basics</a>
428 </li>
429 <li role="presentation">
430 <a href="#remoteDataV2" aria-controls="remoteDataV2" role="tab" data-toggle="tab">V2: Reusable Code</a>
431 </li>
432 </ul>
433
434 <div class="tab-content">
435 <div role="tabpanel" class="tab-pane active" id="remoteDataV1">
436 <p>In order to retrieve suggestions as you type you need to write some JavaScript code that makes an asynchronous HTTP request to retrive the data. You can put this code in a JavaScript Skin extension object. Then you need to load this JavaScript code on the page where you want to activate the suggest widget.</p>
437
438 {{code language="js"}}
439 require.config({
440 paths: {
441 'xwiki-selectize': "$xwiki.getSkinFile('uicomponents/suggest/xwiki.selectize.js', true)" +
442 "?v=$escapetool.url($xwiki.version)"
443 }
444 });
445
446 require(['jquery', 'xwiki-selectize'], function($) {
447 var settings = {
448 load: function(typedText, callback) {
449 $.getJSON('your/service/url', {
450 text: typedText
451 }).done(callback).fail(callback);
452 },
453 loadSelected: function(selectedValue, callback) {
454 $.getJSON('your/service/url', {
455 text: typedText,
456 exactMatch: true
457 }).done(callback).fail(callback);
458 }
459 };
460
461 $('.suggest-countries').xwikiSelectize(settings);
462 });
463 {{/code}}
464
465 {{code language="none"}}
466 {{velocity}}
467 #set ($discard = $xwiki.linkx.use($services.webjars.url('selectize.js', 'css/selectize.bootstrap3.css'),
468 {'type': 'text/css', 'rel': 'stylesheet'}))
469 #set ($discard = $xwiki.ssfx.use('uicomponents/suggest/xwiki.selectize.css', true))
470 #set ($discard = $xwiki.jsx.use('Path.To.Your.JSX'))
471 {{/velocity}}
472
473 {{html}}
474 <select class="suggest-countries">
475 <option value="">Select the country</option>
476 </select>
477 {{/html}}
478 {{/code}}
479
480 </div>
481
482 <div role="tabpanel" class="tab-pane" id="remoteDataV2">
483 <p>In this last version we make the code reusable by creating a jQuery plugin and some helper Velocity macros.</p>
484
485 {{code language="js"}}
486 require.config({
487 paths: {
488 'xwiki-selectize': "$xwiki.getSkinFile('uicomponents/suggest/xwiki.selectize.js', true)" +
489 "?v=$escapetool.url($xwiki.version)"
490 }
491 });
492
493 define('xwiki-suggestCountries', ['jquery', 'xwiki-selectize'], function($) {
494 var getSettings = function(select) {
495 return {
496 load: function(typedText, callback) {
497 $.getJSON('your/service/url', {
498 text: typedText
499 }).done(callback).fail(callback);
500 },
501 loadSelected: function(selectedValue, callback) {
502 $.getJSON('your/service/url', {
503 text: typedText,
504 exactMatch: true
505 }).done(callback).fail(callback);
506 }
507 };
508 };
509
510 $.fn.suggestCountries = function(settings) {
511 return this.each(function() {
512 $(this).xwikiSelectize($.extend(getSettings($(this)), settings));
513 });
514 };
515 });
516
517 require(['jquery', 'xwiki-suggestCountries', 'xwiki-events-bridge'], function($) {
518 var init = function(event, data) {
519 var container = $((data && data.elements) || document);
520 container.find('.suggest-countries').suggestCountries();
521 };
522
523 $(document).on('xwiki:dom:loaded xwiki:dom:updated', init);
524 XWiki.domIsLoaded && init();
525 });
526 {{/code}}
527
528 {{code language="none"}}
529 {{velocity output="false"}}
530 #macro (countryPicker_import)
531 #picker_import
532 #set ($discard = $xwiki.jsx.use('Path.To.Your.JSX'))
533 #end
534
535 #macro (countryPicker $parameters)
536 #countryPicker_import
537 #if ("$!parameters" == "")
538 #set ($parameters = {})
539 #end
540 #set ($discard = $parameters.put('class', "$!parameters.get('class') suggest-countries"))
541 #if (!$parameters.containsKey('placeholder'))
542 #set ($parameters.placeholder = 'Select the country')
543 #end
544 #suggestInput($parameters)
545 #end
546 {{/velocity}}
547
548 {{velocity}}
549 {{html}}
550 #set ($countryPickerParams = {
551 'name': 'country',
552 'value': 'ro'
553 })
554 #countryPicker($countryPickerParams)
555 {{/html}}
556 {{/velocity}}
557 {{/code}}
558
559 </div>
560 </div>
561 </div>
562 {{/html}}
563
564 The remote data should have the following JSON format:
565
566 {{code language="js"}}
567 [
568 {
569 'label': '...',
570 'value': '...',
571 'url': '...',
572 'icon': {
573 'iconSetName': '...',
574 'iconSetType': 'IMAGE or FONT',
575 'cssClass': 'for font icons',
576 'url': 'for image icons'
577 },
578 'hint': '...'
579 },
580 ...
581 ]
582 {{/code}}

Get Connected