Edgewall Software

Extension Point : IHTMLPreviewRenderer

InterfaceIHTMLPreviewRendererSince0.9
Moduletrac.mimeviewSourceapi.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:

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.

Last modified 4 years ago Last modified on Oct 27, 2014, 5:52:46 PM
Note: See TracWiki for help on using the wiki.