Wiki ナビゲーション

Wiki マクロ

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

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

マクロの利用

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

利用例

 [[Timestamp]]

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

Sun Nov 24 12:18:17 2024

 [[HelloWorld(Testing)]]

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

Hello World, args = Testing

マクロ一覧

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

[[InterTrac]]

登録済みの InterTrac プレフィックスの一覧を表示します。

[[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 シンタックスを使用します。 (source:file@rev も可能です)

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

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

指示として解釈されます。有効なキーは以下の通りです:

align, border, width, height, alt, title, longdesc, class, id および usemap
border は数値での指定のみ可能です。

例:

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

他の 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 オプションが有効になっている場合は、マクロのドキュメントを表示することが出来ません!

[[TracIni]]

Trac の設定ファイルのドキュメントを生成します。

通常、このマクロは Wiki ページ TracIni の中で使用されます。省略可能な引数にはコンフィグのセクションのフィルタ、コンフィグのオプション名のフィルタを指定できます:フィルタで指定された文字列で始まるコンフィグのセクションとオプション名のみが出力されます。

[[Timestamp]]

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

[[HelloWorld]]

マクロの例です。

[[TracGuideToc]]

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

[[TracAdminHelp]]

trac-admin コマンドのヘルプを表示します。

例:

[[TracAdminHelp]]               # 全てのコマンド
[[TracAdminHelp(wiki)]]         # 全ての wiki コマンド
[[TracAdminHelp(wiki export)]]  # "wiki export" コマンド
[[TracAdminHelp(upgrade)]]      # upgrade コマンド

[[TicketQuery]]

指定された条件にマッチするチケットを一覧表示します。

このマクロは 2 つのパラメータを許容します。第 2 パラメータは省略可能です。

第 1 パラメータはクエリそのものを指し、 query: のような Wiki リンクと同じシンタックスを使用します ( "?" で始まる可変のシンタックスは 含まれません)。

第 2 パラメータはチケットの一覧がどのように表示されるかを決定します: デフォルトの表示形式は、チケットIDに続いて、チケットの概要が各行に 1 つずつリストされます。第 2 パラメータが以下のように指定された場合:

compact -- チケットID の一覧をカンマ区切りで表示します。
count -- 条件に当てはまるチケットの数のみが表示されます。

Macros from around the world

The Trac Hacks site provides a wide collection of macros and other Trac plugins contributed by the Trac community. If you're looking for new macros, or have written one that you'd like to share with the world, please don't hesitate to visit that site.

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

マクロは、 Trac 自身と同じように Python programming language で書かれています。とてもシンプルなモジュールで、たった一つの execute() 関数だけを持ちます。マクロの識別はファイル名で行います。 Trac は、呼び出されたマクロが返却したデータをマクロが呼び出された Wiki ページの 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.config.get('trac', 'repository_dir')

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

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

See also: WikiProcessors, WikiFormatting, TracGuide

異なるフォーマットでダウンロード:

Plain Text