View Source

User macros are simple template-like macros that allow you to create simple formatting macros using the Confluence web interface.

If you want to distribute your user macro as a plugin, please see User Macro Plugins. If you want to create more complex, programmatic macros in Confluence, you may need to write a Macro Plugin. Note also that Macro Plugins and User Macro Plugins can appear in the Confluence Notation Guide, whereas User Macros do not.

You need to have System Administrator permissions in order to perform this function.

To create a user macro,

Go to the 'Administration Console' and click 'User Macros in the left-hand panel.
Click 'Create a User Macro' at the top of the list of macros.
Enter the macro attributes as explained below, then click the 'Save' button.
Screenshot: Creating a User Macro

'Macro Name' — enter the text that you will type, within curly brackets, to invoke the macro from within a page. E.g. to invoke the 'floatright' macro defined in the above screenshot, you would type:
{floatright}
'Macro has a body' — check this box if you will pass body-text to the macro when you invoke it from within a page, e.g. :
{floatright}my text{floatright}
If you tick the Macro has a body checkbox, you will need to choose one of three options listed below.
For 'Output', choose one of the following options:
- 'Macro generates HTML markup' — choose this if you wish to write your Template in HTML markup (as shown in the above screenshot).
- 'Macro generates wiki markup' — choose this if you wish to write your Template in wiki markup.
'Template' — this is written in the Velocity templating language, and specifies what the macro will do. Note: If you ticked Macro has a body, your Template can refer to the body-text by specifying '$body'.

Options for 'Macro has a body':

When you select 'Macro has a body', anything the user types within the body of the macro will be available in the macro in the $body variable. The options below allow you to tell Confluence to pre-process the body before it is placed in the macro output.

Use unprocessed macro body — the body of the macro will be output verbatim, including any HTML markup. For example if the macro body is body, it will be displayed as body in the page.
Escape HTML in macro body — the body of the macro will be output with HTML markup escaped. So if the macro body is body, it will be displayed as body in the page.
Convert macro body wiki markup to HTML — the body of the macro will be converted from wiki text to HTML markup. So if the macro body is *body*, it will be displayed as body in the page.

Writing user macros: some examples

The name attribute of the macro is how you will use it from within a page, ie {name}.
The template attribute of the macro is written in the Velocity templating language, and controls the rendering of the macro itself.

As an example, let's write a simple macro that simply creates a red box (using an existing Confluence style) around some text (useful for writing about error conditions for example - hence the macro name 'error').

Take a look at an example of a 'Hello World' macro.

After clicking "New User Macro", enter error as the Name of your macro, and then put the following in the Template text area:

<div class="errorbox">$body</div>

Then click Add. You should now see your new macro in the User Macros library, and you can now enable and disable it individually.
To use the macro within a page, you would add notation like:

{error}This is bad{error}

And your page would (magically!) have an error box on it, like so:

This is bad

Another example to demonstrate how you can pass parameters into your macro. Say you wanted to write your own font colour macro:

<span style="color: $param0">$body</span>

The usage of this macro would be:

{colour:red}Some example text{colour}

which will produce:
Some example text
If your macro requires more than one parameter, you can use variables $param0 to $param9 to represent them. To specify multiple parameters, use:

{colour:red|blue|green}

Where red, blue and green are the 1st, 2nd and 3rd parameters respectively.

Available objects

The user macro above uses the $body object, which is available for use within your user macro template if the macro has a body. You can pass parameters to your user macro in the same way as any other macro (separated by | signs), these parameters are provided to your template as param1, param2, ... paramN.

Normally, a parameter like $param2 that is missing will appear as '$param2' in the output. To display nothing when a variable is not set, use an exclamation mark after the dollar sign like '$!param2'.

More information on object usage is available from the Velocity Template Overview.

User Macro Library

Below is a list of existing user macros that can be installed.