== Extension Point : ''IWikiSyntaxProvider'' ==

||'''Interface'''||''IWikiSyntaxProvider''||'''Since'''||0.9||
||'''Module'''||''trac.wiki''||'''Source'''||[source:trunk/trac/wiki/api.py 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.

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 [wiki:TracDev/ComponentArchitecture] and of course [wiki: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 [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)

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
 * [source:trunk/trac/attachment.py AttachmentModule] adds the `raw-attachment` and `attachment` link resolvers.
 * [source:trunk/trac/search/web_ui.py SearchModule] adds the `search` link resolver.
 * [source:trunk/trac/ticket/api.py TicketSystem] adds the `bug`, `ticket` and `comment` link resolvers, the `#123` ticket link syntax and the `#T123` intertrac ticket link syntax.
 * [source:trunk/trac/ticket/query.py QueryModule] adds the `query` link resolver.
 * [source:trunk/trac/ticket/report.py ReportModule] adds the `report` link resolver and the `{123}` report link syntax.
 * [source:trunk/trac/ticket/roadmap.py MilestoneModule] adds the `milestone` link resolver.
 * [source:trunk/trac/wiki/api.py WikiSystem] adds the `wiki` link resolver and WikiPageNames syntax like CamelCase.
 * [source:trunk/trac/timeline/web_ui.py TimelineModule] adds the `timeline` link resolver.
 * [source:trunk/trac/versioncontrol/web_ui/browser.py BrowserModule] adds the `repos`, `export`, `source` and `browser` link resolvers.
 * [source:trunk/trac/versioncontrol/web_ui/changeset.py ChangesetModule] adds the `changeset` and `diff` link resolvers and the `[123]` and `r123` changeset link syntax,
 * [source:trunk/trac/versioncontrol/web_ui/log.py LogModule] adds the `log` link resolver and the `[123:456]` and `r123:456` log link syntax.
 * [source:trunk/trac/web/chrome.py Chrome] adds the `htdocs` link resolver.
 * Sample Plugins
  * [source:trunk/sample-plugins/revision_links.py RevisionLinks] adds a few more ways to refer to changesets.
  * [source:trunk/trac/wiki/tests/formatter.py SampleResolver] adds dummy link resolver used by the unit tests.

== Additional Information and References ==

 * [http://www.edgewall.org/docs/trac-trunk/epydoc/trac.wiki.api.IWikiSyntaxProvider-class.html epydoc]
 * [http://www.edgewall.org/docs/trac-trunk/html/api/trac_wiki_api.html#trac.wiki.api.IWikiSyntaxProvider API Reference]
 * Related to the [[trac.wiki.api.IWikiMacroProvider]]
 * Related tickets:
  * [query:status=!closed&component=wiki+system wiki system component]
 * Related proposals:
  * TracDev/Proposals/WikiParserFormatterSplit  
 * Related mailing list discussions:
  * [TracDev:6435 IWikiSyntaxProvider match order]
 * [source:trunk/trac/wiki/parser.py WikiParser] contains further syntax rules applied before and after the IWikiSyntaxProvider rules.
 * [source:trunk/trac/wiki/formatter.py Formatter] contains further syntax rules (Font styles) applied before and after the IWikiSyntaxProvider rules.