Edgewall Software

Changes between Initial Version and Version 1 of TracDev/PluginDevelopment/ExtensionPoints/trac.wiki.api.IWikiSyntaxProvider


Ignore:
Timestamp:
Jul 14, 2012, 4:36:23 PM (7 years ago)
Author:
Peter Suter
Comment:

Legend:

Unmodified
Added
Removed
Modified
  • TracDev/PluginDevelopment/ExtensionPoints/trac.wiki.api.IWikiSyntaxProvider

    v1 v1  
     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
     6The ''IWikiSyntaxProvider'' allows adding new syntax rules for WikiFormatting.
     7
     8== Purpose ==
     9
     10Trac provides an extensible wiki system. Arbitrary regular expressions can be defined to match new wiki syntax.
     11
     12For the common `namespace:target` TracLink syntax there is a special mechanism in this interface that supports registering new namespaces.
     13
     14To 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
     18Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment].
     19
     20A class implementing !IWikiSyntaxProvider can define multiple link namespaces by returning their names and the corresponding resolver functions from `get_link_resolvers`.
     21
     22That resolver callback function is called for any matching link to be rendered, which it should do by returning the expanded HTML.
     23
     24Similarly, multiple syntax regular expressions and the corresponding callback functions can be returned from `get_wiki_syntax`.
     25
     26Again that callback function is called for any wiki text matching that syntax, and it should return the expanded HTML.
     27
     28In 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
     44Note 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
     48See 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.