Edgewall Software

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


Ignore:
Timestamp:
Jul 14, 2012, 7:45:50 PM (7 years ago)
Author:
Christian Boos
Comment:

add some extra notes about resource and context, and fix 2 links

Legend:

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

    v1 v2  
    1010Trac provides an extensible wiki system. Arbitrary regular expressions can be defined to match new wiki syntax.
    1111
    12 For the common `namespace:target` TracLink syntax there is a special mechanism in this interface that supports registering new namespaces.
     12For the common `namespace:target` TracLink syntax there is a special mechanism in this interface that supports registering new namespaces (see [[trac.resource.IResourceManager]]).
    1313
    1414To 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`).
     
    1818Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment].
    1919
    20 A class implementing !IWikiSyntaxProvider can define multiple link namespaces by returning their names and the corresponding resolver functions from `get_link_resolvers`.
     20A class implementing `IWikiSyntaxProvider` can define multiple link namespaces by returning their names and the corresponding resolver functions from `get_link_resolvers`.
    2121
    2222That resolver callback function is called for any matching link to be rendered, which it should do by returning the expanded HTML.
     
    2828In both cases the callback functions receive among other parameters a `formatter` that provides access to various useful objects:
    2929 * `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.)
     30   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.)
    3131 * `formatter.perm` (a [source:trunk/trac/perm.py trac.perm.PermissionCache])[[BR]]
    3232   The permission cache which can be used to perform fine-grained permission checks.
     
    3434   The URL builder.
    3535 * `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.
     36   The wiki system can be used to access wiki pages, settings and helper functions (e.g. `format_page_name()`).
    3737 * `formatter.wikiparser` (a [source:trunk/trac/wiki/parser.py trac.wiki.parser.WikiParser])[[BR]]
    38    The wiki parser.
     38   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)
    3939 * `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.
     40   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.
    4141 * `formatter.req` (a [source:trunk/trac/web/api.py trac.web.api.Request])[[BR]]
    4242   The web request. (to be deprecated)
     
    7373 * Related to the [[trac.wiki.api.IWikiMacroProvider]]
    7474 * Related tickets:
    75   * [query:status=!closed&component=wiki+system wiki system component]
     75  * [query:"status=!closed&component=wiki system" wiki system component]
    7676 * Related proposals:
    7777  * TracDev/Proposals/WikiParserFormatterSplit 
    7878 * Related mailing list discussions:
    79   * [TracDev:6435 IWikiSyntaxProvider match order]
     79  * [Trac-Dev:6435 IWikiSyntaxProvider match order]
    8080 * [source:trunk/trac/wiki/parser.py WikiParser] contains further syntax rules applied before and after the IWikiSyntaxProvider rules.
    8181 * [source:trunk/trac/wiki/formatter.py Formatter] contains further syntax rules (Font styles) applied before and after the IWikiSyntaxProvider rules.