Extension Point : IHTMLPreviewRenderer

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

The IHTMLPreviewRenderer allows previewing files as HTML with syntax coloring.

Purpose

Trac provides support for previewing files (attachments, files stored in version control) in the browser as HTML with syntax coloring. The same support is also available for embedding via WikiProcessors syntax. Plugins can add support for additional kinds of previews by implementing IHTMLPreviewRenderer.

Usage

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

The implementation has to report how well it supports a given mime type when queried. It might then be called (if no better support is available) to render a preview.

Any module can utilize such a preview rendering by calling Mimeview.render(...) or Mimeview.preview_data(...) (typically used with the preview_file.html template). Core use cases are:

• Viewing a file in the version control browser​.
• Viewing an attachment​.
• Viewing a WikiProcessor​ block when the specified processor name is not found, but is a known mime type.
• Viewing changeset property differences using the DefaultPropertyDiffRenderer​.

Examples

The following minimal example renders non-binary content as all caps plain text:

from trac.core import implements, Component
from trac.mimeview.api import Mimeview, IHTMLPreviewRenderer, content_to_unicode, is_binary

class AllCapsPlainTextRenderer(Component):
        
    implements(IHTMLPreviewRenderer)

    expand_tabs = True
    returns_source = True

    def get_quality_ratio(self, mimetype):
        if mimetype in Mimeview(self.env).treat_as_binary:
            return 0
        return 1

    def render(self, context, mimetype, content, filename=None, url=None):
        if is_binary(content):
            self.log.debug("Binary data; no preview available")
            return

        self.log.debug("Using all caps plain text mimeviewer")
        return str.upper(content_to_unicode(self.env, content, mimetype))

Available Implementations

In Trac:

PlainTextRenderer​	Renders anything as plain text as a fallback.
ImageRenderer​	Renders an image inline (using an img tag).
WikiTextRenderer​	Renders a Trac Wiki page.
PatchRenderer​	Renders patches in unified diff format.
TextileRenderer​	Renders plain text marked up in Textile format.
ReStructuredTextRenderer​	Renders plain text marked up in reStructuredText format.
PygmentsRenderer​	Renders various source code formats with syntax highlighting (using Pygments).

In Trac (optional):

SilverCityRenderer	Renders various source code formats with syntax highlighting (using SilverCity). Deprecated in favor of PygmentsRenderer and removed in 1.1.3.
PHPRenderer	Renders PHP source code with syntax highlighting (using PHP). Deprecated in favor of PygmentsRenderer and removed in 1.1.3.
EnscriptRenderer	Renders various source code formats with syntax highlighting (using GNU Enscript). Deprecated in favor of PygmentsRenderer and removed in 1.1.3.

In third-party plugins:

​th:GraphvizPlugin	Renders graph diagrams (using Graphviz).
​th:GanttChartPlugin	Renders Gantt charts (using PyYAML and PIL).
​th:MscgenPlugin	Renders message sequence chart diagrams (using mscgen).
​th:MetapostPlugin	Renders Metapost drawings (using Metapost).
​th:MindMapMacro	Renders Freemind mind maps (using Flash).
​th:FreemindMacro	Renders Freemind mind maps (using Flash).
​th:TracMathPlugin	Renders LaTeX formulas (using LaTeX and dvipng).
​th:TracMathJaxPlugin	Renders LaTeX formulas (using MathJax and client-side web fonts).
​th:PdfRendererPlugin	Renders PDF documents (using pdftotext).
​th:TracDocBookPlugin	Renders DocBook documents (using XSLT).
​th:DocRenderPlugin	Renders Word DOC documents (using wvWare).
​th:ExcelViewerPlugin	Renders Excel spreadsheets (using clrd).
​th:ScrippetMacro	Renders dialogue and scene description scripts (using scrippet).
​th:ManPageRendererPlugin	Renders unix manual pages (using GNU groff).
​th:LotusNotesParserMacro	Renders Lotus Notes Emails (using regular expressions).

Additional Information and References

• ​API Reference
• Related to the trac.mimeview.api.IContentConverter interface
• Mailing list discussions:
  • In ​early May 2006: Initial discussion about merging IHTMLPreviewRenderer into IContentConverter (then still preliminarily called IMIMETypeConverter).
  • In ​May / June 2006: Discussion for initial release in Trac 0.10. Postponing / dropping merge of IHTMLPreviewRenderer and IContentConverter?
• Related tickets:
  • #3332 Planned major API Redesign
  • MIME tickets
  • Initial discussions about deprecating some renderers to tracopt (initially called tracext)
    • #366 Rejected proposal to switch to colorer
    • #4246 Switch to Pygments
    • #7067 tracext idea
    • #8113 Deprecation to tracopt
  • #5533 extended the interface for Trac 1.0 with an optional method to add support for additional mime types.

Interface deprecation

The docstring for this interface notes:

This interface will be merged with IContentConverter, as conversion to text/html will simply be a particular content conversion.

Note however that the IHTMLPreviewRenderer will still be supported for a while through an adapter, whereas the IContentConverter interface itself will be changed.

So if all you want to do is convert to HTML and don't feel like following the API changes, you should rather implement this interface for the time being.

The docstring of the trac.mimeview.api module notes:

The Mimeview API is quite complex and many things there are currently a bit difficult to work with (e.g. what an actual content might be, see the last paragraph of this description).

So this area is mainly in a work in progress state, which will be improved along the lines described in :teo:#3332.

In particular, if you are interested in writing IContentConverter and IHTMLPreviewRenderer components, note that those interfaces will be merged into a new style IContentConverter. Feel free to contribute remarks and suggestions for improvements to the corresponding ticket (#3332 as well).

These changes initially planned for 0.11 have been postponed to 0.12, then to 0.13 and are currently scheduled for milestone:next-major-0.1X. They have not been under active development since 2006 and would have to be rewritten as a separate API to avoid compatibility issues.

See the mailing list discussions above and #3332.