== 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 IContentConverter
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.