Edgewall Software

Extension Point : IHTMLPreviewAnnotator


The IHTMLPreviewAnnotator allows extending HTML previews of files line-by-line with some additional information.


Trac 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. Plugins can add additional kinds of such added line information by implementing IHTMLPreviewAnnotator.


Implementing the interface follows the standard guidelines found in TracDev/ComponentArchitecture and of course TracDev/PluginDevelopment.

The 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.

Any module can utilize such preview annotations when rendering HTML previews by passing the desired annotation's internal name. (E.g. Mimeview.render(..., annotations=['styleviolations'], ...))


The following example notes trivial TracDev/CodingStyle violations:

from genshi.builder import tag

from trac.core import implements, Component
from trac.mimeview.api import IHTMLPreviewAnnotator
from trac.util.text import to_unicode
from trac.util.translation import _

class CodingStyleViolationAnnotator(Component):
    """Text annotator that adds a column with warnings about basic 
    TracDev/CodingStyle violations."""

    violations = 0
    # IHTMLPreviewAnnotator methods
    def get_annotation_type(self):
        return 'styleviolations', _('Style'), _('Coding style violation')

    def get_annotation_data(self, context):
        return {'violations': 0}

    def annotate_row(self, context, row, lineno, line, data):
        if len(to_unicode(line)) > 79:
            data['violations'] += 1
                                    href='#Violation%d' % data['violations']),
                              title=_('Line is too long'), 
                              id_='Violation%d' % data['violations']))

Available Implementations

In Trac:

LineNumberAnnotator Simply shows line numbers.
BrowserModule Uses BlameAnnotator to implement the version control blame feature.

In Bitten:

TestCoverageAnnotator Notes code coverage results.

In third-party plugins:

th:BittenLintAnnotatePlugin Notes Lint warnings collected by Bitten.
GivenLineNumberAnnotator in th:IncludeSourcePartialPlugin Shows the given (offset) line numbers for partially included files.
th:PeerReviewPlugin Implements line associated code review comments.

Additional Information and References

Last modified 7 years ago Last modified on Jul 23, 2011, 10:29:23 PM
Note: See TracWiki for help on using the wiki.