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

Timestamp:

Jul 7, 2011 11:12:15 PM (2 years ago)

Author:

psuter <petsuter@…>

Comment:

—

TracDev/PluginDevelopment/ExtensionPoints/trac.mimeview.api.IContentConverter

@@ +1 @@
+== Extension Point : ''IContentConverter'' ==
+
+||'''Interface'''||''IContentConverter''||'''Since'''||0.10||
+||'''Module'''||''trac.mimeview''||'''Source'''||[source:trunk/trac/mimeview/api.py api.py]||
+
+The ''IContentConverter'' allows converting content to different MIME types.
+
+== Purpose ==
+
+Trac provides support for converting content to various MIME types. Among other things this allows users to export certain resources in alternate formats and to subscribe to feeds.
+Plugins can add support for additional formats by implementing IContentConverter.
+
+== Usage ==
+
+Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment].
+
+The implementation has to report any supported MIME types when queried. It might then be called when such a conversion is requested.
+
+Such a request is typically triggered by a user clicking a special ''format'' link. Such links may be inserted for each supported format by the `IRequestHandler.handle_request` method of the respective resource on the resource's HTML page:
+{{{#!python
+conversions = Mimeview(self.env).get_supported_conversions('text/x-trac-wiki')
+for key, name, ext, mime_in, mime_out, q in conversions:
+    conversion_href = req.href.wiki(page.name, version=version, format=key)
+    add_link(req, 'alternate', conversion_href, name, mime_out)
+}}}
+(Or can be added by a [wiki:trac.web.api.ITemplateStreamFilter ITemplateStreamFilter].)
+
+The (same / linked) `IRequestHandler.handle_request` method would check for a `format` argument and send the appropriately formatted content:
+{{{#!python
+format = req.args.get('format')
+if format:
+    Mimeview(self.env).send_converted(req, 'text/x-trac-wiki',
+                                      page.text, format, page.name)
+}}}
+
+`Mimeview.send_converted` calls `Mimeview.convert_content` (which calls `content_convert` of the most appropriate `IContentConveter` implementation) and sends back the converted content, ending the request.
+
+== Examples ==
+
+The following minimal example converts Wiki pages to all caps plain text:
+{{{#!python
+from trac.core import implements, Component
+from trac.mimeview.api import IContentConverter
+
+class AllCapsPlainTextWikiContentConverter(Component):
+
+    implements(IContentConverter)
+
+    # IContentConverter methods
+
+    def get_supported_conversions(self):
+        return ('allcaps', 'ALL CAPS PLAIN TEXT', 'txt', 'text/x-trac-wiki',
+                'text/plain', 1)
+
+    def convert_content(self, req, mimetype, content, key):
+        return (str.upper(content), 'text/plain;charset=utf-8')
+}}}
+
+Another approach would be to render the content using a template (see trac.web.chrome.ITemplateProvider). (Typically the code would extensively process the content to extract data to be used in the template.)
+{{{#!python
+from trac.core import implements, Component
+from trac.mimeview.api import IContentConverter
+
+class LatexTemplateWikiContentConverter(Component):
+
+    implements(IContentConverter)
+
+    # IContentConverter methods
+
+    def get_supported_conversions(self):
+        return ('latex', 'LaTeX', 'tex', 'text/x-trac-wiki',
+                'application/x-latex', 8)
+
+    def convert_content(self, req, mimetype, content, key):
+        data = self._extract_latex_template_data(content)
+        output = Chrome(self.env).render_template(req, 'wiki-template.tex',
+                                                  data, 'application/x-latex')
+        return output, 'application/x-latex'
+        
+    def _extract_latex_template_data(self, content)
+        # Fancy data extraction goes here...
+        return {}
+}}}
+
+== Available Implementations ==
+In Trac:
+|| [source:trunk/trac/wiki/web_ui.py WikiModule] || Converts Wiki pages to plain text format. ||
+|| [source:trunk/trac/ticket/web_ui.py TicketModule] || Converts tickets to CSV or RSS feed format. ||
+|| [source:trunk/trac/ticket/query.py QueryModule] || Converts queries to CSV or RSS feed format. ||
+
+In third-party plugins:
+|| th:OdtExportPlugin  || Converts Wiki pages to ODT. ||
+|| th:PageToOdtPlugin || Converts Wiki pages to ODT. ||
+|| th:PageToDocIntegration  || Converts Wiki pages to filtered HTML for import to MS Word. ||
+|| th:WikiExportPlugin  || Converts Wiki pages to PDF, ODT or DOC  (using ''PyUNO'' and ''!OpenOffice''). ||
+|| th:TracWikiToPdfPlugin || Converts Wiki pages to PDF (using ''HTMLDOC''). ||
+|| th:PageToPdfPlugin  || Converts Wiki pages to PDF (using ''HTMLDOC''). ||
+|| th:TracWikiPrintPlugin  || Converts Wiki pages to PDF (using ''xhtml2pdf/PISA'') or printable HTML. ||
+|| th:StickyTicketPlugin  || Converts tickets to PDF sticky notes (using ''reportlab''). ||
+|| th:PdfRendererPlugin  || Converts PDF attachments to HTML (using ''pdftotext''). ||
+|| [th:wiki:Page2DocbookPlugin th:Page2DocbookPlugin] || Converts Wiki pages to docbook. ||
+|| th:SlideShowPlugin  || Converts Wiki pages to S5 slideshows. ||
+|| th:DiscussionPlugin  || Provides RSS feeds for discussion topics. ||
+|| th:IcalViewPlugin  || Provides iCalendar feeds for ticket queries. ||
+
+== Additional Information and References ==
+ * [http://www.edgewall.org/docs/trac-trunk/html/api/trac_mimeview.html#trac.mimeview.api.IContentConverter API Reference]
+ * Related to the [[trac.mimeview.api.IHTMLPreviewRenderer]] 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
+    * #4590 Enhancement request: Changeset and file converter interfaces
+    * #9937 Enhancement request: Milestone converter interfaces
+  * Initial tickets leading to the introduction of this interface:
+    * #1468 Enhancement request: PDF conversion
+    * #2669 Enhancement request: Excel / CSV conversion
+    * #2296 Enhancement request: Latex conversion
+  * #8967 `max_preview_size` setting limits content to be converted to the first bytes
+  * [query:status=!closed&description=~mime MIME tickets]
+
+===  Interface deprecation ===
+The docstring for this interface notes:
+> This api will likely change in the future (see #3332)
+
+The docstring for IHTMLPreviewRenderer 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.
+
+=== content: unicode / str / ... ===
+The docstring of the `trac.mimeview.api` module notes:
+> The actual `content` to be converted might be a `unicode` object, but
+> it can also be the raw byte string (`str`) object, or simply an object
+> that can be `read()`.
+
+=== Content-Disposition ===
+The `Content-Disposition` header controls if and how user agents (i.e., web browser) should download the content as an attachment.
+`Mimeview.send_converted` will automatically send this header. A `IContentConverter` implementation can however send it again, to e.g. add the ''attachment;'' keyword or override the filename.
+See [5274].