Edgewall Software

Extension Point : IWikiSyntaxProvider

InterfaceIWikiSyntaxProviderSince0.9
Moduletrac.wikiSourceapi.py

The IWikiSyntaxProvider allows adding new syntax rules for WikiFormatting.

Purpose

Trac provides an extensible wiki system. Arbitrary regular expressions can be defined to match new wiki syntax.

For the common namespace:target TracLink syntax there is a special mechanism in this interface that supports registering new namespaces (see trac.resource.IResourceManager).

To add new functionality to the wiki system with the standardized and familiar macro or processor syntax, use a trac.wiki.api.IWikiMacroProvider instead. Often this is preferrable for more complex functionality, while syntax providers are mainly used for defining namespace:target links and special shortcut syntax (e.g. {1} instead of report:1).

Usage

Implementing the interface follows the standard guidelines found in TracDev/ComponentArchitecture and of course TracDev/PluginDevelopment.

A class implementing IWikiSyntaxProvider can define multiple link namespaces by returning their names and the corresponding resolver functions from get_link_resolvers.

That resolver callback function is called for any matching link to be rendered, which it should do by returning the expanded HTML.

Similarly, multiple syntax regular expressions and the corresponding callback functions can be returned from get_wiki_syntax.

Again that callback function is called for any wiki text matching that syntax, and it should return the expanded HTML.

In both cases the callback functions receive among other parameters a formatter that provides access to various useful objects:

  • formatter.resource (a trac.resource.Resource)
    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 trac.perm.PermissionCache)
    The permission cache which can be used to perform fine-grained permission checks.
  • formatter.href (a trac.web.Href)
    The URL builder.
  • formatter.wiki (a trac.wiki.api.WikiSystem)
    The wiki system can be used to access wiki pages, settings and helper functions (e.g. format_page_name()).
  • formatter.wikiparser (a trac.wiki.parser.WikiParser)
    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 trac.mimeview.api.RenderingContext)
    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 trac.web.api.Request)
    The web request. (to be deprecated)

Note that InterWiki shortcuts can be used to link resources on an external site. In some cases this may be a viable alternative that requires less effrt than implementing a plugin.

Examples

See wiki:TracDev/IWikiSyntaxProviderExample

Available Implementations

Additional Information and References

Last modified 6 years ago Last modified on Jul 14, 2012, 7:45:50 PM
Note: See TracWiki for help on using the wiki.