Wiki source code of Suggest Widget
Last modified by Lucas Charpentier on 2026/10/14 15:53
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | {{box cssClass="floatinginfobox" title="**Contents**"}} | ||
| 2 | {{toc start="2"/}} | ||
| 3 | {{/box}} | ||
| 4 | |||
| 5 | The suggest widget is implemented using [[Tom Select>>https://github.com/orchidjs/tom-select]] with its Bootstrap skin and is bundled by default in XWiki platform. | ||
| 6 | |||
| 7 | {{version before="18.2.0RC1"}} | ||
| 8 | In older versions of XWiki the suggest widget was implemented using [[Selectize.js>>http://selectize.github.io/selectize.js/]]. Unfortunately Selectize stop being maintained so we decided to replace it with Tom Select, which is actually a fork of Selectize. Tom Select preserves most of the public JavaScript API and configuration options of Selectize, so the following documentation should apply to older XWiki versions using Selectize, with small adjustments. | ||
| 9 | {{/version}} | ||
| 10 | |||
| 11 | == Predefined Suggesters == | ||
| 12 | |||
| 13 | A couple of suggesters are available by default in XWiki. Each suggester provides: | ||
| 14 | |||
| 15 | * dedicated helper Velocity macros (to import required resources and to output the required HTML) | ||
| 16 | * a jQuery plugin to activate the suggest behavior on any input or select element | ||
| 17 | * a CSS class that activates the suggest behavior automatically | ||
| 18 | |||
| 19 | 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: | ||
| 20 | |||
| 21 | |=Data|=Velocity Macros|=jQuery Plugin|=CSS Class | ||
| 22 | |Pages|pagePicker, pagePicker_import|suggestPages|suggest-pages | ||
| 23 | |Attachments|attachmentPicker, attachmentPicker_import|suggestAttachments|suggest-attachments | ||
| 24 | |{{version since="18.9.0RC1"}}Locations{{/version}}|spacePicker, spacePicker_import|suggestSpaces|suggest-spaces | ||
| 25 | |Users|userPicker, userPicker_input, userPicker_import|suggestUsers|suggest-users | ||
| 26 | |Groups|groupPicker|suggestGroups|suggest-groups | ||
| 27 | |Property Values|xpropertySuggestInputDisplayer|suggestPropertyValues|suggest-propertyValues | ||
| 28 | |||
| 29 | === Usage === | ||
| 30 | |||
| 31 | There are 3 ways in which you can activate a predefined suggester: | ||
| 32 | |||
| 33 | * from Velocity (by calling the dedicated Velocity macro) | ||
| 34 | * from JavaScript (by calling the dedicated jQyery plugin) | ||
| 35 | * from HTML (by marking form fields with the dedicated CSS class) | ||
| 36 | |||
| 37 | Use the one that suits you the best. | ||
| 38 | |||
| 39 | ==== From Velocity ==== | ||
| 40 | |||
| 41 | 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 [[Tom Select>>https://tom-select.js.org/docs/]] widget. Each predefined suggester might also have custom parameters you can set, check their documentation below. | ||
| 42 | |||
| 43 | {{code language="none"}} | ||
| 44 | {{velocity}} | ||
| 45 | {{html}} | ||
| 46 | #set ($pagePickerParams = { | ||
| 47 | 'name': 'targetPages', | ||
| 48 | 'value': ['Path.To.Alice', 'Path.To.Bob'], | ||
| 49 | 'multiple': 'multiple' | ||
| 50 | }) | ||
| 51 | #pagePicker($pagePickerParams) | ||
| 52 | {{/html}} | ||
| 53 | {{/velocity}} | ||
| 54 | {{/code}} | ||
| 55 | |||
| 56 | ==== From JavaScript ==== | ||
| 57 | |||
| 58 | 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 [[Tom Select>>https://tom-select.js.org/docs/]] widget) or specific to each suggester (see below). | ||
| 59 | |||
| 60 | {{code language="js"}} | ||
| 61 | require.config({ | ||
| 62 | paths: { | ||
| 63 | 'xwiki-suggestAttachments': "$xwiki.getSkinFile('uicomponents/suggest/suggestAttachments.js', true)" + | ||
| 64 | "?v=$escapetool.url($xwiki.version)" | ||
| 65 | } | ||
| 66 | }); | ||
| 67 | |||
| 68 | require(['jquery', 'xwiki-suggestAttachments'], function($) { | ||
| 69 | $('input[name="logo"]').suggestAttachments({ | ||
| 70 | accept: 'image/,.mp4,.pdf', | ||
| 71 | uploadAllowed: true | ||
| 72 | }); | ||
| 73 | }); | ||
| 74 | {{/code}} | ||
| 75 | |||
| 76 | Of course, you still need to load your skin extension code (from the content of a wiki page): | ||
| 77 | |||
| 78 | {{code language="none"}} | ||
| 79 | {{velocity}} | ||
| 80 | {{html}} | ||
| 81 | #set ($discard = $xwiki.jsx.use('Path.To.Your.JSX')) | ||
| 82 | <input type="text" name="logo" value="[email protected]"/> | ||
| 83 | {{/html}} | ||
| 84 | {{/velocity}} | ||
| 85 | {{/code}} | ||
| 86 | |||
| 87 | ==== From HTML ==== | ||
| 88 | |||
| 89 | 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 [[Tom Select>>https://tom-select.js.org/docs/]] widget. Each predefined suggester might also have custom attributes you can set, check their documentation below. | ||
| 90 | |||
| 91 | {{code language="none"}} | ||
| 92 | {{velocity output="false"}} | ||
| 93 | #userPicker_import | ||
| 94 | {{/velocity}} | ||
| 95 | |||
| 96 | {{html}} | ||
| 97 | <input type="text" name="manager" value="XWiki.mflorea" class="suggest-users"/> | ||
| 98 | {{/html}} | ||
| 99 | {{/code}} | ||
| 100 | |||
| 101 | === Suggest Pages === | ||
| 102 | |||
| 103 | 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. | ||
| 104 | |||
| 105 | {{code language="none"}} | ||
| 106 | {{velocity}} | ||
| 107 | {{html}} | ||
| 108 | #set ($pagePickerParams = { | ||
| 109 | ... | ||
| 110 | }) | ||
| 111 | #pagePicker($pagePickerParams) | ||
| 112 | {{/html}} | ||
| 113 | {{/velocity}} | ||
| 114 | {{/code}} | ||
| 115 | |||
| 116 | {{image reference="pagePicker.png"/}} | ||
| 117 | |||
| 118 | Custom configuration parameters: | ||
| 119 | |||
| 120 | |=Name|=Description|=Default Value | ||
| 121 | |data-document-reference|The document where the selected values are saved. Stored document references will be relative to this document.|Current page | ||
| 122 | |data-search-scope|(((Where to look for pages. The following is supported: | ||
| 123 | * "wiki:wikiName" look for pages in the specified wiki | ||
| 124 | * "space:spaceReference" look for pages in the specified space)))|Current wiki | ||
| 125 | |||
| 126 | === Suggest Attachments === | ||
| 127 | |||
| 128 | 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). | ||
| 129 | |||
| 130 | {{code language="none"}} | ||
| 131 | {{velocity}} | ||
| 132 | {{html}} | ||
| 133 | #set ($attachmentPickerParams = { | ||
| 134 | ... | ||
| 135 | }) | ||
| 136 | #attachmentPicker($attachmentPickerParams) | ||
| 137 | {{/html}} | ||
| 138 | {{/velocity}} | ||
| 139 | {{/code}} | ||
| 140 | |||
| 141 | {{image reference="attachmentPicker.png"/}} | ||
| 142 | |||
| 143 | 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. | ||
| 144 | |||
| 145 | Custom configuration parameters: | ||
| 146 | |||
| 147 | |=Name|=Description|=Default Value | ||
| 148 | |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 | ||
| 149 | |data-search-scope|(((Where to look for attachments. The following is supported: | ||
| 150 | * "wiki:wikiName" look for attachments in the specified wiki | ||
| 151 | * "space:spaceReference" look for attachments in the specified space | ||
| 152 | * "document:documentReference" look for attachments in the specified document)))|Current wiki | ||
| 153 | |data-upload-allowed|Whether to allow the user to upload files|false | ||
| 154 | |data-accept|(((Indicates the type of files that can be selected or uploaded. The value is a comma separated list of: | ||
| 155 | * file name extensions (e.g. .png,.pdf) | ||
| 156 | * complete or partial media types (e.g. image/,video/mpeg) | ||
| 157 | |||
| 158 | If nothing is specified then no restriction is applied.)))|None | ||
| 159 | |||
| 160 | === Suggest Locations === | ||
| 161 | |||
| 162 | {{version since="18.9.0RC1"}} | ||
| 163 | This suggester displays the location title and its parent locations. The value that is saved in the end is the location reference, relative to the wiki of the document where the value is saved. | ||
| 164 | |||
| 165 | {{code language="none"}} | ||
| 166 | {{velocity}} | ||
| 167 | {{html}} | ||
| 168 | #set ($spacePickerParams = { | ||
| 169 | 'name': 'locations', | ||
| 170 | 'multiple': 'multiple' | ||
| 171 | }) | ||
| 172 | #spacePicker($spacePickerParams) | ||
| 173 | {{/html}} | ||
| 174 | {{/velocity}} | ||
| 175 | {{/code}} | ||
| 176 | |||
| 177 | {{image reference="spacePicker.png"/}} | ||
| 178 | |||
| 179 | Set the ##multiple## parameter to ##multiple## to allow selecting more than one location. The form then submits one value per selected location, under the same field name. The user can also type the reference of a location that isn't suggested. | ||
| 180 | |||
| 181 | Custom configuration parameters: | ||
| 182 | |||
| 183 | |=Name|=Description|=Default Value | ||
| 184 | |data-document-reference|The document where the selected values are saved. Stored location references will be relative to the wiki of this document.|Current page | ||
| 185 | |data-search-scope|(((Where to look for locations. The following is supported: | ||
| 186 | * "wiki:wikiName" look for locations in the specified wiki | ||
| 187 | * "space:spaceReference" look for the locations nested in the specified location)))|Current wiki | ||
| 188 | |||
| 189 | ==== Compact Location Picker ==== | ||
| 190 | |||
| 191 | The ##compactLocationPicker## Velocity macro displays the location suggester with a button next to it, which opens a page tree in a drop down to browse for locations. The tree only updates the suggest input, which keeps holding the value. With single selection, selecting a location in the tree replaces the value and closes the drop down. With multiple selection, checking or unchecking a location adds it to or removes it from the value, and the drop down stays open. When the page tree isn't available, only the suggest input is displayed. The macro is defined in the ##locationPicker_macros.vm## template, which you need to load first. | ||
| 192 | |||
| 193 | {{code language="none"}} | ||
| 194 | {{velocity}} | ||
| 195 | {{html}} | ||
| 196 | #template('locationPicker_macros.vm') | ||
| 197 | #set ($locationPickerOptions = { | ||
| 198 | 'name': 'locations', | ||
| 199 | 'multiple': true, | ||
| 200 | 'value': ['Sandbox', 'Help.Applications'] | ||
| 201 | }) | ||
| 202 | #compactLocationPicker($locationPickerOptions) | ||
| 203 | {{/html}} | ||
| 204 | {{/velocity}} | ||
| 205 | {{/code}} | ||
| 206 | |||
| 207 | {{image reference="compactLocationPicker.png"/}} | ||
| 208 | |||
| 209 | The compact location picker is also used to edit [[a wiki macro parameter of type ##java.util.List<org.xwiki.model.reference.SpaceReference>##>>doc:documentation.xs.dev.rendering-macros.macro-parameter-pickers.WebHome]]. | ||
| 210 | |||
| 211 | Options: | ||
| 212 | |||
| 213 | |=Name|=Description|=Default Value | ||
| 214 | |name|The name of the form field holding the value|None | ||
| 215 | |value|The initially selected locations, either as a string or as a collection of ##SpaceReference## objects or of serialized references|None | ||
| 216 | |multiple|Whether more than one location can be selected|false | ||
| 217 | |filterHiddenDocuments|Whether hidden pages are left out of the page tree|true | ||
| 218 | |||
| 219 | The ##root##, ##exclusions## and ##sortDocumentsBy## options are passed on to the page tree, as for the ##documentTree## Velocity macro. They are passed as strings, so give ##exclusions## as a comma-separated list of node ids. The other options, such as ##data-search-scope## and ##data-document-reference##, are passed on to the location suggester. | ||
| 220 | {{/version}} | ||
| 221 | |||
| 222 | === Suggest Users === | ||
| 223 | |||
| 224 | 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). | ||
| 225 | |||
| 226 | The users listed are sorted alphabetically based first on their first name and then last names, independently of the case. When no input is specified, all the users from wiki or the farm are matched. The first 10 users that are accessible to the current user are displayed. | ||
| 227 | |||
| 228 | {{code language="none"}} | ||
| 229 | {{velocity}} | ||
| 230 | {{html}} | ||
| 231 | #set ($userPickerParams = { | ||
| 232 | ... | ||
| 233 | }) | ||
| 234 | #userPicker(true, $userPickerParams) | ||
| 235 | {{/html}} | ||
| 236 | {{/velocity}} | ||
| 237 | {{/code}} | ||
| 238 | |||
| 239 | {{image reference="userPicker.png"/}} | ||
| 240 | |||
| 241 | The ##userPicker## macro requires two parameters: the first one indicates whether the picker accepts multiple values or not, and the second one contains complementary configuration parameters: | ||
| 242 | |||
| 243 | |=Name|=Description|=Default Value | ||
| 244 | |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 | ||
| 245 | |||
| 246 | === Suggest Groups === | ||
| 247 | |||
| 248 | 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). | ||
| 249 | |||
| 250 | {{code language="none"}} | ||
| 251 | {{velocity}} | ||
| 252 | {{html}} | ||
| 253 | #set ($groupPickerParams = { | ||
| 254 | ... | ||
| 255 | }) | ||
| 256 | #groupPicker(true, $groupPickerParams) | ||
| 257 | {{/html}} | ||
| 258 | {{/velocity}} | ||
| 259 | {{/code}} | ||
| 260 | |||
| 261 | {{image reference="groupPicker.png"/}} | ||
| 262 | |||
| 263 | Like the ##userPicker## macro, ##groupPicker## requires two parameters: the first one indicates whether the picker accepts multiple values or not, and the second one contains complementary configuration parameters: | ||
| 264 | |||
| 265 | |=Name|=Description|=Default Value | ||
| 266 | |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 | ||
| 267 | |||
| 268 | === Suggest Property Values === | ||
| 269 | |||
| 270 | 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. | ||
| 271 | |||
| 272 | {{code language="none"}} | ||
| 273 | {{velocity}} | ||
| 274 | $doc.display('myDatabaseListProperty') | ||
| 275 | {{/velocity}} | ||
| 276 | {{/code}} | ||
| 277 | |||
| 278 | {{image reference="propertyValuePicker.png"/}} | ||
| 279 | |||
| 280 | If you don't have a property to display then you can also enable this suggester by calling the generic ##suggestInput## macro like this: | ||
| 281 | |||
| 282 | {{code language="none"}} | ||
| 283 | {{velocity}} | ||
| 284 | {{html}} | ||
| 285 | #set ($discard = $xwiki.jsfx.use('uicomponents/suggest/suggestPropertyValues.js', | ||
| 286 | {'forceSkinAction': true, 'language': $xcontext.locale})) | ||
| 287 | #set ($suggestParams = { | ||
| 288 | 'class': 'suggest-propertyValues', | ||
| 289 | 'placeholder': 'Select the movie director', | ||
| 290 | 'data-className': 'Help.Applications.Movies.Code.MoviesClass', | ||
| 291 | 'data-propertyName': 'databaseList1' | ||
| 292 | }) | ||
| 293 | #suggestInput($suggestParams) | ||
| 294 | {{/html}} | ||
| 295 | {{/velocity}} | ||
| 296 | {{/code}} | ||
| 297 | |||
| 298 | If you need tag suggestions then you can use this configuration: | ||
| 299 | |||
| 300 | {{code language="none"}} | ||
| 301 | #set ($suggestParams = { | ||
| 302 | 'class': 'suggest-propertyValues', | ||
| 303 | 'multiple': 'multiple', | ||
| 304 | 'data-className': 'XWiki.TagClass', | ||
| 305 | 'data-propertyName': 'tags' | ||
| 306 | }) | ||
| 307 | {{/code}} | ||
| 308 | |||
| 309 | Custom configuration parameters: | ||
| 310 | |||
| 311 | |=Name|=Description|=Default Value | ||
| 312 | |data-className|The class where the property is defined|None | ||
| 313 | |data-propertyName|The property whose values are to be retrieved as suggestions|None | ||
| 314 | |data-freeText|Whether free text is allowed or forbidden. Possible values are: allowed, forbidden|None | ||
| 315 | |||
| 316 | == Custom Suggesters == | ||
| 317 | |||
| 318 | === Suggest from Static Data === | ||
| 319 | |||
| 320 | 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). | ||
| 321 | |||
| 322 | {{html wiki="true"}} | ||
| 323 | <div> | ||
| 324 | <ul class="nav nav-tabs" role="tablist"> | ||
| 325 | <li role="presentation" class="active"> | ||
| 326 | <a href="#staticDataV1" aria-controls="staticDataV1" role="tab" data-toggle="tab">V1: The Basics</a> | ||
| 327 | </li> | ||
| 328 | <li role="presentation"> | ||
| 329 | <a href="#staticDataV2" aria-controls="staticDataV2" role="tab" data-toggle="tab">V2: Separate Data</a> | ||
| 330 | </li> | ||
| 331 | <li role="presentation"> | ||
| 332 | <a href="#staticDataV3" aria-controls="staticDataV3" role="tab" data-toggle="tab">V3: Helper Macros</a> | ||
| 333 | </li> | ||
| 334 | <li role="presentation"> | ||
| 335 | <a href="#staticDataV4" aria-controls="staticDataV4" role="tab" data-toggle="tab">V4: Reusable Code</a> | ||
| 336 | </li> | ||
| 337 | </ul> | ||
| 338 | |||
| 339 | <div class="tab-content"> | ||
| 340 | <div role="tabpanel" class="tab-pane active" id="staticDataV1"> | ||
| 341 | <p>The following code:</p> | ||
| 342 | |||
| 343 | * loads the resources (JavaScript and CSS) needed by the suggest widget | ||
| 344 | * outputs the HTML (select element) needed by the suggest widget | ||
| 345 | |||
| 346 | <p>Note that the select element is marked with the ##xwiki-selectize## CSS class which activates the suggest widget.</p> | ||
| 347 | |||
| 348 | {{code language="none"}} | ||
| 349 | {{velocity}} | ||
| 350 | #set ($discard = $xwiki.jsfx.use('uicomponents/suggest/xwiki.selectize.js')) | ||
| 351 | {{/velocity}} | ||
| 352 | |||
| 353 | {{html}} | ||
| 354 | <select class="xwiki-selectize"> | ||
| 355 | <option value="">Select the country</option> | ||
| 356 | <option value="fr">France</option> | ||
| 357 | <option value="de">Germany</option> | ||
| 358 | <option value="ro">Romania</option> | ||
| 359 | </select> | ||
| 360 | {{/html}} | ||
| 361 | {{/code}} | ||
| 362 | |||
| 363 | </div> | ||
| 364 | |||
| 365 | <div role="tabpanel" class="tab-pane" id="staticDataV2"> | ||
| 366 | <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> | ||
| 367 | |||
| 368 | {{code language="none"}} | ||
| 369 | {{velocity}} | ||
| 370 | {{html}} | ||
| 371 | #set ($discard = $xwiki.jsfx.use('uicomponents/suggest/xwiki.selectize.js')) | ||
| 372 | #set ($countries = [ | ||
| 373 | {'name': 'France', 'code': 'fr'}, | ||
| 374 | {'name': 'Germany', 'code': 'de'}, | ||
| 375 | {'name': 'Romania', 'code': 'ro'} | ||
| 376 | ]) | ||
| 377 | ## See https://tom-select.js.org/docs/ | ||
| 378 | #set ($selectizeSettings = {}) | ||
| 379 | <select class="xwiki-selectize" data-xwiki-selectize="$escapetool.xml($jsontool.serialize($selectizeSettings))"> | ||
| 380 | <option value="">Select the country</option> | ||
| 381 | #foreach ($country in $countries) | ||
| 382 | <option value="$!escapetool.xml($country.code)">$!escapetool.xml($country.name)</option> | ||
| 383 | #end | ||
| 384 | </select> | ||
| 385 | {{/html}} | ||
| 386 | {{/velocity}} | ||
| 387 | {{/code}} | ||
| 388 | |||
| 389 | </div> | ||
| 390 | |||
| 391 | <div role="tabpanel" class="tab-pane" id="staticDataV3"> | ||
| 392 | <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> | ||
| 393 | |||
| 394 | {{code language="none"}} | ||
| 395 | {{velocity output="false"}} | ||
| 396 | #set ($countries = [ | ||
| 397 | {'name': 'France', 'code': 'fr'}, | ||
| 398 | {'name': 'Germany', 'code': 'de'}, | ||
| 399 | {'name': 'Romania', 'code': 'ro'} | ||
| 400 | ]) | ||
| 401 | |||
| 402 | #macro (countryPicker_displayOptions $selectedValues) | ||
| 403 | #foreach ($country in $countries) | ||
| 404 | <option value="$!escapetool.xml($country.code)"#if ($selectedValues.contains($country.code)) selected="selected"#end | ||
| 405 | >$!escapetool.xml($country.name)</option> | ||
| 406 | #end | ||
| 407 | #end | ||
| 408 | {{/velocity}} | ||
| 409 | |||
| 410 | {{velocity}} | ||
| 411 | {{html}} | ||
| 412 | #picker_import | ||
| 413 | #set ($discard = $xwiki.jsfx.use('uicomponents/suggest/xwiki.selectize.js')) | ||
| 414 | ## See https://tom-select.js.org/docs/ | ||
| 415 | #set ($selectizeSettings = {}) | ||
| 416 | #set ($suggestInputAttributes = { | ||
| 417 | 'name': 'country', | ||
| 418 | 'class': 'xwiki-selectize', | ||
| 419 | 'data-xwiki-selectize': $selectizeSettings, | ||
| 420 | 'value': 'ro', | ||
| 421 | 'placeholder': 'Select the country' | ||
| 422 | }) | ||
| 423 | #suggestInput($suggestInputAttributes 'countryPicker_displayOptions') | ||
| 424 | {{/html}} | ||
| 425 | {{/velocity}} | ||
| 426 | {{/code}} | ||
| 427 | |||
| 428 | </div> | ||
| 429 | |||
| 430 | <div role="tabpanel" class="tab-pane" id="staticDataV4"> | ||
| 431 | <p>In this last version we make the code reusable by creating the ##countryPicker## and ##countryPicker_import## Velocity macros.</p> | ||
| 432 | |||
| 433 | {{code language="none"}} | ||
| 434 | {{velocity output="false"}} | ||
| 435 | #set ($countries = [ | ||
| 436 | {'name': 'France', 'code': 'fr'}, | ||
| 437 | {'name': 'Germany', 'code': 'de'}, | ||
| 438 | {'name': 'Romania', 'code': 'ro'} | ||
| 439 | ]) | ||
| 440 | |||
| 441 | #macro (countryPicker_displayOptions $selectedValues) | ||
| 442 | #foreach ($country in $countries) | ||
| 443 | <option value="$!escapetool.xml($country.code)"#if ($selectedValues.contains($country.code)) selected="selected"#end | ||
| 444 | >$!escapetool.xml($country.name)</option> | ||
| 445 | #end | ||
| 446 | #end | ||
| 447 | |||
| 448 | #macro (countryPicker_import) | ||
| 449 | #picker_import | ||
| 450 | #set ($discard = $xwiki.jsfx.use('uicomponents/suggest/xwiki.selectize.js')) | ||
| 451 | #end | ||
| 452 | |||
| 453 | #macro (countryPicker $parameters) | ||
| 454 | #countryPicker_import | ||
| 455 | #if ("$!parameters" == "") | ||
| 456 | #set ($parameters = {}) | ||
| 457 | #end | ||
| 458 | #set ($discard = $parameters.put('class', "$!parameters.get('class') xwiki-selectize suggest-countries")) | ||
| 459 | #if (!$parameters.containsKey('placeholder')) | ||
| 460 | #set ($parameters.placeholder = 'Select the country') | ||
| 461 | #end | ||
| 462 | #suggestInput($parameters 'countryPicker_displayOptions') | ||
| 463 | #end | ||
| 464 | {{/velocity}} | ||
| 465 | |||
| 466 | {{velocity}} | ||
| 467 | {{html}} | ||
| 468 | #set ($countryPickerParams = { | ||
| 469 | 'name': 'country', | ||
| 470 | 'value': 'ro' | ||
| 471 | }) | ||
| 472 | #countryPicker($countryPickerParams) | ||
| 473 | {{/html}} | ||
| 474 | {{/velocity}} | ||
| 475 | {{/code}} | ||
| 476 | |||
| 477 | </div> | ||
| 478 | </div> | ||
| 479 | </div> | ||
| 480 | {{/html}} | ||
| 481 | |||
| 482 | === Suggest from Remote Data === | ||
| 483 | |||
| 484 | 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. | ||
| 485 | |||
| 486 | {{html wiki="true"}} | ||
| 487 | <div> | ||
| 488 | <ul class="nav nav-tabs" role="tablist"> | ||
| 489 | <li role="presentation" class="active"> | ||
| 490 | <a href="#remoteDataV1" aria-controls="remoteDataV1" role="tab" data-toggle="tab">V1: The Basics</a> | ||
| 491 | </li> | ||
| 492 | <li role="presentation"> | ||
| 493 | <a href="#remoteDataV2" aria-controls="remoteDataV2" role="tab" data-toggle="tab">V2: Reusable Code</a> | ||
| 494 | </li> | ||
| 495 | </ul> | ||
| 496 | |||
| 497 | <div class="tab-content"> | ||
| 498 | <div role="tabpanel" class="tab-pane active" id="remoteDataV1"> | ||
| 499 | <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> | ||
| 500 | |||
| 501 | {{code language="js"}} | ||
| 502 | require.config({ | ||
| 503 | paths: { | ||
| 504 | 'xwiki-selectize': "$xwiki.getSkinFile('uicomponents/suggest/xwiki.selectize.js')" + | ||
| 505 | "?v=$escapetool.url($xwiki.version)" | ||
| 506 | } | ||
| 507 | }); | ||
| 508 | |||
| 509 | require(['jquery', 'xwiki-selectize'], function($) { | ||
| 510 | var settings = { | ||
| 511 | load: function(typedText, callback) { | ||
| 512 | $.getJSON('your/service/url', { | ||
| 513 | text: typedText | ||
| 514 | }).done(callback).fail(callback); | ||
| 515 | }, | ||
| 516 | loadSelected: function(selectedValue, callback) { | ||
| 517 | $.getJSON('your/service/url', { | ||
| 518 | text: selectedValue, | ||
| 519 | exactMatch: true | ||
| 520 | }).done(callback).fail(callback); | ||
| 521 | } | ||
| 522 | }; | ||
| 523 | |||
| 524 | $('.suggest-countries').xwikiSelectize(settings); | ||
| 525 | }); | ||
| 526 | {{/code}} | ||
| 527 | |||
| 528 | {{code language="none"}} | ||
| 529 | {{velocity}} | ||
| 530 | #set ($discard = $xwiki.jsx.use('Path.To.Your.JSX')) | ||
| 531 | {{/velocity}} | ||
| 532 | |||
| 533 | {{html}} | ||
| 534 | <select class="suggest-countries"> | ||
| 535 | <option value="">Select the country</option> | ||
| 536 | </select> | ||
| 537 | {{/html}} | ||
| 538 | {{/code}} | ||
| 539 | |||
| 540 | </div> | ||
| 541 | |||
| 542 | <div role="tabpanel" class="tab-pane" id="remoteDataV2"> | ||
| 543 | <p>In this last version we make the code reusable by creating a jQuery plugin and some helper Velocity macros.</p> | ||
| 544 | |||
| 545 | {{code language="js"}} | ||
| 546 | require.config({ | ||
| 547 | paths: { | ||
| 548 | 'xwiki-selectize': "$xwiki.getSkinFile('uicomponents/suggest/xwiki.selectize.js')" + | ||
| 549 | "?v=$escapetool.url($xwiki.version)" | ||
| 550 | } | ||
| 551 | }); | ||
| 552 | |||
| 553 | define('xwiki-suggestCountries', ['jquery', 'xwiki-selectize'], function($) { | ||
| 554 | var getSettings = function(select) { | ||
| 555 | return { | ||
| 556 | load: function(typedText, callback) { | ||
| 557 | $.getJSON('your/service/url', { | ||
| 558 | text: typedText | ||
| 559 | }).done(callback).fail(callback); | ||
| 560 | }, | ||
| 561 | loadSelected: function(selectedValue, callback) { | ||
| 562 | $.getJSON('your/service/url', { | ||
| 563 | text: selectedValue, | ||
| 564 | exactMatch: true | ||
| 565 | }).done(callback).fail(callback); | ||
| 566 | } | ||
| 567 | }; | ||
| 568 | }; | ||
| 569 | |||
| 570 | $.fn.suggestCountries = function(settings) { | ||
| 571 | return this.each(function() { | ||
| 572 | $(this).xwikiSelectize($.extend(getSettings($(this)), settings)); | ||
| 573 | }); | ||
| 574 | }; | ||
| 575 | }); | ||
| 576 | |||
| 577 | require(['jquery', 'xwiki-suggestCountries', 'xwiki-events-bridge'], function($) { | ||
| 578 | var init = function(event, data) { | ||
| 579 | var container = $((data && data.elements) || document); | ||
| 580 | container.find('.suggest-countries').suggestCountries(); | ||
| 581 | }; | ||
| 582 | |||
| 583 | $(document).on('xwiki:dom:loaded xwiki:dom:updated', init); | ||
| 584 | XWiki.domIsLoaded && init(); | ||
| 585 | }); | ||
| 586 | {{/code}} | ||
| 587 | |||
| 588 | {{code language="none"}} | ||
| 589 | {{velocity output="false"}} | ||
| 590 | #macro (countryPicker_import) | ||
| 591 | #picker_import | ||
| 592 | #set ($discard = $xwiki.jsx.use('Path.To.Your.JSX')) | ||
| 593 | #end | ||
| 594 | |||
| 595 | #macro (countryPicker $parameters) | ||
| 596 | #countryPicker_import | ||
| 597 | #if ("$!parameters" == "") | ||
| 598 | #set ($parameters = {}) | ||
| 599 | #end | ||
| 600 | #set ($discard = $parameters.put('class', "$!parameters.get('class') suggest-countries")) | ||
| 601 | #if (!$parameters.containsKey('placeholder')) | ||
| 602 | #set ($parameters.placeholder = 'Select the country') | ||
| 603 | #end | ||
| 604 | #suggestInput($parameters) | ||
| 605 | #end | ||
| 606 | {{/velocity}} | ||
| 607 | |||
| 608 | {{velocity}} | ||
| 609 | {{html}} | ||
| 610 | #set ($countryPickerParams = { | ||
| 611 | 'name': 'country', | ||
| 612 | 'value': 'ro' | ||
| 613 | }) | ||
| 614 | #countryPicker($countryPickerParams) | ||
| 615 | {{/html}} | ||
| 616 | {{/velocity}} | ||
| 617 | {{/code}} | ||
| 618 | |||
| 619 | </div> | ||
| 620 | </div> | ||
| 621 | </div> | ||
| 622 | {{/html}} | ||
| 623 | |||
| 624 | The remote data should have the following JSON format: | ||
| 625 | |||
| 626 | {{code language="js"}} | ||
| 627 | [ | ||
| 628 | { | ||
| 629 | 'label': '...', | ||
| 630 | 'value': '...', | ||
| 631 | 'url': '...', | ||
| 632 | 'icon': { | ||
| 633 | 'iconSetName': '...', | ||
| 634 | 'iconSetType': 'IMAGE or FONT', | ||
| 635 | 'cssClass': 'for font icons', | ||
| 636 | 'url': 'for image icons' | ||
| 637 | }, | ||
| 638 | 'hint': '...' | ||
| 639 | }, | ||
| 640 | ... | ||
| 641 | ] | ||
| 642 | {{/code}} |
