XWiki Select Widget
Version 13.1 by Guillaume Delhumeau on 2016/01/21
Summary
This widget have the same objective than a regular select box, but with a nice style and with parameters like icons, descriptions, etc...
This is an example of use:
Note that this component needs JavaScript enabled in the browser.
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-tall' or any other class)
- id: (optional) id to give to the widget
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')
{
'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')
Generates:
The generated HTML code is:
<div class="xwiki-select xwiki-select-small">
<div class="xwiki-select-options">
<ul>
<li>Category 1 (2)
<ul>
<li class="xwiki-select-option xwiki-select-option-selected">
<input checked="checked" data-some-data="some-value" id="nameOfTheField_0" name="nameOfTheField" type="radio" value="option1"/>
<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 id="nameOfTheField_1" name="nameOfTheField" type="radio" value="option2"/>
<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>Category 2 (1)
<ul>
<li class="xwiki-select-option">
<input id="nameOfTheField_2" name="nameOfTheField" type="radio" value="option3"/>
<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>
<div class="xwiki-select-options">
<ul>
<li>Category 1 (2)
<ul>
<li class="xwiki-select-option xwiki-select-option-selected">
<input checked="checked" data-some-data="some-value" id="nameOfTheField_0" name="nameOfTheField" type="radio" value="option1"/>
<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 id="nameOfTheField_1" name="nameOfTheField" type="radio" value="option2"/>
<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>Category 2 (1)
<ul>
<li class="xwiki-select-option">
<input id="nameOfTheField_2" name="nameOfTheField" type="radio" value="option3"/>
<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
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:
$('#myXWikiSelectWidget').xwikiSelectWidget('getValue');
// Clear the selection of the widget:
$('#myXWikiSelectWidget').xwikiSelectWidget('clearSelection');
});
// Get the current selected item:
$('#myXWikiSelectWidget').xwikiSelectWidget('getValue');
// Clear the selection of the widget:
$('#myXWikiSelectWidget').xwikiSelectWidget('clearSelection');
});
