Trac 宏

Trac 宏通过自定义功能扩展 Trac。宏是一种特殊类型的插件，用 Python 编写。宏在任何支持 Wiki格式化 的上下文中生成 HTML。

宏语法是 [[macro-name(optional-arguments)]]。

Wiki处理器 是另一种宏，通常用于使用诸如 !#python 或 !#apache 等处理器进行源代码高亮显示

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

使用宏

宏调用被包含在双括号 [[..]] 中。像 Python 函数一样，宏可以有参数，参数以逗号分隔的列表形式出现在括号 [[..(,)]] 内。一个常用的宏是列出维基页面最近 3 次更改，或者此处，例如，所有以“Trac”开头的维基页面

维基标记	显示
[[RecentChanges(Trac,3)]]	06/02/2023 Trac工作流 (差异) Trac维基 (差异) Trac升级 (差异)

获取详细帮助

可用宏列表和完整帮助可以通过 MacroList 宏获取，请参见 下方。

可以通过 [[MacroList(*)]] 或 [[?]] 获取简要列表。

通过将其作为参数传递给 MacroList，例如 [[MacroList(MacroList)]]，可以获取特定宏的详细帮助，或者更方便地，通过在宏名称后附加问号 (?)，例如 [[MacroList?]]。

可用宏

[[Image]]

在维基格式文本中嵌入图像。

第一个参数是文件规范。文件规范可以通过三种方式引用附件

• module:id:file，其中 module 可以是 wiki 或 ticket，指代指定维基页面或工单中名为 file 的附件。
• id:file：同上，但 id 是工单简称或维基页面名称。
• file 指代名为“file”的本地附件。这仅适用于该维基页面或工单内部。

文件规范也可以指

• 仓库文件，使用 source:file 语法（source:file@rev 也适用）。
• 文件，使用直接 URL：/file 表示项目相对路径，//file 表示服务器相对路径，或 http://server/file 表示绝对位置。可以使用 InterWiki 前缀。
• 嵌入数据，使用 ​rfc2397 data URL 方案，前提是 URL 需用引号括起来。

其余参数是可选的，允许配置渲染的 <img> 元素的属性和样式

• 数字和单位被解释为图像的大小（例如 120px，25%）
• right、left、center、top、bottom 和 middle 被解释为图像的对齐方式（另外，前三个可以使用 align=... 指定，后三个可以使用 valign=... 指定）
• link=一些 Trac链接... 将指向图像源的链接替换为使用 Trac链接 指定的链接。如果未指定值，则链接将被简单地移除。
• 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)]]               # simplest
[[Image(photo.jpg, 120px)]]        # with image width size
[[Image(photo.jpg, right)]]        # aligned by keyword
[[Image(photo.jpg, nolink)]]       # without link to source
[[Image(photo.jpg, align=right)]]  # aligned by attribute

您可以使用来自维基页面、工单或其他模块的图像。

