Reference

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.

Parsing the Content as Wiki Syntax

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 covers what preparation is and what may be stored.

public class MyMacro extends AbstractMacro<MyMacroParameters>
{
    @Inject
    private MacroContentParser contentParser;

    @Override
    public List<Block> execute(MyMacroParameters parameters, String content,
        MacroTransformationContext context) throws MacroExecutionException
    {
        return this.contentParser.parse(content, context, true, context.isInline()).getChildren();
    }

    @Override
    public void prepare(MacroBlock macroBlock) throws MacroPreparationException
    {
        this.contentParser.prepareContentWiki(macroBlock);
    }
}

Finding the Page the Macro Was Called From

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.

@Inject
private DocumentReferenceResolver<String> documentReferenceResolver;

@Override
public List<Block> execute(MyMacroParameters parameters, String content,
    MacroTransformationContext context) throws MacroExecutionException
{
    String source = extractSourceContentReference(context.getCurrentMacroBlock());
    DocumentReference reference = this.documentReferenceResolver.resolve(source);
    // Use the reference.
}

private String extractSourceContentReference(Block block)
{
    MetaDataBlock metaDataBlock =
        block.getFirstBlock(new MetadataBlockMatcher(MetaData.SOURCE), Block.Axes.ANCESTOR);
    if (metaDataBlock == null) {
        return null;
    }
    return (String) metaDataBlock.getMetaData().getMetaData(MetaData.SOURCE);
}

Controlling How Links Are Refactored

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.

The MacroRefactoring role

Related

• Rendering Macros
• Macro Execution Rules
• Write a Macro in Java