Event Listener module
Job module
Language module
Macro Module
Servlet Filter module
Servlet module
Theme module
Web UI modules
Workflow module

Macro module


Confluence 4.0 and later

Starting from Confluence 4.0, macro module was replaced with xhtml-macro module. To function correctly in Confluence, all macros must contain metadata.

Macros are Confluence code that can be invoked from inside a page by putting the name of the macro in curly brackets. Users of Confluence are familiar with macros like {color}, {children}, or {rss}. Thanks to the plugin system, it is easy to write and install new macros into a Confluence instance.

Adding a macro plugin

Macros are a kind of Confluence plugin modules.

The Macro plugin module

Each macro is a plugin module of "xhtml-macro" type. It is packaged with whatever Java classes and other resources (for example, Velocity templates) that the macro requires to run. For easier management, similar macros are usually packaged together into a single plugin. Here is an example of atlassian-plugin.xml file:

<atlassian-plugin key="${atlassian.plugin.key}" name="${project.name}" plugins-version="2">
		<vendor name="${project.organization.name}" url="${project.organization.url}" />
		<param name="plugin-icon">images/pluginIcon.png</param>
		<param name="plugin-logo">images/pluginLogo.png</param>

    <xhtml-macro name="example-macro" key="example-macro" class="path/to/your/macro/class"
		<category name="formatting"/>
		<!-- your parameters -->

    <!-- more macros... -->

The name of the macro defines how it will be referenced from the page. So, if you define your macro as having name="tasklist", the macro will be called from the page as {tasklist}.

The class attribute of the macro defines what Java class is used to process that macro. This is the class you need to write for the macro to function. It must implement the com.atlassian.confluence.macro.Macro interface.

The Including information in your macro for the Macro Browser page describes available <xhtml-macro> elements.

Creating a very basic plugin

Make sure you have created your first macro plugin using
Create a Confluence ‘Hello World’ macro tutorial. That will save you a lot of time. You can find a more complete guide to writing macros on Writing macros page.

Using a Velocity template

To use a Velocity template to provide the output of your macro, see page about Rendering Velocity templates in a macro.

Examples of macro plugins

You can find the source code of a number of macros in the plugins directory of your Confluence distribution. Some of macros are already built and packaged with Confluence. You can modify these macros, but make sure you’re consistent with the Confluence license. If you want to write your own macros, the most interesting ones to read are the following:

  • tasklist — a simple macro that stores its state in a page PropertySet.
  • userlister — a macro that works in combination with an event listener to list logged-in users.
  • livesearch — a macro that leverages JavaScript and XMLHttpRequest in combination with a Struts module to handle the server-side interaction.
  • graphviz — a macro that interacts with an external, non-Java tool.

Rate this page: