ソースを表示する

User macros allow you to create simple formatting macros using the Confluence web interface.

If you want to distribute your user macro as a plugin, please see User Macro Plugins. If you want to create more complex, programmatic macros in Confluence, you may need to write a Macro Plugin. Note also that Macro Plugins and User Macro Plugins can appear in the Confluence Notation Guide, whereas User Macros do not. Here is an example of the Confluence Notation Guide.

You need to have System Administrator permissions in order to create user macros.

On this page:

Creating a User Macro

To create a user macro,

Go to the 'Administration Console' and click 'User Macros' in the left-hand panel.
Click 'Create a User Macro' at the top of the list of macros.
Supply the information in the input fields as explained below, then click the 'Save' button.

Screenshot: Creating a User Macro

Confluence 2.10 > User Macros > create-user-macro.PNG

Input fields:

'Macro Name' — Enter the text that you will type, within curly brackets, to invoke the macro from within a page. For example, to invoke the 'floatright' macro defined in the above screenshot, you would type:
{floatright}
'Macro has a body' — Check this box if you will pass body-text to the macro when you invoke it from within a page, e.g. :
{floatright}my text{floatright}
If you select 'Macro has a body', anything the user types within the body of the macro will be available in the macro in the $body variable. The options below allow you to tell Confluence to pre-process the body before it is placed in the macro output:
- Use unprocessed macro body — The body of the macro will be output exactly as entered, including any HTML markup. For example if the macro body is body, it will be displayed as body in the page.
- Escape HTML in macro body — The body of the macro will be output with HTML markup escaped. So if the macro body is body, it will be displayed as body in the page.
- Convert macro body wiki markup to HTML — The body of the macro will be converted from wiki text to HTML markup. So if the macro body is *body*, it will be displayed as body in the page.
'Output' — Choose one of the following options:
- 'Macro generates HTML markup' — Choose this if you wish to write your Template in HTML markup (as shown in the above screenshot).
- 'Macro generates wiki markup' — Choose this if you wish to write your Template in wiki markup.
'Template' — This specifies what the macro will do. Write this using the Velocity templating language. Here is more information on the Velocity project.
Note: If you ticked Macro has a body, your template can refer to the body-text by specifying $body.

例

Example 1: User Macro to Create a Red Box

As an example, let's write a simple macro that simply creates a red box (using an existing Confluence style) around some text (useful for writing about error conditions for example - hence the macro name 'error').

After clicking "New User Macro", enter error as the Name of your macro, and then put the following in the Template text area:

<div class="errorbox">$body</div>

Then click Add. You should now see your new macro in the User Macros library, and you can now enable and disable it individually.
To use the macro within a page, you would add notation like:

{error}This is bad{error}

And your page would (magically!) have an error box on it, like so:

This is bad

Example 2: User Macro to Display 'Hello World'

Take a look at an example of a 'Hello World' macro.

Example 3: User Macro to Demonstrate the Use of Parameters

This example demonstrates how you can pass parameters into your macro. Let's say you want to write your own font colour macro:

<span style="color: $param0">$body</span>

The usage of this macro would be:

{colour:red}Some example text{colour}

which will produce:
Some example text

If your macro requires more than one parameter, you can use variables $param0 to $param9 to represent them. To specify multiple parameters, use:

{colour:red|blue|green}

Where red, blue and green are the 1st, 2nd and 3rd parameters respectively.

Alternatively, you can also use explicitly named parameters in your macro. These macro parameters will appear as variables with the name $param<x> where <x> is the name of your parameter. To specify named parameters, use:

{style:colour=red}

In your user macro you can then use $paramcolour which will have the value red in this case.

Available Objects

The user macro above uses the $body object, which is available for use within your user macro template if the macro has a body.

You can pass parameters to your user macro in the same way as any other macro, separated by the pipe | sign. These parameters are provided to your template as param1, param2, ... paramN.

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

You can read more about object usage in the Velocity Template Overview.

User Macro Library

Below is a list of existing user macros, written by other Confluence users. If you wish, you can install these on your Confluence site.