Wiki マクロ

Wiki マクロとは、Python で書かれた 'カスタム関数' によって Trac の Wiki エンジンを拡張するプラグインです。 WikiFormatting エンジンがサポートするあらゆるコンテキストにおいて、マクロを使用することによって、動的なHTMLデータが挿入されます。

もう1種類のマクロは WikiProcessors です。これは通常、Wiki以外のマークアップ形式と表示を取り扱うために使用し、多くは、(ソースコードハイライトのような)より大きいブロックに使用します。

マクロの利用

マクロ呼び出しは、二つの 角括弧 (square brackets) で括られた箇所です。Python関数のように、マクロは引数を取ることができ、括弧 (parenthesis) の中に、カンマで区切ったリストで表記します。

利用例

 [[Timestamp]]

は、以下のように表示されます:

Mon Jun 26 16:02:23 2017

 [[HelloWorld(Testing)]]

は、以下のように表示されます:

Hello World, args = Testing

利用可能なマクロ

Note: 以下に示すリストはマクロドキュメントを含むものだけです。 -OO による最適化や、 mod_python での PythonOptimize オプションが設定されていると表示されません。

[[TOC]]

Generate a table of contents for the current page or a set of pages. If no arguments are given, a table of contents is generated for the current page, with the top-level title stripped:

    [[TOC]]

To generate a table of contents for a set of pages, simply pass them as comma separated arguments to the TOC macro, e.g. as in

[[TOC(TracGuide, TracInstall, TracUpgrade, TracIni, TracAdmin, TracBackup, TracLogging,
         TracPermissions, TracWiki, WikiFormatting, TracBrowser, TracRoadmap, TracChangeset,
         TracTickets, TracReports, TracQuery, TracTimeline, TracRss, TracNotification)]]

The following control arguments change the default behaviour of the TOC macro:

Argument Meaning
heading=<x> Override the default heading of "Table of Contents"
noheading Suppress display of the heading.
depth=<n> Display headings of subsequent pages to a maximum depth of <n>.
inline Display TOC inline rather than as a side-bar.
titleindex Only display the page name and title of each page, similar to TitleIndex.

Note that the current page must also be specified if individual wiki pages are given in the argument list.

[[TitleIndex]]

すべての Wiki ページをアルファベットのリスト形式で出力に挿入します。

引数として、接頭辞となる文字列を許容します: 指定された場合、生成されるリストには ページ名が接頭辞で始まるものだけが含まれます。引数が省略された場合、 すべてのページがリストされます。

[[RecentChanges]]

最終更新日付ごとにグループ化し、 最近更新されたすべてのページをリストします。

このマクロは、2つの引数をとります。最初の引数はプレフィックス文字列です。 もし、プレフィックスが渡されていたら、結果のリストにはそのプレフィックスで始まるページ のみが、リストされます。もしこの引数が省略されると、すべてのページがリストされます。

2番目の引数は結果リストに表示するページの数を制限するために使用します。 例えば、5に制限した場合、 最近更新されたページのうち新しいもの5件がリストの中に含まれます。

[[PageOutline]]

現在のwikiページの構造的なアウトラインを表示します。 アウトラインのそれぞれの項目は一致する表題へのリンクとなります。

このマクロは3つの任意のパラメータをとります:

  • 1番目の引数はアウトラインに含まれる表題の範囲(レベル)を設定することができ、 数または数の範囲をとります。例えば、 "1" と指定した場合、アウトラインには トップレベルの表題のみが表示されます。 "2-3" と指定した場合、アウトラインには、 レベル 2 とレベル 3 のすべての表題がネストしたリストとして表示されます。 デフォルトでは、すべてのレベルの表題が表示されます。
  • 2番目の引数は、タイトルを特定するのに使われます。 (デフォルトはタイトルなし)。
  • 3番目の引数はアウトラインのスタイルを指定します。inline または pullout を指定することができます(後者がデフォルトです)。inline スタイルでは、 アウトラインを通常部分として整形しますが、 pullout スタイルでは、アウトラインを ボックスの中に整形します。そして、他の内容の右側に おかれます。
[[Image]]

画像をwiki形式のテキストに組み込みます。

