| 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 | |
| 6 | The ''IHTMLPreviewAnnotator'' allows extending HTML previews of files line-by-line with some additional information. |
| 7 | |
| 8 | == Purpose == |
| 9 | |
| 10 | 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. |
| 11 | Plugins can add additional kinds of such added line information by implementing IHTMLPreviewAnnotator. |
| 12 | |
| 13 | == Usage == |
| 14 | |
| 15 | Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment]. |
| 16 | |
| 17 | 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. |
| 18 | |
| 19 | 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'], ...)`) |
| 20 | |
| 21 | == Examples == |
| 22 | |
| 23 | The following example notes trivial TracDev/CodingStyle violations: |
| 24 | {{{#!python |
| 25 | from genshi.builder import tag |
| 26 | |
| 27 | from trac.core import implements, Component |
| 28 | from trac.mimeview.api import IHTMLPreviewAnnotator |
| 29 | from trac.util.text import to_unicode |
| 30 | from trac.util.translation import _ |
| 31 | |
| 32 | class 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 == |
| 60 | In 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 | |
| 64 | In [bitten: Bitten]: |
| 65 | || [bitten:source:trunk/bitten/report/coverage.py TestCoverageAnnotator] || Notes code coverage results. || |
| 66 | |
| 67 | In 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 |