Writing User Macros

Create a User Macro

To add a new user macro:

1. Go to Administration menu , then General Configuration. > User Macros
2. Choose Create a User Macro
3. Enter the macro details (see table below)
4. Click Add

Edit a user macro

To edit a user macro:

1. Go to Administration menu , then 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 Administration menu , then 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
## Confluence version: Version it was developed for
## 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.

#set($spacekey= $paramspacekey)
#set($numthreads= $paramnumthreads)
#set($numchars= $paramnumchars)

## Check for valid space key, otherwise use current
#if (!$spacekey)
  #set ($spacekey=$space.key)
#end

## Check for valid number of threads, otherwise use default of 5
#if (!$numthreads)
  #set ($numthreads=5)
#end

## Check for valid excerpt size, otherwise use default of 35
#if (!$numchars)
  #set ($numchars=35)
#end

Consider security implications

We recommend thoroughly testing your user macro with a number of permission scenarios, such as restricted pages and space permissions to avoid inadvertently displaying content that a user has no permission to see. See User Macro Template Syntax for more information. 

Example user macros

## @noparams
Hello World!
$body

## @noparams
<div class="aui-message closeable">
Hello World!
$body
</div>

## @noparams
<div class="noprint">$body</div>

## @param 0:title=colour|type=string
## @param 1:title=size|type=string
<span style="color: $param0; font-size: $param1">$body</span>

## @param Colour:title=colour|type=string
## @param Size:title=size|type=string
<span style="color: $paramColour; font-size: $paramSize">$body</span>

## @param Title:title=Title|type=string|desc=Title
<ac:structured-macro ac:name="panel">
        <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>
    <ac:parameter ac:name="title">$!paramTitle</ac:parameter>
    <ac:rich-text-body>$body</ac:rich-text-body>
</ac:structured-macro>

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

title=Title

type=string

desc=Title

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

<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>

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

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

</ac:structured-macro>

Context variables

By default, User macros have access only to the following Velocity context variables:

• $generalUtil

• $htmlUtil

To grant User macros access to additional variables in the default Velocity context, use the system property macro.required.velocity.context.keys and specify the variables in a comma-separated format. Check out the list of available variables in the default Velocity context

For example, to grant access to $authenticatedUser and $action, you can define the following VM option: -Dmacro.required.velocity.context.keys=authenticatedUser,action.

Discover how to configure system properties

Method allowlist

Starting with Confluence 9.0, a new security feature called the Velocity method allowlist requires that all method invocations within a Velocity template, including User macros, be explicitly allowlisted.

Atlassian has already generated and approved a list of common and known safe methods. However, you may still need to manually allowlist additional methods in your User Macros based on the log warning output generated when previewing your User Macro.

After defining and saving your User Macro, try adding it to a new page. If you see log warnings like the ones below, you'll need to manually allowlist these methods (scroll right to see the full example):

16:21:05,888 WARN [http-nio-8080-exec-6] [velocity] log Invocation blocked as method is not allowlisted: com.atlassian.confluence.setup.settings.DarkFeatures#isDarkFeatureEnabled(java.lang.String)

This list of methods collected from the logs can then be allowlisted by a system administrator using the atlassian.velocity.method.allowlist.extra system property.

As an example, you may allowlist two sample methods using the following VM option (scroll right to see the full example):

"-Datlassian.velocity.method.allowlist.extra=com.atlassian.confluence.setup.settings.DarkFeatures#isDarkFeatureEnabled(java.lang.String),com.atlassian.confluence.extra.dynamictasklist2.NameRenderer#render(java.lang.String boolean)"

If the value is configured incorrectly or can't be parsed, Confluence will log warnings during startup to indicate the issue.

Next Steps

Explore the power of user macros further by reading our Writing Advanced User Macros guide.