Edgewall Software

Changes between Initial Version and Version 1 of TracDev/PluginDevelopment/ExtensionPoints/trac.mimeview.api.IHTMLPreviewAnnotator


Ignore:
Timestamp:
Jul 23, 2011, 9:20:30 PM (11 years ago)
Author:
psuter <petsuter@…>
Comment:

Legend:

Unmodified
Added
Removed
Modified
  • TracDev/PluginDevelopment/ExtensionPoints/trac.mimeview.api.IHTMLPreviewAnnotator

    v1 v1  
     1== Extension Point : ''IHTMLPreviewAnnotator'' ==
     2
     3||'''Interface'''||''IHTMLPreviewAnnotator''||'''Since'''||0.9||
     4||'''Module'''||''trac.mimeview''||'''Source'''||[source:trunk/trac/mimeview/api.py api.py]||
     5
     6The ''IHTMLPreviewAnnotator'' allows extending HTML previews of files line-by-line with some additional information.
     7
     8== Purpose ==
     9
     10Trac provides support for previewing files as HTML and syntax highlighting using WikiProcessors. Additionally it is possible to show additional information next to each line of such text.
     11Plugins can add additional kinds of such added line information by implementing IHTMLPreviewAnnotator.
     12
     13== Usage ==
     14
     15Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment].
     16
     17The implementation reports some general metadata for the annotation type, optionally creates a helper data structure for processing a file, and provides for each line the HTML annotation element to show.
     18
     19Any module can utilize such preview annotations when rendering HTML previews by passing the desired annotation's internal name. (E.g. `Mimeview.render(..., annotations=['styleviolations'], ...)`)
     20
     21== Examples ==
     22
     23The following example notes trivial TracDev/CodingStyle violations:
     24{{{#!python
     25from genshi.builder import tag
     26
     27from trac.core import implements, Component
     28from trac.mimeview.api import IHTMLPreviewAnnotator
     29from trac.util.text import to_unicode
     30from trac.util.translation import _
     31
     32class CodingStyleViolationAnnotator(Component):
     33    """Text annotator that adds a column with warnings about basic
     34    TracDev/CodingStyle violations."""
     35   
     36    implements(IHTMLPreviewAnnotator)
     37
     38    violations = 0
     39   
     40    # IHTMLPreviewAnnotator methods
     41   
     42    def get_annotation_type(self):
     43        return 'styleviolations', _('Style'), _('Coding style violation')
     44
     45    def get_annotation_data(self, context):
     46        self.violations = 0
     47        return None
     48
     49    def annotate_row(self, context, row, lineno, line, data):
     50        if len(to_unicode(line)) > 79:
     51            row.append(tag.th(tag.a(_('!'),
     52                                    href='#Violation%d' % self.violations),
     53                              title=_('Line is too long'),
     54                              id_='Violation%d' % self.violations))
     55        else:
     56            row.append(tag.th())
     57}}}
     58
     59== Available Implementations ==
     60In Trac:
     61|| [source:trunk/trac/mimeview/api.py LineNumberAnnotator] || Simply shows line numbers. ||
     62|| [source:trunk/trac/versioncontrol/web_ui/browser.py BrowserModule] || Uses `BlameAnnotator` to implement the version control ''blame'' feature. ||
     63
     64In [bitten: Bitten]:
     65|| [bitten:source:trunk/bitten/report/coverage.py TestCoverageAnnotator] || Notes code coverage results. ||
     66
     67In third-party plugins:
     68|| th:BittenLintAnnotatePlugin || Notes ''Lint'' warnings collected by Bitten. ||
     69|| `GivenLineNumberAnnotator` in th:IncludeSourcePartialPlugin || Shows the given (offset) line numbers for partially included files. ||
     70||  th:PeerReviewPlugin || Implements line associated code review comments. ||
     71
     72== Additional Information and References ==
     73 * [http://www.edgewall.org/docs/trac-trunk/html/api/trac_mimeview.html#trac.mimeview.api.IHTMLPreviewAnnotator API Reference]
     74 * Related to the [[trac.mimeview.api.IHTMLPreviewRenderer]] interface