Wiki source code of XWiki Select Widget

Last modified by Thomas Mortagne on 2023/10/10

version	line-number	content
19.1	1	{{toc/}}
16.1	2
1.1	3	= Summary =
3.1	4
27.5	5	This widget has the same objective as a regular select box, but with a nice style and with parameters like icons, descriptions, etc...
1.1	6
11.1	7	{{info}}
19.1	8	This widget is available since XWiki 7.2. and requires JavaScript enabled in the browser.
11.1	9	{{/info}}
	10
1.1	11	This is an example of use:
	12
3.1	13	{{image reference="xwiki-select.png"/}}
1.1	14
19.1	15	Since 8.4-rc-1, we could also have a filter input:
9.1	16
19.1	17	{{image reference="xwiki-select-filter.png"/}}
	18
1.1	19	= How to use =
3.1	20
4.1	21	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.
1.1	22
4.1	23	You just need to call the ###xwikiSelect()## macro with the following parameters:
1.1	24
	25	* //fieldName//: name of the input field
	26	* //options//: an array of maps describing a category of options, which contains an array of options (see example)
	27	* //defaultValue//: the default value to use (could be null)
4.1	28	* //firstIsDefaultIfDefaultNull//: either if //defaultValue// is null, select the first option or not
27.1	29	* //cssClass//: (optional) class to add to the div (could be '##xwiki-select-small##', '##xwiki-select-medium##', '##xwiki-select-adaptable-medium##' ({{info}}since 8.4.2{{/info}}), '##xwiki-select-tall##' or any other class)
11.1	30	* //id//: {{info}}Since 7.4.1{{/info}} (optional) id to give to the widget
22.1	31	* //enableFilter//: {{info}}Since 8.4-rc-1{{/info}} (optional) enable the filtering of the options
1.1	32
	33	= Example of use =
3.1	34
5.1	35	{{code language="plain"}}
1.1	36	#set($options = [
	37	{
	38	'name': 'Category 1',
	39	'options': [
	40	{ 'name': 'Option 1', 'value': 'option1', 'description': 'Description of the option 1', 'icon': 'wiki', 'data': {'some-data': 'some-value'}},
	41	{ 'name': 'Option 2', 'value': 'option2', 'description': 'Description of the option 2', 'icon': 'page'}
	42	]
	43	},
	44	{
	45	'name': 'Category 2',
	46	'options': [
	47	{ 'name': 'Option 3', 'value': 'option3', 'description': 'Description of the option 3', 'icon': 'check'}
	48	]
	49	}
	50	])
24.1	51	#xwikiSelect('nameOfTheField', $options, 'option1', false, 'xwiki-select-small', 'mySelectWidget', true)
1.1	52	{{/code}}
7.1	53
	54	Generates:
	55
	56	{{image reference="example.png"/}}
8.1	57
	58	The generated HTML code is:
	59
	60	{{code language="html"}}
25.1	61	<div class="xwiki-select xwiki-select-small" id="mySelectWidget">
	62	<p><input class="xwiki-select-filter" placeholder="Type to filter..." type="text"></p>
8.1	63	<div class="xwiki-select-options">
	64	<ul>
25.1	65	<li class="xwiki-select-category">
	66	Category 1 (<span class="xwiki-select-category-count">2</span>)
8.1	67	<ul>
	68	<li class="xwiki-select-option xwiki-select-option-selected">
25.1	69	<input name="nameOfTheField" value="option1" id="nameOfTheField_0" checked="checked" data-some-data="some-value" type="radio">
8.1	70	<span class="xwiki-select-option-icon"><span class="fa fa-globe"></span></span>
	71	<div>
	72	<label for="nameOfTheField_0">Option 1</label>
	73	<p class="xHint">Description of the option 1</p>
	74	</div>
	75	</li>
25.1	76	<li class="xwiki-select-option ">
	77	<input name="nameOfTheField" value="option2" id="nameOfTheField_1" type="radio">
8.1	78	<span class="xwiki-select-option-icon"><span class="fa fa-file"></span></span>
	79	<div>
	80	<label for="nameOfTheField_1">Option 2</label>
	81	<p class="xHint">Description of the option 2</p>
	82	</div>
	83	</li>
	84	</ul>
	85	</li>
25.1	86	<li class="xwiki-select-category">
	87	Category 2 (<span class="xwiki-select-category-count">1</span>)
8.1	88	<ul>
25.1	89	<li class="xwiki-select-option ">
	90	<input name="nameOfTheField" value="option3" id="nameOfTheField_2" type="radio">
8.1	91	<span class="xwiki-select-option-icon"><span class="fa fa-check"></span></span>
	92	<div>
	93	<label for="nameOfTheField_2">Option 3</label>
	94	<p class="xHint">Description of the option 3</p>
	95	</div>
	96	</li>
	97	</ul>
	98	</li>
	99	</ul>
	100	</div>
	101	</div>
	102	{{/code}}
	103
	104	Note the presence of the ##data-some-data## attribute in the first input, as specified in the previous ##$options## variable.
11.1	105
17.1	106	= JavaScript API =
11.1	107
17.1	108	== Events ==
	109
	110	When the selection changed, the event ##xwiki:select:updated## is triggered.
	111
	112	Example of use (using jQuery):
	113
	114	{{code language="javascript"}}
	115	require(['jquery'], function ($) {
	116	// Listen the event triggered when the selection of the widget changes
	117	$('#myWidget').on('xwiki:select:updated', function(event, data) {
	118	// do something...
	119	});
	120	});
	121	{{/code}}
	122
28.1	123	See [[Documentation.DevGuide.JavaScriptAPI]] to have more infos about events handling in XWiki.
17.1	124
	125	== jQuery Plugin {{info}}(Since 7.4.1){{/info}} ==
	126
11.1	127	When an XWiki Select Widget is used on the page, you can control it thanks to a jQuery plugin.
	128
	129	Example of use:
	130
	131	{{code language="javascript"}}
	132	require(['jquery'], function ($) {
	133	// Get the current selected item:
14.1	134	var value = $('#myWidget').xwikiSelectWidget('getValue');
11.1	135	// Clear the selection of the widget:
14.1	136	$('#myWidget').xwikiSelectWidget('clearSelection');
11.1	137	});
	138	{{/code}}

Wiki source code of XWiki Select Widget

Quick Links

Navigation

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected