Macro Categories
Reference
A macro category groups a macro with its peers in the macro picker of the editors. XWiki defines seven categories, and a new macro should use one of them rather than introduce a category of its own.
The default categories
The second column is the translation key that supplies the label the category is displayed under.
| Category | Translation key |
|---|---|
| Content | rendering.macroCategory.Content |
| Development | rendering.macroCategory.Development |
| Formatting | rendering.macroCategory.Formatting |
| Internal | rendering.macroCategory.Internal |
| Layout | rendering.macroCategory.Layout |
| Navigation | rendering.macroCategory.Navigation |
| Deprecated | rendering.macroCategory.Deprecated |
Choosing the categories of a macro
A Java macro declares its categories in its own code, where the seven values above are available as the DEFAULT_CATEGORY_* constants of org.xwiki.rendering.macro.AbstractMacro. Use the constants rather than string literals, so that a macro cannot end up in a category of its own through a typo.
A wiki macro declares them in its "Default categories" field, which Wiki Macro Fields describes.
Renaming and hiding categories
An instance can relabel a category by overriding its translation key from the table above, and it can hide a category from the macro picker. Internal and Deprecated are hidden by default.
Both are set in xwiki.properties: rendering.transformation.macro.hiddenCategories lists the hidden categories, and rendering.transformation.macro.categories overrides the categories of a given macro, as in toc = My Category\,Deprecated, the comma escaped because the value is a list. Category names are case sensitive. See Macros categories and visibility for the configuration itself.
FAQ
Can a macro be in more than one category?
Yes. Both the "Default categories" field of a wiki macro and the categories of a Java macro are a list, so a macro that serves two purposes is listed under both.
Why is my macro missing from the macro picker?
Check its categories: a macro whose only category is hidden, Internal and Deprecated being hidden by default, is not offered in the picker.
