クラウド
Data Center 9.0
バージョン

ユーザーマクロを書く

Confluence 管理者ガイド

このページの内容

このセクションの項目

関連コンテンツ

  • 関連コンテンツがありません

お困りですか?

アトラシアン コミュニティをご利用ください。

コミュニティに質問

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

ユーザー マクロは Confluence 内で作成および管理されているため、自身でアプリ (プラグイン) を開発する必要はありません。ただし、ある程度のコーディング スキルが必要となります。  

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

On this page:

関連ページ

ユーザー マクロを作成する

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

  1. Go to Administration  > General Configuration > User Macros.
  2. Select Create a User Macro.
  3. Enter the macro details (see table below).
  4. [追加] を選択します。
マクロの詳細フィールド説明
macroNameコードに表示されるマクロ名です。
表示方法

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

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

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

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

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

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

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

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

  • マクロ本文なし
    マクロに本文がない場合に選択します。
  • エスケープ済み
    Confluence は、マクロ本文の HTML マークアップにエスケープ文字を追加します。レンダリング後のページで実際の HTML マークアップを表示したい場合にこれを使用します。たとえば、本文が <b>Hello World</b> の場合、<b>Hello World</b>. としてレンダリングされます。
  • レンダリングされていない
    本文内の HTML は、出力前にテンプレート内で処理されます。HTML が、最終的にはテンプレートによって出力されていることを確認してください。
  • レンダリング済み
    Confluence はマクロ本体で HTML を認識し、適宜レンダリングします。たとえば、本文が <b>Hello World</b> の場合は、Hello World とレンダリングされます。
テンプレート

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

  • マクロテンプレートで HTML および Confluence 固有の XML 要素を使用します。
  • Velocity テンプレート言語を使用できます。Velocity プロジェクトの詳細をご確認ください。
  • マクロに本文がある場合、"$body" を指定することでテンプレートでマクロの本文のテキストを参照できます。
  • 使用する各パラメーター変数に、一致するメタデータ定義が必要です。マクロ パラメーターのメタデータを定義するには、@param を使用します。
  • パラメーターを使用して渡された情報を使用する場合、パラメーターを $paramXXX として参照します。"XXX" は @param メタデータ定義で指定したパラメーターです。
  • マクロがパラメーターを許可しない場合は @noparams を使用します。

詳細と例については、「ユーザー マクロ テンプレート構文」を参照してください。

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

ユーザー マクロをプラグインとして配信する場合は、ユーザー マクロ プラグイン モジュール」に関する開発者ガイドを参照してください。Confluence でより複雑な、プログラミングを使用したマクロを作成したい場合は、マクロ プラグインの記述が必要となる場合があります。

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

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

  1. Go to Administration  > General Configuration > User Macros.
  2. Select Edit next to the relevant macro.
  3. Update the macro details.
  4. [保存] を選択します。

ユーザー マクロの削除

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

  1. Go to Administration  > General Configuration > User Macros.
  2. The currently configured user macros will appear.
  3. Select Delete next to the relevant macro.

ユーザー マクロを削除する前に、ページやブログ投稿でのそのマクロの使用箇所をすべて 検索 する必要があります。ページ上でまだ使用されているユーザー マクロを削除すると、ユーザーに「不明なマクロ」エラーが表示されます。  

べスト プラクティス

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

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

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

## Macro title: My macro name
## Macro has a body: Y or N
## Body processing: Selected body processing option
## Output: Selected output option
##
## Developed by: My Name
## Date created: dd/mm/yyyy
## Confluence version: Version it was developed for
## Installed by: My Name

## Short description of what the macro does

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

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

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

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

以下の例では、マクロは 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

セキュリティへの影響を考慮する

また、ユーザーが表示権限を持っていないコンテンツを誤って表示してしまうのを防ぐため、制約付きのページやスペース権限など、多数の権限シナリオでユーザー マクロを徹底的にテストすることをお勧めします。詳細については、「ユーザー マクロ テンプレート構文」を参照してください。 

ユーザー マクロの例

Hello World

この例では、テキスト「Hello World!」を表示するユーザーマクロや、ユーザーがマクロ本文に配置するテキストの作成方法を示します。

フィールド値
macroNamehelloworld
表示方法Visible to all users in the Macro Browser
マクロ タイトルHello World
説明 Displays "Hello World" and the macro body.
カテゴリConfluence Content
アイコンの URLこのフィールドは空白のまま残すことができます
ドキュメント URLこのフィールドは空白のまま残すことができます
マクロ本文処理レンダリング済み
テンプレート

テンプレート フィールドに以下のコードを入力します。この例では、テキストをページ上に直接プリントします。

## @noparams
Hello World!
$body

テキストをパネルに表示させたい場合は、ここに示すように、関連 AUI メッセージ クラスを含めることができます。

