=  Wiki宏 =

[[PageOutline]]

Trac宏是用Python编写的定制'函数'以扩展Trac引擎的插件. 宏可以在任意上下文中插入支持[ZhWikiFormatting Wiki格式]的动态HTML数据.

另一种宏是[ZhWikiProcessors Wiki解析器]. 它们通常处理替换的标记格式, 展示大块信息(就像源代码语法高亮).

== 使用宏 ==

宏的调用是放在两个''方括号''中. 像Python函数一样, 宏可以有参数(括号内用逗号分隔的列表).

Trac宏也可以写成[ZhTracPlugins Trac插件]. 这赋予其宏所不具有的某些能力, 例如直接访问HTTP请求.

=== 例子 ===

列出3个最新修改过的以'Trac'开头的wiki页面:

{{{
 [[RecentChanges(Trac,3)]]
}}}

显示:
 [[RecentChanges(Trac,3)]]

== 可用的宏 ==

''注意, 如果你没有启用`-OO`优化或设置[wiki:TracModPython mod_python]的!PythonOptimize选项, 下面的列表将只包括宏文档.''

[[MacroList]]

== 来自世界各地的宏 ==

[http://trac-hacks.org/ Trac Hacks]网站汇集了丰富的宏,以及Trac社区贡献的其他[TracPlugins Trac插件]. 如果你要找新的宏, 或写了一个想和全世界分享的宏, 请不要犹豫马上访问该网站.

== 开发定制宏 ==
宏, 像Trac本身, 是用[http://www.python.org/ Python编程语言]写的. 他们是很简单的模块, 通过文件名来标识, 并且只包含了一个`execute()`函数. Trac会在宏被调用的地方, 在wiki页面的HTML表示中插入宏的返回值.

关于开发宏的更多信息, 参见项目主站上的[wiki:TracDev 开发资源].


== 实现 ==

下面是2个简单的例子, 关于如何使用[wiki:0.11 Trac 0.11]创建宏. 看看source:trunk/sample-plugins/Timestamp.py的例子, 显示出老式与新式宏之间的区别, 也看看source:trunk/wiki-macros/README, 其中提供了更深入的转换信息.

=== 不带参数的宏 ===
下例应该保存为`TimeStamp.py`, 因为Trac使用模块名作为宏的名字
{{{
#!python
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, args):
        t = datetime.now(utc)
        return tag.b(format_datetime(t, '%c'))
}}}

=== 不带参数的宏 ===
下例应该保存为`HelloWorld.py` (在plugins/目录中),  因为Trac使用模块名作为宏的名字
{{{
#!python
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 TracWikiMacros page).
    """

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

    def expand_macro(self, formatter, name, 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'`),
        `args` 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 `args` is `None`.
        """
        return 'Hello World, args = ' + unicode(args)
    
    # Note that there's no need to HTML escape the returned data,
    # as the template engine (Genshi) will do it for us.
}}}


=== {{{expand_macro}}} 详情 ===
{{{expand_macro}}} 应该返回或者是一个简单的Python字符串(解释为HTML), 或者最好是一个标记(Markup)对象(使用{{{from trac.util.html import Markup}}}).  {{{Markup(string)}}} 仅包装字符串, 以便渲染器将HTML字符串原样(不转义)渲染.

如果你的宏创建标记而不是HTML, 你可以将其转换为HTML:

{{{
#!python
  text = "whatever wiki markup you want, even containing other macros"
  # Convert Wiki markup to HTML, new style
  out = StringIO()
  Formatter(formatter.context).format(text, out)
  return Markup(out.getvalue())
}}}

----
原文版本: TracWikiMacros[[BR]]
相关信息: [ZhWikiProcessors Wiki解析器], [ZhWikiFormatting Wiki格式], [ZhTracGuide Trac导览][[BR]]
See also: WikiProcessors, WikiFormatting, TracGuide