r-labs

h1. wiki マクロを追加する

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

サンプルコード

* "表示":http://code.google.com/p/myoshida-rp/source/browse/#svn%2Ftrunk%2FTips%2Falias%2Fwikimacro%2Fredmine_wikipedia_link%253Fstate%253Dclosed

* "ダウンロード":http://code.google.com/p/myoshida-rp/downloads/detail?name=sample-wikimacro.zip

!wikimacro_view.png!

サンプルとしてウィキペディアへのリンクをはるマクロを考えてみます。

ウィキペディアで例えば _Redmine_ や _日本語_ を表示してみると次のようなアドレスになっています。

<pre>

http://ja.wikipedia.org/wiki/Redmine

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

</pre>

これを見ると <notextile>http://ja.wikipedia.org/wiki</notextile>の後に単語を追加すればいいみたいです。そこで単語をマクロの引数で指定して、それを wiki/ の後に追加するマクロにしましょう。

ちなみに最近のブラウザはかしこいので、アドレスには日本語が表示されていますが、実際には日本語はアドレスとしては使えない文字なので、%E6... といった感じでエスケープされています。

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

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

<pre><code class="ruby">

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

</code></pre>

まず、Plugin の register のように desc でマクロの説明を記述します。

この説明は{{@macro_list@}}で表示されるマクロ一覧に使用されます。

3 行目の macro からマクロの処理を記述します。

引数でマクロのキーワードを指定します。今回 wikipedia が引数になるようにしています。

ブロック引数の @args@ にマクロの引数が配列で入っていて、これを元にリンクを作成していきます。

4, 5 行目でマクロの引数のチェックをしています。

マクロの作成中に @raise@ するとそれがエラーとしてページに挿入されます。

7 行目で空白をとっています。

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

8 行目でリンク先のアドレスを作成しています。

*CGI.escape* は ruby の標準の添付ライブラリである cgi に含まれる関数で日本語や = のようなアドレスとして使えない文字を % 形式のものに変換します。

9 行でリンクの文字列を返しています。この戻り値がそのまま html のページに挿入されます。

*link_to* は rails の関数で <a src = " _addr_ " class="external"> _word_ </a> といった html のリンクタグの文字列を返します。

第一引数が表示名で、今回リンクの表示文字はマクロの引数のままにしています。表示文字の場合も <, >, & といった使えない文字がありますが、これは link_to 内で勝手に直してくれます。

第二引数にはリンク先のアドレスを文字列で渡しています。

第三引数はハッシュでオプションを渡します。ここではタグのクラスを指定しています。Redmine 外部へのリンクの場合先頭に外部リンクをあらわすアイコンが付きますが、この wikipedia へのリンクも外部リンクなのでアイコンをつけた方がいいです。スタイルシートで定義されているので、クラスを @external@ とするだけでアイコンが表示されるようになります。

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

<pre>

* {{wikipedia(Redmine)}}

* {{wikipedia(日本語)}}

* {{wikipedia(two, argument)}}

</pre>