Macro Plugins v1.3

This documentation concerns Confluence version 1.3. For current documentation, see 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.

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

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. Your class should extend com.atlassian.renderer.macro.BaseMacro.

Example Java macros

The Confluence installation contains a custommacros directory with a "Confluence Macro Builder" Ant script and some sample macro projects. The best way to learn how to write your own macros is to start by looking at this example code.

Task List Example Library

As an example, tasklist is one of the example macros, which builds a simple task list within a Confluence page and allows users to complete and uncomplete the various tasks simply. It also serves as a good example of how easy it is to build add functionality to Confluence.

Example

Here's a screenshot of the tasklist macro in action, showing a simple shopping list that's half completed:

This was generated by notation like the following, with tasks completed or uncompleted by clicking on the relevant or :

{tasklist:Shopping List}
Buy apples
Buy bananas
Purchase shopping bag
Collect laundry
Deposit money
{tasklist}

As of 1.3, the tasklist macro is packaged with Confluence as a plugin, and should be available when you install the application.

Building the tasklist library

To build tasklist, go to the custommacros directory within the expanded distribution, and run:

ant -Dlibrary=tasklist build

Your macro library is now located at custommacros/tasklist/dist/macros-tasklist.jar

Installing the tasklist library

To install the library straight into the web application, run:

ant -Dlibrary=tasklist install

and then restart your Confluence instance. Similarly you can uninstall the library like so:

ant -Dlibrary=tasklist uninstall

Note: Confluence must first be shutdown before you can uninstall macros.

Page tree