TipsWikiMacro » 履歴 » バージョン 9
Mitsuyoshi Yoshida, 2011/12/08 12:56
1 | 1 | Mitsuyoshi Yoshida | h1. wiki マクロを追加する |
---|---|---|---|
2 | |||
3 | Redmine では <notextile>{{foo(arg1, arg2)}}</notextile> のような形式で wiki のマクロを記述します。これはプラグインで自由に追加することができます。 |
||
4 | |||
5 | |||
6 | サンプルコード |
||
7 | * "表示":http://code.google.com/p/myoshida-rp/source/browse/#svn%2Ftrunk%2FTips%2Falias%2Fwikimacro%2Fredmine_wikipedia_link%253Fstate%253Dclosed |
||
8 | * "ダウンロード":http://code.google.com/p/myoshida-rp/downloads/detail?name=sample-wikimacro.zip |
||
9 | |||
10 | 2 | Mitsuyoshi Yoshida | !wikimacro_view.png! |
11 | |||
12 | |||
13 | 1 | Mitsuyoshi Yoshida | サンプルとしてウィキペディアへのリンクをはるマクロを考えてみます。 |
14 | ウィキペディアで例えば _Redmine_ や _日本語_ を表示してみると次のようなアドレスになっています。 |
||
15 | <pre> |
||
16 | http://ja.wikipedia.org/wiki/Redmine |
||
17 | http://ja.wikipedia.org/wiki/日本語 |
||
18 | </pre> |
||
19 | 5 | Mitsuyoshi Yoshida | |
20 | 1 | Mitsuyoshi Yoshida | これを見ると <notextile>http://ja.wikipedia.org/wiki</notextile>の後に単語を追加すればいいみたいです。そこで単語をマクロの引数で指定して、それを wiki/ の後に追加するマクロにしましょう。 |
21 | ちなみに最近のブラウザはかしこいので、アドレスには日本語が表示されていますが、実際には日本語はアドレスとしては使えない文字なので、%E6... といった感じでエスケープされています。 |
||
22 | |||
23 | マクロのプラグインの場合も通常のプラグインのように最初にスケルトンを生成します。ただし、今回は簡単なので init.rb しか使用しません。その後 init.rb のプラグインの register 内を適当に記述します。 |
||
24 | |||
25 | wiki マクロを登録するには Plugin のように register 関数で登録します。この関数は実行されればどこに書いてもいいと思いますが、通常 *init.rb* に記述します。 |
||
26 | <pre><code class="ruby"> |
||
27 | Redmine::WikiFormatting::Macros.register do |
||
28 | desc "Wikipedia link macro" |
||
29 | macro :wikipedia do |obj, args| |
||
30 | if (args.size != 1) |
||
31 | raise "Wikipedia macro is given only one argument." |
||
32 | else |
||
33 | word = args.first.strip |
||
34 | addr = "http://ja.wikipedia.org/wiki/" + CGI.escape(word) |
||
35 | return link_to(word, addr, :class => "external") |
||
36 | end |
||
37 | end |
||
38 | end |
||
39 | 4 | Mitsuyoshi Yoshida | </code></pre> |
40 | 1 | Mitsuyoshi Yoshida | |
41 | まず、Plugin の register のように desc でマクロの説明を記述します。 |
||
42 | この説明は{{@macro_list@}}で表示されるマクロ一覧に使用されます。 |
||
43 | |||
44 | 3 行目の macro からマクロの処理を記述します。 |
||
45 | 引数でマクロのキーワードを指定します。今回 wikipedia が引数になるようにしています。 |
||
46 | ブロック引数の @args@ にマクロの引数が配列で入っていて、これを元にリンクを作成していきます。 |
||
47 | 8 | Mitsuyoshi Yoshida | この @args@ では <, >, & といった html に使えない文字をエスケープして格納しているため、そのまま表示に使うことができます。 |
48 | 1 | Mitsuyoshi Yoshida | |
49 | 4, 5 行目でマクロの引数のチェックをしています。 |
||
50 | マクロの作成中に @raise@ するとそれがエラーとしてページに挿入されます。 |
||
51 | |||
52 | 7 行目で空白をとっています。 |
||
53 | wikipedia( Redmine ) というように空白を入れていると引数には空白込みで値がわたってきているためです。 |
||
54 | |||
55 | 8 行目でリンク先のアドレスを作成しています。 |
||
56 | *CGI.escape* は ruby の標準の添付ライブラリである cgi に含まれる関数で日本語や = のようなアドレスとして使えない文字を % 形式のものに変換します。 |
||
57 | 9 | Mitsuyoshi Yoshida | ちなみにアドレスではなく、 html 内で使えない文字(<, >, & )のエスケープは *CGI.escapeHTML* を使います。今回は wikipedia のリンクなので、そのままアドレス用エスケープをしていますが、 @args@ に格納されている文字列は HTML エスケープされているので、正確にエスケープするには一度、 *CGI.unescapeHTML* で戻しておく必要があります。 |
58 | 1 | Mitsuyoshi Yoshida | |
59 | 9 行でリンクの文字列を返しています。この戻り値がそのまま html のページに挿入されます。 |
||
60 | *link_to* は rails の関数で <a src = " _addr_ " class="external"> _word_ </a> といった html のリンクタグの文字列を返します。 |
||
61 | 7 | Mitsuyoshi Yoshida | 第一引数が表示名で、今回リンクの表示文字はマクロの引数のままにしています。 |
62 | 1 | Mitsuyoshi Yoshida | 第二引数にはリンク先のアドレスを文字列で渡しています。 |
63 | 第三引数はハッシュでオプションを渡します。ここではタグのクラスを指定しています。Redmine 外部へのリンクの場合先頭に外部リンクをあらわすアイコンが付きますが、この wikipedia へのリンクも外部リンクなのでアイコンをつけた方がいいです。スタイルシートで定義されているので、クラスを @external@ とするだけでアイコンが表示されるようになります。 |
||
64 | |||
65 | 出来たプラグインを使ってみると、以下のような感じになります。 |
||
66 | <pre> |
||
67 | * {{wikipedia(Redmine)}} |
||
68 | * {{wikipedia(日本語)}} |
||
69 | * {{wikipedia(two, argument)}} |
||
70 | </pre> |