Writing User Macros

User macros are useful if you want to create your own custom macros. These can be to perform specific actions, apply custom formatting and much more. 

User macros are created and managed within Confluence itself, you do not need to develop an add-on. You will need some coding skills though.  

You'll need System Administrator permissions to create and manage user macros. 

On this page:

Related Pages:

Create a User Macro

To add a new user macro:

  1. Go to  > General Configuration > User Macros
  2. Choose Create a User Macro
  3. Enter the macro details (see table below)
  4. Click Add
Macro details field Description
Macro name This is the name of the macro, as it appears in the code.
Visibility

This controls who can see this macro in the macro browser or auto-complete. Options are:

  • Visible to all users
  • Visible only to system administrators

Note that if you select Visible only to system administrators, users will still see the output of the macro on a page, and the macro placeholder will still be visible when a user edits a page. It is only hidden in the macro browser and autocomplete.

All macro information is discoverable, including the macro title, description, parameter names and other metadata. Do not include confidential data anywhere in the definition of a user macro, even if it is marked as visible only to system administrators.

Macro Title This is the title that will appear in the macro browser and auto-complete.
Description This is the description that will appear in the macro browser. The macro browser's search will pick up matches in both the title and description.
Categories Select one or more macro browser categories for your macro to appear in.
Icon URL Enter an absolute URL (for example http://mysite.com/mypath/status.png) or path relative to the Confluence base URL (for example /images/icons/macrobrowser/status.png) if you want the macro browser to display an icon for your macro.
Documentation URL If you have documentation for your macro, enter the URL here.
Macro Body Processing

Specify how Confluence should process the body before passing it to your macro.

The macro body is the content that is displayed on a Confluence page. If your macro has a body, any body content that the user enters will be available to the macro in the $body variable.

Options for processing the macro body include:

  • No macro body
    Select this option if your macro does not have a body.
  • Escaped
    Confluence will add escape characters to the HTML markup in the macro body. Use this if you want to show actual HTML markup in the rendered page. For example, if the body is <b>Hello World</b> it will render as   <b>Hello World</b>.
  • Unrendered
    HTML in the body will be processed within the template before being output. Ensure that HTML is ultimately output by the template.
  • Rendered
    Confluence will recognise HTML in the macro body, and render it appropriately. For example, if the body is <b>Hello World</b> it will render as Hello World.
Template

This is where you write the code that determines what the macro should do.

  • Use HTML and Confluence-specific XML elements in the macro template. Details of Confluence's storage format are in Confluence Storage Format.
  • You can use the Velocity templating language. Here is more information on the Velocity project.
  • If your macro has a body, your template can refer to the macro body text by specifying '$body'.
  • Each parameter variable you use must have a matching metadata definition. Use @param to define metadata for your macro parameters.
  • When using the information passed using parameters, refer to your parameters as $paramXXX where 'XXX' is the parameter name that you specifed in the @param metadata definition.
  • Use @noparams if your macro does not accept parameters.

See User Macro Template Syntax for more information and examples.

Do you need a plugin instead?

If you want to distribute your user macro as a plugin, please refer to the developer's guide to the User Macro plugin module. If you want to create more complex, programmatic macros in Confluence, you may need to write a Macro plugin.

Edit a user macro

To edit a user macro:

  1. Go to  > General Configuration > User Macros
  2. Click Edit next to the relevant macro
  3. Update the macro details
  4. Click Save

Delete a user macro

To delete a user macro:

  1. Go to  > General Configuration > User Macros
  2. The currently configured user macros will appear
  3. Click Delete next to the relevant macro

Before deleting a user macro, you should search for all occurrences of the macro in pages and blog posts. Users will see an 'unknown macro' error if you delete a user macro that is still in use on a page.  

Best practices

This section contains tips and suggestions for best practices when creating your own user macros.

Add a descriptive header to your macro template

We recommend that you include a short description as a comment at the top of the Template field as shown below. 

## Macro title: My macro name
## Macro has a body: Y or N
## Body processing: Selected body processing option
## Output: Selected output option
##
## Developed by: My Name
## Date created: dd/mm/yyyy
## Installed by: My Name

## Short description of what the macro does

Expose your parameters in the macro browser

The macro browser is the easiest way for users to configure your macro.  You can specify the macro category, link to an icon, define the parameters that the macro browser will use to prompt the user for information, and more.

Supply default values for macro parameters

As you can't guarantee that a user has supplied parameters, one of the first things to do in the macro is check that you have received some value if you expect to rely on it later on in the macro code.

In the example below, the macro expects three parameters, and substitutes sensible defaults if they are not supplied.

Example user macros

  Hello World

This example demonstrates how to create a user macro that displays the text 'Hello World!' and any text that the user places in the body of the macro.

Field Value
Macro name helloworld
Visibility Visible to all users in the Macro Browser
Macro Title Hello World
Description Displays "Hello World" and the macro body.
Categories Confluence Content
Icon URL You can leave this field blank
Documentation URL You can leave this field blank
Macro body processing Rendered
Template

Enter the code below in the template field - this example will print the text straight onto the page.

If you wanted the text to appear in a panel you could include the relevant AUI message class as shown here.

Using the 'Hello World' macro on a page

Now you can add the macro to your Confluence page using the Macro Browser, or by typing {hello in the editor and selecting the macro from the list of suggestions.

The result is:

If you chose to include a panel, the result would be:

  NoPrint

This example demonstrates how to create a user macro that can contain text that is visible when viewing a page, but does not print.

Field Value
Macro name noprint
Visibility Visible to all users in the Macro Browser
Macro Title No Print
Description Hides text from printed output.
Categories Confluence Content
Icon URL You can leave this field blank
Documentation URL You can leave this field blank
Macro body processing Rendered
Template

Enter the code below in the template field.

Using the 'NoPrint' Macro on a page

Now you can add the macro to your Confluence page using the Macro Browser. Text entered into the body of the macro placeholder will not be printed, but will appear when the page is viewed online.

Making the PDF export recognise the NoPrint macro

See Advanced PDF Export Customisations.

  Colour and Size

This example demonstrates how you can pass parameters to your macro. We'll create a font style macro which has two parameters to allows the user to specify the colour and size of the text contained in the macro body.

Field Value
Macro name stylish
Visibility Visible to all users in the Macro Browser
Macro Title Stylish
Description Applies colour and size to text.
Categories Confluence Content
Icon URL You can leave this field blank
Documentation URL You can leave this field blank
Macro body processing Rendered
Template

Enter the code below in the template field. If your macro requires more than one parameter, you can use variables $param0 to $param9 to represent them.

Alternatively, you can also use explicitly-named parameters in your macro. These macro parameters will appear as variables with the name $param<x> where <x> is the name of your parameter. 

  Formatted Panel

This example demonstrates how to write a user macro that creates a panel that is preformatted with specific colours. It will create a panel that looks like this:

(Title)

Note: The panel's title will be empty if the user does not give a value for the title parameter.

Field Value
Macro name formpanel
Visibility Visible to all users in the Macro Browser
Macro Title Formatted Panel
Description Creates a panel preformatted with specific colours
Categories Formatting
Icon URL You can leave this field blank
Documentation URL You can leave this field blank
Macro body processing Escaped
Template

Enter the code below in the template field. See below for a more detailed explanation of the code below.

Explanation of the code in the macro template

Below is a breakdown of the user macro template code. 

Item Description
## @param Title:title=Title|type=string|desc=Title

@param defines the metadata for your macro parameters.

@param Title

This parameter is called "Title".

title=Title

defines the parameter title that will appear in the macro browser as "Title".

type=string

defines the field type for the parameter as a text field.

desc=Title

defines the description of the parameter in the macro browser.

<ac:structured-macro ac:name="panel">

This calls the Confluence Panel macro.

The easiest way to find out the code name of a Confluence macro by viewing the Storage Format of a page containing the macro. You'll need Confluence Administrator permissions to view the storage format.

<ac:parameter ac:name="titleBGColor">#ccc</ac:parameter>
<ac:parameter ac:name="borderStyle">solid</ac:parameter>
<ac:parameter ac:name="borderColor">#6699CC</ac:parameter>
<ac:parameter ac:name="borderWidth">2</ac:parameter>
<ac:parameter ac:name="titleColor">#000000</ac:parameter>

Sets the parameters for the macro: the background colour, border style, border colour, border width and title colour.

To discover the names of the parameters for a Confluence macro, view the storage format as described above.

<ac:parameter ac:name="title">$!paramTitle</ac:parameter>

Enters the value stored in the 'Title' parameter into the title section of the macro.

The ! tells the macro to leave the title blank, when there is no data in the "Title" parameter.

<ac:rich-text-body>$body</ac:rich-text-body>

Users can enter data that is stored in the body of the macro. This line enables the macro to access and store the body content passed to your macro.

</ac:structured-macro>

This command marks the end of the macro.


Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport