User Macro Template Syntax

Writing User Macros

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

See Writing User Macros for an introduction to writing a user macro. 

This page provides information about the code you can enter in a user macro template.

Accessing your macro's body

Use the $body object within your user macro template to access the content passed to your macro in the macro body.

The $body object is available if you have specified that your macro has a body (in other words, if you have not selected No macro body).

Example: Let's assume your macro is called helloworld.
Enter the following code in your template:

Hello World: $body

A user, when editing a Confluence page, chooses your macro in the macro browser and then enters the following in the macro placeholder that is displayed in the edit view:

From Matthew

The wiki page will display the following:

Hello World: From Matthew

On this page:

Related pages:

Using parameters in your user macro

You can specify parameters for your macro, so that users can pass it information to determine its behavior on a Confluence page.

How your macro parameters are used on a Confluence page

When adding a macro to a Confluence page, the macro browser will display an input field for each macro parameter. The field type is determined by the parameter type you specify.

Defining the parameters

A parameter definition in the template contains:

  • @param
  • The parameter name
  • A number of attributes (optional).

Format:

## @param MYNAME:title=MY TITLE|type=MY TYPE|desc=MY DESCRIPTION|required=true|multiple=true|default=MY DEFAULT VALUE

Additional notes:

  • The order of the parameters in the template determines the order in which the macro browser displays the parameters.
  • We recommend that you define the parameters at the top of the template.
  • There may be additional attributes, depending on the parameter type you specify.

The sections below describe each of the attributes in detail.

Attribute name

Description

Required / Recommended / Optional

(an unnamed, first attribute)

A unique name for the parameter. The parameter name is the first attribute in the list. The name attribute itself does not have a name. See the section on name below.

Required

title

The parameter title will appear in the macro browser. If you do not specify a title, Confluence will use the parameter name.

Recommended

type

The field type for the parameter. See the section on type below.

Recommended

desc

The parameter description will appear in the macro browser.

Optional

required

Specifies whether the user must enter information for this parameter. Defaults to false.

Optional

multiple

Specifies whether the parameter accepts multiple values. Defaults to false.

Optional

default

The default value for the parameter.

Optional

Parameter name

The parameter name is the first attribute in the list. The name attribute itself does not have a name.

Example: The following code defines 2 parameters, named 'foo' and 'bar':

## @param foo
## @param bar

Parameter type

The field type for the parameter. If you do not specify a type, the default is string.

Parameter type

Description

boolean

Displays a checkbox to the user and passes the value 'true' or 'false' to the macro as a string.

enum

Offers a list of values for selection. You can specify the values to appear in a dropdown in the macro browser. Example of specifying the enum values:

## @param colour:title=Colour|type=enum|enumValues=Grey,Red,Yellow,Green

Note about i18n: Confluence does not support internationalization of the enum values.The value the user sees is the one passed to the macro as the parameter value, with the capitalization given. In this case 'Grey', 'Red', etc.

string

A text field. This is the default type. Example with a required field:

## @param status:title=Status|type=string|required=true|desc=Status to display

confluence-content

Offers a control allowing the user to search for a page or blog post. Example:

## @param page:title=Page|type=confluence-content|required=true|desc=Select a page do use

username

Search for user.

## @param user:title=Username|type=username|desc=Select username to display

spacekey

Offers a list of spaces for selection. Passes the space key to the macro. Example:

## @param space:title=Space|type=spacekey

date

Confluence accepts this type, but currently treats it in the same way as 'string'. Example:

## @param fromDate:title=From Date|type=date|desc=Date to start from. Format: dd/mm/YYYY 

Note about dates: A user can enter a date in any format, you should validate the date format in your user macro.

int

Confluence accepts this type, but treats it in the same way as 'string'. Example with a default value:

## @param numPosts:title=Number of Posts|type=int|default=15|desc=Number of posts to display

percentage

Confluence accepts this type, but treats it in the same way as 'string'. Example:

## @param pcent:title=Percentage|type=percentage|desc=Number of posts to display 

Using the parameters in your macro code

The parameters are available in your template as $paramfoo, $parambar for parameters named "foo" and "bar".

Normally, a parameter like $paramfoo that is missing will appear as '$paramfoo' in the output. To display nothing when a parameter is not set, use an exclamation mark after the dollar sign like this: $!paramfoo 

Using no parameters

If your macro does not accept parameters, you should use @noparams in your template. 

If the user macro contains no parameters and does not specify @noparams, then the macro browser will display a free-format text box allowing users to enter undefined parameters. This can be confusing if the macro does not accept parameters.

Example: Add the following line at the top of your template:

## @noparams

Objects available to your macro

Including the macro body and parameters, the following Confluence objects are available to the macro:

Variable

Description

Class Reference

$body

The body of the macro (if the macro has a body)

String

$paramfoo, $parambar, ... $param<name>

Named parameters ("foo", "bar") passed to your macro.

String

$config

The BootstrapManager object, useful for retrieving Confluence properties.

BootstrapManager

$renderContext

The PageContext object, useful for (among other things) checking $renderContext.outputType

PageContext

$space

The Space object that this content object (page, blog post, etc) is located in (if relevant).

Space

$content

The current ContentEntity object that this macro is a included in (if available).

ContentEntityObject

Macros can also access objects available in the default Velocity context, as described in the developer documentation.

Security consideration

When creating a User Macro you should avoid using $content.getChildren() or $content.getDescendants() as these methods will list all pages, regardless of page restrictions or space permissions. This may lead to page viewers seeing pages that they do not have permission to see.

We also recommend thoroughly testing your user macro with a number of permission scenarios, such as restricted pages and space permissions.

Rendering HTML with variables

If HTML is rendered with variable assignment, the variable name needs to end with "Html". This will render HTML instead of escaping it.

Example: $outputHtml instead of $output

Controlling parameter appearance in the editor placeholder

You can determine which macro parameters should appear in the placeholder in the Confluence editor.

By default as many parameters as can fit will be displayed in the placeholder, as shown here:

You can control which parameters you want to display here, to ensure the most relevant information is visible to the author.

For example, the Confluence Warning macro has two parameters, title and icon. We consider title to be the most interesting parameter, so we have configured the Warning macro to show only the value of the title parameter.

Let's assume an author adds the Warning macro to a page, and gives it a title of 'The title of the warning'. The macro configuration leads to a placeholder as shown here:

To configure the macro placeholder for a user macro, you will add attributes to the @param entry in the template.

For example, if our Warning macro is a user macro, the configuration for the title parameter is as follows:

## @param title:type=string|option-showNameInPlaceholder=false|option-showValueInPlaceholder=true

The attribute showNameInPlaceholder specifies that the title parameter's name should not be shown.

The attribute showValueInPlaceholder specifies that the title parameter's value should be shown.

If none of the parameters in a macro include any of the above attributes, then the default behavior is to show all the parameters that fit in the placeholder: full title and value.

If one or more parameters has either attribute set, then all parameters that do not include the attributes will default to false (that is, they will not be shown).

Last modified on Oct 3, 2024

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.