User Macro Template Syntax
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
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: 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: |
confluence-content | Offers a control allowing the user to search for a page or blog post. Example: |
username | Search for user. |
spacekey | Offers a list of spaces for selection. Passes the space key to the macro. Example: |
date | Confluence accepts this type, but currently treats it in the same way as 'string'. Example: 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: |
percentage | Confluence accepts this type, but treats it in the same way as 'string'. Example: |
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 |
|---|---|---|
| The body of the macro (if the macro has a body) | String |
| Named parameters ("foo", "bar") passed to your macro. | String |
| The | |
| The | |
| The | |
| The current |
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=trueThe 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).