Summary

This widget has the same objective as a regular select box, but with a nice style and with parameters like icons, descriptions, etc...

This widget is available since XWiki 7.2. and requires JavaScript enabled in the browser.

This is an example of use:

xwiki-select.png

Since 8.4-rc-1, we could also have a filter input:

xwiki-select-filter.png

How to use

This component is usable in any Wiki page or Velocity template. For a wiki page, you need to be both inside a {{velocity}} and a {{html}} macros.

You just need to call the #xwikiSelect() macro with the following parameters:

  • fieldName: name of the input field
  • options: an array of maps describing a category of options, which contains an array of options (see example)
  • defaultValue: the default value to use (could be null)
  • firstIsDefaultIfDefaultNull: either if defaultValue is null, select the first option or not
  • cssClass: (optional) class to add to the div (could be 'xwiki-select-small', 'xwiki-select-medium', 'xwiki-select-adaptable-medium' (since 8.4.2), 'xwiki-select-tall' or any other class)
  • id: Since 7.4.1 (optional) id to give to the widget
  • enableFilter: Since 8.4-rc-1 (optional) enable the filtering of the options

Example of use

#set($options = [
                   {
                     'name': 'Category 1',
                     'options': [
                       { 'name': 'Option 1', 'value': 'option1', 'description': 'Description of the option 1', 'icon': 'wiki', 'data': {'some-data': 'some-value'}},
                       { 'name': 'Option 2', 'value': 'option2', 'description': 'Description of the option 2', 'icon': 'page'}
                     ]
                   },
                   {
                     'name': 'Category 2',
                     'options': [
                       { 'name': 'Option 3', 'value': 'option3', 'description': 'Description of the option 3', 'icon': 'check'}
                     ]
                   }
                 ])
#xwikiSelect('nameOfTheField', $options, 'option1', false, 'xwiki-select-small', 'mySelectWidget', true)

Generates:

example.png

The generated HTML code is:

<div class="xwiki-select xwiki-select-small" id="mySelectWidget">
  <p><input class="xwiki-select-filter" placeholder="Type to filter..." type="text"></p>
  <div class="xwiki-select-options">
    <ul>
      <li class="xwiki-select-category">
        Category 1 (<span class="xwiki-select-category-count">2</span>)
        <ul>
          <li class="xwiki-select-option xwiki-select-option-selected">
            <input name="nameOfTheField" value="option1" id="nameOfTheField_0" checked="checked" data-some-data="some-value" type="radio">
            <span class="xwiki-select-option-icon"><span class="fa fa-globe"></span></span>
            <div>
              <label for="nameOfTheField_0">Option 1</label>
              <p class="xHint">Description of the option 1</p>
            </div>
          </li>
          <li class="xwiki-select-option ">
            <input name="nameOfTheField" value="option2" id="nameOfTheField_1" type="radio">
            <span class="xwiki-select-option-icon"><span class="fa fa-file"></span></span>
            <div>
              <label for="nameOfTheField_1">Option 2</label>
              <p class="xHint">Description of the option 2</p>
            </div>
          </li>
        </ul>
      </li>
      <li class="xwiki-select-category">
        Category 2 (<span class="xwiki-select-category-count">1</span>)
        <ul>
          <li class="xwiki-select-option ">
            <input name="nameOfTheField" value="option3" id="nameOfTheField_2" type="radio">
            <span class="xwiki-select-option-icon"><span class="fa fa-check"></span></span>
            <div>
              <label for="nameOfTheField_2">Option 3</label>
              <p class="xHint">Description of the option 3</p>
            </div>
          </li>
        </ul>
      </li>
    </ul>
  </div>
</div>

Note the presence of the data-some-data attribute in the first input, as specified in the previous $options variable.

JavaScript API

Events

When the selection changed, the event xwiki:select:updated is triggered.

Example of use (using jQuery):

require(['jquery'], function ($) {
 // Listen the event triggered when the selection of the widget changes
 $('#myWidget').on('xwiki:select:updated', function(event, data) {
   // do something...
 });
});

See JavaScriptAPI to have more infos about events handling in XWiki.

jQuery Plugin (Since 7.4.1)

When an XWiki Select Widget is used on the page, you can control it thanks to a jQuery plugin.

Example of use:

require(['jquery'], function ($) {
 // Get the current selected item:
 var value = $('#myWidget').xwikiSelectWidget('getValue');
 // Clear the selection of the widget:
 $('#myWidget').xwikiSelectWidget('clearSelection');
});
Tags:
Created by Vincent Massol on 2017/09/04
   

Get Connected