Extension Point : IHTMLPreviewAnnotator

Interface	IHTMLPreviewAnnotator	Since	0.9
Module	trac.mimeview	Source	api.py​

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

Purpose

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.

Usage

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'], ...))

Examples

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."""
    
    implements(IHTMLPreviewAnnotator)

    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
            row.append(tag.th(tag.a(_('!'),
                                    href='#Violation%d' % data['violations']),
                              title=_('Line is too long'), 
                              id_='Violation%d' % data['violations']))
        else:
            row.append(tag.th())

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

• ​API Reference
• Related to the trac.mimeview.api.IHTMLPreviewRenderer interface