VirtualBox

版本 2 (由 trac 修改，於 13 年 前) ( 差異 )

--

Trac Macros

  1. Trac Macros
    1. Using Macros
      1. Getting Detailed Help
      2. Example
    2. Available Macros
    3. Macros from around the world
    4. Developing Custom Macros
      1. Macro without arguments
      2. Macro with arguments

Trac macros are plugins to extend the Trac engine with custom 'functions' written in Python. A macro inserts dynamic HTML data in any context supporting WikiFormatting.

Another kind of macros are WikiProcessors. They typically deal with alternate markup formats and representation of larger blocks of information (like source code highlighting).

Using Macros

Macro calls are enclosed in two square brackets. Like Python functions, macros can also have arguments, a comma separated list within parentheses.

Getting Detailed Help

The list of available macros and the full help can be obtained using the MacroList macro, as seen below.

A brief list can be obtained via [[MacroList(*)]] or [[?]].

Detailed 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?]].

Example

A list of 3 most recently changed wiki pages starting with 'Trac':

Wiki Markup Display 
[[RecentChanges(Trac,3)]]

2023-6-2

[[RecentChanges?(Trac,3)]]

[[RecentChanges]]

列出所有最近被修改的頁面，並按最後修改的時間排序。

此巨集能接受兩個參數以及一個已命名參數。 已命名參數可以放在參數列表中的任何位置。

第一個參數是前綴字串：如果提供，則結果列表中僅包含以前綴開頭的頁面。 如果省略此參數，則所有頁面都包括在列表中。

第二個參數是列表中最大條目數。

group參數決定列表的顯示方式：

group=date
頁面顯示在按日期分組的項目符號列表中(預設)。
group=none
頁面顯示在單個項目符號列表中。

提示: 如果您只想指定最大條目數，並且不想按前綴過濾，請指定第一個參數為空。 例如: [[RecentChanges(,10,group=none)]]. 

[[?]]

[[Image]]

Embed an image in wiki-formatted text. The first argument is the file …

[[InterTrac]]

Provide a list of known InterTrac prefixes.

[[InterWiki]]

Provide a description list for the known InterWiki prefixes.

[[KnownMimeTypes]]

List all known mime-types which can be used as WikiProcessors. Can be …

etc.

Available Macros

Note that the following list will only contain the macro documentation if you've not enabled -OO optimizations, or not set the PythonOptimize option for mod_python.

[[Image]]

在Wiki格式的文字中嵌入一張圖像。

第一個參數是檔案規範。檔案規範有三種方式引用附件:

  • module:id:file，其中模塊可以是Wiki或待辦事項，以引用指定的附件文件。
  • id:file 與上面相同，但id是待辦事項縮寫或Wiki頁面名稱。
  • file用來引用本地附件。這僅在Wiki頁面或待辦事項中有效。

檔案規範也可以參考:

  • 儲存庫裡的檔案, 使用 source:file 語法 (source:file@rev 也可以用)。
  • 直接URLs: Trac專案下使用/file, 伺服器下使用//file, 或其他伺服器下http://server/file。 也可以使用InterWiki前綴。
  • 數據URL方案​rfc2397，前提是該URL要用引號括起來。

剩餘的參數是可選的，並允許配置<img>元素的屬性和樣式:

  • 數字加上單位被譯為圖像的大小 (例如: 120px，25%)
  • right, left, center, top, bottom 和 middle 被譯為圖像對齊方式 (替代地，前三個能被align=...指定，而後三個使用valign=...)
  • link=some TracLinks...可用TracLinks替換原本原圖像的連接。如果未指定任何值，則刪除連接。
  • inline指定將生成的內容作為內嵌XHTML元素。 預設情況下，不會生成內嵌內容，因此圖像不會出現在章節標題和其他單行內容中。
  • nolink表示沒有連接到原圖像(已廢棄，請改用link=)
  • key=value樣式被譯為圖像的HTML屬性或CSS樣式指示。有效保留字為:
    • align, valign, border, width, height, alt, title, longdesc, class, margin, margin-(left,right,top,bottom), id 和 usemap
    • border, margin, 和 margin-* 只能給一個數字(單位是像素)。
    • margin由使用自動邊距的center代替

範例: 

[[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)]]           # 來自另一個待辦事項
[[Image(ticket:36:boo.jpg)]]    # 來自另一個待辦事項 (長格式)
[[Image(source:/img/bee.jpg)]]  # 來自儲存庫
[[Image(htdocs:foo/bar.png)]]   # 來自專案htdocs目錄
[[Image(shared:foo/bar.png)]]   # 來自共享的htdocs目錄 (從 1.0.2)

