Edgewall Software

Changes between Initial Version and Version 1 of TracDev/PluginDevelopment/ExtensionPoints/trac.mimeview.api.IHTMLPreviewRenderer


Ignore:
Timestamp:
Jul 23, 2011, 11:51:48 AM (9 years ago)
Author:
psuter <petsuter@…>
Comment:

Legend:

Unmodified
Added
Removed
Modified
  • TracDev/PluginDevelopment/ExtensionPoints/trac.mimeview.api.IHTMLPreviewRenderer

    v1 v1  
     1== Extension Point : ''IHTMLPreviewRenderer'' ==
     2
     3||'''Interface'''||''IHTMLPreviewRenderer''||'''Since'''||0.9||
     4||'''Module'''||''trac.mimeview''||'''Source'''||[source:trunk/trac/mimeview/api.py api.py]||
     5
     6The ''IHTMLPreviewRenderer'' allows previewing files as HTML with syntax coloring.
     7
     8== Purpose ==
     9
     10Trac provides support for previewing files (attachments, files stored in version control) in the browser as HTML with [TracSyntaxColoring syntax coloring].
     11The same support is also available for embedding via WikiProcessors syntax.
     12Plugins can add support for additional kinds of previews by implementing IHTMLPreviewRenderer.
     13
     14== Usage ==
     15
     16Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment].
     17
     18The 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.
     19
     20Any 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:
     21* Viewing a file in the version control [source:trunk/trac/versioncontrol/web_ui/browser.py browser].
     22* Viewing an [source:trunk/trac/attachment.py attachment].
     23* Viewing a [source:trunk/trac/wiki/formatter.py WikiProcessor] block when the specified processor name is not found, but is a known mime type.
     24* Viewing changeset property differences using the [source:trunk/trac/versioncontrol/web_ui/changeset.py DefaultPropertyDiffRenderer].
     25
     26== Examples ==
     27
     28The following minimal example renders non-binary content as all caps plain text:
     29{{{#!python
     30from trac.core import implements, Component
     31from trac.mimeview.api import IContentConverter
     32
     33class AllCapsPlainTextRenderer(Component):
     34       
     35    implements(IHTMLPreviewRenderer)
     36
     37    expand_tabs = True
     38    returns_source = True
     39
     40    def get_quality_ratio(self, mimetype):
     41        if mimetype in Mimeview(self.env).treat_as_binary:
     42            return 0
     43        return 1
     44
     45    def render(self, context, mimetype, content, filename=None, url=None):
     46        if is_binary(content):
     47            self.log.debug("Binary data; no preview available")
     48            return
     49
     50        self.log.debug("Using all caps plain text mimeviewer")
     51        return str.upper(content_to_unicode(self.env, content, mimetype))
     52}}}
     53
     54== Available Implementations ==
     55
     56In Trac:
     57|| [source:trunk/trac/mimeview/api.py PlainTextRenderer] || Renders anything as plain text as a fallback. ||
     58|| [source:trunk/trac/mimeview/api.py ImageRenderer] || Renders an image inline (using an `img` tag). ||
     59|| [source:trunk/trac/mimeview/api.py WikiTextRenderer] || Renders a Trac Wiki page. ||
     60|| [source:trunk/trac/mimeview/patch.py PatchRenderer] || Renders patches in unified diff format. ||
     61|| [source:trunk/trac/mimeview/txtl.py TextileRenderer] || Renders plain text marked up in Textile format. ||
     62|| [source:trunk/trac/mimeview/rst.py ReStructuredTextRenderer] || Renders plain text marked up in reStructuredText format. ||
     63|| [source:trunk/trac/mimeview/pygments.py PygmentsRenderer] || Renders various source code formats with syntax highlighting (using ''Pygments''). ||
     64
     65In Trac (optional):
     66|| [source:trunk/tracopt/mimeview/silvercity.py SilverCityRenderer] || Renders various source code formats with syntax highlighting (using ''SilverCity''). Deprecated in favor of !PygmentsRenderer. ||
     67|| [source:trunk/tracopt/mimeview/php.py PHPRenderer] || Renders PHP source code with syntax highlighting (using ''PHP''). Deprecated in favor of !PygmentsRenderer.  ||
     68|| [source:trunk/tracopt/mimeview/enscript.py EnscriptRenderer] || Renders various source code formats with syntax highlighting (using ''GNU Enscript''). Deprecated in favor of !PygmentsRenderer.  ||
     69
     70In third-party plugins:
     71|| th:GraphvizPlugin || Renders graph diagrams (using ''Graphviz''). ||
     72|| th:GanttChartPlugin || Renders Gantt charts (using ''PyYAML'' and ''PIL''). ||
     73|| th:MscgenPlugin || Renders message sequence chart diagrams (using ''mscgen''). ||
     74|| th:MetapostPlugin || Renders Metapost drawings  (using ''Metapost''). ||
     75|| th:MindMapMacro || Renders Freemind mind maps (using ''Flash''). ||
     76|| th:FreemindMacro || Renders Freemind mind maps (using ''Flash''). ||
     77|| th:TracMathPlugin || Renders LaTeX formulas (using ''LaTeX'' and ''dvipng''). ||
     78|| th:TracMathJaxPlugin || Renders LaTeX formulas (using ''!MathJax'' and client-side web fonts). ||
     79|| th:PdfRendererPlugin || Renders PDF documents (using ''pdftotext''). ||
     80|| th:TracDocBookPlugin || Renders !DocBook documents (using XSLT). ||
     81|| th:DocRenderPlugin || Renders Word DOC documents (using ''wvWare''). ||
     82|| th:ExcelViewerPlugin || Renders Excel spreadsheets (using ''clrd''). ||
     83|| th:ScrippetMacro || Renders dialogue and scene description scripts (using ''scrippet''). ||
     84|| th:ManPageRendererPlugin || Renders unix manual pages (using ''GNU groff''). ||
     85|| th:LotusNotesParserMacro || Renders Lotus Notes Emails (using regular expressions). ||
     86
     87== Additional Information and References ==
     88 * [http://www.edgewall.org/docs/trac-trunk/html/api/trac_mimeview.html#trac.mimeview.api.IHTMLPreviewRenderer API Reference]
     89 * Related to the [[trac.mimeview.api.IContentConverter]] interface
     90 * Mailing list discussions:
     91   * In [Trac-Dev:494 early May 2006]: Initial discussion about merging `IHTMLPreviewRenderer` into `IContentConverter` (then still preliminarily called `IMIMETypeConverter`).
     92   * In [Trac-Dev:539 May / June 2006]: Discussion for initial release in Trac 0.10. Postponing / dropping merge of `IHTMLPreviewRenderer` and `IContentConverter`?
     93 * Related tickets:
     94  * #3332 Planned major API Redesign
     95  * [query:status=!closed&description=~mime MIME tickets]
     96  * Initial discussions about deprecating some renderers to `tracopt` (initially called `tracext`)
     97    * #366 Rejected proposal to switch to ''colorer''
     98    * #4246 Switch to ''Pygments''
     99    * #7067 `tracext` idea
     100    * #8113 Deprecation to `tracopt`
     101
     102===  Interface deprecation ===
     103The docstring for this interface notes:
     104> This interface will be merged with IContentConverter, as
     105> conversion to text/html will simply be a particular content
     106> conversion.
     107>
     108> Note however that the IHTMLPreviewRenderer will still be
     109> supported for a while through an adapter, whereas the
     110> IContentConverter interface itself will be changed.
     111>
     112> So if all you want to do is convert to HTML and don't feel like
     113> following the API changes, you should rather implement this
     114> interface for the time being.
     115
     116The docstring of the `trac.mimeview.api` module notes:
     117> The Mimeview API is quite complex and many things there are
     118> currently a bit difficult to work with (e.g. what an actual
     119> `content` might be, see the last paragraph of this description).
     120>
     121> So this area is mainly in a ''work in progress'' state, which will
     122> be improved along the lines described in :teo:`#3332`.
     123>
     124> In particular, if you are interested in writing `IContentConverter`
     125> and `IHTMLPreviewRenderer` components, note that those interfaces
     126> will be merged into a new style `IContentConverter`.  Feel free to
     127> contribute remarks and suggestions for improvements to the
     128> corresponding ticket (#3332 as well).
     129
     130These 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.
     131
     132See the mailing list discussions above and #3332.