Confluence 3.5 : Guide to User Macro Templates
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.
The rest of this page gives more details of the above procedure. On this page: Coding in HTML or Wiki MarkupIf 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 BodyUse 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. Hello World: $body A user enters the following on a Confluence page: {helloworld}From Matthew{helloworld} The wiki page will display the following:
Using Parameters in your User MacroYou 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 PageWhen adding a macro to a Confluence page, users can pass parameters to your user macro in the same way as any other macro:
Defining the ParametersIn summary, a parameter definition contains:
Format: ## @param MYNAME:title=MY TITLE|type=MY TYPE|desc=MY DESCRIPTION|required=true|multiple=true|default=MY DEFAULT VALUE Additional notes:
The sections below describe each of the attributes in detail.
Parameter NameThe 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 TypeThe field type for the parameter. If you do not specify a type, the default is string.
Using the Parameters in your Macro CodeThe 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 ParametersIf 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 MacroAs 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:
For a list of objects available in the default Velocity context, see the developer documentation. RELATED TOPICS |
![]() |
Document generated by Confluence on Mar 16, 2011 18:31 |