Wiki source code of Macro Parameter Pickers
Last modified by Lucas Charpentier on 2026/10/14 15:26
Hide last authors
| author | version | line-number | content |
|---|---|---|---|
 |
3.1 | 1 | The ##type## property of an ##XWiki.WikiMacroParameterClass## object says which Java type the value of a parameter, always stored as a String, is converted to. For some types the macro editor replaces the plain text field with a **picker**: a colour swatch, a date field, a page suggest. [[Wiki Macro Fields>>doc:documentation.xs.dev.rendering-macros.wiki-macros.wiki-macro-fields.WebHome]] defines the field itself. |
| 2 | |||
| 3 | {{image reference="macro-parameter-picker.png" size="large" alt="The Edit Macro dialog of a wiki macro, with a colour picker, a date field, a checkbox and a page picker instead of plain text fields"/}} | ||
| 4 | |||
| 5 | == Types with a picker == | ||
| 6 | |||
| 7 | |=Type|=Picker | ||
| 8 | |##org.xwiki.model.reference.AttachmentReference##|Attachment picker | ||
| 9 | |##java.lang.Boolean##|Checkbox | ||
| 10 | |##java.awt.Color##|Color picker | ||
| 11 | |##java.util.Date##|Date picker | ||
| 12 | |##org.xwiki.model.reference.DocumentReference##|Page picker | ||
| 13 | |##org.xwiki.model.reference.EntityReferenceString##|Custom picker for entity references | ||
| 14 | |##org.xwiki.model.EntityType##|Custom picker for entity types | ||
 |
6.2 | 15 | |##java.util.List<org.xwiki.model.reference.SpaceReference>##|{{version since="18.9.0RC1"}}[[Compact location picker>>doc:Documentation.DevGuide.FrontendResources.AutoSuggestWidget.WebHome||anchor="HCompactLocationPicker"]], with multiple selection{{/version}} |
| |
3.1 | 16 | |##org.xwiki.user.UserReference##|User Picker |
| 17 | |||
| 18 | Giving the reference of an existing Java ##Enum## gets a select picker over its values. To build your own set of values, see [[Use your own enum>>||anchor="HUseyourownenum"]] below. | ||
| 19 | |||
| 20 | == How a picker is chosen == | ||
| 21 | |||
| 22 | A picker is an HTML displayer template, not code. For a parameter of a given type, the macro editor displays the parameter in the ##edit## mode and uses the first of these templates that exists: | ||
| 23 | |||
| 24 | 1. ##html_displayer/[type]/[mode].vm## | ||
| 25 | 1. ##html_displayer/[type].vm## | ||
| 26 | 1. ##html_displayer/[mode].vm## | ||
| 27 | 1. ##html_displayer/default.vm## | ||
| 28 | |||
| 29 | How ##[type]## is computed depends on the kind of type: | ||
| 30 | |||
| 31 | * for a class, it is the simple name of the class, lowercased, so ##org.xwiki.model.reference.DocumentReference## is looked up as ##documentreference##. For an ##Enum##, ##enum## is tried after the class name; | ||
| 32 | * for a parameterized type, it is first the fully qualified name, lowercased. {{version since="18.9.0RC1"}}It is then a short name where every class the type is made of is reduced to its simple name.{{/version}} For instance ##java.util.List<org.xwiki.model.reference.SpaceReference>## is looked up as ##java.util.list(org.xwiki.model.reference.spacereference)## and then as ##list(spacereference)##. Since several types can share the same short name, use the fully qualified name to target one precise type. | ||
| 33 | |||
| 34 | The first two templates of the list are tried for each ##[type]## candidate in turn, before falling back to ##html_displayer/[mode].vm##. In those paths, ##<## and ##>## are replaced by parentheses, ##?## is replaced by ##_## and spaces are removed. The edit picker of a ##java.util.List<org.xwiki.model.reference.SpaceReference>## parameter is therefore looked up, in this order, as: | ||
| 35 | |||
| 36 | 1. ##html_displayer/java.util.list(org.xwiki.model.reference.spacereference)/edit.vm## | ||
| 37 | 1. ##html_displayer/java.util.list(org.xwiki.model.reference.spacereference).vm## | ||
| 38 | 1. ##html_displayer/list(spacereference)/edit.vm## | ||
| 39 | 1. ##html_displayer/list(spacereference).vm## | ||
| 40 | 1. ##html_displayer/edit.vm## | ||
| 41 | 1. ##html_displayer/default.vm## | ||
| 42 | |||
| 43 | The templates that ship with XWiki are the {{scm path="xwiki-platform-core/xwiki-platform-web/xwiki-platform-web-templates/src/main/resources/templates/html_displayer"}}pickers implementation{{/scm}}. | ||
| 44 | |||
| 45 | == Use your own enum == | ||
| 46 | |||
| 47 | To display a parameter as a select picker over a fixed set of values, you need a Java ##Enum## available in the wiki whose constants are those values. The example below builds an ##Ascending## and ##Descending## picker for a sort order parameter. | ||
| 48 | |||
| 49 | 1. Write the enum: ((( | ||
| 50 | {{code language="java"}} | ||
| 51 | package your.enum.package; | ||
| 52 | |||
| 53 | public enum SortOrderEnum | ||
| 54 | { | ||
| 55 | asc, | ||
| 56 | desc; | ||
| 57 | } | ||
| 58 | {{/code}} | ||
| 59 | |||
| 60 | {{info}} | ||
| 61 | The constants you choose are the values saved for the parameter, and the values a user edits in the wiki editor, so prefer camelCase over ALL_CAPS. | ||
| 62 | {{/info}} | ||
| 63 | ))) | ||
| 64 | 1. Bundle the enum as a jar and import it into your instance, either by placing it in the ##WEB-INF/lib## directory or through the Extension Manager. | ||
| 65 | 1. Set the parameter type to the fully qualified name of the enum, ##your.enum.package.SortOrderEnum##, on the wiki macro page. The enum picker is then used automatically when the macro parameters are edited. | ||
| 66 | 1. Give each value a readable label. Without translations the picker displays the constants as they are. Create a translation document, as [[Translate a Wiki Macro>>doc:documentation.xs.dev.rendering-macros.wiki-macros.translate-wiki-macro.WebHome]] describes, and key each value by the full name of the enum concatenated with the value. These keys are the enum's own, not the ##rendering.macro.*## keys that name the macro and its parameters: ((( | ||
| 67 | {{code language="plain"}} | ||
| 68 | your.enum.package.SortOrderEnum.asc=Ascending | ||
| 69 | your.enum.package.SortOrderEnum.desc=Descending | ||
| 70 | {{/code}} | ||
| 71 | ))) |
