com.jivesoftware.community.renderer
Interface RenderMacro

All Superinterfaces:

RenderFilter

All Known Implementing Classes:

BaseMacro

public interface RenderMacro
extends RenderFilter

The RenderMacro interface is an extension to the RenderFilter interface, the main difference being that it will not execute over the whole page, rather it will be provided with just the text between the macro tags, if it exists.

Macros have 0 or more properties that can be configured by an administrator. Each property may control any aspect of how the macro works -- for example, a property named "color" could control which color to format text in. All properties are configurable through the standard JavaBeans conventions. You should specify exactly which properties can be controlled by an administrator by using the BeanInfo interface and JiveBeanInfo class described above.

See Also:

RenderFilter, JiveBeanInfo

Method Summary

java.lang.String	execute(java.lang.String string, RenderContext renderContext) Executes the render macro against the provided string and render context.
java.lang.String	getMacroTagName() Returns the tag name of the macro.
java.util.Map<java.lang.String,java.lang.String>	getParameters() Returns a Map of user provided parameters to the macro.
boolean	isSingleTagMacro() Returns true is the macro has only a single tag such as {testMacro}, false if the macro should have both an opening and closing tag ({testMacro}text here{testMacro})
void	setParameters(java.util.Map<java.lang.String,java.lang.String> parameters) Sets a map of user provided parameters for the macro to use.

Methods inherited from interface com.jivesoftware.community.renderer.RenderFilter

getName, getUserDocumentation, isEnabled, setEnabled

Method Detail

getMacroTagName

java.lang.String getMacroTagName()

Returns the tag name of the macro. The tag name will be used to map between macro tag names and the macro to execute. For example, if the macro tag name is testMacro the processing engine will know to associate any {testMacro} tag with the macro.

Returns:

the macro tag name.

isSingleTagMacro

boolean isSingleTagMacro()

Returns true is the macro has only a single tag such as {testMacro}, false if the macro should have both an opening and closing tag ({testMacro}text here{testMacro})

Returns:

true is the macro has only a single tag, false if the macro should have both an opening and closing tag

execute

java.lang.String execute(java.lang.String string,
                         RenderContext renderContext)

Executes the render macro against the provided string and render context.

A typical implementation of this method would use the following pattern:

1. Inspect the render context to see if the macro should execute. For example, If the RenderStrategy denotes that macros should not run or that links should not be filtered and the current macro does nothing but insert links, then the macro should just return the input string.
2. Inspect the render context to determine the RenderTarget that the macro should target the output towards.
3. Examine the string and markup all or portions of it as required.
4. Reassemble the complete string and returns it.
Macros that are called with a render target of RenderTarget.TARGET_WYSIWYG_EDITOR must support being 'unrendered' using a render target of RenderTarget.TARGET_PLAIN_TEXT if they are to output html. Otherwise, macros should just output the wiki macro syntax when called with a strategy that uses the RenderTarget.TARGET_WYSIWYG_EDITOR target.

Macros should expect that further processing of the returned text will be done. Use the RenderedTextStore to store text snippets if no further rendering of the all or portions of the returned content should not be performed.

Specified by:

execute in interface RenderFilter

Parameters:

string - the body of the macro if this macro has both opening and closing tags, null otherwise

renderContext - the context the macro is being executed within

Returns:

a filtered string

See Also:

RenderFilter.execute(String, RenderContext)

getParameters

java.util.Map<java.lang.String,java.lang.String> getParameters()

Returns a Map of user provided parameters to the macro.

Returns:

a Map of user provided parameters to the macro

setParameters

void setParameters(java.util.Map<java.lang.String,java.lang.String> parameters)

Sets a map of user provided parameters for the macro to use.

Parameters:

parameters - a map of user provided parameters