改編自Shun-ichi Goto創建的Image.py巨集 <gotoh@…>

[[Include]]

A macro to include other resources in wiki pages.

More documentation to follow.

[[InterTrac]]

提供一個已知InterTrac前綴的列表。

[[InterWiki]]

提供一個已知InterWiki前綴的描述列表。

[[KnownMimeTypes]]

列出所有已知可以用作WikiProcessors的MIME類型。

可以給定一個選填參數，作為MIME類型過濾。

[[MacroList]]

顯示所有已安裝的Wiki巨集列表，包括其文檔。

可以將特定巨集的名稱作為參數提供。 在這種情況下，將僅呈現該巨集的文檔。

注意，如果為mod_python啟用了PythonOptimize選項，則此巨集將無法顯示巨集的文檔！

[[PageOutline]]

顯示當前Wiki頁面的結構大綱，大綱中的每個項目都是指向相應標題的連結。

此巨集接受四個可選參數:

  • 第一個是配置大綱中應包括的標題級別。 例如，在此處指定"1"將僅頂層標題包含在大綱中。 指定"2-3"將使大綱包括第二層和第三層的所有標題。預設是包括所有標題級別。
  • 第二個參數用於指定自定義標題(預設是無標題)。
  • 第三個參數選擇大綱的樣式。可以是inline或pullout(預設是後者)。 inline樣式將大綱呈現為內容的一部分，而pullout會導致大綱在默認情況下浮動到內容右側的框中。
  • 第四個參數指定大綱是否編號。可以編號或不編號（預設是編號）。 此參數僅在inline樣式中有效。

[[RecentChanges]]

列出所有最近被修改的頁面，並按最後修改的時間排序。

此巨集能接受兩個參數以及一個已命名參數。 已命名參數可以放在參數列表中的任何位置。

第一個參數是前綴字串：如果提供，則結果列表中僅包含以前綴開頭的頁面。 如果省略此參數，則所有頁面都包括在列表中。

第二個參數是列表中最大條目數。

group參數決定列表的顯示方式：

group=date
頁面顯示在按日期分組的項目符號列表中(預設)。
group=none
頁面顯示在單個項目符號列表中。

提示: 如果您只想指定最大條目數，並且不想按前綴過濾，請指定第一個參數為空。 例如: [[RecentChanges(,10,group=none)]].

[[RepositoryIndex]]

顯示可用儲存庫的列表。

可以接收以下已命名參數:

format
選擇呈現格式:
  • compact 產生一個以逗號分隔的儲存庫列表 (預設)
  • list 產生一個儲存庫清單
  • table 產生一個表格檢視，類似於瀏覽檢視頁面
glob
對儲存庫名進行全局過濾 (預設過濾是 '*')
order
以給定的欄位進行排序 ("name", "date" 或 "author")
desc
設置為1時，按降序排列

[[SubscriberList]]

顯示所有已安裝的提醒訂閱者列表，包括其文檔。

可以將特定訂閱者的名稱作為參數提供。 在這種情況下，將僅呈現該訂閱者的文檔。

注意，如果為mod_python啟用了PythonOptimize選項，則此巨集將無法顯示訂閱者的文檔！

[[TicketQuery]]

Wiki巨集列出符合特定條件的待辦事項。

此巨集接受以逗號分隔的鍵值參數列表，形式為"key=value"。

如果鍵是欄位名，則該值必須使用 TracQuery#QueryLanguage 中定義的過濾器說明符語法。 請注意，這不同於query:以?開頭的簡化URL語法。 逗號(,)可以包含在欄位值中，方法是使用反斜杠(\)進行跳脫。

欄位限制可以用or參數連接形成或邏輯。

除過濾器外，其他幾個已命名參數也可用於控制結果的顯示方式。它們都是可選的。

format 參數決定待辦事項列表的顯示方式:

  • list -- 默認的顯示方式，每行顯示待辦事項ID與摘要。
  • compact -- 以逗號分隔待辦事項ID來顯示。
  • count -- 僅顯示匹配待辦事項的數量
  • rawcount -- 僅顯示匹配待辦事項的數量，甚至不顯示相應查詢的連結 (從 1.1.1)
  • table -- 與自定義查詢類似的視圖 (但沒有控制界面)
  • progress -- 與里程碑進度條類似的視圖

