Reference

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 defines the field itself.

Types with a picker

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 below.

How a picker is chosen

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:

1. html_displayer/[type]/[mode].vm
2. html_displayer/[type].vm
3. html_displayer/[mode].vm
4. html_displayer/default.vm

How [type] is computed depends on the kind of type:

• 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;
• for a parameterized type, it is first the fully qualified name, lowercased. XWiki 18.9.0+ It is then a short name where every class the type is made of is reduced to its simple name. 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.

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:

1. html_displayer/java.util.list(org.xwiki.model.reference.spacereference)/edit.vm
2. html_displayer/java.util.list(org.xwiki.model.reference.spacereference).vm
3. html_displayer/list(spacereference)/edit.vm
4. html_displayer/list(spacereference).vm
5. html_displayer/edit.vm
6. html_displayer/default.vm

The templates that ship with XWiki are the pickers implementation.

Use your own enum

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.

1. Write the enum:

   package your.enum.package;
   
   public enum SortOrderEnum
   {
       asc,
       desc;
   }

   Information

   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.

2. 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.
3. 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.
4. 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 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:

   your.enum.package.SortOrderEnum.asc=Ascending
   your.enum.package.SortOrderEnum.desc=Descending

FAQ

Why does my parameter still show a plain text field?

No template matched its type, so the lookup fell through to html_displayer/default.vm. Check that the type property holds the fully qualified name of the type, and that one of the candidate templates listed above exists for it.

Can I add a picker without writing Java?

For a fixed set of values, yes: the enum still has to be a Java enum, but the picker itself needs no further code. For a type of your own, the picker is a Velocity template rather than Java code: add an html_displayer template at one of the paths the lookup above tries for that type. XWiki resolves it through the current skin before the templates it ships, so a skin or an extension that ships templates can provide one.

Related

• Rendering Macros
• Wiki Macro Fields
• Wiki Macros