Wiki source code of Wiki Macro Fields
Last modified by Eleni Cojocariu on 2026/10/12 15:27
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | 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. | ||
| 2 | |||
| 3 | To see these fields filled in, follow [[Write a Macro in a Wiki Page>>doc:documentation.xs.dev.rendering-macros.wiki-macros.write-wiki-macro.WebHome]]. | ||
| 4 | |||
| 5 | == Macro fields == | ||
| 6 | |||
| 7 | The fields of ##XWiki.WikiMacroClass##, in the order the object editor lists them. | ||
| 8 | |||
| 9 | |=Field|=Values|=Default|=What it does | ||
| 10 | |Macro id|text|(none)|The id callers type to invoke the macro, as in ##~{~{hello/~}~}##. | ||
| 11 | |Macro name|text|(none)|The name displayed in the editor's macro picker. | ||
| 12 | |Macro description|text|(none)|A short description, displayed in the editor next to the name. | ||
| 13 | |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>>doc:documentation.xs.dev.rendering-macros.macro-categories.WebHome]]. | ||
| 14 | |Supports inline mode|Yes, No|No|Whether the macro can be used in an inline context, such as inside a sentence. | ||
| 15 | |Macro visibility|##Current User##, ##Current Wiki##, ##Global##|(none)|Who can use the macro, and which rights its author needs. See [[Wiki Macros>>doc:documentation.xs.dev.rendering-macros.wiki-macros.WebHome]]. | ||
| 16 | |Macro content availability|##Optional##, ##Mandatory##, ##No content##|(none)|Whether the macro accepts a body. | ||
| 17 | |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##. | ||
| 18 | |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##. | ||
| 19 | |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. | ||
| 20 | |Priority|integer|1000|The execution order relative to the other macros: the lowest value runs first. | ||
| 21 | |Isolated Execution|Yes, No|No|{{version since="17.3.0RC1,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.{{/version}} | ||
| 22 | |Content order property|integer|(none)|{{version since="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.{{/version}} | ||
| 23 | |Asynchronous rendering|Yes, No|No|Whether the macro result is rendered asynchronously. | ||
| 24 | |Cached|Yes, No|No|Whether the result of an execution is cached. | ||
| 25 | |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. | ||
| 26 | |||
| 27 | == Parameter fields == | ||
| 28 | |||
| 29 | The fields of ##XWiki.WikiMacroParameterClass##. Add one object per parameter. | ||
| 30 | |||
| 31 | |=Field|=Values|=Default|=What it does | ||
| 32 | |Parameter name|text|(none)|The name callers use when they pass the parameter. | ||
| 33 | |Parameter description|text|(none)|A short description, displayed in the editor. | ||
| 34 | |Parameter mandatory|Yes, No|No|When a mandatory parameter is missing, the macro fails to execute. | ||
| 35 | |Parameter default value|text|(none)|The value used when the caller leaves the parameter empty. | ||
| 36 | |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>>doc:documentation.xs.dev.rendering-macros.macro-parameter-pickers.WebHome]], and the ##~{~{wikimacroparameter~}~}## macro needs it to know how to render the value. | ||
| 37 | |Parameter feature|text|(none)|The feature this parameter is bound to. Parameters sharing a feature are a choice, see below. | ||
| 38 | |Parameter group property|text, several allowed|(none)|The group this parameter belongs to. Parameters of one group are displayed together, see below. | ||
| 39 | |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. | ||
| 40 | |Parameter advanced|Yes, No|No|Whether the parameter is emphasized in the macro configuration UI. | ||
| 41 | |Parameter deprecated|Yes, No|No|Marks a parameter that should no longer be used. | ||
| 42 | |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. | ||
| 43 | |Parameter order property|integer|(none)|{{version since="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.{{/version}} | ||
| 44 | |||
| 45 | == Features and groups == | ||
| 46 | |||
| 47 | The two fields organize the parameters of a macro, and they do different things: | ||
| 48 | |||
| 49 | * a **feature** is a choice: the parameters bound to the same feature are mutually exclusive, and a caller uses one of them; | ||
| 50 | * a **group** is a set: the parameters of one group serve the same need, are displayed together, and can be combined. | ||
| 51 | |||
| 52 | 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: | ||
| 53 | |||
| 54 | |=Parameter|=Feature|=Group | ||
| 55 | |##url##|##reference##|(none) | ||
| 56 | |##internalRepresentation##|##reference##|##internalrepresentation## | ||
| 57 | |##internalRepresentationType##|##reference##|##internalrepresentation## | ||
| 58 | |||
| 59 | 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. |
