Wiki source code of Java Macro Helpers
Last modified by Eleni Cojocariu on 2026/10/13 12:59
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | Beyond the methods it implements, a macro reaches the rendering engine through components it has injected or roles it supplies. These are the three a Java macro needs most often. | ||
| 2 | |||
| 3 | |=Helper|=How the macro gets it|=What it gives the macro | ||
| 4 | |##MacroContentParser##|Injected|Parses the macro's content as wiki syntax into blocks | ||
| 5 | |##MetaData.SOURCE## and ##DocumentReferenceResolver~<String~>##|Read from the current macro block, then resolved|The reference of the page the macro was called from | ||
| 6 | |##MacroRefactoring##|Implemented as a component named after the macro|Control over the links the macro declares, so they are refactored when a page moves | ||
| 7 | |||
| 8 | == Parsing the Content as Wiki Syntax == | ||
| 9 | |||
| 10 | ##MacroContentParser## turns content written in wiki syntax into the blocks the macro returns. ##prepareContentWiki## is its preparation helper, which stores the parsed content on the macro block. [[Macro Execution Rules>>doc:documentation.xs.dev.rendering-macros.macro-execution-rules.WebHome]] covers what preparation is and what may be stored. | ||
| 11 | |||
| 12 | {{code language="java"}} | ||
| 13 | public class MyMacro extends AbstractMacro<MyMacroParameters> | ||
| 14 | { | ||
| 15 | @Inject | ||
| 16 | private MacroContentParser contentParser; | ||
| 17 | |||
| 18 | @Override | ||
| 19 | public List<Block> execute(MyMacroParameters parameters, String content, | ||
| 20 | MacroTransformationContext context) throws MacroExecutionException | ||
| 21 | { | ||
| 22 | return this.contentParser.parse(content, context, true, context.isInline()).getChildren(); | ||
| 23 | } | ||
| 24 | |||
| 25 | @Override | ||
| 26 | public void prepare(MacroBlock macroBlock) throws MacroPreparationException | ||
| 27 | { | ||
| 28 | this.contentParser.prepareContentWiki(macroBlock); | ||
| 29 | } | ||
| 30 | } | ||
| 31 | {{/code}} | ||
| 32 | |||
| 33 | == Finding the Page the Macro Was Called From == | ||
| 34 | |||
| 35 | The reference of that page is not passed to ##execute##. It is carried by a ##MetaData.SOURCE## entry on an ancestor of the macro block, as a string, which an injected ##DocumentReferenceResolver~<String~>## turns into a ##DocumentReference##. | ||
| 36 | |||
| 37 | {{code language="java"}} | ||
| 38 | @Inject | ||
| 39 | private DocumentReferenceResolver<String> documentReferenceResolver; | ||
| 40 | |||
| 41 | @Override | ||
| 42 | public List<Block> execute(MyMacroParameters parameters, String content, | ||
| 43 | MacroTransformationContext context) throws MacroExecutionException | ||
| 44 | { | ||
| 45 | String source = extractSourceContentReference(context.getCurrentMacroBlock()); | ||
| 46 | DocumentReference reference = this.documentReferenceResolver.resolve(source); | ||
| 47 | // Use the reference. | ||
| 48 | } | ||
| 49 | |||
| 50 | private String extractSourceContentReference(Block block) | ||
| 51 | { | ||
| 52 | MetaDataBlock metaDataBlock = | ||
| 53 | block.getFirstBlock(new MetadataBlockMatcher(MetaData.SOURCE), Block.Axes.ANCESTOR); | ||
| 54 | if (metaDataBlock == null) { | ||
| 55 | return null; | ||
| 56 | } | ||
| 57 | return (String) metaDataBlock.getMetaData().getMetaData(MetaData.SOURCE); | ||
| 58 | } | ||
| 59 | {{/code}} | ||
| 60 | |||
| 61 | == Controlling How Links Are Refactored == | ||
| 62 | |||
| 63 | Links are extracted automatically from the content of any macro that declares the wiki content type, whatever the macro then does with them, which is what gives the page its backlinks and what lets those links be rewritten when a page is moved or renamed. A macro that holds links somewhere else, in a parameter for instance, or that needs its content read differently, supplies its own implementation of the ##MacroRefactoring## role, registered under the macro's own name; the engine falls back to the default implementation for every macro that does not. | ||
| 64 | |||
| 65 | {{scm project="xwiki-platform" path="xwiki-platform-core/xwiki-platform-rendering/xwiki-platform-rendering-xwiki/src/main/java/org/xwiki/rendering/macro/MacroRefactoring.java"}}The MacroRefactoring role{{/scm}} |
