This page last changed on Oct 03, 2005 by jnolen.
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.

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:

<macro-libraries>
   <macro-library name="Task List Macros" 
      key="confluence.extra.tasklist"
      description="An example macro library which generates task lists.">

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

      <!-- more macros -->

   </macro-library>
   
   <!-- more macro libraries -->

</macro-libraries>

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:

!tasklist-screenshot.gif|align=center!

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}

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:

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.


macros-tasklist.jar (application/java-archive)

How can I put static resource to a macros? Our macros shows some custom images. Where should I locate them and how should I reference that images in the generated code?

Posted by mike at Jun 11, 2004 07:58

Mike,

Good question - for static resources your macros need to read (ie properties / XML files or Velocity templates etc), just bundle them in the JAR and load them via the classpath.

For images, I think you'd have to put them into the WAR itself at the moment and then reference them as $req.contextPath/images/mymacrolibrary/image.gif or something similar.

It would be useful to have an ability to serve images from the classpath I suppose via some sort of servlet, we don't have that yet but I can see it would be very neat now. We'll add that this issue. The big issue there would be security of course, we wouldn't want to allow the web interface to serve up generic resources from the classpath!

Would it be OK if you had to alias all required resources in your XML file and then use those aliases in your reference? The servlet would then only serve resources that it had aliases for. It could be a pain if you had a lot of images I suppose - hrm... ideas?

Cheers,
Mike

Posted by mike@atlassian.com at Jun 14, 2004 04:38

You can find more macro libraries in the [Custom Macros] space.

Cheers,
Mike

Posted by mike@atlassian.com at Jun 14, 2004 04:52

> Would it be OK if you had to alias all required resources in your XML file and then use those aliases in your reference?
Shouldn't be a problem.

Posted by mike at Jun 14, 2004 07:36

>You can find more macro libraries in the Custom Macros space.
There seem to be no such space.

Posted by mike at Jun 14, 2004 07:37

Apologies - I hadn't set up the permissions for the new space, it should now be [accessible]

Posted by mike@atlassian.com at Jun 14, 2004 17:56

All the links above are still broken and I can't find documentation for creating the custom Java macros. I know for example that 1.3 added the support for putting images into the JAR but is there documentation for this other than the JIRA issue?

Posted by sulka at Dec 10, 2004 04:24
Document generated by Confluence on Feb 08, 2007 00:13