Wiki source code of Macro Transformation API
Last modified by Eleni Cojocariu on 2026/10/13 18:18
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | 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>>doc:documentation.xs.dev.rendering-macros.macro-transformation.WebHome]] explains how the engine uses them. | ||
| 2 | |||
| 3 | |=Role|=How you use it|=What it gives you | ||
| 4 | |##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>>doc:documentation.xs.dev.rendering-macros.WebHome]] and [[Macro Execution Rules>>doc:documentation.xs.dev.rendering-macros.macro-execution-rules.WebHome]] cover its methods | ||
| 5 | |##MacroManager##|Injected|The macros registered on the wiki: their ids, the macro behind an id, and whether an id exists | ||
| 6 | |##MacroId##|Constructed|A macro's name, plus the one syntax it is registered for when it is not registered for all of them | ||
| 7 | |##MacroIdFactory##|Injected|A ##MacroId## parsed out of its string form, ##html/confluence/1.0## | ||
| 8 | |##MacroContentParser##|Injected|The macro's own content parsed as wiki syntax, see [[Java Macro Helpers>>doc:documentation.xs.dev.rendering-macros.java-macro-helpers.WebHome]] | ||
| 9 | |##MacroCategoryManager##|Injected|The categories macros are listed under in the editors, see [[Macro Categories>>doc:documentation.xs.dev.rendering-macros.macro-categories.WebHome]] | ||
| 10 | |##MacroTransformationConfiguration##|Injected|The category overrides and the hidden categories the instance configured | ||
| 11 | |##RawBlockFilter##|Implemented, under its own name|A say in the raw content a macro produces, before a renderer sees it | ||
| 12 | |||
| 13 | == Looking Up Macros == | ||
| 14 | |||
| 15 | ##MacroManager## looks macros up through the Context Component Manager, so the answer covers the macros of the current wiki and user, [[wiki macros>>doc:documentation.xs.dev.rendering-macros.wiki-macros.WebHome]] of limited visibility included, and not only the macros bundled with the platform. | ||
| 16 | |||
| 17 | {{code language="java"}} | ||
| 18 | @Inject | ||
| 19 | private MacroManager macroManager; | ||
| 20 | |||
| 21 | @Inject | ||
| 22 | private MacroIdFactory macroIdFactory; | ||
| 23 | |||
| 24 | public MacroDescriptor describe(String macroIdAsString) | ||
| 25 | { | ||
| 26 | try { | ||
| 27 | MacroId macroId = this.macroIdFactory.createMacroId(macroIdAsString); | ||
| 28 | return this.macroManager.getMacro(macroId).getDescriptor(); | ||
| 29 | } catch (ParseException | MacroLookupException e) { | ||
| 30 | return null; | ||
| 31 | } | ||
| 32 | } | ||
| 33 | {{/code}} | ||
| 34 | |||
| 35 | 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. | ||
| 36 | |||
| 37 | ##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. | ||
| 38 | |||
| 39 | == Filtering Raw Content == | ||
| 40 | |||
| 41 | 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. | ||
| 42 | |||
| 43 | 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. | ||
| 44 | |||
| 45 | {{code language="java"}} | ||
| 46 | @Component | ||
| 47 | @Named("mymacro") | ||
| 48 | @Singleton | ||
| 49 | public class MyRawBlockFilter implements RawBlockFilter | ||
| 50 | { | ||
| 51 | @Override | ||
| 52 | public RawBlock filter(RawBlock block, RawBlockFilterParameters parameters) | ||
| 53 | throws MacroExecutionException | ||
| 54 | { | ||
| 55 | if (!parameters.isRestricted()) { | ||
| 56 | return block; | ||
| 57 | } | ||
| 58 | return new RawBlock(sanitize(block.getRawContent()), block.getSyntax()); | ||
| 59 | } | ||
| 60 | |||
| 61 | @Override | ||
| 62 | public int getPriority() | ||
| 63 | { | ||
| 64 | return 500; | ||
| 65 | } | ||
| 66 | } | ||
| 67 | {{/code}} |
