wiki マクロを追加する¶

Redmine では {{foo(arg1, arg2)}} のような形式で wiki のマクロを記述します。これはプラグインで自由に追加することができます。

サンプルコード

• 表示
• ダウンロード

サンプルとしてウィキペディアへのリンクをはるマクロを考えてみます。
ウィキペディアで例えば Redmine や 日本語 を表示してみると次のようなアドレスになっています。

http://ja.wikipedia.org/wiki/Redmine
http://ja.wikipedia.org/wiki/日本語

これを見ると http://ja.wikipedia.org/wikiの後に単語を追加すればいいみたいです。そこで単語をマクロの引数で指定して、それを wiki/ の後に追加するマクロにしましょう。
ちなみに最近のブラウザはかしこいので、アドレスには日本語が表示されていますが、実際には日本語はアドレスとしては使えない文字なので、%E6... といった感じでエスケープされています。

マクロのプラグインの場合も通常のプラグインのように最初にスケルトンを生成します。ただし、今回は簡単なので init.rb しか使用しません。その後 init.rb のプラグインの register 内を適当に記述します。

wiki マクロを登録するには Plugin のように register 関数で登録します。この関数は実行されればどこに書いてもいいと思いますが、通常 init.rb に記述します。

Redmine::WikiFormatting::Macros.register do
  desc "Wikipedia link macro" 
  macro :wikipedia do |obj, args|
    if (args.size != 1)
      raise "Wikipedia macro is given only one argument." 
    else
      word = args.first.strip
      addr = "http://ja.wikipedia.org/wiki/" + CGI.escape(word)
      return link_to(word, addr, :class => "external")
    end
  end
end

まず、Plugin の register のように desc でマクロの説明を記述します。
この説明は{{macro_list}}で表示されるマクロ一覧に使用されます。

3 行目の macro からマクロの処理を記述します。
引数でマクロのキーワードを指定します。今回 wikipedia が引数になるようにしています。
ブロック引数の args にマクロの引数が配列で入っていて、これを元にリンクを作成していきます。
この args では <, >, & といった html に使えない文字をエスケープして格納しているため、そのまま表示に使うことができます。

4, 5 行目でマクロの引数のチェックをしています。
マクロの作成中に raise するとそれがエラーとしてページに挿入されます。

7 行目で空白をとっています。
wikipedia( Redmine ) というように空白を入れていると引数には空白込みで値がわたってきているためです。

8 行目でリンク先のアドレスを作成しています。
CGI.escape は ruby の標準の添付ライブラリである cgi に含まれる関数で日本語や = のようなアドレスとして使えない文字を % 形式のものに変換します。
ちなみにアドレスではなく、 html 内で使えない文字(<, >, & )のエスケープは CGI.escapeHTML を使います。 args に格納されている文字列は HTML エスケープされているため、正確にエスケープするには一度、 CGI.unescapeHTML で戻しておく必要があります。ただ、今回は wikipedia のリンクなので、そのままアドレス用エスケープをしています。

9 行でリンクの文字列を返しています。この戻り値がそのまま html のページに挿入されます。
link_to は rails の関数で <a src = " addr " class="external"> word </a> といった html のリンクタグの文字列を返します。
第一引数が表示名で、今回リンクの表示文字はマクロの引数のままにしています。
第二引数にはリンク先のアドレスを文字列で渡しています。
第三引数はハッシュでオプションを渡します。ここではタグのクラスを指定しています。Redmine 外部へのリンクの場合先頭に外部リンクをあらわすアイコンが付きますが、この wikipedia へのリンクも外部リンクなのでアイコンをつけた方がいいです。スタイルシートで定義されているので、クラスを external とするだけでアイコンが表示されるようになります。

出来たプラグインを使ってみると、以下のような感じになります。

* {{wikipedia(Redmine)}}
* {{wikipedia(日本語)}}
* {{wikipedia(two, argument)}}