Cloud
Data Center 7.20
Versions

Writing User Macros

Confluence administrator's guide

On this page

In this section

Related content

  • No related content found

Still need help?

The Atlassian Community is here for you.

Ask the community

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 app (plugin). 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 Administration  > General Configuration > User Macros.
  2. Select Create a User Macro.
  3. Enter the macro details (see table below).
  4. Select Add.
Macro details fieldDescription
Macro nameThis 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 TitleThis is the title that will appear in the macro browser and auto-complete.
DescriptionThis 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.
CategoriesSelect one or more macro browser categories for your macro to appear in.
Icon URLEnter 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 URLIf 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 recognize 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.
  • 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 Administration  > General Configuration > User Macros.
  2. Select Edit next to the relevant macro.
  3. Update the macro details.
  4. Select Save.

Delete a user macro

To delete a user macro:

  1. Go to Administration  > General Configuration > User Macros.
  2. The currently configured user macros will appear.
  3. Select 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

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.

FieldValue
Macro namehelloworld
VisibilityVisible to all users in the Macro Browser
Macro TitleHello World
DescriptionDisplays "Hello World" and the macro body.
CategoriesConfluence Content
Icon URLYou can leave this field blank
Documentation URLYou can leave this field blank
Macro body processingRendered
Template

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

## @noparams
Hello World!
$body

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

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

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:

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.

FieldValue
Macro namenoprint
VisibilityVisible to all users in the Macro Browser
Macro TitleNo Print
DescriptionHides text from printed output.
CategoriesConfluence Content
Icon URLYou can leave this field blank
Documentation URLYou can leave this field blank
Macro body processingRendered
Template

Enter the code below in the template field.

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

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 recognize the NoPrint macro

See Advanced PDF Export Customizations.


Color 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 color and size of the text contained in the macro body.

FieldValue
Macro namestylish
VisibilityVisible to all users in the Macro Browser
Macro TitleStylish
DescriptionApplies colour and size to text.
CategoriesConfluence Content
Icon URLYou can leave this field blank
Documentation URLYou can leave this field blank
Macro body processingRendered
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.

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

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. 

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

This example demonstrates how to write a user macro that creates a panel that is preformatted with specific colors. 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.

FieldValue
Macro nameformpanel
VisibilityVisible to all users in the Macro Browser
Macro TitleFormatted Panel
DescriptionCreates a panel preformatted with specific colors
CategoriesFormatting
Icon URLYou can leave this field blank
Documentation URLYou can leave this field blank
Macro body processingEscaped
Template

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

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

Explanation of the code in the macro template

Below is a breakdown of the user macro template code. 

ItemDescription
## @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 color, border style, border color, border width and title color.

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.


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

tip/resting Created with Sketch.

Do more with Confluence

Not keen to write your own macro? There are a ton of free and paid macros available in the Atlassian Marketplace. Here are some of our most popular:

Next Steps

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

Last modified on Dec 5, 2024

Was this helpful?

Yes
No
Provide feedback about this article

In this section

Related content

  • No related content found
Powered by Confluence and Scroll Viewport.