max 參數可用於限制顯示的待辦事項數量(預設為0，即無最大值)。

order 參數設置用於排序待辦事項的欄位(預設為id)。

desc 參數指示是否應反轉待辦事項的排序(預設為false)。

group 參數設定用於待辦事項分組的欄位(預設為未設置)。

groupdesc 參數指示是否應反轉群組的排序(預設為false)。

可以將verbose參數設置為true值，來列出待辦事項的描述。 僅適用於table格式。 不推薦使用rows參數

rows 參數可用於指定應將哪些欄位視為行，例如 rows=description|summary

col 參數可用於指定應將哪些欄位視為列。僅適用於table格式。

為了與Trac 0.10兼容，如果為巨集提供了最後一個位置參數，它將用於指定format。 同樣，"&"仍然可以作為欄位分隔符(order除外)，但不建議使用。

[[TitleIndex]]

依字母順序列出所有wiki頁面。

接受一個前綴字串參數:如果提供，則結果列表中僅包含以前綴開頭的頁面。 如果省略此參數，則所有頁面都包括在列表中。 如果指定了前綴，還可以指定第二個參數hideprefix，隱藏前綴字串的顯示。

前綴字串支持標準的相對路徑表示法(當在Wiki頁面中使用巨集)。 以./開頭的前綴字串相對於當前頁面，並且可以用../指定父頁面。

幾個可使用的已命名參數:

  • format=compact: 頁面以逗號分隔的方式顯示。
  • format=group: 頁面列表將根據通用前綴進行分組。 此格式還支持一個min=n參數，其中n是要分成一個組的最小數目。
  • format=hierarchy: 頁面列表將根據路徑層次結構顯示。 此格式還支持一個min=n參數，其中n是要階層顯示的最小層數
  • depth=n: 限制要列出頁面的深度。 如果設置為0，則僅顯示頂層頁面； 如果設置為1，則僅顯示到頂層的子頁面。 如果未設置或設置為-1，則將顯示所有頁面。
  • include=page1:page*2: 僅包含以冒號分隔的頁面列表中匹配的頁面。 如果列表為空，或者沒有給出include參數，則包括所有頁面。
  • exclude=page1:page*2: 排除以冒號分隔的頁面列表中匹配的頁面。

include和exclude列表接受shell樣式的模式。

[[TracAdminHelp]]

顯示 trac-admin 指令說明.

例如: 

[[TracAdminHelp]]               # 所有指令
[[TracAdminHelp(wiki)]]         # 所有 wiki 指令
[[TracAdminHelp(wiki export)]]  # "wiki export" 指令
[[TracAdminHelp(upgrade)]]      # upgrade 指令

[[TracGuideToc]]

顯示Trac手冊的內容索引。

此巨集顯示了製作手冊內容索引的一種快速而骯髒的方法。 內容索引將包含Trac*和WikiFormatting頁面，且無法自定義。 更多自定義內容請參閱 ​TocMacro

[[TracIni]]

生成Trac配置文檔的說明文件。

通常，這將使用在TracIni頁面。 此巨集能接受兩個參數以及兩個已命名參數。

兩個參數依序是 區段過濾 與 選項過濾: 僅名字從頭開始有批配的選項被顯示。

可使用的已命名參數:

section
對區段名的全局過濾
option
對選項名的全局過濾

[[Workflow]]

產生一個工作流程圖.

此巨集接受一個TracWorkflow配置，然後將狀態和狀態轉換的關係化為一張有向圖。 如果未提供任何參數，則呈現當前待辦事項的工作流程。

在WikiProcessor模式下，可以指定width與height參數。 (預設: width = 800 和 heigth = 600)

工作流程檔案路徑可以被指定在巨集或 WikiProcessor 的file參數中。 要指定檔案修訂版本可以在路徑後加上@<rev>。 file參數必須加上單或雙引號。(從 1.3.2)

範例: 

[[Workflow()]]

[[Workflow(go = here -> there; return = there -> here)]]

[[Workflow(file=/contrib/workflow/enterprise-workflow.ini@1)]]

{{{#!Workflow file="/contrib/workflow/enterprise-workflow.ini"
}}}

