Reference

The classPicker Velocity macro outputs a form field for picking one or more XWiki Classes. It renders a select element that the suggest widget turns into a searchable drop-down list. The class and object editors use it to switch to another class and to choose the class of a new object.

Signature

#classPicker($parameters)

$parameters is a map. It is optional: an empty or missing map gives a single-selection picker with no name. The macro adds entries to the map you pass, so pass a new map on each call.

Parameters

The drop-down list is a Tom Select widget.

Most entries become HTML attributes of the select element. A value that is not a String is serialized as JSON.

Displayed Classes

The drop-down list shows every class of the current wiki that the current user can view, plus the classes of value. Classes are grouped by location: each group is labeled with the space path of its classes, such as XWiki or Help / Applications / Movies / Code. Each option shows the plain title of the class page. Typing in the field filters the list.

Submitted Value

The field is a standard select element, so the form submits it like any other field. The value of each selected class is its local page reference, without the wiki: Help.Applications.Movies.Code.MoviesClass, for instance. With multiple, the form submits one name parameter per selected class, plus the empty one from the hidden field. The field also fires a change event when the selection changes.

Required Resources

The macro loads its resources itself, through #classPicker_import. Call #classPicker_import alone when you write the select element yourself.

• #classPicker_import loads uicomponents/suggest/xwiki.selectize.js through the skin action, because the file contains Velocity code.
• That script defines the xwiki-selectize RequireJS module. The module loads Tom Select and two stylesheets: tom-select.bootstrap4.min.css and uicomponents/suggest/xwiki.selectize.css.
• The script activates every element with the xwiki-selectize CSS class when the page loads and on each xwiki:dom:updated event. Fire this event after you insert a picker with JavaScript.
• The suggest-classes styles (a 400px high drop-down list, an inline field) live in js/xwiki/editors/dataeditors.css. Only the class and object editors load this file, so load it with $xwiki.ssfx.use if you want the same look.

Example

The object editor displays its "Select a Class" field with the following parameters. Wrap them in the velocity and html macros to use them in a wiki page:

{{velocity}}
{{html}}
#set ($classPickerParameters = {
  'id': 'classname',
  'name': 'classname',
  'placeholder': $services.localization.render('core.editors.object.add.selectClass'),
  'data-xwiki-selectize': {
    'copyClassesToDropdown': true,
    'takeInputWidth': true
  }
})
#classPicker($classPickerParameters)
{{/html}}
{{/velocity}}

The macro outputs the following HTML, shortened to one group and one option, with the attribute values unescaped for readability:

<select id='classname' name='classname'
    data-xwiki-selectize='{"copyClassesToDropdown":true,"takeInputWidth":true,"maxOptions":null}'
    class=' xwiki-selectize suggest-classes' title='Pick a class.' size='1'>
  <option value="">Select a Class</option>
  <optgroup label="Help / Applications / Movies / Code">
    <option value="Help.Applications.Movies.Code.MoviesClass"
        data-data='{"url":"\/xwiki\/bin\/view\/Help\/Applications\/Movies\/Code\/MoviesClass"}'>
      Movies Class
    </option>
  </optgroup>
</select>

Related

• Suggest Widget (for Developers)
• Edit a Page with the Class Editor (for Users)