ユーザーマクロを書く

User macros are short pieces of code that perform an often-used function or add some custom formatting to a page. People can call the macro into action by adding the macro keyword to their Confluence pages. You can write a user macro by adding code on a screen in the Confluence Administration Console.

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

代わりにプラグインが必要ですか?

If you want to distribute your user macro as a plugin, please refer to the developer's guide to the User Macro plugin module. If you want to create more complex, programmatic macros in Confluence, you may need to write a Macro plugin. Note also that Macro modules and User Macro modules can appear in the Confluence Notation Guide, whereas user macros cannot.

On this page:

Creating a User Macro

To create a user macro,

Go to the Confluence Administration Console and click 'User Macros' in the left-hand panel.
Click the link on the text 'Click here to create a new 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.

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, if you enter a macro name of 'status', then you would enter the following wiki markup on a Confluence page to invoke the macro:

{status}

Partial screenshot: Entering the macro name when creating a user macro

表示方法

Set the visibility options to specify who can see this macro when they are searching via the Macro Browser or Autocomplete.

The options are as follows:

Visibility Option

意味

すべてのユーザーに表示

All users will see this macro when searching for a macro via the Macro Browser or Autocomplete.

システム管理者にのみ表示

Choose this option if you want the macro to be 'hidden' from most users when the users are looking for a macro to add to a page. Note that this does not completely hide the macro. Instead, it us useful if you want to avoid cluttering the Macro Browser and Autocomplete with unnecessary macros. Specifically:

Editing a page and inserting a macro via the Macro Browser: Only system administrators will see this macro in the Macro Browser. For other users, the macro will not show up in the Macro Browser when the user searches for a macro to add to a page.
Editing a page and inserting a macro via Autocomplete: Only system administrators will see this macro in Autocomplete. For other users, the macro will not show up in the Autocomplete list when the user searches for a macro to add to a page.
Editing a page and inserting a macro via wiki markup: Anyone who knows the wiki markup can insert the macro.
Viewing the page: The macro output will be visible to all users who have permission to see the page.
Editing a page that already contains the macro: Provided a user has permission to edit the page, the macro will be visible to all users when editing the page, and all users who have permission to edit the page will also be able to edit or remove the macro.
Additional notes. Please note that all the macro information will also be discoverable, including the macro title, description, parameter names and other metadata. Do not include confidential data anywhere in the definition of a user macro, even if it is marked as visible only to system administrators.

Partial screenshot: Visibility

マクロタイトル

Enter the text that should appear in the Macro Browser and in Autocomplete, to identify this macro when people are looking for it to insert onto a page.

Partial screenshot: Macro Title

説明

Enter the text that should appear in the Macro Browser describing this macro. Note that the Macro Browser's search will pick up matches in the description as well as in the title.

Partial screenshot: Macro Description

カテゴリ

Select one or more categories for your macro. To select more than one category, hold down the 'Ctrl' key while selecting. These are the categories that appear in the Macro Browser, helping users to choose a macro from a logical set.

Partial screenshot: Macro Categories

アイコンの URL

If you would like the Macro Browser to display an icon for your macro, enter the URL here. You can enter an absolute URL or a path relative to the Confluence base URL. For example:

Absolute URL:
```
http://mysite.com/mypath/status.png
```
Relative URL:
```
/images/icons/macrobrowser/status.png
```

Partial screenshot: Icon URL

ドキュメント URL

Enter the URL pointing to the online help or other documentation for your macro.

Partial screenshot: Documentation URL

マクロ本文処理

Specify how you want Confluence to process the body of your macro before passing it to your macro. Below is an explanation of the macro body and the options available.

What is the macro body?

The macro body is the content on the wiki page between the macro start tag and end tags. If the macro allows a body, users will be able to enter content into the macro body.

How can I use the macro body?

If you specify that your macro has a body, you will be able to pass text to the macro when you invoke it from within a page. For example:

{expand}My expandable/collapsible text.{expand}

If your macro has a body, anything the user types within the body of the macro will be available to the macro in the $body variable. See the section about the template below. In addition, the options below allow you to tell Confluence to pre-process the body before it is placed in the macro output.

What are the options for macro body?

Body Processing Option	意味
No macro body	Select this option if your macro does not need a body.
Render HTML	If your macro has a body, and you make use of the body as `$body` in your template, Confluence will recognise HTML in the macro body. For example, if the body is: <b>Hello World</b> Then value of $body will be: <b>Hello World</b> If your 'Output Format' is 'HTML', the above will render as: Hello World
Escape HTML	If your macro has a body, and you make use of the body as `$body` in your template, Confluence will add escape characters to the HTML markup in the macro body. You could use this if you want to show the HTML markup in the rendered page. For example, if the body is: <b>Hello World</b> Then value of $body will be: <b>Hello World</b> If your 'Output Format' is 'HTML', the above will render as: <b>Hello World</b>
Convert wiki markup to HTML	If your macro has a body, and you make use of the body as `$body` in your template, Confluence will recognise wiki markup in the macro body and will convert it to HTML. For example, if the body is: Hello World Then value of $body will be: <b>Hello World</b> If your 'Output Format' is 'HTML', the above will render as: Hello World

Partial screenshot: Macro Body Processing

Output Format

Select the markup format that you will use when coding the macro processing in the macro template (see below). If you want to code in HTML (Velocity), select HTML. If you want to code in wiki markup, select that.

Note: If you select the macro body processing option of 'Convert wiki markup to HTML' with an output format of 'Wiki Markup', you will get unexpected results. The rendered HTML is escaped, as if the user had typed HTML into the page.

Partial screenshot: Output Format_

テンプレート

Enter code to specify what the macro will do.

クイックガイド:

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.
マクロに本文がある場合、"$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.

See our detailed guide to writing a user macro template.

Examples and Best Practices

参照先:

ページツリー