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

Timestamp:

Jul 23, 2011, 9:20:30 PM (13 years ago)

Author:

psuter <petsuter@…>

Comment:

—

TracDev/PluginDevelopment/ExtensionPoints/trac.mimeview.api.IHTMLPreviewAnnotator

@@ +1 @@
+== 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):
+        self.violations = 0
+        return None
+
+    def annotate_row(self, context, row, lineno, line, data):
+        if len(to_unicode(line)) > 79:
+            row.append(tag.th(tag.a(_('!'),
+                                    href='#Violation%d' % self.violations),
+                              title=_('Line is too long'), 
+                              id_='Violation%d' % self.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