## @noparams
<div class="aui-message closeable">
Hello World!
$body
</div>

ページでの 'Hello World' マクロの使用

マクロ ブラウザーを使用するか、エディターに「{hello」と入力し、候補のリストからマクロを選択して、Confluence ページにマクロを追加することができるようになりました。

結果は次のようになります。

NoPrint

この例では、ページを表示した際に見えるけれども印刷できないテキストをふくめることができるユーザー マクロの記述用法を示しています。

フィールド値
macroNamenoprint
表示方法Visible to all users in the Macro Browser
マクロ タイトルNo Print
説明 Hides text from printed output.
カテゴリConfluence Content
アイコンの URLこのフィールドは空白のまま残すことができます
ドキュメント URLこのフィールドは空白のまま残すことができます
マクロ本文処理Rendered
テンプレート

テンプレート フィールドに以下のコードを入力します。

## @noparams
<div class="noprint">$body</div>

Using the “NoPrint” Macro on a page

マクロ ブラウザーを使用いて、Confluence ページにマクロを追加できるようになりました。マクロ プレースホルダーの本文に入力れたテキストは印刷されませんが、ページをオンラインで閲覧したときに表示されます。

PDF エクスポートが NoPrint マクロを認識するようにする

PDF エクスポートの高度なカスタマイズを参照してください。


色とサイズ

この例は、パラメーターをマクロに渡す方法を示しています。ユーザーに対し、マクロ本文に含まれるテキストの色とサイズの指定を許可する 2 つのパラメーターを持つ、フォント スタイル マクロを作成します。

フィールド値
macroNamestylish
表示方法Visible to all users in the Macro Browser
マクロ タイトルStylish
説明 Applies colour and size to text.
カテゴリConfluence Content
アイコンの URLこのフィールドは空白のまま残すことができます
ドキュメント URLこのフィールドは空白のまま残すことができます
マクロ本文処理Rendered
テンプレート

テンプレート フィールドに以下のコードを入力します。マクロで 1 つ以上のパラメーターが必要な場合、$param0 から $param9 の変数を使用してそれらを表すことができます。

## @param 0:title=colour|type=string
## @param 1:title=size|type=string
<span style="color: $param0; font-size: $param1">$body</span>

また、マクロで明示的に名前の付いたパラメターを使用することもできます。これらのマクロ パラメーターは $param<x> という名前の変数として表示されます。<x> はパラメーターの名前です。 

## @param Colour:title=colour|type=string
## @param Size:title=size|type=string
<span style="color: $paramColour; font-size: $paramSize">$body</span>
書式設定済みパネル

この例では、特定の色を使用した書式設定済みパネルを作成するユーザー マクロの記述用法を示しています。次のようなパネルを作成します。

(タイトル)


注:ユーザーがタイトル パラメーターに値を指定しない場合、パネルのタイトルは空になります。

フィールド値
macroNameformpanel
表示方法Visible to all users in the Macro Browser
マクロ タイトル書式設定済みパネル
説明 特定の色で事前定義されたパネルを作成する
カテゴリFormatting
アイコンの URLこのフィールドは空白のまま残すことができます
ドキュメント URLこのフィールドは空白のまま残すことができます
マクロ本文処理エスケープ済み
テンプレート

テンプレート フィールドに以下のコードを入力します。詳細は、以下のコードの詳細な説明を参照してください。

## @param Title:title=Title|type=string|desc=Title
<ac:structured-macro ac:name="panel">
        <ac:parameter ac:name="titleBGColor">#ccc</ac:parameter>
        <ac:parameter ac:name="borderStyle">solid</ac:parameter>
        <ac:parameter ac:name="borderColor">#6699CC</ac:parameter>
        <ac:parameter ac:name="borderWidth">2</ac:parameter>
        <ac:parameter ac:name="titleColor">#000000</ac:parameter>
    <ac:parameter ac:name="title">$!paramTitle</ac:parameter>
    <ac:rich-text-body>$body</ac:rich-text-body>
</ac:structured-macro>

マクロ テンプレートのコードの例

ユーザー マクロ テンプレート コードの内訳を以下に示します。 

項目説明 
## @param Title:title=Title|type=string|desc=Title

@param はマクロ パラメータのメタデータを定義します。

@param Title

このパラメーターは "Title" ト呼ばれます。

title=Title

マクロ ブラウザーに "Title" として表示されるパラメーター タイトルを定義します。

type=string

は、パラメーターのフィールド タイプをテキスト フィールドとして定義します。

desc=Title

は、マクロ ブラウザー内のパラメーターの説明を定義します。

<ac:structured-macro ac:name="panel">

これを、Confluence パネル マクロト呼びます。

Confluence マウロのコード名を見つける最も簡単な方法は、マクロを含むページのストレージ形式を表示することです。ストレージ形式を見るには、Confluence 管理者権限が必要になります。

<ac:parameter ac:name="titleBGColor">#ccc</ac:parameter>
<ac:parameter ac:name="borderStyle">solid</ac:parameter>
<ac:parameter ac:name="borderColor">#6699CC</ac:parameter>
<ac:parameter ac:name="borderWidth">2</ac:parameter>
<ac:parameter ac:name="titleColor">#000000</ac:parameter>

パラメーターをマクロに設定する: 背景色、枠線スタイル、枠線の色、枠線の幅およびタイトルの色。

Confluence マクロのパラメーター名を見つけるには、上記のようにストレージ形式を確認してください。

<ac:parameter ac:name="title">$!paramTitle</ac:parameter>

'Title' パラメーターに保存されている値を、マクロの title セクションに入力します。

「!」は、「タイトル」パラメーターにデータがないときに、タイトルを空白のまま残すようマクロに伝えます。

<ac:rich-text-body>$body</ac:rich-text-body>

ユーザーは、マクロの本文に保存されているデータを使用できます。この行により、マクロはマクロに渡された本文コンテンツへのアクセスと保存が可能になります。

</ac:structured-macro>

このコマンドは、マクロの終了を示します。


コンテキスト変数

既定では、ユーザー マクロは次のベロシティ コンテキスト変数にのみアクセスできます。

  • $generalUtil

  • $htmlUtil

ユーザー マクロに既定のベロシティ コンテキストの追加変数へのアクセスを許可するには、macro.required.velocity.context.keys システム プロパティを使用して、変数をコンマ区切り形式で指定します。既定のベロシティ コンテキストで使用可能な変数のリストを確認してください。

たとえば、$authenticatedUser と $action へのアクセスを許可するには、VM オプションとして -Dmacro.required.velocity.context.keys=authenticatedUser,action のように定義できます。

システム プロパティの設定方法をご確認ください。

メソッドの許可リスト

Confluence 9.0 以降では、ベロシティ メソッドの許可リストと呼ばれるセキュリティ機能が新たに導入され、ユーザー マクロを含め、ベロシティ テンプレート内のすべてのメソッド呼び出しを明示的に許可リストに登録する必要があります。

アトラシアンは、一般的で既知の安全なメソッドのリストをあらかじめ作成して承認しています。ただし、ユーザー マクロのプレビュー時に生成されたログ警告出力に基づいて、ユーザー マクロ内の他のメソッドを手動で許可リストに登録する必要がある場合があります。

ユーザー マクロを定義して保存したら、新しいページに追加してみてください。次のようなログ警告が表示された場合は、これらのメソッドを手動で許可リストに登録する必要があります (右にスクロールすると完全な例が表示されます)。

16:21:05,888 WARN [http-nio-8080-exec-6] [velocity] log Invocation blocked as method is not allowlisted: com.atlassian.confluence.setup.settings.DarkFeatures#isDarkFeatureEnabled(java.lang.String)

ログから収集されたメソッドのリストは、システム管理者が atlassian.velocity.method.allowlist.extra システム プロパティを使用して許可リストに登録できます。

たとえば、次の VM オプションを使用して 2 つのサンプル メソッドを許可リストに登録できます (右にスクロールすると完全な例が表示されます)。

"-Datlassian.velocity.method.allowlist.extra=com.atlassian.confluence.setup.settings.DarkFeatures#isDarkFeatureEnabled(java.lang.String),com.atlassian.confluence.extra.dynamictasklist2.NameRenderer#render(java.lang.String boolean)"

値が正しく設定されていないか解析できない場合は、Confluence の起動時に問題を示す警告が記録されます。


tip/resting Created with Sketch.

Confluence を使いこなす

マクロの作成が難しい場合、Atlassian Marketplace で多数の無料および有料マクロが提供されています。最も人気のあるマクロの一部を紹介します。

  • Numbered Headings: 見出しに自動的に番号を付与し、ナビゲーションおよびドキュメント作成を支援
  • HideElements for Confluence: いくつかの Confluence ページ要素 (例: タイトル、コメント、ボタン) をワンクリックで非表示に
  • Composition Tabs & Page Layout: タブ、ハイライト、インスタント フォーカス、メニュー、および拡張可能なセクションでコンテンツを強化

次のステップ

ユーザー マクロの力をさらに詳しく調べるには、「高度なユーザー マクロを記述する」ガイドを参照してください。

最終更新日: 2024 年 12 月 9 日

この内容はお役に立ちましたか?

はい
いいえ
この記事についてのフィードバックを送信する

このセクションの項目

関連コンテンツ

  • 関連コンテンツがありません
Powered by Confluence and Scroll Viewport.