| | 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. |
