== Extension Point : ''IHTMLPreviewRenderer'' ==

||'''Interface'''||''IHTMLPreviewRenderer''||'''Since'''||0.9||
||'''Module'''||''trac.mimeview''||'''Source'''||[source:trunk/trac/mimeview/api.py 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 [TracSyntaxColoring 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 [wiki:TracDev/ComponentArchitecture] and of course [wiki: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 [source:trunk/trac/versioncontrol/web_ui/browser.py browser].
* Viewing an [source:trunk/trac/attachment.py attachment].
* Viewing a [source:trunk/trac/wiki/formatter.py WikiProcessor] block when the specified processor name is not found, but is a known mime type.
* Viewing changeset property differences using the [source:trunk/trac/versioncontrol/web_ui/changeset.py DefaultPropertyDiffRenderer].

== Examples ==

The following minimal example renders non-binary content as all caps plain text:
{{{#!python
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:
|| [source:trunk/trac/mimeview/api.py PlainTextRenderer] || Renders anything as plain text as a fallback. ||
|| [source:trunk/trac/mimeview/api.py ImageRenderer] || Renders an image inline (using an `img` tag). ||
|| [source:trunk/trac/mimeview/api.py WikiTextRenderer] || Renders a Trac Wiki page. ||
|| [source:trunk/trac/mimeview/patch.py PatchRenderer] || Renders patches in unified diff format. ||
|| [source:trunk/trac/mimeview/txtl.py TextileRenderer] || Renders plain text marked up in Textile format. ||
|| [source:trunk/trac/mimeview/rst.py ReStructuredTextRenderer] || Renders plain text marked up in reStructuredText format. ||
|| [source:trunk/trac/mimeview/pygments.py PygmentsRenderer] || Renders various source code formats with syntax highlighting (using ''Pygments''). ||

In Trac (optional):
|| [source:trunk/tracopt/mimeview/silvercity.py SilverCityRenderer] || Renders various source code formats with syntax highlighting (using ''SilverCity''). Deprecated in favor of !PygmentsRenderer. ||
|| [source:trunk/tracopt/mimeview/php.py PHPRenderer] || Renders PHP source code with syntax highlighting (using ''PHP''). Deprecated in favor of !PygmentsRenderer.  ||
|| [source:trunk/tracopt/mimeview/enscript.py EnscriptRenderer] || Renders various source code formats with syntax highlighting (using ''GNU Enscript''). Deprecated in favor of !PygmentsRenderer.  ||

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 ==
 * [http://www.edgewall.org/docs/trac-trunk/html/api/trac_mimeview.html#trac.mimeview.api.IHTMLPreviewRenderer API Reference]
 * Related to the [[trac.mimeview.api.IContentConverter]] interface
 * Mailing list discussions:
   * In [Trac-Dev:494 early May 2006]: Initial discussion about merging `IHTMLPreviewRenderer` into `IContentConverter` (then still preliminarily called `IMIMETypeConverter`).
   * In [Trac-Dev:539 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
  * [query:status=!closed&description=~mime 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`

===  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 [http://trac.edgewall.org/wiki/TracDev/ApiChanges/0.10#IHTMLPreviewRenderer0.100.9 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.