iconPicker
Audit
- Macro ID
- iconPicker
- Source
- XS
- Type
- Generator
- Classification reason
- The macro has no content and its output is an invisible script that applies the icon picker to the input fields that its id or class names, so most of its output comes from its parameters and the page around it, like id.
- Status
- Reviewed
- Criteria version
- 15.20
- XWiki version
- 18.8.0
- Audit date
- 2026-10-20
- Auditor
- Compared macros
- attachmentGalleryPicker displayIcon
Lucas CharpentierSources
Where to gather the information the criteria are checked against, see Gather the sources.
| Other sources specific to this macro |
|---|
|
of the description.| Criterion | Result | Notes |
|---|---|---|
| D1 wording | OK | "Icon Picker" is plain words and a user looking for an icon finds it by its name. A user who types "icon" gets it only at rank 32, after the two Icon entries of displayIcon, so no developer widget comes before the entry that does what the user searched for. |
| D2 summary | KO | "Select an icon within the XWiki icon set." describes what the picker does once it is on a field, not what the macro adds to the page: it adds nothing visible, it only turns existing input fields into icon pickers by their id or CSS class. It also uses "icon set", the historical name of what the administration calls an Icon Theme. To reproduce: open the Insert Macro dialog and select Icon Picker. |
| D3 category | OK | the macro is in the Development category, like attachmentGalleryPicker, the other picker widget that a script wires to the page. displayIcon is in a user category, where users look for the icon they want to display, which is not the use of this macro. |
| D4 quick-action | KO | Quick Actions finds the macro first for "iconPicker", "Icon Picker" and the French name "Sélecteur d'icônes". The synonym "icon" finds it only at rank 32, after Icon, Icon, Content, Embed content, Include Page and the other entries, and "icon selector", "icon chooser", "symbol" and "glyph" give no result. The Insert Macro dialog finds "Icon Picker" and "icon set" but not the ID, which is generic, see XWIKI-20230. |
| L1 consistency | OK | compared with attachmentGalleryPicker and displayIcon. Like both, no parameter is mandatory, there is no content, and the Quick Action inserts the macro right away with no dialog. All three are generators with their own parameters, so the differences are by design. |
| L2 doc-parameters | KO | the documentation is the legacy page of the Icon Theme Application on extensions.xwiki.org, not the new documentation tree. It has no parameter table: id and class are only mentioned in the text, and prefix is not documented. Its default for prefix, " is not the real one, see prefix C3. |
| L3 doc-example | KO | neither the legacy page nor any other documentation has an example that calls the macro. The only sample is on the page of the macro itself, {{iconPicker id="myPicker" class="fieldWithPicker" prefix="icon:" /}} , which no documentation shows. The example used for the audit is the most frequent call in XWiki Standard, {{iconPicker id="XWiki.TemplateProviderClass_0_icon" prefix="" /}} , in TemplateProviderSheet and in AppWithinMinutes TemplateProviderEditSheet, against one call with id="applicationIcon" prefix="icon:" in LiveTableEditSheet. |
| I1 pattern | OK | compared with children, the reference generator: both are inserted by their Quick Action without a dialog, and through the Insert Macro dialog with fields that are all optional. Nothing is macro-specific. |
| I2 zero-config | KO | Quick Actions and the Edit Macro dialog submitted with the default values insert {{iconPicker/}} . View mode shows nothing and no error, since without an id or a class the macro renders an empty script, and the editor shows only the generic placeholder, so nothing tells the user that the macro does nothing until it is configured. To reproduce: insert Icon Picker from Quick Actions and save. |
| I3 instant | N/A | |
| I4 cursor | N/A | |
| I5 focus | KO | the macro has no mandatory parameter, but it does nothing without an id or a class, and neither the dialog nor the descriptor says so. The three fields are visible without scrolling and the focus is on Class, which is the field the examples of XWiki Standard never set. Essential parameters that are not mandatory are a KO, like the server fields of jira. |
| E1 wysiwyg | KO | the editor shows only the generic "macro:iconPicker" placeholder, while the macro has no visible output in view mode either: the placeholder does not say that the macro turns the input fields of the page into icon pickers, nor which fields. To reproduce: insert {{iconPicker id="XWiki.TemplateProviderClass_0_icon" prefix="" /}} , see XWIKI-23036. |
| E2 errors | KO | invalid values are accepted silently, and the macro renders nothing when it has no target. {{iconPicker id="my id"/}} renders the selector #my\ id with no message, {{iconPicker class="a b"/}} renders .a\ b, and {{iconPicker/}} , {{iconPicker id=""/}} and {{iconPicker prefix="icon"/}} render an empty script, so no picker is applied and no message explains why. The source is the Velocity of the wiki macro, which tests only that the id or the class is not empty. An unknown parameter is generic, not recorded. |
| E3 nesting | OK | in a list item, a table cell and a box, the macro renders with no error in the editor and in view mode, and the picker script applies to the target field like at the top level of the page. |
| E4 inline-support | OK | the macro declares inline support, and in the middle of a sentence it renders inline with no block element and no error: its only output is a script. |
| E5 empty | N/A | |
| E6 inplace | N/A |
Parameters
| Parameter | C1 clarity | C2 mandatory | C3 defaults | C4 input-assistance | C5 groups | C6 order | C7 alternatives | C8 advanced | C9 technical | C13 constraints | Notes |
|---|---|---|---|---|---|---|---|---|---|---|---|
| id | OK | OK | OK | OK | OK | OK | KO | OK | OK | KO | C1: "DOM id of the input field where the picker will apply to" says what the id is for and what it targets, which is enough for a developer macro. It does not say that nothing happens when neither the id nor the class is set, which I5 covers. C7: id and class are two ways to name the field that gets the picker, and the macro does nothing without one of them, but the dialog presents them as two unrelated optional fields and requires neither. To reproduce: insert {{iconPicker/}} from the Insert Macro dialog. C13, minor: the id is any text, and {{iconPicker id="my id"/}} is accepted and escaped into the selector #my\ id, which matches no field, with no message. An id with no space is the format a DOM id must have. C6: the dialog lists Class, Id and Prefix, while the calls of XWiki Standard set id and prefix and never class. The three fields are visible without scrolling and in any order they are as easy to reach, so this is OK. |
| class | OK | OK | OK | OK | OK | OK | KO | KO | OK | KO | C1: "CSS class of inputs where the picker will apply to" says what the class targets, which is enough for a developer macro, with a single class name and no dot. C7: see id, the class is the other way to name the fields that get the picker, and neither of them is required by the dialog. C8, minor: no call of XWiki Standard sets class, only the sample on the page of the macro does, and it is not marked as advanced. C13, minor: the class is a single class name, and {{iconPicker class="a b"/}} is accepted and escaped into the selector .a\ b, which matches no field, with no message. |
| prefix | KO | OK | KO | OK | OK | OK | N/A | OK | OK | OK | C1, minor: the description does not say that an empty value means no prefix at all, which is the value both calls of TemplateProviderSheet and TemplateProviderEditSheet use, and it states a default, " C3: the field opens empty and the description gives the default " |
KOs and tickets
Every KO needs a ticket covering it, see Report the KOs. One ticket can cover several KOs. Known issues filed for this macro are suggested in italics: link them as existing tickets when they cover the KO.
| KO | Criterion | Existing tickets | New tickets |
|---|---|---|---|
| D2 | D2 summary | XWIKI-25485 | |
| D4 | D4 quick-action | XWIKI-25444 | |
| L2 | L2 doc-parameters | XINFRA-525 | |
| L3 | L3 doc-example | XINFRA-526 | |
| I2 | I2 zero-config | XWIKI-25513 | |
| I5 | I5 focus | XWIKI-25486 | |
| E1 | E1 wysiwyg | XWIKI-25536 | |
| E2 | E2 errors | XWIKI-25197 (partial) | XCOMMONS-3847 (partial), XRENDERING-823 (partial), XWIKI-25486 (partial) |
| C7:id | C7 alternatives, id | XWIKI-25486 | |
| C13:id | C13 constraints, id | XWIKI-25197 | |
| C7:class | C7 alternatives, class | XWIKI-25486 | |
| C8:class | C8 advanced, class | XWIKI-25486 | |
| C13:class | C13 constraints, class | XWIKI-25197 | |
| C1:prefix | C1 clarity, prefix | XWIKI-25485 | |
| C3:prefix | C3 defaults, prefix | XWIKI-25486 |
Tickets
| Ticket | Origin | KOs covered | KOs partly covered |
|---|---|---|---|
| XWIKI-25197 | Existing | C13:class C13:id | E2 |
| XCOMMONS-3847 | New | E2 | |
| XRENDERING-823 | New | E2 | |
| XWIKI-25444 | New | D4 | |
| XWIKI-25485 | New | C1:prefix D2 | |
| XWIKI-25486 | New | C3:prefix C8:class C7:id C7:class I5 | E2 |
| XINFRA-525 | New | L2 | |
| XINFRA-526 | New | L3 | |
| XWIKI-25513 | New | I2 | |
| XWIKI-25536 | New | E1 |
Known issues of this macro
No known issue is specific to this macro.
68 more known issues affect every macro: see the Known issues.
