Changes between Version 4 and Version 5 of TracDev/IWikiSyntaxProviderExample
- Timestamp:
- Feb 14, 2015, 11:50:13 AM (9 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
TracDev/IWikiSyntaxProviderExample
v4 v5 1 = Interface IWikiSyntaxProvider 1 2 2 3 == Interface IWikiSyntaxProvider ==4 === File: trac/wiki/api.py ===5 3 The IWikiSyntaxProvider is an Interface you could use to write plugins that allow you to bring your own wiki syntax into trac. 6 4 Like the e.g. #5 to see Ticket with id 5. Or the e.g {1} way to see report number 1. 7 5 8 Here is the interface description from IWikiSyntaxProvider taken from the source file trac/wiki/api.py 6 == File: trac/wiki/api.py 7 8 Here is the interface description from IWikiSyntaxProvider taken from the source file trac/wiki/api.py: 9 9 10 10 {{{ … … 30 30 """ 31 31 }}} 32 Ok, lets try to implement the following example wiki syntax: 32 33 Let's try to implement the following example wiki syntax: 33 34 34 35 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''. … … 36 37 We need to implement the method '''get_link_resolvers()''' to make that happen. 37 38 38 I know you could also use the search:?q=searchword&wiki=on syntax, but i think its a good example for demonstration anyway.39 You could also use the search:?q=searchword&wiki=on syntax, but this is for illustrative purposes only. 39 40 40 41 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. 41 42 42 43 The 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:44 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: 44 45 {{{ 45 46 #!python … … 49 50 }}} 50 51 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.52 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. 52 53 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()'''.54 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()''': 54 55 {{{ 55 56 #!python … … 68 69 '=on', title="Search for %s in %s(s)" % (searchword, domain)) 69 70 }}} 70 The method gets 4 Arguments: 71 72 The method gets 4 arguments: 71 73 * 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''. 73 75 * 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''. 75 77 76 78 The 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 79 The first thing the method does is splitting the target into the domain and searchword: 78 80 {{{ 79 81 #!python … … 84 86 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''. 85 87 86 == = Part two ===88 == Part two 87 89 88 90 In the second part we implement the following wiki syntax using the second interface method '''get_wiki_syntax()''': … … 92 94 * ?w_searchword? Creates a link to a search for '''searchword''' in the wiki domain. 93 95 94 You are not limited in creating new link types with this Interface but mostly you would use WikiMacros instead.96 You are not limited in creating new link types with this Interface, but mostly you would use WikiMacros instead. 95 97 96 We have to implement get_wiki_syntax() to be able to use regular expressions in our new wiki syntax .98 We have to implement get_wiki_syntax() to be able to use regular expressions in our new wiki syntax: 97 99 {{{ 98 100 #!python … … 103 105 }}} 104 106 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.107 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. 106 108 107 == Attention == 109 == Attention 110 108 111 Group 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. 109 112 110 The given callback method must take 3 Arguments:113 The given callback method must take 3 arguments: 111 114 * a formatter object 112 115 * a namespace, this is full match of the regex as string, same as match.group(0) … … 130 133 All it does is extracting the ''domain'' and ''searchword'' out of the match object and then returning a link to the search page. 131 134 132 133 134 Here the full source for our little IWikiSyntaxProvider Test 135 Here the full source for our little IWikiSyntaxProvider Test: 135 136 {{{ 136 137 #!python
