Guide to User Macro Templates

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 behaviour on a Confluence page.

How your macro's 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 of your macro's parameters. The field type is determined by the parameter type you specify for each parameter.

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.

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.

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

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

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

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

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

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

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

## @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. That will let Confluence know that it need not display a parameter input field in the macro browser.

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, especially 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:

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

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 behaviour 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).