com.atlassian.renderer.v2.macro

Interface Macro

All Known Implementing Classes:

AbstractPanelMacro, BaseMacro, BasicAnchorMacro, CodeMacro, ColorMacro, InlineHtmlMacro, LoremIpsumMacro, NoformatMacro, PanelMacro, QuoteMacro, RadeoxCompatibilityMacro, ResourceAwareMacroDecorator

public interface Macro

A pluggable, programmatic module for inserting interesting things into a wiki page.

See Also:

Macro Plugins Documentation

Field Summary

Fields

Modifier and Type	Field and Description
static String	RAW_PARAMS_KEY

Method Summary

Modifier and Type	Method and Description
String	execute(Map<String,Object> parameters, String body, RenderContext renderContext) Execute the macro.
RenderMode	getBodyRenderMode() If the macro has a body, return the mode in which the body of the macro should be rendered.
TokenType	getTokenType(Map<String,Object> parameters, String body, RenderContext context) Declares what sort of html elements are returned by the macro.
WysiwygBodyType	getWysiwygBodyType() Defines how the Macro's body should be rendered for Wysiwyg editors.
boolean	hasBody() Determine if the macro is a one-shot macro, or one that takes a body.
boolean	isInline() Deprecated. since Renderer 6 (Confluence 3.1) use getTokenType(java.util.Map<java.lang.String, java.lang.Object>, java.lang.String, com.atlassian.renderer.RenderContext) instead, which will by default call this method. However, for macros to be backwardly compatible they will still need to implement isInline() too.
boolean	suppressMacroRenderingDuringWysiwyg() Suppress the rendering of the macro -- the macro's body may still be rendered (depending on the render mode of the macro), but the HTML the macro adds will not be created.
boolean	suppressSurroundingTagDuringWysiwygRendering() Suppress surrounding div/span during Wysiwyg rendering.

Field Detail

RAW_PARAMS_KEY

static final String RAW_PARAMS_KEY

See Also:

Constant Field Values

Method Detail

getTokenType

TokenType getTokenType(Map<String,Object> parameters,
                       String body,
                       RenderContext context)

Declares what sort of html elements are returned by the macro. TokenType.INLINE elements will have paragraphs drawn around them, or be incorporated into paragraphs they are included in. TokenType.BLOCK elements will be treated as their own paragraph, splitting any paragraphs they would otherwise be in. TokenType.INLINE_BLOCK elements will not have paragraphs drawn around them, but they won't split any paragraphs they appear in either.

Macros that contain elements that shouldn't appear in a paragraph, such as pre, should return TokenType.BLOCK. If it produces a span, replacement text or text decoration, return TokenType.INLINE. If it affects logic of whether its children are displayed but doesn't add its own content, or you aren't sure what to return, return TokenType.INLINE_BLOCK.

Parameters:

parameters - the parameters passed to the macro. These are useful here for macros that take parameters which dramatically alter the appearance of the macro.

body - the macro body is provided in case its content could have a bearing on the type of element returned by the macro

context - the context is provided in case its content could have a bearing on the type of element returned by the macro

Returns:

the TokenType that matches the content produced by this macro

isInline

boolean isInline()

Deprecated. since Renderer 6 (Confluence 3.1) use getTokenType(java.util.Map<java.lang.String, java.lang.Object>, java.lang.String, com.atlassian.renderer.RenderContext) instead, which will by default call this method. However, for macros to be backwardly compatible they will still need to implement isInline() too.

Determine if the macro is an "inline" element in the resulting HTML. Inline elements will have paragraphs drawn around them, or be incorporated into paragraphs they are included in. As a rule of thumb, if your macro produces a paragraph, table or div (or so on), you should return false. If it produces a span, replacement text or text decoration, return true.

Most macros will want to return false here.

Returns:

true if the macro output is included inline within the surrounding HTML, false if it forms its own HTML block.

hasBody

boolean hasBody()

Determine if the macro is a one-shot macro, or one that takes a body. If this method returns false, the renderer will NOT look for an end-tag for the macro. If the method returns true, the renderer will look for an end-tag, but if the end-tag is not found then the macro will be processed with an empty body.

getBodyRenderMode

RenderMode getBodyRenderMode()

If the macro has a body, return the mode in which the body of the macro should be rendered. The body of the macro will be rendered before the macro is executed!

If this method returns null, it causes the macro processor to treat the macro as one that returns wiki-text rather than HTML. The body of the macro will be passed in un-rendered, and the macro's output will be inserted back into the page for further normal processing by the wiki-engine.

Returns:

the RenderMode in which the body of this macro should be rendered, or null if the macro is substituting wiki-text

execute

String execute(Map<String,Object> parameters,
               String body,
               RenderContext renderContext)
        throws MacroException

Execute the macro. Macros should write any output to the writer (it will be rendered in the RenderMode returned in getBodyRenderMode()).

Macros are expected to output HTML. The output of macros will not be subjected to any further processing by the wiki-engine. If your macro produces wiki-text, you are responsible for rendering that text to HTML yourself using a SubRenderer or WikiStyleRenderer. If your macro returns pure wiki-text, you can force further processing in the normal chain by returning null from getBodyRenderMode()

Parameters:

parameters - the parameters included in the macro

body - the content of the body of the macro

renderContext - the rendering context in which the macro was executed

Returns:

the output of the macro

Throws:

MacroException - if the macro fails in some unremarkable way. If the macro fails in a way that is important to the server maintainer (i.e. something is badly wrong), throw a RuntimeException instead.

suppressSurroundingTagDuringWysiwygRendering

boolean suppressSurroundingTagDuringWysiwygRendering()

Suppress surrounding div/span during Wysiwyg rendering. This should return true if the macro provides it's own Wysiwyg processing HTML.

suppressMacroRenderingDuringWysiwyg

boolean suppressMacroRenderingDuringWysiwyg()

Suppress the rendering of the macro -- the macro's body may still be rendered (depending on the render mode of the macro), but the HTML the macro adds will not be created.

Returns:

getWysiwygBodyType

WysiwygBodyType getWysiwygBodyType()

Defines how the Macro's body should be rendered for Wysiwyg editors. This method is only relevant for macros that return false from suppressSurroundingTagDuringWysiwygRendering(), true from suppressMacroRenderingDuringWysiwyg() and true from hasBody().