Changes between Version 2 and Version 3 of WikiMacros


Ignore:
Timestamp:
Jun 28, 2019, 2:20:16 PM (5 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • WikiMacros

    v2 v3  
    1 = Trac マクロ = #TracMacros
     1= Trac Macros
    22
    3 [[PageOutline]]
     3[[PageOutline(2-5,Contents,pullout)]]
    44
    5 Trac マクロとは、 Python で書かれた 'カスタム関数' によって Trac の Wiki エンジンを拡張するプラグインです。 WikiFormatting エンジンが利用可能なあらゆるコンテキストにおいて、マクロを使用することによって、動的な HTML データが挿入されます。
     5'''Trac macros''' extend Trac with custom functionality. Macros are a special type of plugin and are written in Python. A macro generates HTML in any context supporting WikiFormatting.
    66
    7 もう 1 種類のマクロは WikiProcessors です。これは通常、 Wiki 以外のマークアップ形式と表示を取り扱うために使用し、多くは、 (ソースコードハイライトのような) より大きいブロックに使用します。
     7The macro syntax is `[[macro-name(optional-arguments)]]`.
    88
    9 == マクロの利用 == #UsingMacros
     9'''WikiProcessors''' are another kind of macro, commonly used for source code highlighting using a processor like `!#python` or `!#apache`:
    1010
    11 マクロ呼び出しは、二つの ''角括弧 (square brackets) '' で括られた箇所です。 Python 関数のように、マクロは引数を取ることができ、括弧 (parenthesis) の中に、カンマで区切ったリストで表記します。
     11{{{
     12{{{#!wiki-processor-name
     13...
     14}}}
     15}}}
    1216
    13 === 詳細なヘルプを見るには === #GettingDetailedHelp
    14 マクロの一覧と完全なヘルプは、 下記の[#AvailableMacros マクロ一覧] にある !MacroList マクロを使用してみることができます。
     17== Using Macros
    1518
    16 簡単なマクロ一覧は `[[MacroList(*)]]` や `[[?]]` で見ることができます。
     19Macro calls are enclosed in double-square brackets `[[..]]`. Like Python functions macros can have arguments, which take the form of a comma separated list within parentheses `[[..(,)]]`. A common macro used is a list of the 3 most recent changes to a wiki page, or here, for example, all wiki pages starting with 'Trac':
    1720
    18 特定のマクロの詳細なヘルプを参照したい場合は、 !MacroList マクロに引数渡すことによって参照することができます。 例) `[[MacroList(MacroList)]]` 。もしくは、便宜上、 `[[MacroList?]]` のようにマクロ名にクエスチョンマーク ('?') をつけることでヘルプをみることができます。
    19 
    20 
    21 
    22 === 利用例 === #Example
    23 
    24 'Trac' で始まる Wiki ページの最近の変更履歴 3 件分を表示するマクロです:
    25 
    26 ||= Wiki マークアップ =||= 表示 =||
     21||= Wiki Markup =||= Display =||
    2722{{{#!td
    2823  {{{
    … …  
    3328[[RecentChanges(Trac,3)]]
    3429}}}
    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 形式のテキストに組み込みます。
    5430
    55 1 番目の引数は、ファイル名を指定します。ファイルの指定は添付ファイルなど …
    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 }}}
    61 etc.
    62 }}}
     31=== Getting Detailed Help
    6332
    64 == マクロ一覧 == #AvailableMacros
     33The list of available macros and the full help can be obtained using the !MacroList macro, see [#AvailableMacros below].
    6534
    66 ''Note: 以下に示すリストはマクロドキュメントを含むものだけです。 `-OO` による最適化や、 [wiki:TracModPython mod_python] での `PythonOptimize` オプションが設定されていると表示されません。''
     35A brief list can be obtained via `[[MacroList(*)]]` or `[[?]]`.
     36
     37Detailed help on a specific macro can be obtained by passing it as an argument to !MacroList, e.g. `[[MacroList(MacroList)]]`, or more conveniently, by appending a question mark (`?`) to the macro's name, like in `[[MacroList?]]`.
     38
     39== Available Macros
    6740
    6841[[MacroList]]
    6942
    70 == 世界のマクロを共有 == #Macrosfromaroundtheworld
     43== Contributed macros
    7144
    72 [http://trac-hacks.org/ Trac Hacks] というサイトは、コミュニティに寄稿されたマクロと [TracPlugins プラグイン] を収集し提供しています。新しいマクロを探している、共有したいマクロを作成した、などの場合は遠慮なく Trac Hacks のサイトを訪問してください。
     45The [http://trac-hacks.org/ Trac Hacks] site provides a large collection of macros and other Trac [TracPlugins plugins] contributed by the Trac community. If you are looking for new macros, or have written one that you would like to share, please visit that site.
    7346
    74 == カスタムマクロを開発する == #DevelopingCustomMacros
    75 マクロは、 Trac 本体と同様 [http://python.org/ Python] で書かれています。そして TracPlugins の一種として開発します。
     47== Developing Custom Macros
    7648
    77 マクロの開発についての詳しい情報は [trac:TracDev リソースの開発] を参照してください。
     49Macros, like Trac itself, are written in the [http://python.org/ Python programming language] and are a type of [TracPlugins plugin].
    7850
     51Here are 2 simple examples showing how to create a Macro. For more information about developing macros, see the [trac:TracDev development resources] and [trac:browser:branches/1.2-stable/sample-plugins sample-plugins].
    7952
    80 Trac 0.11 でマクロを作成する簡単な例を 2 つ紹介します。
     53=== Macro without arguments
    8154
    82 古いマクロと新しいマクロの違いを示す例は [http://trac.edgewall.org/browser/tags/trac-0.11/sample-plugins/Timestamp.py Timestamp.py] を参照してください。また、古いマクロから新しいマクロに移行するための情報は [http://trac.edgewall.org/browser/tags/trac-0.11/wiki-macros/README macros/README] を参照してください。
     55To test the following code, copy it to `timestamp_sample.py` in the TracEnvironment's `plugins/` directory.
    8356
    84 === 引数なしのマクロ === #Macrowithoutarguments
    85 下記のソースコードをテストするためには、このソースコードを `timestamp_sample.py` として保存し、 TracEnvironment の `plugins/` に配置しなければなりません。
    86 {{{
    87 #!python
    88 from datetime import datetime
    89 # Note: since Trac 0.11, datetime objects are used internally
    90 
    91 from genshi.builder import tag
    92 
    93 from trac.util.datefmt import format_datetime, utc
     57{{{#!python
     58from trac.util.datefmt import datetime_now, format_datetime, utc
     59from trac.util.html import tag
    9460from trac.wiki.macros import WikiMacroBase
    9561
    96 class TimeStampMacro(WikiMacroBase):
    97     """Inserts the current time (in seconds) into the wiki page."""
     62class TimestampMacro(WikiMacroBase):
     63    _description = "Inserts the current time (in seconds) into the wiki page."
    9864
    99     revision = "$Rev$"
    100     url = "$URL$"
    101 
    102     def expand_macro(self, formatter, name, text):
    103         t = datetime.now(utc)
    104         return tag.b(format_datetime(t, '%c'))
     65    def expand_macro(self, formatter, name, content, args=None):
     66        t = datetime_now(utc)
     67        return tag.strong(format_datetime(t, '%c'))
    10568}}}
    10669
    107 === 引数付きのマクロ === #Macrowitharguments
    108 下記のソースコードをテストするためには、このソースコードを `helloworld_sample.py` として保存し、 TracEnvironment の `plugins/` に配置しなければなりません。
    109 {{{
    110 #!python
    111 from genshi.core import Markup
     70=== Macro with arguments
    11271
     72To test the following code, copy it to `helloworld_sample.py` in the TracEnvironment's `plugins/` directory.
     73
     74{{{#!python
     75from trac.util.translation import cleandoc_
    11376from trac.wiki.macros import WikiMacroBase
    11477
    11578class HelloWorldMacro(WikiMacroBase):
     79    _description = cleandoc_(
    11680    """Simple HelloWorld macro.
    11781
    … …  
    12387    will become the documentation of the macro, as shown by
    12488    the !MacroList macro (usually used in the WikiMacros page).
    125     """
     89    """)
    12690
    127     revision = "$Rev$"
    128     url = "$URL$"
    129 
    130     def expand_macro(self, formatter, name, text, args):
     91    def expand_macro(self, formatter, name, content, args=None):
    13192        """Return some output that will be displayed in the Wiki content.
    13293
    13394        `name` is the actual name of the macro (no surprise, here it'll be
    13495        `'HelloWorld'`),
    135         `text` is the text enclosed in parenthesis at the call of the macro.
    136           Note that if there are ''no'' parenthesis (like in, e.g.
    137           [[HelloWorld]]), then `text` is `None`.
    138         `args` are the arguments passed when HelloWorld is called using a
    139         `#!HelloWorld` code block.
     96        `content` is the text enclosed in parenthesis at the call of the
     97          macro. Note that if there are ''no'' parenthesis (like in, e.g.
     98          [[HelloWorld]]), then `content` is `None`.
     99        `args` will contain a dictionary of arguments when called using the
     100          Wiki processor syntax and will be `None` if called using the
     101          macro syntax.
    140102        """
    141         return 'Hello World, text = %s, args = %s' % \
    142             (Markup.escape(text), Markup.escape(repr(args)))
    143 
     103        return 'Hello World, content = ' + unicode(content)
    144104}}}
    145105
    146 Note: `expand_macro` は 第4パラメータに、 ''`args`'' を任意に取ることもできます。 このマクロが [WikiProcessors WikiProcessor] として呼ばれたとき、 `key=value` 形式の [WikiProcessors#UsingProcessors プロセッサパラメータ] を渡すことも可能です。もし、このパラメータを指定したとき、これらの値は、ディクショナリの中に保存され、 追加の `args` パラメータによって渡されます。一方で、マクロとして呼び出されたときは、 `args` パラメータは、 `None` として扱われます (''0.12 以降'') 。
     106Note that `expand_macro` optionally takes a 4^th^ parameter ''`args`''. When the macro is called as a [WikiProcessors WikiProcessor], it is also possible to pass `key=value` [WikiProcessors#UsingProcessors processor parameters]. If given, those are stored in a dictionary and passed in this extra `args` parameter. When called as a macro, `args` is `None`.
    147107
    148 例として、このように記述した場合:
     108For example, when writing:
    149109{{{
    150110{{{#!HelloWorld style="polite" -silent verbose
    … …  
    158118[[HelloWorld(<Hello World!>)]]
    159119}}}
    160 結果はこのようになります:
     120
     121One should get:
    161122{{{
    162 Hello World, text = <Hello World!> , args = {'style': u'polite', 'silent': False, 'verbose': True}
    163 Hello World, text = <Hello World!> , args = {}
    164 Hello World, text = <Hello World!> , args = None
     123Hello World, text = <Hello World!>, args = {'style': u'polite', 'silent': False, 'verbose': True}
     124Hello World, text = <Hello World!>, args = {}
     125Hello World, text = <Hello World!>, args = None
    165126}}}
    166127
    167 Note: `expand_macro` が返す値は、 HTML がエスケープされて '''いない''' ことに注意して下さい。期待する戻り値によっては、あなた自身でエスケープする必要があります (`return Markup.escape(result)` を使用できます)。また、戻り値として HTML が返ってくると分かっているならば、結果を (`return Markup(result)`) という風に Genshi が提供している Markup (`from genshi.core import Markup`) オブジェクトでラップすることもできます。
     128Note that the return value of `expand_macro` is '''not''' HTML escaped. Depending on the expected result, you should escape it yourself (using `return Markup.escape(result)`), or if this is indeed HTML, wrap it in a Markup object: `return Markup(result)` (`from trac.util.html import Markup`).
    168129
    169 また、`text` を Wiki としてマークアップする場合、 Wiki Formatter (`from trac.wiki import Formatter`) オブジェクトも再帰的に使用することができます。以下がサンプルです:
     130You can also recursively use a wiki formatter to process the `content` as wiki markup:
    170131
    171 {{{
    172 #!python
    173 from genshi.core import Markup
     132{{{#!python
     133from trac.wiki.formatter import format_to_html
    174134from trac.wiki.macros import WikiMacroBase
    175 from trac.wiki import Formatter
    176 import StringIO
    177135
    178136class 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())
     137    def expand_macro(self, formatter, name, content, args):
     138        content = "any '''wiki''' markup you want, even containing other macros"
     139        # Convert Wiki markup to HTML
     140        return format_to_html(self.env, formatter.context, content)
    185141}}}