Confluenceのユーザーマクロ作成の基本

コンフルエンスには記事（ページ）を手軽にリッチにするための様々なマクロが用意されています。
例
[Confluence マクロ 解説；ページプロパティレポートとページプロパティ](http://qiita.com/kajinari/items/e27b010ea310b6c44d8f)
[confluence > 情報をexpand/collapseしたい > 展開マクロを使う](http://qiita.com/7of9/items/e6463ccdb5522d4bf790)

この記事ではそんなマクロを自作するときの基本について書きたいと思います。
この記事で扱うコンフルエンスのバージョンは5系になります

※ちなみにユーザーマクロを自作するには権限が必要なのでその辺は管理者の方と相談してください。

# 公式ドキュメント系
はじめに私が参考にした公式ドキュメントのリンクを貼っておきます。
ユーザーマクロを書く
https://confluence.atlassian.com/conf53/writing-user-macros-411108914.html

サンプル集
https://confluence.atlassian.com/conf53/examples-of-user-macros-411108916.html

日本語も少しはあったような気がするんですけど改めてブックマークみたら英語しかなかったです。
私が英語があまりよくわからないので、よくわからないです。

# ユーザーマクロ編集画面
ではさっそくマクロを作る画面の説明を始めます。
以下はそのページの一部を切り取ったものです。
![スクリーンショット 2016-12-14 12.29.05.png](https://qiita-image-store.s3.amazonaws.com/0/149859/813d2d35-7ec6-91ca-2347-7d924209aef4.png)
本当はこの画面には他にも項目があるんですけど、`マクロ名`とか見ればわかるものばかりなので省略しています。
この記事では最も重要な部分となるこの`ユーザーマクロの設定`について説明していきます。

※ちなみにテンプレート内に色々書いてありますがこれはもともと書いてあったもので、私が書いたものはありません。なので今回はスルーします。

## マクロ本体の処理
まず`マクロ本体の処理`についてです。
ここでは４つのタイプからマクロのタイプを選択します。

### 1. マクロ本文はありません
最初は意味がわからなかったんですが、これは**Bodyがないマクロ**になります。Body(テンプレートとは別)がないっていうのは
<img width="93" alt="目次.png" src="https://qiita-image-store.s3.amazonaws.com/0/149859/b9c7d07e-4136-888e-7fae-1d1ac780876e.png">
上記の目次マクロみたい中身を書き込む必要がないマクロです。
逆にBodyがあるマクロというのは、
<img width="398" alt="コードブロック.png" src="https://qiita-image-store.s3.amazonaws.com/0/149859/fc4265e3-e3b6-2970-5447-be0c74779bb7.png">
コードブロックのように中身があって初めて真価を発揮するマクロになります。

ちなみに`Body`がないマクロのタイプはこの`マクロ本文はありません`だけになります。


### 2. エスケープ
これ以降は全て`Body`があります。`エスケープ`は文字通り`Body`の内容をエスケープします
見たほうが早いと思うので、`テンプレート`の説明の後、サンプルを用意して説明しようと思います。

### 3. レンダリングしない
ちょっとややこしいです。一応使ってみた感じで説明すると「BodyにHTMLが書けるけど、HTMLをそのままBodyに反映できない」でしょうか。。
エスケープとの対比で考えれば簡単です。**「BodyにHTMLがかける」ぐらいに思ってもらうのが理解が早いと思います**。

### 4. レンダリングする
こっちはさらに一言だと説明しにくいです。`レンダリングしない`と同様にBodyにHTMLを書くことができます。
ただしこっちはさらに、Body内のテキストをコンフルエンスの編集機能で加工することができます。色を変えたりとか、下線を入れたりとか、文字を大きくしたりとか。
HTMLを書かなくてもビジュアルを変更できるので万人向けかもしれません。

`レンダリングしない`との対比で考えると、`レンダリングしない`のほうはテキストを編集することはできません。見た目を変えるには自分でHTMLを書く必要があります。

以上が`マクロ本体の処理`で選択できる４つのタイプの説明になります。
なおあとでそれぞれの特徴がわかるサンプルを用意したので、あまり理解してなくても読み進めて問題ありません。

ただサンプルの前にテンプレート欄についても軽く説明しておきます。

## テンプレート
こちらにマクロの中身を書き込みます。さっきまで`Body`、`Body`と連呼していたものとは別物です。
ちなみにマクロのタイプに`マクロ本文はありません`**以外**を指定していた場合は`$body`でその内容を扱うことができます。

と説明はこれぐらいにして、次からはサンプルを紹介しようと思います。

### サンプル１ータイプ：マクロ本文はありません
Hello Worldを表示させるだけのマクロです。
公式にも[サンプル](https://confluence.atlassian.com/conf53/hello-world-example-of-user-macro-411108917.html)あるんですけどそれとはちょっと変えてます。

**マクロ本体の処理**
マクロ本文はありません

```html:テンプレート
## @noparams
<h1>Hello World!</h1>
```
このマクロを使ってみると
<img width="300" alt="Hello World1.png" src="https://qiita-image-store.s3.amazonaws.com/0/149859/0c7aeeed-426f-d14c-fb84-10f0913971d8.png">
おっきいHello World!が表示されます。

### サンプル２ータイプ：エスケープ
ここからはBodyがあるマクロです。このサンプルはそのBodyをエスケープします。
Bodyの内容は$bodyで利用できます。

**マクロ本体の処理**
エスケープ

```:テンプレート
## @noparams
$body
```
Bodyがあるので利用時にこのように入力欄が出現します。
<img width="357" alt="エスケープ確認.png" src="https://qiita-image-store.s3.amazonaws.com/0/149859/fbd26bda-b583-c849-eb22-a493d8ba9ce6.png">
上記のように入力しても
<img width="229" alt="エスケープ結果.png" src="https://qiita-image-store.s3.amazonaws.com/0/149859/56774550-6dfd-92fa-b5d6-7a82f5827847.png">
出力はみごとにエスケープされました。
テンプレートの中身がエスケープされるわけではないので注意です。


### サンプル3ータイプ：レンダリングしない
続いてはサンプル2を`レンダリングしない`に変更したマクロです。

**マクロ本体の処理**
レンダリングしない

```:テンプレート
## @noparams
$body
```
<img width="357" alt="エスケープ確認.png" src="https://qiita-image-store.s3.amazonaws.com/0/149859/1a129b77-35b9-880a-f0a0-d428268d9766.png">
サンプル２と同じように入力すると
<img width="300" alt="Hello World1.png" src="https://qiita-image-store.s3.amazonaws.com/0/149859/59705e26-c202-1ca8-e179-a8c4ec9d1ca3.png">
今度はHTMLが反映されて大きくなりました。

### サンプル４ータイプ：レンダリングする
最後に`レンダリングする`に変更したサンプルです。
**マクロ本体の処理**
レンダリングする

```:テンプレート
## @noparams
$body
```
<img width="348" alt="レンダリングする入力.png" src="https://qiita-image-store.s3.amazonaws.com/0/149859/d2d35495-2a0b-6026-8b6f-15dd93be9473.png">
`Body`の中身は「Hello World！」と入力した後コンフルエンス標準の編集機能で文字を大きくしました。
<img width="300" alt="Hello World1.png" src="https://qiita-image-store.s3.amazonaws.com/0/149859/3d136323-7bea-b36a-fda0-13fe85dcbc35.png">
出力も変わらずでかいままです。`レンダリングしない`だと書式設定済みとなってしまい編集できないのがこれとの大きな違いになります。

以上こんな感じでそれぞれ特徴があります。
マクロのタイプについてはこれぐらいにしておいて、次はテンプレートの注意点について書こうと思います。

# テンプレート記述時の注意

## 引数の定義
ちょっと説明を省いてしまっていたのですが、上にある４つのサンプルに、共通して書いてある１文があります。

それは`## @noparams`です。

この１文は、「このマクロには引数がない」ということを表しています。

引数とは、Bodyとは別で、マクロに対して入力できる項目になります。
Bodyと最も異なるのはデフォルト値の設定や簡単な入力値の制限をかけたりすることができるところです。

そして注意しなければならないのは、全てのマクロには**引数についてなんらかの記述をする必要がある**ということです。

そうしないといざマクロを使用しようとした際にマクロ一覧に出てこないのです。初めてマクロを書いてみた時そこでいきなりつまづいて時間を食いました。。

**なので引数がないときでも必ず`## @noparams`は書くようにしましょう。**

引数がある場合については、これからサンプルを書いて説明します

## 引数のサンプルー背景色のある文字列を表示するマクロ
<img width="229" alt="背景色付き文字.png" src="https://qiita-image-store.s3.amazonaws.com/0/149859/983241fb-2cb0-74ef-0ade-b4f442b0e7ea.png">
こんな感じの結果になるマクロです。３色あるのでこのマクロを計３回使っています。

色の美的センスが全く感じられません。が、それはさておきマクロは以下のようになっています。

**マクロ本体の処理**
レンダリングする
※「レンダリングする」にしたのはコンフルエンスにもともとある文字色変更機能を使えるようにするためです。$bodyが使えれば別に他のやつでも構いません。

```html:テンプレート
## @param BGColor:title=color|type=string|default=red
<span style="background-color: $paramBGColor;">$body</span>
```

引数の定義はテンプレートの１行目になります

`## @param プログラム引数名：title=表示名|type=型|default=デフォルト値`

ここで定義した引数はテンプレート内では２行目にもあるとおり、`$paramプログラム引数名`でアクセス可能です。
他はただのHTMLと$bodyしかないのでとくに説明の必要はないかなと思います。

ちなみに引数定義時のパラメータについては公式ドキュメントのこちらをごらんください。
https://confluence.atlassian.com/conf53/guide-to-user-macro-templates-411108923.html
それでもちょっとだけこの記事で言及するならば
・プログラム引数名が必須
・titleとtypeが推奨
・その他（defaultとか）はオプション
のようです。

このように引数を定義しておくとマクロ利用時の編集画面で入力できるようになります。
<img width="226" alt="マクロ利用時.png" src="https://qiita-image-store.s3.amazonaws.com/0/149859/515858f3-ac80-18da-98af-2108cd5f502f.png">
「編集」を押すと以下の画面が出てきます。
<img width="462" alt="マクロ利用時編集画面.png" src="https://qiita-image-store.s3.amazonaws.com/0/149859/a9249910-8e2c-d365-9752-ff24ac6b573d.png">
ここで引数に入力可能です。

最後にもう１つだけ書いて終わりにしようと思います

# テンプレートにjQueryが使える
HTMLが書けるのでもちろんjavascriptも書けるんですが、javascriptってそのまま使うとDOM操作面倒ですよね。

でも安心jQueryが使えます。
（最近はなんか他にもいろいろ便利なのがあるみたいですが、しばらくjavascript触ってないのとjQueryしか使ったことないので他のやつはよくわかりません、すみません）

jQueryといえば`$`ですが`$`はVelocityでばりばり使うのでjQueryのまんまで使いました。
何かいい案あれば教えていただけると幸いです。

ためしにさっきの色変える奴にjQueryでクリックイベントをつけてみようと思います。

## 背景色のある文字列を表示するマクロ~クリックでアラート発火Ver

**マクロ本体の処理**
レンダリングする

```html:テンプレート
## @param BGColor:title=color|type=string|default=red
<span class="colorText" style="background-color: $paramBGColor;">$body</span>
<script type="text/javascript">
jQuery(document).ready(function(){
  jQuery(".colorText").click(function(){
    alert(jQuery(this).text());
  });
});
</script>
```
やっつけ感満載で申し訳ないですが、これでテキストをクリックするとちゃんとアラートが表示されます。
<img width="554" alt="アラート表示.png" src="https://qiita-image-store.s3.amazonaws.com/0/149859/18151a2a-c0a2-7c90-81ff-4fa0d3adb925.png">

このコード自体はマクロの数だけアラートが出てくるとか問題点はありますが、
jQueryも使えるよということでした。

# 最後に
自作マクロはHTMLやjavascriptが書けるのでいろんなことができてしまいます。
コンフルエンス自体は多分基本的には閉じたコミュニティで使用するものだとは思うんですが、しっかり仕組みを理解した上で安全に使っていきたいですね。

多分そのために権限が設定されているんだと思いますが。

また記事を書く機会があれば、今度はマクロの中でマクロを使うことなんかをかければなと思います。
ちょっと今回書きすぎたのでできれば次回は短めで。

# 参考
Confluenceのユーザーマクロの作り方 - tohokuaikiのチラシの裏
http://tohokuaiki.hateblo.jp/entry/confluence/plugin/user-macro/howto

公式ドキュメント系
https://confluence.atlassian.com/conf53/writing-user-macros-411108914.html
https://confluence.atlassian.com/conf53/examples-of-user-macros-411108916.html