This page last changed on Dec 19, 2010 by don.willis@atlassian.com.

The 'template' is one of the fields that you will define when creating a user macro. (See the rest of the guide to writing user macros.) This page gives you guidelines about the code you can enter in a user macro template.

Quick guide to user macro templates
  • If you choose an output format of 'Wiki Markup', you should write the template using Confluence wiki markup.
  • If you choose an output format of 'HTML', you should write the template using HTML.
  • You can also 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'.
  • Use @param to define parameters for your macro.
  • When using the information passed via parameters, refer to your parameters as $paramXXX where 'XXX' is the parameter name that you specify in @param.
  • Use @noparams if your macro does not accept parameters.

The rest of this page gives more details of the above procedure.

On this page:

Coding in HTML or Wiki Markup

If you chose an output format of 'HTML', you must write the content of the template using HTML. In addition, you can use the Velocity templating language. For more information about the Velocity template language, see the Velocity user's guide.

If you chose an output format of 'Wiki Markup', you must write the content of the template using Confluence wiki markup.

Note: When coding in wiki markup, you can use $body, $paramFoo and Velocity too, as described in detail below. For example:

Foo $!paramFoo Honk
$body
Bar
$action.getText('done.name')
Eek

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 enters the following on a Confluence page:

{helloworld}From Matthew{helloworld}

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, users can pass parameters to your user macro in the same way as any other macro:

  • When adding the macro via wiki markup, users can pass parameters separated by the pipe (|) sign.
  • 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

In summary, a parameter definition 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 internationalisation of the enum values.The value the user sees is the one passed to the macro as the parameter value, with the capitalisation 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 currently 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 currently 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".

This example shows how the parameters would be used on a wiki page: {macro:foo=value|bar=value}.

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

Other Objects Available to your Macro

As well as the macro body and parameters, there are a variety of Confluence objects available in the Velocity context. In addition to the default context, user macros also include the following:

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

For a list of objects available in the default Velocity context, see the developer documentation.

RELATED TOPICS

Writing User Macros
Examples of User Macros

Document generated by Confluence on Mar 16, 2011 18:31