Extension Point : IWikiSyntaxProvider

Interface	IWikiSyntaxProvider	Since	0.9
Module	trac.wiki	Source	api.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

• Syntax in Trac
  • AttachmentModule​ adds the raw-attachment and attachment link resolvers.
  • SearchModule​ adds the search link resolver.
  • TicketSystem​ adds the bug, ticket and comment link resolvers, the #123 ticket link syntax and the #T123 intertrac ticket link syntax.
  • QueryModule​ adds the query link resolver.
  • ReportModule​ adds the report link resolver and the {123} report link syntax.
  • MilestoneModule​ adds the milestone link resolver.
  • WikiSystem​ adds the wiki link resolver and WikiPageNames syntax like CamelCase.
  • TimelineModule​ adds the timeline link resolver.
  • BrowserModule​ adds the repos, export, source and browser link resolvers.
  • ChangesetModule​ adds the changeset and diff link resolvers and the [123] and r123 changeset link syntax,
  • LogModule​ adds the log link resolver and the [123:456] and r123:456 log link syntax.
  • Chrome​ adds the htdocs link resolver.
  • Sample Plugins
    • RevisionLinks​ adds a few more ways to refer to changesets.
    • SampleResolver​ adds dummy link resolver used by the unit tests.

Additional Information and References

• ​epydoc
• ​API Reference
• Related to the trac.wiki.api.IWikiMacroProvider
• Related tickets:
  • wiki system component
• Related proposals:
  • TracDev/Proposals/WikiParserFormatterSplit
• Related mailing list discussions:
  • ​IWikiSyntaxProvider match order
• WikiParser​ contains further syntax rules applied before and after the IWikiSyntaxProvider rules.
• Formatter​ contains further syntax rules (Font styles) applied before and after the IWikiSyntaxProvider rules.