1番目の引数は、ファイル名を指定します。ファイルの指定は添付ファイルやファイルなど 3つの指定方法があります。

  • module:id:file:module には wiki または ticket が指定でき、 file という名前の特定のwiki ページ または チケットの 添付ファイルを 参照します。
  • id:file: 上記と同様ですが、id は チケットまたは wiki の簡単な指定方法 です。
  • file:'file' というローカルの添付ファイルを指します。これはwiki ページまたは チケットの中でのみ使用できます。

またファイルはリポジトリのファイルも指定できます。 source:file のシンタックスを使用します。

残りの引数は任意で、 <img> 要素の 属性を設定します:

  • 数字と単位はサイズと解釈されます。 (ex. 120, 25%)
  • rightlefttopbottom は画像の配置として 解釈されます。
  • nolink は画像へのリンクを除外します。
  • key=value スタイルは 画像のHTML の属性として解釈されます。
  • key:value スタイルは、画像のCSS スタイルの指示として解釈されます。

例:

    [[Image(photo.jpg)]]                           # シンプルな指定方法
    [[Image(photo.jpg, 120px)]]                    # サイズ指定
    [[Image(photo.jpg, right)]]                    # キーワードによる配置指定
    [[Image(photo.jpg, nolink)]]                   # ソースへのリンクなし
    [[Image(photo.jpg, align=right)]]              # 属性による配置指定
    [[Image(photo.jpg, float:right)]]              # スタイルによるは位置指定
    [[Image(photo.jpg, float:right, border:solid 5px green)]] # 2つのスタイル指定

他の wiki ページ、チケット、モジュールの画像を使用することができます。

    [[Image(OtherPage:foo.bmp)]]    # 現在のモジュールが wiki の場合
    [[Image(base/sub:bar.bmp)]]     # 下位の wiki ページから
    [[Image(#3:baz.bmp)]]           # #3というチケットを指している場合
    [[Image(ticket:36:boo.jpg)]]
    [[Image(source:/images/bee.jpg)]] # リポジトリから直接指定する!
    [[Image(htdocs:foo/bar.png)]]   # プロジェクトのhtdocsディレクトリにあるファイル

Adapted from the Image.py macro created by Shun-ichi Goto <gotoh@taiyo.co.jp>

[[MacroList]]

インストールされている、すべての Wiki マクロをリストします。 もし利用可能ならばドキュメントも含みます。

非必須オプションとして、特定のマクロの名前を引数として渡すことが出来ます。 この場合、指定されたマクロのドキュメントだけを表示します。

Note: このマクロは mod_python の PythonOptimize オプションが有効になっている 場合は、マクロのドキュメントを表示することが出来ません!

[[Timestamp]]

現在の時刻を (秒単位で) Wiki ページに挿入する。

[[HelloWorld]]

マクロの例です。

[[TracGuideToc]]

このマクロは Wiki ページ一式の目次 (ToC) を簡単かつ荒っぽく作成する 例です。

[[LastModified]]

Macros from around the world

The Trac Project has a section dedicated to user-contributed macros, MacroBazaar. If you're looking for new macros, or have written new ones to share with the world, don't hesitate adding it to the MacroBazaar wiki page.


カスタムマクロを開発する

マクロは、 Trac 自身と同じように Python programming language で書かれています。とてもシンプルなモジュールで、たった一つの インタフェース (entry point) 関数だけを持ちます。マクロの識別はファイル名で行います。Trac は、呼び出されたマクロが返却したデータを HTML に挿入して表示を行います。

最も簡単なマクロの例です:

# MyMacro.py -- The world's simplest macro

def execute(hdf, args, env):
    return "Hello World called with args: %s" % args

Environment (env) オブジェクトを使用することも出来ます。この例では、コンフィグレーションとデータベースにアクセスしています:

def execute(hdf, txt, env):
    return env.get_config('trac', 'repository_dir')

Note: バージョン 0.9 以降、 Wiki マクロは TracPlugins でも書くことが出来るようになりました。これによって、 HTTP request へのアクセスなど、 "古い" マクロでは実現できなかったことが出来るようになりました。

マクロ開発についての詳しい情報は、プロジェクトメインサイトの 開発リソース を参照してください。


See also: WikiProcessors, WikiFormatting, TracGuide