Changes between Initial Version and Version 1 of TracDev/IWikiSyntaxProviderExample

Timestamp:

Dec 14, 2009, 7:47:33 AM (14 years ago)

Author:

Karsten Fuhrmann <karsten_fuhrmann@…>

Comment:

—

TracDev/IWikiSyntaxProviderExample

@@ +1 @@
+
+
+== Interface IWikiSyntaxProvider ==
+=== File: trac/wiki/api.py ===
+The IWikiSyntaxProvider is an Interface you could use to write plugins that allow you to bring your own wiki syntax into trac.
+Like the e.g. #5 to see Ticket with id 5. Or the e.g {1} way to see report number 1.
+
+Here is the interface description from IWikiSyntaxProvider taken from the source file trac/wiki/api.py 
+
+{{{
+#!python
+class IWikiSyntaxProvider(Interface):
+ 
+    def get_wiki_syntax():
+        """Return an iterable that provides additional wiki syntax.
+
+        Additional wiki syntax correspond to a pair of (regexp, cb),
+        the `regexp` for the additional syntax and the callback `cb`
+        which will be called if there's a match.
+        That function is of the form cb(formatter, ns, match).
+        """
+ 
+    def get_link_resolvers():
+        """Return an iterable over (namespace, formatter) tuples.
+
+        Each formatter should be a function of the form
+        fmt(formatter, ns, target, label), and should
+        return some HTML fragment.
+        The `label` is already HTML escaped, whereas the `target` is not.
+        """
+}}}
+Ok, lets try to implement the following example wiki syntax:
+
+We want to be able to use something like ''s:w:someword'' to generate a link to a search in the wiki pages for ''someword''.
+Searching in Tickets and Milestones should work equally by using ''s:t:someword'' and ''s:m:someword''.
+We need to implement the method '''get_link_resolvers()''' to make that happen.
+
+I know you could also use the search:?q=searchword&wiki=on syntax, but i think its a good example for demonstration anyway.
+
+As you can see in the source above, there are just 2 methods you must implement to get your own wiki syntax up and running.
+
+The easiest one is '''get_link_resolvers()'''.
+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: 
+{{{
+#!python
+def get_link_resolvers(self):
+    return [ ('s', self._format_search_link) ]
+
+}}}
+
+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.
+
+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()'''.
+{{{
+#!python
+def _format_search_link(self, formatter, ns, target, label):
+    self.env.log.debug('formatter: %s ns: %s' % (formatter, ns))
+    domains = {'w': 'wiki', 't': 'ticket', 'm': 'milestone'}
+    domain = 'wiki'
+    searchword = None
+    if ":" in target:
+        domain, searchword = target.split(':')
+    else:
+        searchword = target
+    domain = domains.get(domain, 'wiki')
+    return tag.a(label, href=formatter.href.search() +
+        '?q=' + searchword + '&' + domain +
+        '=on', title="Search for %s in %s(s)" % (searchword, domain))
+}}}
+The method gets 4 Arguments:
+ * a formatter object.
+ * a namespace, this string is our prefix for the linktype, in this case ''s''
+ * a target, this is the string which followed the namespace prefix of the link without the trailing '':'' after namespace.
+ * a label, this the full string of the link, e.g. ''s:searchword''
+
+The return value should be some html, in our case it is a link to the specified search query.
+The first thing the method does is splitting the target into the domain and searchword
+{{{
+#!python
+domain, searchword = target.split(':')
+
+}}}
+
+Then 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''.
+
+=== Part two ===
+
+In the second part we implement the following wiki syntax using the second interface method '''get_wiki_syntax()''':
+
+ * ?t_searchword? Creates a link to a search for '''searchword''' in the Ticket domain.
+ * ?m_searchword? Creates a link to a search for '''searchword''' in the Milestone domain.
+ * ?w_searchword? Creates a link to a search for '''searchword''' in the wiki domain.
+
+You are not limited in creating new link types with this Interface but mostly you would use WikiMacros instead.
+
+We have to implement get_wiki_syntax() to be able to use regular expressions in our new wiki syntax.
+{{{
+#!python
+def get_wiki_syntax(self):
+    #group numbers dont work, why? Must use group names inside the regex.
+    yield ( r'\?(?P<domain>[tmw])_(?P<searchword>.+?)\?', self._format_regex_link)
+
+}}}
+
+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.
+
+== Attention ==
+Using group numbers instead of group names inside the regular expression didn't work here. '''Anyone have a clue?'''
+
+The given callback method must take 3 Arguments:
+ * a formatter object
+ * a namespace,  this is full match of the regex as string, same as match.group(0)
+ * a match, this is a regex match object.
+
+Here is the callback method:
+{{{
+#!python
+def _format_regex_link(self, formatter, ns, match):
+    domains = {'w': 'wiki', 't': 'ticket', 'm': 'milestone'}
+    searchword = match.group('searchword') or 'test'
+    label= match.group(0)
+    domain= match.group('domain')
+    domain = domains.get(domain,'wiki')
+    return tag.a(label, href=formatter.href.search() +
+        '?q=' + searchword + '&' + domain + '=on',
+        title="Search for %s in %s(s)" % (searchword, domain))
+
+}}}
+
+All it does is extracting the ''domain'' and ''searchword'' out of the match object and then returning a link to the search page.
+
+
+
+Here the full source for our little IWikiSyntaxProvider Test
+{{{
+#!python
+# encoding: utf-8
+"""
+WikiSyntaxProviderTest.py
+
+Created by Karsten Fuhrmann on 2009-12-14.
+Copyright (c) 2009 Karsten Fuhrmann (karsten_fuhrmann AT web.de) All rights reserved.
+"""
+
+from trac.core import *
+from trac.wiki import IWikiSyntaxProvider
+from genshi.builder import tag
+
+class WikiSyntaxProviderTest(Component):
+    '''This is a test Component to demonstrate the use of the IWikiSyntaxProvider Interface of Trac.'''
+    implements(IWikiSyntaxProvider)
+
+    # IWikiSyntaxProvider methods
+
+    def get_link_resolvers(self):
+        return [ ('s', self._format_search_link) ]
+
+    def get_wiki_syntax(self):
+        #group numbers dont work, why? Must use group names inside the regex.
+        yield ( r'\?(?P<domain>[tmw])_(?P<searchword>.+?)\?', self._format_regex_link)
+
+    def _format_regex_link(self, formatter, ns, match):
+        self.env.log.debug('formatter: %s ns: %s' % (formatter, ns))
+        domains = {'w': 'wiki', 't': 'ticket', 'm': 'milestone'}
+        searchword = match.group('searchword') or 'test'
+        label= match.group(0)
+        domain= match.group('domain')
+        domain = domains.get(domain,'wiki')
+        return tag.a(label, href=formatter.href.search() +
+            '?q=' + searchword + '&' + domain +
+            '=on', title="Search for %s in %s(s)" % (searchword, domain))
+
+    def _format_search_link(self, formatter, ns, target, label):
+        self.env.log.debug('formatter: %s ns: %s' % (formatter, ns))
+        domains = {'w': 'wiki', 't': 'ticket', 'm': 'milestone'}
+        domain = 'wiki'
+        searchword = None
+        if ":" in target:
+            domain, searchword = target.split(':')
+        else:
+            searchword = target
+        domain = domains.get(domain, 'wiki')
+        return tag.a(label, href=formatter.href.search() +
+            '?q=' + searchword + '&' + domain +
+            '=on', title="Search for %s in %s(s)" % (searchword, domain))
+
+}}}