[[Image(OtherPage:foo.bmp)]]    # from a wiki page
[[Image(base/sub:bar.bmp)]]     # from hierarchical wiki page
[[Image(#3:baz.bmp)]]           # from another ticket
[[Image(ticket:36:boo.jpg)]]    # from another ticket (long form)
[[Image(source:/img/bee.jpg)]]  # from the repository
[[Image(htdocs:foo/bar.png)]]   # from project htdocs dir
[[Image(shared:foo/bar.png)]]   # from shared htdocs dir (since 1.0.2)

改编自 Shun-ichi Goto <gotoh@…> 创建的 Image.py 宏

[[Include]]

一个用于在维基页面中包含其他资源的宏。

更多文档待补充。

[[InterTrac]]

提供已知 InterTrac 前缀的列表。

[[InterWiki]]

提供已知 InterWiki 前缀的描述列表。

[[KnownMimeTypes]]

列出所有可用作 Wiki处理器 的已知 MIME 类型。

可以给定一个可选参数，该参数被解释为 MIME 类型过滤器。

[[MacroList]]

显示所有已安装的 Wiki 宏列表，包括可用文档。

可选地，可以提供特定宏的名称作为参数。在这种情况下，将只渲染该宏的文档。

请注意，如果 mod_python 启用了 PythonOptimize 选项，此宏将无法显示宏的文档！

[[PageOutline]]

显示当前维基页面的结构化大纲，大纲中的每个项目都是指向相应标题的链接。

此宏接受四个可选参数

• 第一个是数字或范围，用于配置应包含在大纲中的标题的最小和最大级别。例如，在此处指定“1”将导致大纲中只包含顶级标题。指定“2-3”将使大纲包含级别 2 和 3 的所有标题，作为一个嵌套列表。默认是包含所有标题级别。
• 第二个参数可用于指定自定义标题（默认为无标题）。
• 第三个参数选择大纲的样式。可以是 inline 或 pullout（后者是默认值）。inline 样式将大纲作为内容的正常部分渲染，而 pullout 则使大纲渲染在一个默认浮动到其他内容右侧的框中。
• 第四个参数指定大纲是否编号。可以是 numbered 或 unnumbered（前者是默认值）。此参数仅在 inline 样式中有效。

[[RecentChanges]]

列出所有最近修改过的页面，按上次修改时间排序。

此宏接受两个有序参数和一个命名参数。命名参数可以放置在参数列表中的任何位置。

第一个参数是前缀字符串：如果提供，则结果列表中只包含名称以此前缀开头的页面。如果省略此参数，则列表中包含所有页面。

第二个参数是列表中包含的最大页面数。

group 参数决定列表的呈现方式

group=date

页面以按日期分组的（默认）项目符号列表形式呈现。

group=none

页面以单个项目符号列表形式呈现。

提示：如果您只想指定最大条目数，而不想按前缀筛选，请指定一个空的第一个参数，例如 [[RecentChanges(,10,group=none)]]。

[[RepositoryIndex]]

显示可用仓库列表。

可以给定以下命名参数

format

选择渲染格式

• compact 生成逗号分隔的仓库前缀名称列表（默认）
• list 生成仓库前缀名称的描述列表
• table 生成表格视图，类似于“浏览视图”页面中可见的视图

glob

对仓库名称进行 glob 样式过滤（默认为 '*'）

order

按给定列（“name”、“date”或“author”之一）排序仓库

desc

设置为 1 时，按降序排序

[[SubscriberList]]

显示所有已安装通知订阅者的列表，包括可用文档。

可选地，可以提供特定订阅者的名称作为参数。在这种情况下，将只渲染该订阅者的文档。

请注意，如果 mod_python 启用了 PythonOptimize 选项，此宏将无法显示订阅者的文档！

[[TicketQuery]]

列出符合特定条件的工单的维基宏。

此宏接受逗号分隔的键值对参数列表，形式为“key=value”。

如果键是字段的名称，则该值必须使用 TracQuery#QueryLanguage 中定义的过滤器说明符语法。请注意，这与 query: 链接以 ? 字符开头的简化 URL 语法*不同*。逗号 (,) 可以通过反斜杠 (\) 转义后包含在字段值中。

要进行 OR 运算的字段约束组可以通过字面 or 参数分隔。

除了过滤器，还可以使用其他几个命名参数来控制结果的呈现方式。所有这些都是可选的。

format 参数决定工单列表的呈现方式

• list -- 默认显示方式是列出工单 ID 旁边的摘要，每个工单占一行。
• compact -- 工单以逗号分隔的工单 ID 列表形式呈现。
• count -- 只显示匹配工单的数量
• rawcount -- 只显示匹配工单的数量，甚至不带指向相应查询的链接（自 1.1.1 起）
• table -- 类似于自定义查询视图（但没有控件）的视图
• progress -- 类似于里程碑进度条的视图

max 参数可用于限制显示的工单数量（默认为 0，即无最大限制）。

order 参数设置用于工单排序的字段（默认为 id）。

desc 参数指示工单的顺序是否应反转（默认为 false）。

group 参数设置用于工单分组的字段（默认为未设置）。

groupdesc 参数指示组的自然显示顺序是否应反转（默认为 false）。

verbose 参数可以设置为真值，以获取列出工单的描述。仅适用于 table 格式。*已弃用，请使用 rows 参数*

rows 参数可用于指定哪些字段应作为行查看，例如 rows=description|summary

col 参数可用于指定哪些字段应作为列查看。仅适用于 table 格式。

为了与 Trac 0.10 兼容，如果宏给定最后一个位置参数，它将用于指定 format。此外，使用“&”作为字段分隔符仍然有效（order 除外），但已被弃用。

[[TitleIndex]]

在输出中插入所有维基页面的字母顺序列表。

接受一个前缀字符串作为参数：如果提供，则结果列表中只包含名称以此前缀开头的页面。如果省略此参数，则列出所有页面。如果指定了前缀，还可以给定一个值为 hideprefix 的第二个参数，以便从输出中移除该前缀。

前缀字符串支持标准相对路径表示法 *在维基页面中使用宏时*。以 ./ 开头的前缀字符串将相对于当前页面，父页面可以使用 ../ 指定。

可以指定几个命名参数

• 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]]               # all commands
[[TracAdminHelp(wiki)]]         # all wiki commands
[[TracAdminHelp(wiki export)]]  # the "wiki export" command
[[TracAdminHelp(upgrade)]]      # the upgrade command

[[TracGuideToc]]

显示 Trac 指南的目录。

此宏展示了一种快速且简单的方法来为帮助/指南创建目录。目录将包含 Trac* 和 WikiFormatting 页面，且无法自定义。有关更可定制的目录，请参见 ​TocMacro。

[[TracIni]]

生成 Trac 配置文件文档。

通常，这将在 TracIni 页面中使用。此宏接受两个有序参数和两个命名参数。

有序参数是配置节过滤器和配置选项名称过滤器：只有其节和名称以这些过滤器开头的配置选项才会被输出。

命名参数可以指定

section

对节名称进行 glob 样式过滤

option

对选项名称进行 glob 样式过滤

[[Workflow]]

渲染工作流图。

此宏接受 Trac工作流 配置，并将状态和转换渲染为有向图。如果未给定参数，则渲染当前工单工作流。

在 Wiki处理器 模式下，可以指定 width 和 height 参数（默认值：width = 800 和 height = 600）。

工作流文件的仓库范围路径可以指定为宏或 Wiki处理器 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
}}}

