VirtualBox

Trac Macros

Contents

  1. Using Macros
    1. Getting Detailed Help
  2. Available Macros
  3. Contributed macros
  4. Developing Custom Macros
    1. Macro without arguments
    2. Macro with arguments

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.

The macro syntax is [[macro-name(optional-arguments)]].

WikiProcessors are another kind of macro, commonly used for source code highlighting using a processor like !#python or !#apache: 

{{{#!wiki-processor-name
...
}}}

Using Macros

Macro 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':

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

2023-6-2

Getting Detailed Help

The list of available macros and the full help can be obtained using the MacroList macro, see 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?]].

Available Macros

[[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
}}}

Contributed macros

The ​Trac Hacks site provides a large collection of macros and other Trac 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.

Developing Custom Macros

Macros, like Trac itself, are written in the ​Python programming language and are a type of plugin.

Here are 2 simple examples showing how to create a Macro. For more information about developing macros, see the ​development resources and ​sample-plugins.

Macro without arguments

To test the following code, copy it to timestamp_sample.py in the TracEnvironment's plugins/ directory. 

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

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

    def expand_macro(self, formatter, name, content, args=None):
        t = datetime_now(utc)
        return tag.strong(format_datetime(t, '%c'))

Macro with arguments

To test the following code, copy it to helloworld_sample.py in the TracEnvironment's plugins/ directory. 

from trac.util.translation import cleandoc_
from trac.wiki.macros import WikiMacroBase

class HelloWorldMacro(WikiMacroBase):
    _description = cleandoc_(
    """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).
    """)

    def expand_macro(self, formatter, name, content, args=None):
        """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'`),
        `content` 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 `content` is `None`.
        `args` will contain a dictionary of arguments when called using the
          Wiki processor syntax and will be `None` if called using the
          macro syntax.
        """
        return 'Hello World, content = ' + unicode(content)

Note that expand_macro optionally takes a 4th parameter args. When the macro is called as a WikiProcessor, it is also possible to pass key=value 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.

For example, when writing: 

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

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

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

One should get: 

Hello World, text = <Hello World!>, args = {'style': u'polite', 'silent': False, 'verbose': True}
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 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).

You can also recursively use a wiki formatter to process the content as wiki markup: 

from trac.wiki.formatter import format_to_html
from trac.wiki.macros import WikiMacroBase

class HelloWorldMacro(WikiMacroBase):
    def expand_macro(self, formatter, name, content, args):
        content = "any '''wiki''' markup you want, even containing other macros"
        # Convert Wiki markup to HTML
        return format_to_html(self.env, formatter.context, content)
最後修改 18 月 前 最後修訂日期 2023-6-2 上午10:32:55
注意: 瀏覽 TracWiki 來幫助您使用wiki功能

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