== Extension Point : ''IHTMLPreviewAnnotator'' ==

||'''Interface'''||''IHTMLPreviewAnnotator''||'''Since'''||0.9||
||'''Module'''||''trac.mimeview''||'''Source'''||[source:trunk/trac/mimeview/api.py 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 [wiki:TracDev/ComponentArchitecture] and of course [wiki: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:
{{{#!python
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:
|| [source:trunk/trac/mimeview/api.py LineNumberAnnotator] || Simply shows line numbers. ||
|| [source:trunk/trac/versioncontrol/web_ui/browser.py BrowserModule] || Uses `BlameAnnotator` to implement the version control ''blame'' feature. ||

In [bitten: Bitten]:
|| [bitten:source:trunk/bitten/report/coverage.py 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 ==
 * [http://www.edgewall.org/docs/trac-trunk/html/api/trac_mimeview.html#trac.mimeview.api.IHTMLPreviewAnnotator API Reference]
 * Related to the [[trac.mimeview.api.IHTMLPreviewRenderer]] interface