Changes between Initial Version and Version 1 of WikiMacros


Ignore:
Timestamp:
2010/10/12 00:14:07 (14 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • WikiMacros

    v1 v1  
     1= Trac マクロ = #TracMacros 
     2 
     3[[PageOutline]] 
     4 
     5Trac マクロとは、 Python で書かれた 'カスタム関数' によって Trac の Wiki エンジンを拡張するプラグインです。 WikiFormatting エンジンが利用可能なあらゆるコンテキストにおいて、マクロを使用することによって、動的な HTML データが挿入されます。 
     6 
     7もう 1 種類のマクロは WikiProcessors です。これは通常、 Wiki 以外のマークアップ形式と表示を取り扱うために使用し、多くは、 (ソースコードハイライトのような) より大きいブロックに使用します。 
     8 
     9== マクロの利用 == #UsingMacros 
     10 
     11マクロ呼び出しは、二つの ''角括弧 (square brackets) '' で括られた箇所です。 Python 関数のように、マクロは引数を取ることができ、括弧 (parenthesis) の中に、カンマで区切ったリストで表記します。 
     12 
     13=== 詳細なヘルプを見るには ===#GettingDetailedHelp  
     14マクロの一覧と完全なヘルプは、 下記の[#AvailableMacros マクロ一覧] にある !MacroList マクロを使用してみることができます。 
     15 
     16簡単なマクロ一覧は ![[MacroList(*)]] や ![[?]] で見ることができます。 
     17 
     18特定のマクロの詳細なヘルプを参照したい場合は、 !MacroList マクロに引数渡すことによって参照することができます。例) ![[MacroList(MacroList)]] 。もしくは、便宜上、 ![[MacroList?]] のようにマクロ名にクエスチョンマーク (?) をつけることでヘルプをみることができます。 
     19 
     20 
     21 
     22=== 利用例 === #Example 
     23 
     24'Trac' で始まる Wiki ページの最近の変更履歴 3 件分を表示するマクロです: 
     25 
     26||= Wiki マークアップ =||= 表示 =|| 
     27{{{#!td 
     28  {{{ 
     29  [[RecentChanges(Trac,3)]] 
     30  }}} 
     31}}} 
     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; font-size: 80%" 
     51[[?]] 
     52}}} 
     53 
     54== マクロ一覧 == #AvailableMacros 
     55 
     56''Note: 以下に示すリストはマクロドキュメントを含むものだけです。 `-OO` による最適化や、 [wiki:TracModPython mod_python] での `PythonOptimize` オプションが設定されていると表示されません。'' 
     57 
     58[[MacroList]] 
     59 
     60== 世界のマクロを共有 == #Macrosfromaroundtheworld 
     61 
     62[http://trac-hacks.org/ Trac Hacks] というサイトは、コミュニティに寄稿されたマクロと [TracPlugins プラグイン] を収集し提供しています。新しいマクロを探している、共有したいマクロを作成した、などの場合は遠慮なく Trac Hacks のサイトを訪問してください。 
     63 
     64== カスタムマクロを開発する == #DevelopingCustomMacros 
     65マクロは、 Trac 本体と同様 [http://python.org/ Python] で書かれています。そして TracPlugins の一種として開発します 
     66 
     67マクロの開発についての詳しい情報は [http://trac.edgewall.org/wiki/TracDev リソースの開発] を参照してください。 
     68 
     69 
     70Trac 0.11 でマクロを作成する簡単な例を 2 つ紹介します。 
     71 
     72古いマクロと新しいマクロの違いを示す例は [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] を参照してください。 
     73 
     74=== 引数なしのマクロ === #Macrowithoutarguments 
     75下記のソースコードをテストするためには、このソースコードを `timestamp_sample.py` として保存し、 TracEnvironment の `plugins/` に配置しなければなりません。 
     76{{{ 
     77#!python 
     78from datetime import datetime 
     79# Note: since Trac 0.11, datetime objects are used internally 
     80 
     81from genshi.builder import tag 
     82 
     83from trac.util.datefmt import format_datetime, utc 
     84from trac.wiki.macros import WikiMacroBase 
     85 
     86class TimeStampMacro(WikiMacroBase): 
     87    """Inserts the current time (in seconds) into the wiki page.""" 
     88 
     89    revision = "$Rev$" 
     90    url = "$URL$" 
     91 
     92    def expand_macro(self, formatter, name, text): 
     93        t = datetime.now(utc) 
     94        return tag.b(format_datetime(t, '%c')) 
     95}}} 
     96 
     97=== 引数付きのマクロ === #Macrowitharguments 
     98下記のソースコードをテストするためには、このソースコードを `helloworld_sample.py` として保存し、 TracEnvironment の `plugins/` に配置しなければなりません。 
     99{{{ 
     100#!python 
     101from genshi.core import Markup 
     102 
     103from trac.wiki.macros import WikiMacroBase 
     104 
     105class HelloWorldMacro(WikiMacroBase): 
     106    """Simple HelloWorld macro. 
     107 
     108    Note that the name of the class is meaningful: 
     109     - it must end with "Macro" 
     110     - what comes before "Macro" ends up being the macro name 
     111 
     112    The documentation of the class (i.e. what you're reading) 
     113    will become the documentation of the macro, as shown by 
     114    the !MacroList macro (usually used in the WikiMacros page). 
     115    """ 
     116 
     117    revision = "$Rev$" 
     118    url = "$URL$" 
     119 
     120    def expand_macro(self, formatter, name, text, args): 
     121        """Return some output that will be displayed in the Wiki content. 
     122 
     123        `name` is the actual name of the macro (no surprise, here it'll be 
     124        `'HelloWorld'`), 
     125        `text` is the text enclosed in parenthesis at the call of the macro. 
     126          Note that if there are ''no'' parenthesis (like in, e.g. 
     127          [[HelloWorld]]), then `text` is `None`. 
     128        `args` are the arguments passed when HelloWorld is called using a 
     129        `#!HelloWorld` code block. 
     130        """ 
     131        return 'Hello World, text = %s, args = %s' % \ 
     132            (Markup.escape(text), Markup.escape(repr(args))) 
     133 
     134}}} 
     135 
     136Note: `expand_macro` は 第4パラメータに、 ''`args`'' を任意に取ることもできます。 このマクロが [WikiProcessors WikiProcessor] として呼ばれたとき、 `key=value` 形式の [WikiProcessors#UsingProcessors プロセッサパラメータ] を渡すことも可能です。もし、このパラメータを指定したとき、これらの値は、ディクショナリの中に保存され、 追加の `args` パラメータによって渡されます。一方で、マクロとして呼び出されたときは、 `args` パラメータは、 `None` として扱われます (''0.12 以降'') 。 
     137 
     138例として、このように記述した場合: 
     139{{{ 
     140{{{#!HelloWorld style="polite" 
     141<Hello World!> 
     142}}} 
     143 
     144{{{#!HelloWorld 
     145<Hello World!> 
     146}}} 
     147 
     148[[HelloWorld(<Hello World!>)]] 
     149}}} 
     150結果はこのようになります: 
     151{{{ 
     152Hello World, text = <Hello World!> , args = {'style': u'polite'} 
     153Hello World, text = <Hello World!> , args = {} 
     154Hello World, text = <Hello World!> , args = None 
     155}}} 
     156 
     157Note: `expand_macro` が返す値は、 HTML がエスケープされて '''いない''' ことに注意して下さい。期待する戻り値によっては、あなた自身でエスケープする必要があります (`return Markup.escape(result)` を使用できます)。また、戻り値として HTML が返ってくると分かっているならば、結果を (`return Markup(result)`) という風に Genshi が提供している Markup (`from genshi.core import Markup`) オブジェクトでラップすることもできます。 
     158 
     159また、`text` を Wiki としてマークアップする場合、 Wiki Formatter (`from trac.wiki import Formatter`) オブジェクトも再帰的に使用することができます。以下がサンプルです: 
     160 
     161{{{ 
     162#!python 
     163    text = "whatever wiki markup you want, even containing other macros" 
     164    # Convert Wiki markup to HTML, new style 
     165    out = StringIO() 
     166    Formatter(self.env, formatter.context).format(text, out) 
     167    return Markup(out.getvalue()) 
     168}}}