Edgewall Software

Version 4 (modified by Peter Suter, 12 years ago) ( diff )

Inline macros

Extension Point : IWikiMacroProvider

InterfaceIWikiMacroProviderSince0.9
Moduletrac.wikiSourceapi.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 TracDev/ComponentArchitecture and of course 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:

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 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 title contains an inline macro

This Div(title, style=background:#ff7) contains a non-inline macro

Examples

The following example macro allows using the HTML5 <audio/> element (available in recent browser) to play audio files: 

from genshi.builder import tag
from trac.wiki.macros import WikiMacroBase
from trac.wiki.api import parse_args
from trac.core import TracError

class AudioMacro(WikiMacroBase):
    """Embed an audio element in wiki-formatted text.
   
    The first argument is the URL of the audio file to be played.
   
    Example:
    {{{
        [[Audio(http://images.wikia.com/lotr/images/e/e5/HelmsDeepSound.ogg)]]
    }}}
    """

    def expand_macro(self, formatter, name, content):
        args, kw = parse_args(content)
        if not args:
            raise TracError('No audio file found')
        return tag.audio(src=args[0], autoplay='', controls='')(
                    "Your browser does not support audio.")

Available Implementations

Additional Information and References

API History

  • 0.9 introduced the interface (replacing old-style macros)
  • 0.11 added the expand_macro method and deprecated render_macro
  • 0.12 added parameter args for wiki processor arguments
Note: See TracWiki for help on using the wiki.