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