Macro Transformation API
Reference
The macro transformation module exposes more than the Macro role: the components that look macros up, the identifier they are looked up by, and the filter applied to the raw content a macro produces. Macro Transformation explains how the engine uses them.
| Role | How you use it | What it gives you |
|---|---|---|
| Macro | Implemented, one component per macro, named after the macro | Its descriptor, its priority, whether it can be used inline, and the blocks it returns. Rendering Macros and Macro Execution Rules cover its methods |
| MacroManager | Injected | The macros registered on the wiki: their ids, the macro behind an id, and whether an id exists |
| MacroId | Constructed | A macro's name, plus the one syntax it is registered for when it is not registered for all of them |
| MacroIdFactory | Injected | A MacroId parsed out of its string form, html/confluence/1.0 |
| MacroContentParser | Injected | The macro's own content parsed as wiki syntax, see Java Macro Helpers |
| MacroCategoryManager | Injected | The categories macros are listed under in the editors, see Macro Categories |
| MacroTransformationConfiguration | Injected | The category overrides and the hidden categories the instance configured |
| RawBlockFilter | Implemented, under its own name | A say in the raw content a macro produces, before a renderer sees it |
Looking Up Macros
MacroManager looks macros up through the Context Component Manager, so the answer covers the macros of the current wiki and user, wiki macros of limited visibility included, and not only the macros bundled with the platform.
@Inject
private MacroManager macroManager;
@Inject
private MacroIdFactory macroIdFactory;
public MacroDescriptor describe(String macroIdAsString)
{
try {
MacroId macroId = this.macroIdFactory.createMacroId(macroIdAsString);
return this.macroManager.getMacro(macroId).getDescriptor();
} catch (ParseException | MacroLookupException e) {
return null;
}
}The two lookups treat the syntax of a MacroId differently, which is the one trap here: getMacro falls back to the macros registered for all syntaxes when it finds none registered for the syntax asked for, while exists does not and answers false for a macro that is registered for all syntaxes only.
getMacroIds() lists every registered macro, and getMacroIds(syntax) narrows that to the ones a page in that syntax can call, which is what the macro picker of the editors is built from.
Filtering Raw Content
A macro that turns content an author wrote into a raw block hands the renderer markup that never went through the parser, so nothing has checked it. RawBlockFilter is the point at which that content is cleaned. The bundled filter sanitizes HTML raw blocks; a macro producing raw content of another kind, or needing a stricter rule than the default, registers its own.
Filters run in priority order, lowest first, each one receiving what the previous one returned. RawBlockFilterParameters says whether the rendering is restricted and whether the content is to be cleaned, and carries the macro transformation context.
@Component
@Named("mymacro")
@Singleton
public class MyRawBlockFilter implements RawBlockFilter
{
@Override
public RawBlock filter(RawBlock block, RawBlockFilterParameters parameters)
throws MacroExecutionException
{
if (!parameters.isRestricted()) {
return block;
}
return new RawBlock(sanitize(block.getRawContent()), block.getSyntax());
}
@Override
public int getPriority()
{
return 500;
}
}FAQ
What does the string form of a macro id look like?
toc for a macro registered for every syntax, and id/syntaxtype/syntaxversion, as in html/confluence/1.0, for one registered for a single syntax.
Does my macro need a RawBlockFilter?
Only if it builds a raw block out of content it did not produce itself, such as HTML an author wrote. A macro returning ordinary blocks has nothing to filter.
Why can I not find these roles in the platform sources?
They belong to the XWiki Rendering project rather than to XWiki Platform, in the xwiki-rendering-transformation-macro module.
