Edgewall Software
Home
Trac
Trac Hacks
Genshi
Babel
Bitten
Home
Download
Documentation
Mailing Lists
License
FAQ
Search:
Login
Preferences
Help/Guide
About Trac
Wiki
Timeline
Roadmap
Browse Source
View Tickets
New Ticket
Search
Context Navigation
-1
Start Page
Index
History
Editing TracDev/PluginDevelopment/ExtensionPoints/trac.wiki.api.IWikiMacroProvider
Adjust edit area height:
8
12
16
20
24
28
32
36
40
Edit side-by-side
== 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.) * `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. * `formatter.wikiparser` (a [source:trunk/trac/wiki/parser.py trac.wiki.parser.WikiParser])[[BR]] The wiki parser. * `formatter.context` (a [source:trunk/trac/mimeview/api.py trac.mimeview.api.RenderingContext])[[BR]] The rendering context in which this wiki formatting takes place. * `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.) == Examples == The following example macro allows using the HTML5 `<audio/>` element (available in recent browser) to play audio files: {{{#!python 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 == * Macros in Trac * Sample Plugins * [source:trunk/sample-plugins/HelloWorld.py HelloWorld] * [source:trunk/sample-plugins/Timestamp.py Timestamp] * Default macros * Based on `WikiMacroBase` * [source:trunk/trac/wiki/macros.py TitleIndex] * [source:trunk/trac/wiki/macros.py RecentChanges] * [source:trunk/trac/wiki/macros.py PageOutline] * [source:trunk/trac/wiki/macros.py Image] * [source:trunk/trac/wiki/macros.py MacroList] * [source:trunk/trac/wiki/macros.py TracIni] * [source:trunk/trac/wiki/macros.py KnownMimeTypes] * [source:trunk/trac/wiki/macros.py TracGuideToc] * [source:trunk/trac/ticket/default_workflow.py Workflow] * [source:trunk/trac/ticket/query.py TicketQuery] * [source:trunk/trac/admin/console.py TracAdminHelp] * Part of another component implementing `IWikiSyntaxProvider` directly: * [source:trunk/trac/versioncontrol/web_ui/browser.py RepositoryIndex] (part of `BrowserModule`) * [source:trunk/trac/wiki/intertrac.py InterTrac] (part of `InterTracDispatcher`) * [source:trunk/trac/wiki/interwiki.py InterWiki] (part of `InterWikiMap`) * [source:trunk/tracopt/ticket/commit_updater.py CommitTicketReferenceMacro] (Optional macro from from `tracopt`) * [source:trunk/trac/wiki/tests/formatter.py various simple test macros] used for unit testing * In third-party plugins: * [th:wiki:macro Macros on trac-hacks] * [th:wiki:AddCommentMacro AddCommentMacro] * [th:wiki:ChangeLogMacro ChangeLogMacro] * [th:wiki:ColorMacro ColorMacro] * [th:wiki:FootNoteMacro FootNoteMacro] * [th:wiki:NewsFlashMacro NewsFlashMacro] * [th:wiki:PollMacro PollMacro] * [th:wiki:TocMacro TocMacro] * [th:wiki:WikiExtrasPlugin WikiExtrasPlugin] * ... * MacroBazaar and ProcessorBazaar (Deprecated) == Additional Information and References == * [http://www.edgewall.org/docs/trac-trunk/epydoc/trac.wiki.api.IWikiMacroProvider-class.html epydoc] * [http://www.edgewall.org/docs/trac-trunk/html/api/trac_wiki_api.html#trac.wiki.api.IWikiMacroProvider API Reference] * WikiMacros#DevelopingCustomMacros * Related to the [[trac.wiki.api.IWikiSyntaxProvider]] * Related tickets: * [query:status=!closed&component=wiki+system wiki system component] * [query:?status=!closed&keywords=~macro macro keywords] * #10038 Translated macro descriptions * #10201 Detailed help for WikiProcessors ==== API History ==== * 0.9 introduced the interface (replacing old-style macros) * [wiki:TracDev/ApiChanges/0.11#IWikiMacroProvider 0.11] added the `expand_macro` method and deprecated `render_macro` * [wiki:TracDev/ApiChanges/0.12#IWikiMacroProvider 0.12] added parameter `args` for wiki processor arguments
Note:
See
WikiFormatting
and
TracWiki
for help on editing wiki content.
Change information
Your email or username:
E-mail address and name can be saved in the
Preferences
Comment about this change (optional):
Note:
See
TracWiki
for help on using the wiki.