User Macros - Confluence User Guides and Documents - netoCiety

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.

To create a user macro,

You must be a Confluence administrator to create user macros.

Go to the 'Administration Console' and click 'User Macros in the left panel. (Users of Confluence 1.1 or 1.2 will find user macros under Administration -> Macro Management -> User Macros)
Click 'Create a User Macro' at the top of the list of macros.
Enter the macro attributes as explained below this screenshot, then click the 'Save' button.

'Macro Name' — enter the test 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').

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.

The complete list of objects available for use are:

Name	Description	Doc Reference
$body	The body of the macro (if the macro has a body)
$param0-n	The parameters passed to your macro (as available)
$config	The `BootstrapManager` object, useful for retrieving Confluence properties	BootstrapManager
$content	The current `ContentEntity` object that this macro is a included in (if available)	ContentEntityObject
$space	The `Space` object that this content object is located in (if relevant)	Space
$generalUtil	A `GeneralUtil` object, with useful utility methods for URL encoding etc	GeneralUtil
$action	A blank `ConfluenceActionSupport` object, useful for retrieving i18n text if needed	ConfluenceActionSupport
$webwork	A `VelocityWebWorkUtil` object, for it's htmlEncode() method	VelocityWebWorkUtil
$req	The current `HttpServletRequest` object (if the page is rendered as a result of an HTTP request)
$res	The corresponding `HttpServletResponse` object (not recommended to be played with)
$userAccessor	For retrieving users, groups and checking membership	UserAccessor

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.

No content found for label(s) user-macro.