XWiki Select Widget
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 is an example of use:
Since 8.4-rc-1, we could also have a filter input:
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' (), 'xwiki-select-tall' or any other class)
- id: (optional) id to give to the widget
- enableFilter: (optional) enable the filtering of the options
Example of use
{
'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:
The generated HTML code is:
<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):
// 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
When an XWiki Select Widget is used on the page, you can control it thanks to a jQuery plugin.
Example of use:
// Get the current selected item:
var value = $('#myWidget').xwikiSelectWidget('getValue');
// Clear the selection of the widget:
$('#myWidget').xwikiSelectWidget('clearSelection');
});
