com.jivesoftware.community.renderer
Interface RenderMacro

All Superinterfaces:

com.jivesoftware.community.renderer.RenderPlugin

All Known Implementing Classes:

BaseMacro

public interface RenderMacro
extends com.jivesoftware.community.renderer.RenderPlugin

The RenderMacro interface provides the ability to transfor element(s) of a document. For example a "User" macro may transform the text inside an element to an link to users profile page.

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:

JiveBeanInfo

Nested Class Summary

static class

RenderMacro.Type

Field Summary

static java.lang.String

MACROS_SHOW_OBJECT_TITLES

Method Summary

void	execute(org.w3c.dom.Element element, RenderContext renderContext) Applies the filter to the passed in string and returns the filtered string.
java.util.List<com.jivesoftware.community.renderer.macro.MacroParameter<?>>	getAllowedParameters() return a list of all parameters allowed by this macro
java.lang.String	getIcon() returns the relative path of the icon image.
java.util.List<com.jivesoftware.community.renderer.macro.MacroParameterSet>	getMacroParameterSets() Returns a list of all available default parameter implementations, if any
RenderMacro.Type	getMacroTag() returns tag type
int	getOrder() returns the order the macro should be run in. 0 should be "normal"
java.lang.String	getShortMacroName() Returns the tag name of the macro.
java.lang.String	getUrl() Returns the optional URL to open when adding this macro
boolean	isButton() Returns true if the macro should be displayed as a button in the toolbar as opposed to the insert menu
boolean	isIncludeContainerAsUrlParam() Should the container id and type be included in the url that is included in the macro's RTE menu item.
boolean	isIncludeJiveContentObjectAsUrlParam() Should the content object id and type be included in the url that is included in the macro's RTE menu item.
boolean	isShowInRTE() Returns true if the macro should be displayed and edited using the RTE editor
boolean	isShowSettings() returns true if the macro's settings should be editable in the RTE
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})

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

getName, getParameters, isEnabled, setEnabled, setParameters

Field Detail

MACROS_SHOW_OBJECT_TITLES

static final java.lang.String MACROS_SHOW_OBJECT_TITLES

See Also:

Constant Field Values

Method Detail

getShortMacroName

java.lang.String getShortMacroName()

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

getUrl

java.lang.String getUrl()

Returns the optional URL to open when adding this macro

Returns:

the url

isShowInRTE

boolean isShowInRTE()

Returns true if the macro should be displayed and edited using the RTE editor

Returns:

true if it should be shown

isButton

boolean isButton()

Returns true if the macro should be displayed as a button in the toolbar as opposed to the insert menu

Returns:

if it should be a button

isShowSettings

boolean isShowSettings()

returns true if the macro's settings should be editable in the RTE

Returns:

settings should be shown

getMacroTag

RenderMacro.Type getMacroTag()

returns tag type

Returns:

the tag type

getOrder

int getOrder()

returns the order the macro should be run in. 0 should be "normal"

Specified by:

getOrder in interface com.jivesoftware.community.renderer.RenderPlugin

Returns:

the order

getIcon

java.lang.String getIcon()

returns the relative path of the icon image. For ex: plugins should /resources/images/foo_icon.gif

Returns:

the relative path to the icon

getAllowedParameters

java.util.List<com.jivesoftware.community.renderer.macro.MacroParameter<?>> getAllowedParameters()

return a list of all parameters allowed by this macro

Returns:

all allowed parameters

getMacroParameterSets

java.util.List<com.jivesoftware.community.renderer.macro.MacroParameterSet> getMacroParameterSets()

Returns a list of all available default parameter implementations, if any

Returns:

a list of parameter sets

isIncludeJiveContentObjectAsUrlParam

boolean isIncludeJiveContentObjectAsUrlParam()

Should the content object id and type be included in the url that is included in the macro's RTE menu item. For plug-ins this is automatically set from the macro metadata in plugin.xml.

Returns:

true if the content object id and type should be included as url parameters

isIncludeContainerAsUrlParam

boolean isIncludeContainerAsUrlParam()

Should the container id and type be included in the url that is included in the macro's RTE menu item. For plug-ins this is automatically set from the macro metadata in plugin.xml.

Returns:

true if the container object id and type should be included as url parameters

execute

void execute(org.w3c.dom.Element element,
             RenderContext renderContext)

Applies the filter to the passed in string and returns the filtered string.

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

1. Inspect the render context to see if the filter should execute. For example, If the RenderStrategy denotes that links should not be filtered and the current filter does nothing but change text to links, then the filter should just return the input string.
2. Inspect the render context to determine the RenderTarget that the filter should target the output towards.
3. Examine the string and filter all or portions of it as required.
4. Reassemble the complete string and returns it.

Filters 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.

Parameters:

element - the element to filter and which the filtered string will modify

renderContext - the context the filter is being executed within