贡献的宏

​Trac Hacks 网站提供了由 Trac 社区贡献的大量宏和其他 Trac 插件。如果您正在寻找新的宏，或者已经编写了希望分享的宏，请访问该网站。

开发自定义宏

宏，像 Trac 本身一样，是用 ​Python 编程语言 编写的，并且是一种 插件。

这里有两个简单的例子展示如何创建宏。有关开发宏的更多信息，请参阅 ​开发资源 和 ​示例插件。

无参数宏

要测试以下代码，请将其复制到 Trac环境 的 plugins/ 目录中的 timestamp_sample.py 文件。

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'))

带参数宏

要测试以下代码，请将其复制到 Trac环境 的 plugins/ 目录中的 helloworld_sample.py 文件。

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)

请注意，expand_macro 可选地接受第四个参数 args。当宏作为 Wiki处理器 调用时，也可以传递 key=value 处理器参数。如果给定，这些参数将存储在字典中，并作为额外的 args 参数传递。当作为宏调用时，args 为 None。

例如，当编写时

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

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

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

应该得到

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

请注意，expand_macro 的返回值**未**进行 HTML 转义。根据预期结果，您应该自行转义（使用 return Markup.escape(result)），或者如果这确实是 HTML，则将其包装在 Markup 对象中：return Markup(result)（from trac.util.html import Markup）。

您还可以递归地使用维基格式化器将 content 处理为维基标记

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)