Changes between Version 1 and Version 2 of WikiMacros


Ignore:
Timestamp:
Aug 13, 2014, 12:08:18 AM (10 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • WikiMacros

    v1 v2  
    88
    99== マクロの利用 == #UsingMacros
     10
    1011マクロ呼び出しは、二つの ''角括弧 (square brackets) '' で括られた箇所です。 Python 関数のように、マクロは引数を取ることができ、括弧 (parenthesis) の中に、カンマで区切ったリストで表記します。
    1112
    12 Trac マクロは、 TracPlugins としても作成することができます。 TracPlugins として Trac マクロを作成することで「直接 HTTP リクエストにアクセスする。」といった通常の Trac マクロでは実現できない機能を実装することができます。
     13=== 詳細なヘルプを見るには === #GettingDetailedHelp
     14マクロの一覧と完全なヘルプは、 下記の[#AvailableMacros マクロ一覧] にある !MacroList マクロを使用してみることができます。
     15
     16簡単なマクロ一覧は `[[MacroList(*)]]` や `[[?]]` で見ることができます。
     17
     18特定のマクロの詳細なヘルプを参照したい場合は、 !MacroList マクロに引数渡すことによって参照することができます。 例) `[[MacroList(MacroList)]]` 。もしくは、便宜上、 `[[MacroList?]]` のようにマクロ名にクエスチョンマーク ('?') をつけることでヘルプをみることができます。
     19
     20
    1321
    1422=== 利用例 === #Example
    … …  
    1624'Trac' で始まる Wiki ページの最近の変更履歴 3 件分を表示するマクロです:
    1725
    18 {{{
    19  [[RecentChanges(Trac,3)]]
     26||= Wiki マークアップ =||= 表示 =||
     27{{{#!td
     28  {{{
     29  [[RecentChanges(Trac,3)]]
     30  }}}
    2031}}}
     32{{{#!td style="padding-left: 2em;"
     33[[RecentChanges(Trac,3)]]
     34}}}
     35|-----------------------------------
     36{{{#!td
     37  {{{
     38  [[RecentChanges?(Trac,3)]]
     39  }}}
     40}}}
     41{{{#!td style="padding-left: 2em;"
     42[[RecentChanges?(Trac,3)]]
     43}}}
     44|-----------------------------------
     45{{{#!td
     46  {{{
     47  [[?]]
     48  }}}
     49}}}
     50{{{#!td style="padding-left: 2em"
     51{{{#!html
     52<div style="font-size: 80%" class="trac-macrolist">
     53<h3><code>[[Image]]</code></h3>画像を Wiki 形式のテキストに組み込みます。
    2154
    22 は、以下のように表示されます:
    23  [[RecentChanges(Trac,3)]]
     551 番目の引数は、ファイル名を指定します。ファイルの指定は添付ファイルなど …
     56<h3><code>[[InterTrac]]</code></h3>既知の <a class="wiki" href="/wiki/InterTrac">InterTrac</a> プレフィックスをリスト形式で表示します。
     57<h3><code>[[InterWiki]]</code></h3>既知の <a class="wiki" href="/wiki/InterWiki">InterWiki</a> プレフィックスに関する概要のリストを表示します。
     58<h3><code>[[KnownMimeTypes]]</code></h3><a class="wiki" href="/wiki/WikiProcessors">WikiProcessors</a> で処理できる既知の mime-type を表示します。
     59引数が与えられた場合は、 mime-type ...</div>
     60}}}
     61etc.
     62}}}
    2463
    2564== マクロ一覧 == #AvailableMacros
    … …  
    3473
    3574== カスタムマクロを開発する == #DevelopingCustomMacros
    36 マクロは、 Trac 自身と同じように [http://www.python.org/ Python] で書かれています。
     75マクロは、 Trac 本体と同様 [http://python.org/ Python] で書かれています。そして TracPlugins の一種として開発します。
    3776
    38 マクロの開発についての詳しい情報は [http://trac.edgewall.org/wiki/TracDev リソースの開発] を参照してください。
     77マクロの開発についての詳しい情報は [trac:TracDev リソースの開発] を参照してください。
    3978
    40 
    41 == マクロの実装 == #Implementation
    4279
    4380Trac 0.11 でマクロを作成する簡単な例を 2 つ紹介します。
    … …  
    4683
    4784=== 引数なしのマクロ === #Macrowithoutarguments
    48 Trac は マクロ名としてモジュール名を使用するので以下のサンプルは (TracEnvironment 配下の `plugins/` ディレクトリに) `TimeStamp.py` という名前で保存しなければなりません。
     85下記のソースコードをテストするためには、このソースコードを `timestamp_sample.py` として保存し、 TracEnvironment の `plugins/` に配置しなければなりません。
    4986{{{
    5087#!python
    … …  
    63100    url = "$URL$"
    64101
    65     def expand_macro(self, formatter, name, args):
     102    def expand_macro(self, formatter, name, text):
    66103        t = datetime.now(utc)
    67104        return tag.b(format_datetime(t, '%c'))
    … …  
    69106
    70107=== 引数付きのマクロ === #Macrowitharguments
    71 Trac は マクロ名としてモジュール名を使用するので以下のサンプルは `HelloWorld.py` という名前で (TracEnvironemnt 配下の `plugins/` ディレクトリに) 保存しなければなりません。
     108下記のソースコードをテストするためには、このソースコードを `helloworld_sample.py` として保存し、 TracEnvironment の `plugins/` に配置しなければなりません。
    72109{{{
    73110#!python
     111from genshi.core import Markup
     112
    74113from trac.wiki.macros import WikiMacroBase
    75114
    … …  
    89128    url = "$URL$"
    90129
    91     def expand_macro(self, formatter, name, args):
     130    def expand_macro(self, formatter, name, text, args):
    92131        """Return some output that will be displayed in the Wiki content.
    93132
    94133        `name` is the actual name of the macro (no surprise, here it'll be
    95134        `'HelloWorld'`),
    96         `args` is the text enclosed in parenthesis at the call of the macro.
     135        `text` is the text enclosed in parenthesis at the call of the macro.
    97136          Note that if there are ''no'' parenthesis (like in, e.g.
    98           [[HelloWorld]]), then `args` is `None`.
     137          [[HelloWorld]]), then `text` is `None`.
     138        `args` are the arguments passed when HelloWorld is called using a
     139        `#!HelloWorld` code block.
    99140        """
    100         return 'Hello World, args = ' + unicode(args)
    101    
    102     # Note that there's no need to HTML escape the returned data,
    103     # as the template engine (Genshi) will do it for us.
     141        return 'Hello World, text = %s, args = %s' % \
     142            (Markup.escape(text), Markup.escape(repr(args)))
     143
    104144}}}
    105145
     146Note: `expand_macro` は 第4パラメータに、 ''`args`'' を任意に取ることもできます。 このマクロが [WikiProcessors WikiProcessor] として呼ばれたとき、 `key=value` 形式の [WikiProcessors#UsingProcessors プロセッサパラメータ] を渡すことも可能です。もし、このパラメータを指定したとき、これらの値は、ディクショナリの中に保存され、 追加の `args` パラメータによって渡されます。一方で、マクロとして呼び出されたときは、 `args` パラメータは、 `None` として扱われます (''0.12 以降'') 。
     147
     148例として、このように記述した場合:
    106149{{{
    107 #!div class=important
    108 訳注 '''重要''':
    109 
    110 Wiki マクロが引数を持つ場合、引数は必ずサニタイズしてください。
    111 expand_macro の戻り値は `<script>` タグやイベントハンドラなどもそのまま出力するので、入力をチェックせずに、そのまま戻り値に使用するのは極めて危険です。
    112 Genshi の tag オブジェクトにラップすれば、エスケープ機構が働きますので、通常はこれを使うとよいでしょう。
    113 `HelloWorld.py` は、以下の通り書き直すことができます:
    114 {{{
    115 #!python
    116 from trac.wiki.macros import WikiMacroBase
    117 from genshi.builder import tag
    118 class HelloWorldMacro(WikiMacroBase):
    119     def expand_macro(self, formatter, name, args):
    120         return tag.div(u'Hello World, args = ', unicode(args))
    121 }}}
     150{{{#!HelloWorld style="polite" -silent verbose
     151<Hello World!>
    122152}}}
    123153
    124 === {{{expand_macro}}} について === #expand_macrodetails
    125 {{{expand_macro}}} は HTML として解釈できる単純な文字列か Markup オブジェクト ({{{from trac.util.html import Markup}}} を使用する ) のどちらかを返さなければなりません。 {{{Markup(string)}}} はそのまま `string` を解釈するので、 HTML 文字列はエスケープされずに、そのとおり表示されます。 Wiki フォーマッタを使用した場合は {{{from trac.wiki import Formatter}}} のように import してください。
     154{{{#!HelloWorld
     155<Hello World!>
     156}}}
    126157
    127 マクロで HTML ではなく Wiki マークアップを使用したい場合、以下のように HTML に変換します:
     158[[HelloWorld(<Hello World!>)]]
     159}}}
     160結果はこのようになります:
     161{{{
     162Hello World, text = <Hello World!> , args = {'style': u'polite', 'silent': False, 'verbose': True}
     163Hello World, text = <Hello World!> , args = {}
     164Hello World, text = <Hello World!> , args = None
     165}}}
     166
     167Note: `expand_macro` が返す値は、 HTML がエスケープされて '''いない''' ことに注意して下さい。期待する戻り値によっては、あなた自身でエスケープする必要があります (`return Markup.escape(result)` を使用できます)。また、戻り値として HTML が返ってくると分かっているならば、結果を (`return Markup(result)`) という風に Genshi が提供している Markup (`from genshi.core import Markup`) オブジェクトでラップすることもできます。
     168
     169また、`text` を Wiki としてマークアップする場合、 Wiki Formatter (`from trac.wiki import Formatter`) オブジェクトも再帰的に使用することができます。以下がサンプルです:
    128170
    129171{{{
    130172#!python
    131   text = "whatever wiki markup you want, even containing other macros"
    132   # Convert Wiki markup to HTML, new style
    133   out = StringIO()
    134   Formatter(self.env, formatter.context).format(text, out)
    135   return Markup(out.getvalue())
     173from genshi.core import Markup
     174from trac.wiki.macros import WikiMacroBase
     175from trac.wiki import Formatter
     176import StringIO
     177
     178class HelloWorldMacro(WikiMacroBase):
     179        def expand_macro(self, formatter, name, text, args):
     180                text = "whatever '''wiki''' markup you want, even containing other macros"
     181                # Convert Wiki markup to HTML, new style
     182                out = StringIO.StringIO()
     183                Formatter(self.env, formatter.context).format(text, out)
     184                return Markup(out.getvalue())
    136185}}}