Confluence 4.3 has reached end of life
Check out the [latest version] of the documentation
User macros are short pieces of code that perform an often-used function or add some custom formatting to a page. People can add the macro to a page by choosing it from the Macro Browser when editing a Confluence page. The macro is run when the page is loaded by the browser. You can write a user macro by adding code on a screen in the Confluence Administration Console.
You need to have System Administrator permissions in order to create user macros.
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.
On this page:
The information on this page does not apply to
Creating a User Macro
To create a user macro:
- Go to the Confluence Administration Console and click User Macros in the left-hand panel.
- Click Create a User Macro.
- Supply the information in the input fields as explained below, then click Add.
The sections below tell you about each of the input fields.
Macro Name
Enter the text that people will see when looking for the macro in the Macro Browser.
Visibility
Set the visibility options to specify who can see this macro when they are searching using the Macro Browser or Autocomplete.
User macros must have parameters defined in order to appear in the Confluence 4.0 Macro Browser.
The options are as follows:
Visibility Option | Meaning |
---|---|
Visible to all users | All users will see this macro when searching for a macro using the Macro Browser or Autocomplete. |
Visible only to system administrators | Choose this option if you want the macro to be 'hidden' from most users when the users are looking for a macro to add to a page. Note that this does not completely hide the macro. Instead, it is useful if you want to avoid cluttering the Macro Browser and Autocomplete with unnecessary macros. Specifically, if you are:
Please note that all the macro information will also be 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
Enter the text that should appear in the Macro Browser and in Autocomplete, to identify this macro when people are looking for it to insert onto a page.
Description
Enter the text that should appear in the Macro Browser describing this macro. Note that the Macro Browser's search will pick up matches in the description as well as in the title.
Categories
Select one or more categories for your macro. To select more than one category, hold down the 'Ctrl' key while selecting. These are the categories that appear in the Macro Browser, helping users to choose a macro from a logical set.
Icon URL
If you would like the Macro Browser to display an icon for your macro, enter the URL here. You can enter an absolute URL or a path relative to the Confluence base URL. For example:
Absolute URL:
http://mysite.com/mypath/status.png
Relative URL:
/images/icons/macrobrowser/status.png
Documentation URL
Enter the URL pointing to the online help or other documentation for your macro.
Macro Body Processing
Specify how you want Confluence to process the body of your macro before passing it to your macro. Below is an explanation of the macro body and the options available.
What is the macro body?
The macro body is the content that is displayed on the wiki page. If the macro allows a body, users will be able to enter body content when configuring the macro in the Macro Browser.
How can I use the macro body?
If you specify that your macro has a body, you will be able to pass text to the macro when you invoke it from within a page.
If your macro has a body, any body content that the user enters will be available to the macro in the $body
variable. See the section about the template below. In addition, the options below allow you to tell Confluence to pre-process the body before it is placed in the macro output.
What are the options for macro body?
Body Processing Option | Meaning |
---|---|
No macro body | Select this option if your macro does not need a body. |
Escaped | If your macro has a body, and you make use of the body as <b>Hello World</b> Then value of $body will be: <b>Hello World</b> This will render as: <b>Hello World</b> |
Unrendered | If your macro has a body, and you make use of the body as $body in your template, HTML in the body will be processed within the template before being output. Ensure that HTML is ultimately output by the template. |
Rendered | If your macro has a body, and you make use of the body as <b>Hello World</b> Then value of $body will be: <b>Hello World</b> This will render as: |
Template
Enter code to specify what the macro will do. For example, to add a macro inside the macro you are writing, you would write:
<ac:macro ac:name="someOtherMacro" />
Quick guide:
- 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. Note that this will prevent your macro appearing in the macro browser.
See our detailed guide to writing a user macro template.
Examples and Best Practices
See:
Related Topics
Developer documentation:
Library of user-contributed user macros
Be careful when installing user macros. Ideally use only macros from authors and sources that are well known to you.