ユーザーマクロを書く

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

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,

Screenshot: Creating a User Macro



The sections below tell you about each of the input fields.

macroName

Enter the text that you and other users 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 enter the following on a Confluence page:

{floatright}

Macro Body

Tick 'Macro has a body' if you want to be able to pass text to the macro when you invoke it from within a page, for example like this:

{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 '<b>body</b>', 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 '<b>body</b>', it will be displayed as '<b>body</b>' 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.

出力

以下のオプションから１つ選択します:

• Macro generates HTML markup – Choose this if you wish to write your Template (see below) 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.

テンプレート

This specifies what the macro will do. Write this content 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'.

Add a descriptive header:
We recommend that you include a short description of your macro via comments at the top of the 'Template' field as follows. You can see an excellent example in the 'Image rollover' user macro.

## Macro name: My macro name
## Macro has a body: Y or N
## Body format: Selected formatting option
## Output: Selected output option
##
## Developed by: My Name
## Date created: dd/mm/yyyy
## Installed by: My Name

## Short description of what the macro does

例

Example 1: User Macro to Create a Red Box

As an example, let's write a simple macro that creates a red box (using an existing Confluence style) around some text. This may be 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="error">$body</div>

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 this:

{error}This is bad{error}

Your page would (magically!) have an error box on it, like this:

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. Parameters without a name are available in your template as $param1, $param2, ... $paramN. Named parameters are available as $paramfoo, $parambar for parameters named "foo" and "bar" like in this example: {macro:foo=value|bar=value}.

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'.

There are also 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 Confluence Objects Accessible From Velocity​.

For more information about the Velocity template language, see Velocity Template Overview​.

Best Practice Tips

This section contains tips and suggestions for best practice in macro coding.

1. Add a descriptive header to your macro template, as described CONFDEV:above.
   
   
2. Supply default values for macro parameters. You cannot guarantee that a user will supply parameters, so one of the first things to do in the macro is check that you have received some value if you expect to rely on it later on in the macro code. In the example below, the macro expects 3 parameters. It substitutes sensible defaults if they are not supplied:

   #set($spacekey= $paramspacekey)
   #set($numthreads= $paramnumthreads)
   #set($numchars= $paramnumchars)
   
   ## Check for valid space key, otherwise use current
   #if (!$spacekey)
     #set ($spacekey=$space.key)
   #end
   
   ## Check for valid number of threads, otherwise use default of 5
   #if (!$numthreads)
     #set ($numthreads=5)
   #end
   
   ## Check for valid excerpt size, otherwise use default of 35
   #if (!$numchars)
     #set ($numchars=35)
   #end
   

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.

関連トピック

User Macro Module​
Macro Module​
Confluence Plugin Guide​