ユーザーマクロを書く
独自のカスタム マクロを作成する場合、ユーザー マクロを使用すると便利です。これらは特定のアクションを実行、カスタムの初期設定を適用するなどの操作が可能です。
ユーザー マクロは Confluence 内で作成および管理されているため、自身でアプリ (プラグイン) を開発する必要はありません。ただし、ある程度のコーディング スキルが必要となります。
ユーザー マクロを作成して管理するには、システム管理者権限が必要となります。
ユーザー マクロを作成する
新しいユーザー マクロを追加するには:
- [管理] > [一般設定] > [ユーザー マクロ] に移動します。
- ユーザー マクロの作成を選択します。
- マクロの詳細を入力します (以下の表を参照)。
- 追加をクリックします
マクロの詳細フィールド | 説明 |
---|---|
macroName | コードに表示されるマクロ名です。 |
表示方法 | マクロ ブラウザーまたはオートコンプリートでこのマクロを表示できるユーザーを制御します。オプションは次のとおりです。
「システム管理者にのみ表示」を選択した場合でも、ユーザーはページ上のマクロの出力を見ることができ、ユーザーがページを編集する際、マクロ プレースホルダーも表示されます。マクロ ブラウザーとオートコンプリートでのみ非表示になります。 マクロのタイトル、説明、パラメーター名およびその他のメタデータを含め、すべてのマクロ情報は検出可能です。システム管理者にのみ表示とマークされている場合であっても、ユーザー マクロの定義に機密データを含めないでください。 |
マクロ タイトル | マクロ ブラウザーとオートコンプリートに表示されるタイトル。 |
説明 | マクロ ブラウザーに表示される説明です。マクロ ブラウザーの検索は、タイトルと説明の両方の一致をピックアップします。 |
カテゴリ | マクロが表示されるマクロ ブラウザー カテゴリーを 1 つ以上選択します。 |
アイコンの URL | マクロ ブラウザにマクロのアイコンを表示したい場合、絶対 URL (例: http://mysite.com/mypath/status.png ) または Confluence ベース URL への相対パス (例: /images/icons/macrobrowser/status.png ) を入力します。 |
ドキュメント URL | マクロのドキュメントがある場合は、ここに URL を入力します。 |
マクロ本文処理 | マクロに渡す前に Confluence が本体をどのように処理するかを指定します。 マクロ本文は、Confluence ページに表示されるコンテンツです。マクロに本文がある場合、ユーザーが入力する本文のコンテンツは、 マクロ本体の処理オプション:
|
テンプレート | ここで、マクロの動作を決定するコードを作成します。
詳細と例については、「ユーザー マクロ テンプレート構文」を参照してください。 |
代わりにプラグインが必要ですか?
ユーザー マクロをプラグインとして配信する場合は、ユーザー マクロ プラグイン モジュール」に関する開発者ガイドを参照してください。Confluence でより複雑な、プログラミングを使用したマクロを作成したい場合は、マクロ プラグインの記述が必要となる場合があります。
ユーザー マクロを編集する
ユーザー マクロを編集するには
- [管理] > [一般設定] > [ユーザー マクロ] に移動します。
- 関連マクロの隣にある 編集 をクリックします。
- マクロの詳細を更新する
- 保存 をクリックします。
ユーザー マクロの削除
ユーザー マクロを削除するには:
- [管理] > [一般設定] > [ユーザー マクロ] に移動します。
- 現在設定されているユーザー マクロが表示されます
- 関連するマクロの横にある 削除 をクリックします。
ユーザー マクロを削除する前に、ページやブログ投稿でのそのマクロの使用箇所をすべて 検索 する必要があります。ページ上でまだ使用されているユーザー マクロを削除すると、ユーザーに「不明なマクロ」エラーが表示されます。
べスト プラクティス
このセクションには、独自のユーザー マクロを作成する際のベストプラクティスに関するヒントや提案が含まれています。
マクロ ヘッダーに説明的なヘッダーを追加する
テンプレート フィールドの一番上に、以下の用にコメントとして短い説明を含めることをお勧めします。
## 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
セキュリティへの影響を考慮する
また、ユーザーが表示権限を持っていないコンテンツを誤って表示してしまうのを防ぐため、制約付きのページやスペース権限など、多数の権限シナリオでユーザー マクロを徹底的にテストすることをお勧めします。詳細については、「ユーザー マクロ テンプレート構文」を参照してください。
ユーザー マクロの例
Context variables
By default, User macros have access only to the following Velocity context variables:
$generalUtil
$htmlUtil
To grant User macros access to additional variables in the default Velocity context, use the system property macro.required.velocity.context.keys
and specify the variables in a comma-separated format. Check out the list of available variables in the default Velocity context
For example, to grant access to $authenticatedUser
and $action
, you can define the following VM option: Dmacro.required.velocity.context.keys=authenticatedUser,action.
Discover how to configure system properties
Method allowlist
Starting with Confluence 9.0, a new security feature called the Velocity method allowlist requires that all method invocations within a Velocity template, including User macros, be explicitly allowlisted.
Atlassian has already generated and approved a list of common and known safe methods. However, you may still need to manually allowlist additional methods in your User Macros based on the log warning output generated when previewing your User Macro.
After defining and saving your User Macro, try adding it to a new page. If you see log warnings like the ones below, you'll need to manually allowlist these methods:
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)
This list of methods collected from the logs can then be allowlisted by a system administrator using the atlassian.velocity.method.allowlist.extra
system property.
As an example, you may allowlist two sample methods using the following VM option:
"-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)"
If the value is configured incorrectly or can't be parsed, Confluence will log warnings during startup to indicate the issue.
Confluence を使いこなす
マクロの作成が難しい場合、Atlassian Marketplace で多数の無料および有料マクロが提供されています。最も人気のあるマクロの一部を紹介します。
- Numbered Headings: 見出しに自動的に番号を付与し、ナビゲーションおよびドキュメント作成を支援
- HideElements for Confluence: いくつかの Confluence ページ要素 (例: タイトル、コメント、ボタン) をワンクリックで非表示に
- Composition Tabs & Page Layout: タブ、ハイライト、インスタント フォーカス、メニュー、および拡張可能なセクションでコンテンツを強化
次のステップ
ユーザー マクロの力をさらに詳しく調べるには、「高度なユーザー マクロを記述する」ガイドを参照してください。