みなさんの職場では、社内 wiki やドキュメントツールは何を使用されていますでしょうか。

など Markdown で書けてコラボレーションが可能なツールが出てきていますが、 その中でも昔から根強い人気を誇るのが Atlassian 製の Confluence です。

日本語検索が貧弱だったり、ドキュメント自体がプラグインを入れないと暗号化できなかったりと色々辛かったりしますが、 非エンジニアでも使える、マクロが豊富であるなどがあり選択されているところも多いかと思います。

しかし、そのマクロも有料版になると課金がユーザー数分跳ね上がり経費が多くかかることもあります。

今回はちょっとしたプラグインであれば、お金をかけずに拡張できるユーザーマクロを実例と交えて紹介していきます。

ユーザーマクロとは

本家のドキュメントにも記載されていますが、ユーザーマクロとは独自のカスタムマクロであり、特定のアクションの実行やカスタムの初期設定を適用するなどの操作が可能となります。

ユーザーマクロの作成や編集などの管理には、システム管理者権限が必要となります。

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

  1. 右上にある歯車マーク > 一般設定 > ユーザー マクロ に移動します。
  2. ユーザーマクロの作成を選択します。
  3. マクロの詳細を入力します。
  4. 追加をクリックします。

上記の作業をするだけで作成できます。 設定すべき項目が幾つかありますが、特に重要なのが

  • Macro Body Processing
  • Template

の2つです。

Macro Body Processing

そもそもマクロ本文とは、ユーザーがマクロを選択した際に、ユーザーが入力する本文のコンテンツのことです。

マクロ本文の例

No macro body

マクロ本文が必要ない際に使用します。

マクロ本文なしの例

Escaped

マクロ本文の HTML をエスケープする際に設定します。

エスケープ済みのイメージ1 エスケープ済みのイメージ2

上記の場合ですと、b タグがエスケープされないと太字になってしまいますが、エスケープすることによってそのまま表示されます。

Unrendered

マクロ本文に記載された HTML がテンプレートの部分で処理する際にはまだレンダリングされていない状態で使用できるようになります。

Rendered

マクロ本文に記載された HTML が適宜レンダリングされます。

Template

マクロの動作を司るコードを設定できます。 実態は Velocity のテンプレートとなっています。

マクロ本文が存在する場合、 $body という変数で参照することができます。

Template のベストプラクティス

Writing User Macros においても記載されていますが、 テンプレートはコードなので、テンプレートがどの環境・設定で動作を想定しているのかをテンプレートのヘッダーに記載しましょう。

## Macro title: マクロタイトル
## Description: A container within which to group AUI Tabs
## Categories: Confluence content
## Macro has a body: Y or N
## Body processing: Rendered
##
## Developed by: kenchan0130
## Date created: 2018/04/09
## Confluence version: 3.5
## Installed by: kenchan0130

ユーザーマクロの例

実際に作ってみないとわからないので、Confluence に標準では入っていないタブの機能を用意してみましょう。

テンプレートの準備

ベストプラクティスには書かれていませんでしたが、挿入するマクロのメインの親要素には

#set( $id = $action.dateFormatter.calendar.timeInMillis )

上記のように ID を付与することをオススメします。 なぜなら、エンドユーザーは定義したマクロを1ページ中に複数回使用する可能性があり、 一意特定できなくなってしまうと、セレクタなどがうまく動かずバグになってしまう可能性があるためです。

タブの中身

## Macro name: tab-content
## Macro title: Tab Content
## Description: A Tab content for Tabs Container
## Categories: Confluence content
## Macro has a body: Y
## Body processing: Rendered
##
## Developed by: kenchan0130
## Date created: 2018-04-15
## Installed by: kenchan0130
##
## @param TabName:title=TabName|type=string|required=true|desc=Please input tab name.

#set( $id = $action.dateFormatter.calendar.timeInMillis )

<div class="js-tabs-pane" id="tab-$id" data-name="$paramTabName">
$body
</div>

@param というのは、マクロの挿入時に渡せるパラメーターです。 テンプレート内では、 $param定義した名前 で参照することができます。 また、複数パラメーターを用意することもできます。 詳しくは User Macro Template Syntax を御覧ください。

タブ全体のコンテナ

## Macro name: tabs-container
## Macro title: Tabs Container
## Description: A container within which to group Tabs
## Categories: Confluence content
## Macro has a body: Y
## Body processing: Rendered
##
## Developed by: kenchan0130
## Date created: 2018-04-15
## Installed by: kenchan0130
##
## @noparams

#set( $uniqueId = $action.dateFormatter.calendar.timeInMillis )

<div id="tabs-$uniqueId" class="dvdsmpsn user-macro aui-tabs horizontal-tabs">
$body
</div>

<script>
AJS.toInit(function(jQuery) {
  var tabsContainer = jQuery('#tabs-$uniqueId');
  tabsContainer.prepend('<ul class="tabs-menu"></ul>');
  tabsContainerFirstUl = tabsContainer.find('ul:first');

  tabsContainer.find('.js-tabs-pane').each(function() {
    var tabLabel = jQuery('<a>').attr({
      href: '#' + jQuery(this).attr('id')
    }).text(jQuery(this).data('name'));
    var tabLi = jQuery('<li>').addClass('js-menu-item').append(tabLabel);
    tabsContainerFirstUl.append(tabLi);
  });

  tabsContainer.find('li.js-menu-item:first').addClass('active-tab');
  tabsContainer.find('.js-tabs-pane:first').addClass('active-pane');

  tabsContainer.find('.js-menu-item').click(function() {
    jQuery(this).addClass('active-tab').siblings().removeClass('active-tab');
    jQuery(jQuery(this).find('a:first').attr('href')).addClass('active-pane').siblings().removeClass('active-pane');
    return false;
  });

  AJS.tabs.setup();
});
</script>

パラメーターがある場合は @param を記載していましたが、パラメーターが必要ない場合は @noparam を指定しましょう。 細かい挙動に関しては JavaScript の話ですので、ここでは割愛します。

また、 AJS という Confluence が jQuery などをラップしたオブジェクトを用意しており、 Confluence を拡張する際に使用できます。

マクロの登録

ベストプラクティス通り、コメント設定すべき内容がテンプレートにほぼ記載されているため、 内容を確認しつつマクロを登録していきます。

ユーザーマクロブラウザの作成

アイコンの URL を指定しておくと、ユーザーマクロを選択する際に視認性が増す効果があります。

ユーザーマクロの設定

設定項目を入れたら、最後はテンプレートを挿入して保存ボタンを押すとマクロの作成が完了です。

まずは、マクロブラウザの設定項目の マクロブラウザーは管理者のみ表示されます を選択して、管理者のみで挙動を確認して、確認が終了したら マクロブラウザーで全てのユーザーに表示されます を選択してエンドユーザーに使用可能になった旨を通知すると良いと思います。

まとめ

Confluence のユーザーマクロについて紹介しました。 Web の技術がほぼ全て使用できるので、拡張性は無限大です。

ユーザーマクロを使用することでコスト削減が可能となります。 もちろんメンテナンスなど工数がかさむ可能性もあるため、機能によっては有料のプラグインを入れることも検討しましょう。

是非ステキな Confluence 生活を送って行きましょう。