This documentation relates to an earlier version of Confluence.
View this page in the current documentation or visit the current documentation home.
Skip to end of metadata
Comment: Corrected links that should have been relative instead of absolute.
Go to start of metadata
Old Documentation

This documentation is for Confluence 1.1 and Confluence 1.2. If you are using Confluence 1.3 or later, macros are now written as Confluence Plugins, and you should read the Macro Plugins documentation instead.

Java-based macros give you the most power to create your own Confluence macros that can produce complex HTML, retrieve data from Confluence, manipulate pages and interact with other systems and resources.

(warning) If you want to create more simple formatting macros in Confluence, you may only need a User macro.

Adding a Java macro

To add a Java macro library, drop the macro library JAR (called by convention macros-name.jar - ie macros-tasklist.jar) into the WEB-INF/lib directory within your Confluence web application and restart Confluence.

Structure of a Java macro library

A Confluence macro library is a JAR file containing classes and resources (ie Velocity templates) used by the macros in the library, as well as a macro library descriptor file macro-library.xml. This descriptor defines and documents the macro library, like the example below:

A descriptor can contain multiple library definitions, each with multiple macros.

Building Java macros

The Confluence installation contains a custommacros directory with a "Confluence Macro Builder" Ant script and some sample macro projects.

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 (tick) or (error) :

You can download a prebuilt tasklist library or build it yourself as below.

Building the tasklist library

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

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:

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

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

Labels
  • None