独自のカスタム マクロを作成する場合、ユーザー マクロを使用すると便利です。これらは特定のアクションを実行、カスタムの初期設定を適用するなどの操作が可能です。 

ユーザー マクロは Confluence 内で作成および管理され、アドオンを開発する必要はありません。ただし、ある程度のコーディング スキルが必要となります。  

ユーザー マクロを作成して管理するには、システム管理者権限が必要となります。 

On this page:

関連ページ

Creating a User Macro

新しいユーザー マクロを追加するには:

  1. Go to  > General Configuration > User Macros.
  2. Choose Create a User Macro.
  3. マクロの詳細を入力します (以下の表を参照)。
  4. [追加] をクリックします。
マクロの詳細フィールド説明
macroNameコードに表示されるマクロ名です。
表示方法

マクロ ブラウザーまたはオートコンプリートでこのマクロを表示できるユーザーを制御します。オプションは次のとおりです。

  • すべてのユーザーに表示
  • システム管理者にのみ表示

「システム管理者にのみ表示」を選択した場合でも、ユーザーはページ上のマクロの出力を見ることができ、ユーザーがページを編集する際、マクロ プレースホルダーも表示されます。マクロ ブラウザーとオートコンプリートでのみ非表示になります。

マクロのタイトル、説明、パラメーター名およびその他のメタデータを含め、すべてのマクロ情報は検出可能です。システム管理者にのみ表示とマークされている場合であっても、ユーザー マクロの定義に機密データを含めないでください。

マクロ タイトルマクロ ブラウザーとオートコンプリートに表示されるタイトル。
説明 マクロ ブラウザーに表示される説明です。マクロ ブラウザーの検索は、タイトルと説明の両方の一致をピックアップします。
カテゴリマクロが表示されるマクロ ブラウザー カテゴリーを 1 つ以上選択します。
アイコンの URLマクロ ブラウザにマクロのアイコンを表示したい場合、絶対 URL (例: http://mysite.com/mypath/status.png) または Confluence ベース URL への相対パス (例: /images/icons/macrobrowser/status.png) を入力します。
ドキュメント URLマクロのドキュメントがある場合は、ここに URL を入力します。
マクロ本文処理

マクロに渡す前に Confluence が本体をどのように処理するかを指定します。

マクロ本文は、Confluence ページに表示されるコンテンツです。マクロに本文がある場合、ユーザーが入力する本文のコンテンツは、$body 変数のマクロで利用可能となります。

マクロ本体の処理オプション:

  • No macro body
    Select this option if your macro does not have a body.
  • Escaped
    Confluence will add escape characters to the HTML markup in the macro body. Use this if you want to show actual HTML markup in the rendered page. For example, if the body is <b>Hello World</b> it will render as  <b>Hello World</b>.
  • Unrendered
    HTML in the body will be processed within the template before being output. Ensure that HTML is ultimately output by the template.
  • Rendered
    Confluence will recognise HTML in the macro body, and render it appropriately. For example, if the body is <b>Hello World</b> it will render as Hello World.
テンプレート

ここで、マクロの動作を決定するコードを作成します。

  • Use HTML and Confluence-specific XML elements in the macro template. Details of Confluence's storage format are in Confluence Storage Format.
  • You can use the Velocity templating language. Here is more information on the Velocity project.
  • マクロに本文がある場合、"$body" を指定することでテンプレートでマクロの本文のテキストを参照できます。
  • Each parameter variable you use must have a matching metadata definition. Use @param to define metadata for your macro parameters.
  • When using the information passed using parameters, refer to your parameters as $paramXXX where 'XXX' is the parameter name that you specifed in the @param metadata definition.
  • Use @noparams if your macro does not accept parameters.

See User Macro Template Syntax for more information and examples.

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

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.

Editing a user macro

ユーザー マクロを編集するには

  1. Go to  > General Configuration > User Macros.
  2. Click Edit next to the relevant macro.
  3. Update the macro details as explained in the guide to writing user macros.
  4. 保存をクリックします。

Deleting a user macro

ユーザー マクロを削除するには:

  1. Go to  > General Configuration > User Macros.
  2. 現在設定されているユーザー マクロが表示されます。
  3. Click Delete next to the relevant macro.

Before deleting a user macro, you should search for all occurrences of the macro in pages and blog posts. Users will see an 'unknown macro' error if you delete a user macro that is still in use on a page.  

べスト プラクティス

このセクションには、独自のユーザー マクロを作成する際のベストプラクティスに関するヒントや提案が含まれています。

マクロ ヘッダーに説明的なヘッダーを追加する

テンプレート フィールドの一番上に、以下の用にコメントとして短い説明を含めることをお勧めします。 

## マクロ タイトル: マクロ名
## マクロに本文があるかどうか: Y / N
## 本文の処理: 選択した本文処理オプション
## 出力: 選択した出力オプション
##
## 開発者: My 名前
## 作成日: dd/mm/yyyy
## インストール担当者: 自分の名前

## マクロが行う動作の短い説明

マクロ ブラウザーにパラメーターを表示する

ユーザーがマクロを構成する最も簡単な方法はマクロ ブラウザーです。ユーザーはマクロ カテゴリーを指定、アイコンへリンク、およびマクロ ブラウザーがユーザーに情報を要求するために使用するパラメーターを定義するなどを行うことができます。

マクロ パラメーターのデフォルトの値を供給する

ユーザーがパラメーターを指定したかどうかはわからないため、マクロ コードで後から依存する予定がある場合、最初に、マクロで一部の値を受け取ったかどうかを確認する必要があります。

以下の例では、マクロは 3 つのパラメーターを期待し、指定されない場合は実用的な既定値に置き換えられます。

#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
  • ラベルなし