{{{#!Workflow width=700 height=700
leave = * -> *
leave.operations = leave_status
leave.default = 1

create = <none> -> new
create.default = 1

create_and_assign = <none> -> assigned
create_and_assign.label = assign
create_and_assign.permissions = TICKET_MODIFY
create_and_assign.operations = may_set_owner

accept = new,assigned,accepted,reopened -> accepted
accept.permissions = TICKET_MODIFY
accept.operations = set_owner_to_self

resolve = new,assigned,accepted,reopened -> closed
resolve.permissions = TICKET_MODIFY
resolve.operations = set_resolution

reassign = new,assigned,accepted,reopened -> assigned
reassign.permissions = TICKET_MODIFY
reassign.operations = set_owner

reopen = closed -> reopened
reopen.permissions = TICKET_CREATE
reopen.operations = del_resolution
}}}

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.

Developing Custom Macros

Macros, like Trac itself, are written in the ​Python programming language and are developed as part of TracPlugins.

For more information about developing macros, see the ​development resources on the main project site.

Here are 2 simple examples showing how to create a Macro with Trac 0.11.

Also, have a look at ​Timestamp.py for an example that shows the difference between old style and new style macros and at the ​macros/README which provides a little more insight about the transition.

Macro without arguments

To test the following code, you should saved it in a timestamp_sample.py file located in the TracEnvironment's plugins/ directory. 

from datetime import datetime
# Note: since Trac 0.11, datetime objects are used internally

from genshi.builder import tag

from trac.util.datefmt import format_datetime, utc
from trac.wiki.macros import WikiMacroBase

class TimeStampMacro(WikiMacroBase):
    """Inserts the current time (in seconds) into the wiki page."""

    revision = "$Rev$"
    url = "$URL$"

    def expand_macro(self, formatter, name, text):
        t = datetime.now(utc)
        return tag.b(format_datetime(t, '%c'))

Macro with arguments

To test the following code, you should saved it in a helloworld_sample.py file located in the TracEnvironment's plugins/ directory. 

from genshi.core import Markup

from trac.wiki.macros import WikiMacroBase

class HelloWorldMacro(WikiMacroBase):
    """Simple HelloWorld macro.

    Note that the name of the class is meaningful:
     - it must end with "Macro"
     - what comes before "Macro" ends up being the macro name

    The documentation of the class (i.e. what you're reading)
    will become the documentation of the macro, as shown by
    the !MacroList macro (usually used in the WikiMacros page).
    """

    revision = "$Rev$"
    url = "$URL$"

    def expand_macro(self, formatter, name, text, args):
        """Return some output that will be displayed in the Wiki content.

        `name` is the actual name of the macro (no surprise, here it'll be
        `'HelloWorld'`),
        `text` is the text enclosed in parenthesis at the call of the macro.
          Note that if there are ''no'' parenthesis (like in, e.g.
          [[HelloWorld]]), then `text` is `None`.
        `args` are the arguments passed when HelloWorld is called using a
        `#!HelloWorld` code block.
        """
        return 'Hello World, text = %s, args = %s' % \
            (Markup.escape(text), Markup.escape(repr(args)))

Note that expand_macro optionally takes a 4th parameter args. When the macro is called as a WikiProcessor, it's also possible to pass key=value processor parameters. If given, those are stored in a dictionary and passed in this extra args parameter. On the contrary, when called as a macro, args is None. (since 0.12).

For example, when writing: 

{{{#!HelloWorld style="polite"
<Hello World!>
}}}

{{{#!HelloWorld
<Hello World!>
}}}

[[HelloWorld(<Hello World!>)]]

One should get: 

Hello World, text = <Hello World!> , args = {'style': u'polite'}
Hello World, text = <Hello World!> , args = {}
Hello World, text = <Hello World!> , args = None

Note that the return value of expand_macro is not HTML escaped. Depending on the expected result, you should escape it by yourself (using return Markup.escape(result)) or, if this is indeed HTML, wrap it in a Markup object (return Markup(result)) with Markup coming from Genshi, (from genshi.core import Markup).

You can also recursively use a wiki Formatter (from trac.wiki import Formatter) to process the text as wiki markup, for example by doing: 

from genshi.core import Markup
from trac.wiki.macros import WikiMacroBase
from trac.wiki import Formatter
import StringIO

class HelloWorldMacro(WikiMacroBase):
        def expand_macro(self, formatter, name, text, args):
                text = "whatever '''wiki''' markup you want, even containing other macros"
                # Convert Wiki markup to HTML, new style
                out = StringIO.StringIO()
                Formatter(self.env, formatter.context).format(text, out)
                return Markup(out.getvalue())
注意: 瀏覽 TracWiki 來幫助您使用wiki功能

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette