Confluence Macro Manager
Confluence 4.0 and later
In Confluence 4.0 macros are accessed via a new com.atlassian.confluence.macro.xhtml.MacroManager interface.
- The interface contains methods to register and unregister macros. These are called automatically when plugins are installed, uninstalled, enabled or disabled or individual macros are enabled or disabled.
- The main method however is getMacroByName. It obtains an instance of a Macro unless the macro does not exist or is disabled in which case null is returned.
The Confluence 3.x com.atlassian.renderer.v2.macro.MacroManager interface still exists in order to support 3.x plugins, to migrate content to the new XHTML storage format and to view content that has not been fully migrated.
Source of macros
The Confluence 4.0 MacroManager is composed of 4 sub managers, one for each source of macros. When requested for a macro, each sub manager is checked in sequence.
- XhtmlMacroManager is populated with Confluence 4.0 style macros. Plugin developers supply 4.0 macro definitions as <xhtml-macro> elements in atlassin-plugin.xml files. Internally the definitions are held as XhtmlMacroModuleDescriptors.
- V2CompatibilityMacroManager is populated with bodyless Confluence 3.x style macros automatically wrapped in a V2CompatibilityMacro (a 4.0 macro). Plugin developers supply 3.x macro definitions as <macro> elements in atlassin-plugin.xml files. Internally the definitions are held as CustomMacroModuleDescriptors. Older style macros with bodies are not automatically wrapped, as the 4.0 macro's body type (PLAIN_TEXT or RICH_TEXT) is unknown.
- UserMacroLibraryMacroManager is populated with user macros added via the admin interface. Internally it delegates to a UserMacroLibrary which keeps track of user macros.
- UserMacroPluginMacroManager is populated with user macros added via the plugin subsystem. Plugin developers supply user macro definitions as <user-macro> elements in atlassin-plugin.xml files. Internally the definitions are held as UserMacroModuleDescriptors.
The Confluence 4.0 MacroManager may be autowired using the name "xhtmlMacroManager"
The Confluence 3.x MacroManager is still available using the name "macroManager".
Example XHTML macro definition
Example usage from a macro
The following (rather contrived) example is taken from a macro that outputs only selected nested macros. The output from nested macros are only included if there is a parameter with the nested macro's name. The value of the parameter is supplied to the nested macro. Note the check that the macro returned from the macroManager is not null. It may be null if the macro is disabled or does not exist.