Edgewall Software

Version 1 (modified by Peter Suter, 7 years ago) ( diff )

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.

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:

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

Note: See TracWiki for help on using the wiki.