Redmine - Wiki マクロの追加方法

Redmine Advent Calendar の一つとして、Wiki マクロの追加方法を紹介したいと思います。

Redmine では Wiki を記述する際、 textile 記法 だけではなく、 Wiki マクロと呼ばれるものが書けます。 これは {{child_pages(Foo)}} のような感じで {{ }} の中に関数のように記述します。
そして、この Wiki マクロ、自分で追加して Wiki を拡張することができるようになっています。

で、実際にどうやって追加するかというとプラグインを作成する必要があります。
ただ、プラグインといってもそんな大層なものではありません。 簡単なものであれば、数行で出来るので、 プラグイン作成のとっかかりとしてもちょうどいいのではないかと思います。 私が最初に作ったのも Wiki マクロの追加のプラグインです。

最初に作ったのは TestLink Link プラグイン という Redmine から TestLink(テスト管理システム) にリンクを張るプラグインでした。 TestLink から Redmine へはリンクがはれたのですが、逆はなくて、なにかいい方法はないかなと探していたところ、 Wiki マクロを自分で作れば一番簡単そうということで作ったものです。
この TestLink Link プラグインも最初に自分用に作った時は、数行の簡単なものでした。 それが、あれもこれもといろいろと機能を追加していくうちに、せっかくだからと公開しました。
ただ、最近私が TestLink を使わなくなった(^_^;) ため、引き継いでくれる人を募集しています。

ちょっと話が脱線してしまいましたが、以下、作成方法について書いていきたいと思います。

開発用 Redmine を用意する

まず、開発用の Redmine を用意しましょう。 最近では All-in-one パッケージで簡単に用意できるみたいです。

• プラグインの開発環境の準備
• Redmine オールインワンパッケージ

init.rb を用意する

今回は簡単なものなので、プラグインの中身は init.rb のファイル一つで十分です。 これを準備しましょう。

まず、 インストールした Redmine のトップディレクトリにいってプラグインの雛形作成用のコマンドを実行します。

$ ruby script/generate redmine_plugin プラグイン名
$ ruby script/generate redmine_plugin sample_macros

vender/plugins/redmine_sample_macros 以下にいろいろとファイルが出来ます。 今回は使わないので、 init.rb 以外のファイル、ディレクトリをすべて削除します。

プラグインの情報を書く

生成された init.rb には、以下のようなプラグインの登録情報が書いてあるので、これを適当に書き直します。

Redmine::Plugin.register :redmine_sample_macros do
  name 'Redmine Sample Macros plugin'
           #:

ここは公開するということでもなければ、別にそのままでもかまいません。

マクロの登録

いよいよ、マクロの追加(登録) ですが、 例として ウィキペディアへのリンクのマクロを書いてみます。
できたマクロの書き方とリンク先は次のようになります。

{{wikipedia(Redmine)}}
http://ja.wikipedia.org/wiki/Redmine

記述するコードは以下のようなものです。

Redmine::WikiFormatting::Macros.register do
  macro :wikipedia do |obj, args|
    word = args.first
    link_to(word, "http://ja.wikipedia.org/wiki/" + CGI.escape(word))
  end
end

エラー処理とか、いろいろ省いて書いていますが、一応これでもちゃんと動きます。
もう少し詳しい説明とエラー処理つきのコードは r-labs のプラグイン Tips に記述していますので、そちらを見てください。

その他の例

その他の例をいろいろと挙げてみたいと思います。

マクロで指定した中身を Google で検索します。

{{google(Redmine)}}
http://www.google.co.jp/search?ie=UTF-8&q=Redmine

Redmine::WikiFormatting::Macros.register do
  macro :google do |obj, args|
    word = args.first
    link_to(word+"?", "http://www.google.co.jp/search?ie=UTF-8&q=" + CGI.escape(word))
  end
end

redmine.org に登録されているプラグインリストのページへのリンクです。 こちらはキーワードを直接書くので、 CGI.escape は不要です。

{{plugin(glossary)}}
http://www.redmine.org/plugins/glossary

Redmine::WikiFormatting::Macros.register do
  macro :plugin do |obj, args|
    word = args.first
    link_to("Plugin:"+word, "http://www.redmine.org/plugins/" + word)
  end
end

SNS のはてなブックマーク へのリンクです。

{{b_hatena(yohshiy)}}
http://b.hatena.ne.jp/yohshiy

Redmine::WikiFormatting::Macros.register do
  macro b_hatena do |obj, args|
    word = args.first
    link_to("Bookmark:"+word, "http://b.hatena.ne.jp/" + word)
  end
end

本の BSDN を指定して、 amazon へのリンクを作成します。

{{bsdn(4798121622)}}
http://www.amazon.co.jp/exec/obidos/ASIN/4798121622

Redmine::WikiFormatting::Macros.register do
  macro :bsdn do |obj, args|
    word = args.first
    link_to("BSDN-"+word, "http://www.amazon.co.jp/exec/obidos/ASIN/" + word)
  end
end

リンクだけではなく、 textile で用意されているもの以外の html タグを使いたい場合にも使えます。 以下はフリガナ(ルビ)を記述するマクロです。
ちなみに content_tag は第 2 引数またはブロックを中身にするタグを出力します。 また、 args の文字列は <, & などの html の特殊文字を &lt; などにエスケープした状態でわたってきます。

{{rubi(漢字,かんじ)}}
<ruby><rb>漢字</rb><rp>(</rp><rt>かんじ</rt><rp>)</rp></ruby>

Redmine::WikiFormatting::Macros.register do
  macro :rubi do |obj, args|
    content_tag(:ruby) {
      out = content_tag(:rb, args[0])
      out += content_tag(:rp, '(')
      out += content_tag(:rt, args[1])
      out += content_tag(:rp, ')')
    }
  end
end

さらなる拡張へ

ちょっとしたコードを書くだけで、 wiki を拡張できることがお伝えできたでしょうか。
これで、アイディアを刺激されてプラグインを作ってみようと思っていただけると幸いです。

もうちょっと拡張したいと思った場合は、 r-labs のプラグイン Tips に以下の記事も書いているので、 参考にしてください。

1. プラグインの設定で値を変更できるようにする
2. Wiki のツールボタンを追加して書きやすくする

Wiki マクロの追加だけでなく、もっといろんなプラグインを作ってみたいと思った場合は Rails を知らない人のための Redmine プラグイン開発ガイド を見てください。 結構詳しく説明を書いたつもりです。
また、 このプラグイン開発ガイドは、まだ詳細は何も考えてませんが、 2012/01/21(土) に行われる shinagawa.redmine で解説も行うつもりです。

サンプルコード

実際に使うにはエラー処理など書き足さないとだめですが、 一応、今回紹介したコードの全文も公開しておきます。

init.rb