Macro Plugins

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 will be familiar with macros like {color} or {children} or {rss}. Thanks to the plugin system, it is easy to write and install new macros into a Confluence server.

Created a new macro or looking for macros?
Share your macros and find new plugins in the Confluence extensions space.

For Simple Macros
If you want to create a macro that just inserts some boiler-plate text or performs simple formatting, you may only need a User Macro. User macros can be written entirely from within the Confluence web interface, and require no special installation or programming knowledge.

Adding a macro plugin

Macros are a kind of Confluence plugin module.

For more information about plugins in general, read Confluence Plugin Guide.
To learn how to install and configure plugins (including macros), read Installing and Configuring Plugins manually.
For an introduction to writing your own plugins, read Writing Confluence Plugins

First steps: Creating a very basic plugin

Make sure you have created your first macro plugin using our description over here. That will save you a lot of time.

The next step: Understanding a slightly more realistic macro plugin

The WoW plugin is a fun side-project created by Confluence developer Matthew Jensen. It loads information about World-of-Warcraft from a remote server, renders it on a Confluence page, and uses JavaScript for a nice hover-effect. You should download the source and learn more about it on the WoW Macro explanation page.

The Macro Plugin Module

Each macro is a plugin module of type "macro", packaged with whatever Java classes and other resources (i.e. Velocity templates) that the macro requires in order to run. Generally, similar macros are packaged together into a single plugin, for ease of management. Here is an example atlassian-plugin.xml file

<atlassian-plugin name='Task List Macros' key='confluence.extra.tasklist'>
    <plugin-info>
        <description>Macros to generate simple task lists</description>
        <vendor name="Atlassian Software Systems" url="http://www.atlassian.com"/>
        <version>1.3</version>
    </plugin-info>

    <macro name='tasklist' class='com.atlassian.confluence.extra.tasklist.TaskListMacro'
           key='tasklist'>
        <description>Creates a very simple task list, with user checkable tasks</description>
    </macro>

    <!-- more macros... -->
</atlassian-plugin>

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 Macro Plugin Module Implementing Class

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

A more complete guide to writing macros can be found in Writing Macros.

Using a Velocity Template

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

Example Macro Plugins

The source-code of a number of macros (some of which are already built and packaged with Confluence) can be found in the plugins directory of your Confluence distribution. You can modify these macros (consistent with the Confluence license). The most interesting macros to read if you're looking at writing your own are probably:

tasklist – a simple macro that stores its state in a page's 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 an XWork plugin to handle the server-side interaction.
graphviz – a macro that interacts with an external, non-Java tool

Macro Plugins

Adding a macro plugin

First steps: Creating a very basic plugin

The next step: Understanding a slightly more realistic macro plugin

The Macro Plugin Module

The Macro Plugin Module Implementing Class

Using a Velocity Template

Example Macro Plugins

Labels:

Children (4)

Comments (5)

Ville Valtasaari says:

Matt Ryall says:

Simon Keary says:

Anonymous says:

Azwandi Mohd Aris says: