| 1 | == Extension Point : ''IWikiSyntaxProvider'' == |
| 2 | |
| 3 | ||'''Interface'''||''IWikiSyntaxProvider''||'''Since'''||0.9|| |
| 4 | ||'''Module'''||''trac.wiki''||'''Source'''||[source:trunk/trac/wiki/api.py api.py]|| |
| 5 | |
| 6 | The ''IWikiSyntaxProvider'' allows adding new syntax rules for WikiFormatting. |
| 7 | |
| 8 | == Purpose == |
| 9 | |
| 10 | Trac provides an extensible wiki system. Arbitrary regular expressions can be defined to match new wiki syntax. |
| 11 | |
| 12 | For the common `namespace:target` TracLink syntax there is a special mechanism in this interface that supports registering new namespaces. |
| 13 | |
| 14 | 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`). |
| 15 | |
| 16 | == Usage == |
| 17 | |
| 18 | Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment]. |
| 19 | |
| 20 | A class implementing !IWikiSyntaxProvider can define multiple link namespaces by returning their names and the corresponding resolver functions from `get_link_resolvers`. |
| 21 | |
| 22 | That resolver callback function is called for any matching link to be rendered, which it should do by returning the expanded HTML. |
| 23 | |
| 24 | Similarly, multiple syntax regular expressions and the corresponding callback functions can be returned from `get_wiki_syntax`. |
| 25 | |
| 26 | Again that callback function is called for any wiki text matching that syntax, and it should return the expanded HTML. |
| 27 | |
| 28 | In both cases the callback functions receive among other parameters a `formatter` that provides access to various useful objects: |
| 29 | * `formatter.resource` (a [source:trunk/trac/resource.py trac.resource.Resource])[[BR]] |
| 30 | The resource identifier which owns the text being formatted. (E.g. a wiki page, where `formatter.resource.id` is the page name.) |
| 31 | * `formatter.perm` (a [source:trunk/trac/perm.py trac.perm.PermissionCache])[[BR]] |
| 32 | The permission cache which can be used to perform fine-grained permission checks. |
| 33 | * `formatter.href` (a [source:trunk/trac/web/href.py trac.web.Href])[[BR]] |
| 34 | The URL builder. |
| 35 | * `formatter.wiki` (a [source:trunk/trac/wiki/api.py trac.wiki.api.WikiSystem])[[BR]] |
| 36 | The wiki system can be used to access wiki pages. |
| 37 | * `formatter.wikiparser` (a [source:trunk/trac/wiki/parser.py trac.wiki.parser.WikiParser])[[BR]] |
| 38 | The wiki parser. |
| 39 | * `formatter.context` (a [source:trunk/trac/mimeview/api.py trac.mimeview.api.RenderingContext])[[BR]] |
| 40 | The rendering context in which this wiki formatting takes place. |
| 41 | * `formatter.req` (a [source:trunk/trac/web/api.py trac.web.api.Request])[[BR]] |
| 42 | The web request. (to be deprecated) |
| 43 | |
| 44 | 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. |
| 45 | |
| 46 | == Examples == |
| 47 | |
| 48 | See wiki:TracDev/IWikiSyntaxProviderExample |
| 49 | |
| 50 | == Available Implementations == |
| 51 | |
| 52 | * Syntax in Trac |
| 53 | * [source:trunk/trac/attachment.py AttachmentModule] adds the `raw-attachment` and `attachment` link resolvers. |
| 54 | * [source:trunk/trac/search/web_ui.py SearchModule] adds the `search` link resolver. |
| 55 | * [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. |
| 56 | * [source:trunk/trac/ticket/query.py QueryModule] adds the `query` link resolver. |
| 57 | * [source:trunk/trac/ticket/report.py ReportModule] adds the `report` link resolver and the `{123}` report link syntax. |
| 58 | * [source:trunk/trac/ticket/roadmap.py MilestoneModule] adds the `milestone` link resolver. |
| 59 | * [source:trunk/trac/wiki/api.py WikiSystem] adds the `wiki` link resolver and WikiPageNames syntax like CamelCase. |
| 60 | * [source:trunk/trac/timeline/web_ui.py TimelineModule] adds the `timeline` link resolver. |
| 61 | * [source:trunk/trac/versioncontrol/web_ui/browser.py BrowserModule] adds the `repos`, `export`, `source` and `browser` link resolvers. |
| 62 | * [source:trunk/trac/versioncontrol/web_ui/changeset.py ChangesetModule] adds the `changeset` and `diff` link resolvers and the `[123]` and `r123` changeset link syntax, |
| 63 | * [source:trunk/trac/versioncontrol/web_ui/log.py LogModule] adds the `log` link resolver and the `[123:456]` and `r123:456` log link syntax. |
| 64 | * [source:trunk/trac/web/chrome.py Chrome] adds the `htdocs` link resolver. |
| 65 | * Sample Plugins |
| 66 | * [source:trunk/sample-plugins/revision_links.py RevisionLinks] adds a few more ways to refer to changesets. |
| 67 | * [source:trunk/trac/wiki/tests/formatter.py SampleResolver] adds dummy link resolver used by the unit tests. |
| 68 | |
| 69 | == Additional Information and References == |
| 70 | |
| 71 | * [http://www.edgewall.org/docs/trac-trunk/epydoc/trac.wiki.api.IWikiSyntaxProvider-class.html epydoc] |
| 72 | * [http://www.edgewall.org/docs/trac-trunk/html/api/trac_wiki_api.html#trac.wiki.api.IWikiSyntaxProvider API Reference] |
| 73 | * Related to the [[trac.wiki.api.IWikiMacroProvider]] |
| 74 | * Related tickets: |
| 75 | * [query:status=!closed&component=wiki+system wiki system component] |
| 76 | * Related proposals: |
| 77 | * TracDev/Proposals/WikiParserFormatterSplit |
| 78 | * Related mailing list discussions: |
| 79 | * [TracDev:6435 IWikiSyntaxProvider match order] |
| 80 | * [source:trunk/trac/wiki/parser.py WikiParser] contains further syntax rules applied before and after the IWikiSyntaxProvider rules. |
| 81 | * [source:trunk/trac/wiki/formatter.py Formatter] contains further syntax rules (Font styles) applied before and after the IWikiSyntaxProvider rules. |