Wiki Macro Fields
Reference
A wiki macro is described by two XClasses: XWiki.WikiMacroClass, which declares the macro itself, and XWiki.WikiMacroParameterClass, which declares one of its parameters. This page lists every field of both, under the name the object editor shows.
To see these fields filled in, follow Write a Macro in a Wiki Page.
Macro fields
The fields of XWiki.WikiMacroClass, in the order the object editor lists them.
| Field | Values | Default | What it does |
|---|---|---|---|
| Macro id | text | (none) | The id callers type to invoke the macro, as in {{hello/}}. |
| Macro name | text | (none) | The name displayed in the editor's macro picker. |
| Macro description | text | (none) | A short description, displayed in the editor next to the name. |
| Default categories | one or more categories | (none) | The categories the macro is listed under in the macro picker. The field suggests the categories the wiki knows, listed in Macro Categories. |
| Supports inline mode | Yes, No | No | Whether the macro can be used in an inline context, such as inside a sentence. |
| Macro visibility | Current User, Current Wiki, Global | (none) | Who can use the macro, and which rights its author needs. See Wiki Macros. |
| Macro content availability | Optional, Mandatory, No content | (none) | Whether the macro accepts a body. |
| Macro content type | Unknown, Wiki, or a Java type | Unknown | How the body is handled: Wiki parses it as wiki content, Unknown passes it as plain text, and a Java type such as java.util.List<java.lang.String> converts it. Leaving the field empty is the same as Unknown. |
| Content description | text | (none) | A short description of the body, displayed in the editor. It does not apply when the content availability is No content. |
| Macro code | wiki content | (none) | The content evaluated every time the macro runs. Write it in the same syntax as the page that holds it. |
| Priority | integer | 1000 | The execution order relative to the other macros: the lowest value runs first. |
| Isolated Execution | Yes, No | No | XWiki 17.3.0+, 16.10.9+ Set it when the execution of the macro does not modify the XDOM, including through the macros it executes. Reading the XDOM, and reading or writing other context information, still counts as isolated. Marking a macro isolated speeds its execution up. |
| Content order property | integer | (none) | XWiki 17.5.0+ Where the body is displayed in the macro configuration UI. A lower value comes first, and -1 means no value. It is computed together with the parameter order. |
| Asynchronous rendering | Yes, No | No | Whether the macro result is rendered asynchronously. |
| Cached | Yes, No | No | Whether the result of an execution is cached. |
| Context elements | one or more context entries | (none) | The context information the macro needs while it executes, such as the current user or the current document. It is also what the cache key is built from. |
Parameter fields
The fields of XWiki.WikiMacroParameterClass. Add one object per parameter.
| Field | Values | Default | What it does |
|---|---|---|---|
| Parameter name | text | (none) | The name callers use when they pass the parameter. |
| Parameter description | text | (none) | A short description, displayed in the editor. |
| Parameter mandatory | Yes, No | No | When a mandatory parameter is missing, the macro fails to execute. |
| Parameter default value | text | (none) | The value used when the caller leaves the parameter empty. |
| Parameter type | Unknown, Wiki, or a Java type | Unknown | Which Java type the value is converted to: Wiki for wiki content, Unknown for plain text, or a type such as java.util.List<java.lang.String>. The type also decides which widget the editor shows, see Macro Parameter Pickers, and the {{wikimacroparameter}} macro needs it to know how to render the value. |
| Parameter feature | text | (none) | The feature this parameter is bound to. Parameters sharing a feature are a choice, see below. |
| Parameter group property | text, several allowed | (none) | The group this parameter belongs to. Parameters of one group are displayed together, see below. |
| Parameter hidden | Yes, No | No | Set it to hide the parameter from the macro configuration UI. A hidden parameter is still displayed when it has a value. |
| Parameter advanced | Yes, No | No | Whether the parameter is emphasized in the macro configuration UI. |
| Parameter deprecated | Yes, No | No | Marks a parameter that should no longer be used. |
| Parameter feature mandatory | Yes, No | No | The parameter itself can stay optional while its feature is mandatory, meaning at least one parameter of that feature has to be used. |
| Parameter order property | integer | (none) | XWiki 17.5.0+ Where the parameter is displayed in the macro configuration UI. A lower value comes first, and -1 means no value. It is computed together with the content order. |
Features and groups
The two fields organize the parameters of a macro, and they do different things:
- a feature is a choice: the parameters bound to the same feature are mutually exclusive, and a caller uses one of them;
- a group is a set: the parameters of one group serve the same need, are displayed together, and can be combined.
The two can be mixed. A macro that takes a reference either as a URL or as an internal representation, which is a string plus the type of that string, declares three parameters:
| Parameter | Feature | Group |
|---|---|---|
| url | reference | (none) |
| internalRepresentation | reference | internalrepresentation |
| internalRepresentationType | reference | internalrepresentation |
The group is what makes the last two travel together as one side of the choice. "Parameter feature mandatory" then states that one side has to be used, even though each parameter is optional on its own.
FAQ
What does an empty type field mean?
Unknown, which is the default of both "Macro content type" and "Parameter type". The value is then passed on as plain text.
Why does my parameter not appear in the macro editor?
Check "Parameter hidden", which removes it from the macro configuration UI, and "Parameter order property", which may have pushed it to the end of the form.
