How do I configure my Rich Text macro to receive unformatted input?

When writing a bodied macro, developers can access the body content entered by the user in the body parameter of the Macro class' execute method.

1
2
public String execute(Map<String, String> parameters, String body, ConversionContext context) throws MacroExecutionException;

Developers may define their macro body as RICH_TEXT or PLAIN_TEXT. By default, the body of a Rich Text macro is automatically rendered by Confluence and converted from Confluence Storage Format to rendered HTML before it is passed in to the macro's execute method. However, it is somtetimes necessary for a developer to access the un-rendered, raw Storage Format of the macro - and handle the rendering manually.

In earlier versions of Confluence, this was possible by setting the getBodyRenderMode method to return a value of RenderMode.NO_RENDER. However, this method is no longer available on the macro definition in Confluence 4.0 and later.

The new way to do this is by using the RequiresFormat annotation.  Add the RequiresFormat annotation to your execute method and set the value to Storage.  Here's a trivial example:

1
2
package com.example.test;

import com.atlassian.confluence.content.render.xhtml.ConversionContext;
import com.atlassian.confluence.content.render.xhtml.macro.annotation.Format;
import com.atlassian.confluence.content.render.xhtml.macro.annotation.RequiresFormat;
import com.atlassian.confluence.macro.Macro;
import com.atlassian.confluence.macro.MacroExecutionException;

import java.util.Map;

public class MyMacro implements Macro
{
    @Override
    public BodyType getBodyType() 
    {
        return BodyType.RICH_TEXT;
    }

    @Override
    public OutputType getOutputType()
    {
        return OutputType.BLOCK;
    }

    @Override
    @RequiresFormat(Format.Storage)
    public String execute(Map<String, String> parameters, String body, ConversionContext context) throws MacroExecutionException
    {
        return "Un-rendered macro body: " + body;
    }
}