Extension Point : IHTMLPreviewRenderer
The IHTMLPreviewRenderer allows previewing files as HTML with syntax coloring.
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.
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.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.
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))
|PlainTextRenderer||Renders anything as plain text as a fallback.|
|ImageRenderer|| Renders an image inline (using an |
|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:
- Related tickets:
- #3332 Planned major API Redesign
- MIME tickets
- Initial discussions about deprecating some renderers to
- #5533 extended the interface for Trac 1.0 with an optional method to add support for additional mime types.
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
contentmight 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:
In particular, if you are interested in writing
IHTMLPreviewRenderercomponents, 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.