Wiki source code of Icon Picker
Last modified by Eleni Cojocariu on 2026/08/25 16:23
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | The Icon Picker lists the icons of [[the XWiki Icon Set>>doc:documentation.xs.admin.icons.icon-set.WebHome]] under a text field and writes the name of the one that is clicked into it. Attach it to a field with the ##iconPicker## macro, as [[Add an Icon Picker>>doc:documentation.xs.dev.icons.add-icon-picker.WebHome]] does, or with the jQuery plugin the macro itself calls. | ||
| 2 | |||
| 3 | == The iconPicker macro == | ||
| 4 | |||
| 5 | |=Parameter|=Description | ||
| 6 | |##id##|//(optional)// The DOM id of the input field the picker applies to. | ||
| 7 | |##class##|//(optional)// The CSS class of the input fields the picker applies to. | ||
| 8 | |##prefix##|//(optional)// The text the chosen icon name is written behind. Left out, the plugin's own default applies. | ||
| 9 | |||
| 10 | The macro takes no content, works inline, and applies to an ##id##, a ##class##, or both at once. It also pulls in the picker's stylesheet and the resources of every theme, so that each one can be previewed: | ||
| 11 | |||
| 12 | {{code language="none"}} | ||
| 13 | {{html}} | ||
| 14 | <p>Field 1: <input type="text" id="myPicker"/></p> | ||
| 15 | <p>Field 2: <input type="text" class="fieldWithPicker"/></p> | ||
| 16 | {{/html}} | ||
| 17 | |||
| 18 | {{iconPicker id="myPicker" class="fieldWithPicker" prefix="image:icon:"/}} | ||
| 19 | {{/code}} | ||
| 20 | |||
| 21 | == The jQuery plugin == | ||
| 22 | |||
| 23 | The plugin is published by the ##IconThemesCode.IconPicker## page as a JavaScript Extension, and calling it directly is only worth it when your own JavaScript creates the fields. The resources the macro pulls in then have to be asked for as well: | ||
| 24 | |||
| 25 | {{code language="velocity"}} | ||
| 26 | {{velocity output="false"}} | ||
| 27 | $xwiki.ssx.use('IconThemesCode.IconPicker') | ||
| 28 | #foreach ($iconSetName in $services.icon.iconSetNames) | ||
| 29 | $services.icon.use($iconSetName) | ||
| 30 | #end | ||
| 31 | {{/velocity}} | ||
| 32 | |||
| 33 | {{velocity}} | ||
| 34 | {{html clean="false"}} | ||
| 35 | <script> | ||
| 36 | require.config({ | ||
| 37 | paths: { | ||
| 38 | 'xwiki-icon-picker': '$xwiki.getURL($services.model.createDocumentReference('', 'IconThemesCode', 'IconPicker'), 'jsx', "minify=$!{escapetool.url($request.minify)}")' | ||
| 39 | } | ||
| 40 | }); | ||
| 41 | require(['jquery', 'xwiki-icon-picker'], function($) { | ||
| 42 | $('#someField').xwikiIconPicker({prefix: 'image:icon:'}); | ||
| 43 | }); | ||
| 44 | </script> | ||
| 45 | {{/html}} | ||
| 46 | {{/velocity}} | ||
| 47 | {{/code}} | ||
| 48 | |||
| 49 | ##xwikiIconPicker## takes one option, ##prefix##, whose default value has the two halves of {{code language="none"}}image:icon:{{/code}} the wrong way round, so pass it rather than rely on it. The plugin ignores every element that is not an ##input##, opens the picker when one of them takes the focus, and closes it when both the field and the picker have lost it. | ||
| 50 | |||
| 51 | == What the picker shows == | ||
| 52 | |||
| 53 | * the icons of one theme at a time, listed by their Icon Set names in alphabetical order | ||
| 54 | * a "Preview with:" selector holding every Icon Theme of the wiki, so a name can be checked against the theme that will draw it | ||
| 55 | * only the names containing what the field already holds, which is how a list of several hundred is narrowed | ||
| 56 | |||
| 57 | One picker exists at a time: focusing another field closes the one that is open. |
