Edgewall Software

Changes between Version 4 and Version 5 of TracDev/IWikiSyntaxProviderExample


Ignore:
Timestamp:
Feb 14, 2015, 11:50:13 AM (5 years ago)
Author:
figaro
Comment:

Cosmetic changes

Legend:

Unmodified
Added
Removed
Modified
  • TracDev/IWikiSyntaxProviderExample

    v4 v5  
     1= Interface IWikiSyntaxProvider
    12
    2 
    3 == Interface IWikiSyntaxProvider ==
    4 === File: trac/wiki/api.py ===
    53The IWikiSyntaxProvider is an Interface you could use to write plugins that allow you to bring your own wiki syntax into trac.
    64Like the e.g. #5 to see Ticket with id 5. Or the e.g {1} way to see report number 1.
    75
    8 Here is the interface description from IWikiSyntaxProvider taken from the source file trac/wiki/api.py
     6== File: trac/wiki/api.py
     7
     8Here is the interface description from IWikiSyntaxProvider taken from the source file trac/wiki/api.py:
    99
    1010{{{
     
    3030        """
    3131}}}
    32 Ok, lets try to implement the following example wiki syntax:
     32
     33Let's try to implement the following example wiki syntax:
    3334
    3435We want to be able to use something like ''s:w:someword'' to generate a link to a search in the wiki pages for ''someword''.
     
    3637We need to implement the method '''get_link_resolvers()''' to make that happen.
    3738
    38 I know you could also use the search:?q=searchword&wiki=on syntax, but i think its a good example for demonstration anyway.
     39You could also use the search:?q=searchword&wiki=on syntax, but this is for illustrative purposes only.
    3940
    4041As you can see in the source above, there are just 2 methods you must implement to get your own wiki syntax up and running.
    4142
    4243The easiest one is '''get_link_resolvers()'''.
    43 You need to return an iterable of tuples consisting of a string used as the prefix for a new linktype in trac and a callback, to be called when the prefix matches. In our example the string will be ''s'' shorthand for search. The method is really simple:
     44You need to return an iterable of tuples consisting of a string used as the prefix for a new linktype in trac and a callback, to be called when the prefix matches. In our example the string will be ''s'' shorthand for search:
    4445{{{
    4546#!python
     
    4950}}}
    5051
    51 It just returns one tuple, but you could return more if you want. This tuple tells trac that it should call our '''_format_search_link()''' method every time it finds the string s:''anystring'' in some wiki content.
     52It just returns one tuple, but you could return more if you want. This tuple tells Trac that it should call our '''_format_search_link()''' method every time it finds the string s:''anystring'' in some wiki content.
    5253
    53 The real work will be done in our next method: '''_format_search_link'''. This method is called anytime trac encounters one of our prefixes (inside wiki context), we registered through '''get_link_resolvers()'''.
     54The real work will be done in our next method: '''_format_search_link'''. This method is called anytime Trac encounters one of our prefixes (inside wiki context), we registered through '''get_link_resolvers()''':
    5455{{{
    5556#!python
     
    6869        '=on', title="Search for %s in %s(s)" % (searchword, domain))
    6970}}}
    70 The method gets 4 Arguments:
     71
     72The method gets 4 arguments:
    7173 * a formatter object.
    72  * a namespace, this string is our prefix for the linktype, in this case ''s''
     74 * a namespace, this string is our prefix for the linktype, in this case ''s''.
    7375 * a target, this is the string which followed the namespace prefix of the link without the trailing '':'' after namespace.
    74  * a label, this the full string of the link, e.g. ''s:searchword''
     76 * a label, this the full string of the link, e.g. ''s:searchword''.
    7577
    7678The return value should be some html, in our case it is a link to the specified search query.
    77 The first thing the method does is splitting the target into the domain and searchword
     79The first thing the method does is splitting the target into the domain and searchword:
    7880{{{
    7981#!python
     
    8486Then we return a valid link to a search page with our given searchquery. If there is no domain specified we use default to ''wiki'' and use the ''target'' string as  ''searchword''.
    8587
    86 === Part two ===
     88== Part two
    8789
    8890In the second part we implement the following wiki syntax using the second interface method '''get_wiki_syntax()''':
     
    9294 * ?w_searchword? Creates a link to a search for '''searchword''' in the wiki domain.
    9395
    94 You are not limited in creating new link types with this Interface but mostly you would use WikiMacros instead.
     96You are not limited in creating new link types with this Interface, but mostly you would use WikiMacros instead.
    9597
    96 We have to implement get_wiki_syntax() to be able to use regular expressions in our new wiki syntax.
     98We have to implement get_wiki_syntax() to be able to use regular expressions in our new wiki syntax:
    9799{{{
    98100#!python
     
    103105}}}
    104106
    105 All this method does is telling trac that whenever it encounters a hit with our given regular expression(s) (as in '''get_link_resolvers()''' you can have more than one) it should call the given callback method.
     107All this method does is telling Trac that whenever it encounters a hit with our given regular expression(s) - as in '''get_link_resolvers()''' you can have more than one - it should call the given callback method.
    106108
    107 == Attention ==
     109== Attention
     110
    108111Group numbers cannot be used, because the regexp is integrated into a larger expression, therefore not preserving the position of the groups. Group names must be used instead.
    109112
    110 The given callback method must take 3 Arguments:
     113The given callback method must take 3 arguments:
    111114 * a formatter object
    112115 * a namespace,  this is full match of the regex as string, same as match.group(0)
     
    130133All it does is extracting the ''domain'' and ''searchword'' out of the match object and then returning a link to the search page.
    131134
    132 
    133 
    134 Here the full source for our little IWikiSyntaxProvider Test
     135Here the full source for our little IWikiSyntaxProvider Test:
    135136{{{
    136137#!python