== Extension Point : ''IWikiMacroProvider'' == ||'''Interface'''||''IWikiMacroProvider''||'''Since'''||0.9|| ||'''Module'''||''trac.wiki''||'''Source'''||[source:trunk/trac/wiki/api.py api.py]|| The ''IWikiMacroProvider'' allows adding new WikiMacros. == Purpose == Trac provides an extensible wiki system. WikiMacros are a flexible and powerful way to add new functionality with a standardized and familiar syntax. All macros are also WikiProcessors automatically and can thus be used with block syntax. To add not only new functionality, but also new syntax to the wiki system, use a [[trac.wiki.api.IWikiSyntaxProvider]]. == Usage == Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment]. A class implementing IWikiMacroProvider directly can provide multiple macros by returning their names from `get_macros`. The `expand_macro` method is then called each time one of these macros is rendered. That method should render the macro invocation, by returning the expanded HTML string. The name of the macro to be invoked in the `name` parameter. The arguments to the macro are passed in the `content` parameter as a single string. If multiple separate arguments should be supported, this string can be parsed using `trac.wiki.api.parse_args`. A further parameter `formatter` provides access to various useful objects: * `formatter.resource` (a [source:trunk/trac/resource.py trac.resource.Resource])[[BR]] The resource identifier which owns the text being formatted. (E.g. a wiki page, where `formatter.resource.id` is the page name.) In practice, it's used to identify the target URL for relative links present in that Wiki text (e.g. `[#section see Section]`) independently from where the rendered text gets displayed (in the timeline, in a report, etc.) * `formatter.perm` (a [source:trunk/trac/perm.py trac.perm.PermissionCache])[[BR]] The permission cache which can be used to perform fine-grained permission checks. * `formatter.href` (a [source:trunk/trac/web/href.py trac.web.Href])[[BR]] The URL builder. * `formatter.wiki` (a [source:trunk/trac/wiki/api.py trac.wiki.api.WikiSystem])[[BR]] The wiki system can be used to access wiki pages, settings and helper functions (e.g. `format_page_name()`). * `formatter.wikiparser` (a [source:trunk/trac/wiki/parser.py trac.wiki.parser.WikiParser])[[BR]] The wiki parser (for now, only the constants used to form the standard regexps are there; the full "parser" is still in formatter.py for historical reasons) * `formatter.context` (a [source:trunk/trac/mimeview/api.py trac.mimeview.api.RenderingContext])[[BR]] The rendering context in which this wiki formatting takes place. Use this rather than the `.req` to retrieve information about the author, the permissions and the like. * `formatter.req` (a [source:trunk/trac/web/api.py trac.web.api.Request])[[BR]] The web request. (to be deprecated) In case the macro was invoked using wiki processor syntax, an additional `args` parameter contains the dictionary of wiki processor syntax arguments, while `content` contains the code block content. A simpler way to implement the interface is to derive a class from [source:trunk/trac/wiki/macros.py trac.wiki.macros.WikiMacroBase] for each macro. That way the macro's name is automatically the same as the class name, and only the `expand_macro` method has to be implemented. (The `render_macro` method is deprecated and can be ignored. It was used in macros for Trac 0.9 and 0.10.) === Inline macros Many macros expand to content that can not appear inline in a line of text, so macros are usually replaced by a [[macro(...)]] indicator when used in ''outline'' or ''one line'' formatters. Since 0.13, macros implementing the optional `is_inline` method can appear in such inline content. They should of course produce inline XHTML in this case. Example: The ''Span'' macro implements `is_inline`, the ''Div'' macro does not: {{{ ==== This [[Span(title, style=background:#ff7)]] contains an inline macro ==== This [[Div(title, style=background:#ff7)]] contains a non-inline macro }}} ==== This [[Span(title, style=background:#ff7)]] contains an inline macro ==== This [[Div(title, style=background:#ff7)]] contains a non-inline macro == Examples == The following example macro allows using the HTML5 `