| | 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 | |
| | 6 | The ''IHTMLPreviewRenderer'' allows previewing files as HTML with syntax coloring. |
| | 7 | |
| | 8 | == Purpose == |
| | 9 | |
| | 10 | Trac provides support for previewing files (attachments, files stored in version control) in the browser as HTML with [TracSyntaxColoring syntax coloring]. |
| | 11 | The same support is also available for embedding via WikiProcessors syntax. |
| | 12 | Plugins can add support for additional kinds of previews by implementing IHTMLPreviewRenderer. |
| | 13 | |
| | 14 | == Usage == |
| | 15 | |
| | 16 | Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment]. |
| | 17 | |
| | 18 | 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. |
| | 19 | |
| | 20 | 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: |
| | 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 | |
| | 28 | The following minimal example renders non-binary content as all caps plain text: |
| | 29 | {{{#!python |
| | 30 | from trac.core import implements, Component |
| | 31 | from trac.mimeview.api import IContentConverter |
| | 32 | |
| | 33 | class 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 | |
| | 56 | In 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 | |
| | 65 | In 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 | |
| | 70 | In 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 === |
| | 103 | The 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 | |
| | 116 | The 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 | |
| | 130 | 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. |
| | 131 | |
| | 132 | See the mailing list discussions above and #3332. |
