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.

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

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.

Compatibility with Confluence 1.3 Macros

Confluence 1.4 includes a compatibility layer that will run the majority, but not all macros from Confluence 1.3. Two thirds of the macros shipped with Confluence are still written to the old Radeox macro API and are run in compatibility mode.

The best way to find out if your macro still runs in Confluence 1.4 is to try it. If it doesn't work you may need to update your macro slightly, as some classes have moved from the com.atlassian.confluence.renderer package into com.atlassian.renderer. If you still can't get your macro to run, then you should rewrite it to the 1.4 API. The process is simple and should take you only hours at most.

Build a plugin

Maven

If your plugin is one based on the Confluence Plugin Development Kit or has the appropriate project.xml files, you can use Maven to build your plugin. Simply run the command: maven jar. This will build a jar file and deposit it in the $my_plugin_dir/target directory.

Then you can install the plugin using the Plugin Administration interface within Confluence. However, if you need to install an XWork plugin, see the Ant instructions below.

ant

You will have to have Ant installed in order to build the macro plugins.
Use the following commands from within the plugins directory in you Confluence installation to:

Create the jar file only:

ant -Dlibrary=macroname build

install the plugin:

You can install the plugin using ant, as shown below.

ant -Dlibrary=macroname install

You must use this method if your plugin contains xwork actions. Plugins installed via ant are not preserved when you upgrade Confluence, so if your plugin does not contain xwork actions, you should install it via the Administration, Plugin Manager page, where you can browse for and upload plugins.

Plugin Building Walkthrough

This section is a step by step description of creating a plugin. It assumes familiarity with your operating system's command line

1. Go to the plugins directory. Each plugin is a subdirectory in this directory.
2. Create a new plugin directory and source code. You can do this by copying an existing plugin, e.g. on unix cp -r information information2. You'll then need to change the package of all the java source files to com.atlassian.confluence.extra.information2 and change the name and key of the plugin and the keys of the macros in information2/src/etc/atlassian-plugin.xml. All the reference to the package com.atlassian.confluence.extra.information in this file need to be changed to com.atlassian.confluence.extra.information2 as well.
3. Build the plugin. From the directory plugins, run the command ant -Dlibrary=information2 build. This will create a jar file called plugins/information2/dist/plugins-information2.jar.
4. Install the plugin either by running ant -Dlibrary=information2 install, which copies the jar file to confluence/WEB-INF/lib, or by uploading the plugin using the Plugin Manager page, which copies the jar file to <confluence.home>/plugins.

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