Edgewall Software

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


Ignore:
Timestamp:
Jul 7, 2011 11:12:15 PM (3 years ago)
Author:
psuter <petsuter@…>
Comment:

Legend:

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

    v1 v1  
     1== Extension Point : ''IContentConverter'' ==
     2
     3||'''Interface'''||''IContentConverter''||'''Since'''||0.10||
     4||'''Module'''||''trac.mimeview''||'''Source'''||[source:trunk/trac/mimeview/api.py api.py]||
     5
     6The ''IContentConverter'' allows converting content to different MIME types.
     7
     8== Purpose ==
     9
     10Trac 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.
     11Plugins can add support for additional formats by implementing IContentConverter.
     12
     13== Usage ==
     14
     15Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment].
     16
     17The implementation has to report any supported MIME types when queried. It might then be called when such a conversion is requested.
     18
     19Such 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:
     20{{{#!python
     21conversions = Mimeview(self.env).get_supported_conversions('text/x-trac-wiki')
     22for key, name, ext, mime_in, mime_out, q in conversions:
     23    conversion_href = req.href.wiki(page.name, version=version, format=key)
     24    add_link(req, 'alternate', conversion_href, name, mime_out)
     25}}}
     26(Or can be added by a [wiki:trac.web.api.ITemplateStreamFilter ITemplateStreamFilter].)
     27
     28The (same / linked) `IRequestHandler.handle_request` method would check for a `format` argument and send the appropriately formatted content:
     29{{{#!python
     30format = req.args.get('format')
     31if format:
     32    Mimeview(self.env).send_converted(req, 'text/x-trac-wiki',
     33                                      page.text, format, page.name)
     34}}}
     35
     36`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.
     37
     38== Examples ==
     39
     40The following minimal example converts Wiki pages to all caps plain text:
     41{{{#!python
     42from trac.core import implements, Component
     43from trac.mimeview.api import IContentConverter
     44
     45class AllCapsPlainTextWikiContentConverter(Component):
     46
     47    implements(IContentConverter)
     48
     49    # IContentConverter methods
     50
     51    def get_supported_conversions(self):
     52        return ('allcaps', 'ALL CAPS PLAIN TEXT', 'txt', 'text/x-trac-wiki',
     53                'text/plain', 1)
     54
     55    def convert_content(self, req, mimetype, content, key):
     56        return (str.upper(content), 'text/plain;charset=utf-8')
     57}}}
     58
     59Another 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.)
     60{{{#!python
     61from trac.core import implements, Component
     62from trac.mimeview.api import IContentConverter
     63
     64class LatexTemplateWikiContentConverter(Component):
     65
     66    implements(IContentConverter)
     67
     68    # IContentConverter methods
     69
     70    def get_supported_conversions(self):
     71        return ('latex', 'LaTeX', 'tex', 'text/x-trac-wiki',
     72                'application/x-latex', 8)
     73
     74    def convert_content(self, req, mimetype, content, key):
     75        data = self._extract_latex_template_data(content)
     76        output = Chrome(self.env).render_template(req, 'wiki-template.tex',
     77                                                  data, 'application/x-latex')
     78        return output, 'application/x-latex'
     79       
     80    def _extract_latex_template_data(self, content)
     81        # Fancy data extraction goes here...
     82        return {}
     83}}}
     84
     85== Available Implementations ==
     86In Trac:
     87|| [source:trunk/trac/wiki/web_ui.py WikiModule] || Converts Wiki pages to plain text format. ||
     88|| [source:trunk/trac/ticket/web_ui.py TicketModule] || Converts tickets to CSV or RSS feed format. ||
     89|| [source:trunk/trac/ticket/query.py QueryModule] || Converts queries to CSV or RSS feed format. ||
     90
     91In third-party plugins:
     92|| th:OdtExportPlugin  || Converts Wiki pages to ODT. ||
     93|| th:PageToOdtPlugin || Converts Wiki pages to ODT. ||
     94|| th:PageToDocIntegration  || Converts Wiki pages to filtered HTML for import to MS Word. ||
     95|| th:WikiExportPlugin  || Converts Wiki pages to PDF, ODT or DOC  (using ''PyUNO'' and ''!OpenOffice''). ||
     96|| th:TracWikiToPdfPlugin || Converts Wiki pages to PDF (using ''HTMLDOC''). ||
     97|| th:PageToPdfPlugin  || Converts Wiki pages to PDF (using ''HTMLDOC''). ||
     98|| th:TracWikiPrintPlugin  || Converts Wiki pages to PDF (using ''xhtml2pdf/PISA'') or printable HTML. ||
     99|| th:StickyTicketPlugin  || Converts tickets to PDF sticky notes (using ''reportlab''). ||
     100|| th:PdfRendererPlugin  || Converts PDF attachments to HTML (using ''pdftotext''). ||
     101|| [th:wiki:Page2DocbookPlugin th:Page2DocbookPlugin] || Converts Wiki pages to docbook. ||
     102|| th:SlideShowPlugin  || Converts Wiki pages to S5 slideshows. ||
     103|| th:DiscussionPlugin  || Provides RSS feeds for discussion topics. ||
     104|| th:IcalViewPlugin  || Provides iCalendar feeds for ticket queries. ||
     105
     106== Additional Information and References ==
     107 * [http://www.edgewall.org/docs/trac-trunk/html/api/trac_mimeview.html#trac.mimeview.api.IContentConverter API Reference]
     108 * Related to the [[trac.mimeview.api.IHTMLPreviewRenderer]] interface
     109 * Mailing list discussions:
     110   * In [Trac-Dev:494 early May 2006]: Initial discussion about merging `IHTMLPreviewRenderer` into `IContentConverter` (then still preliminarily called `IMIMETypeConverter`).
     111   * In [Trac-Dev:539 May / June 2006]: Discussion for initial release in Trac 0.10. Postponing / dropping merge of `IHTMLPreviewRenderer` and `IContentConverter`?
     112 * Related tickets:
     113  * #3332 Planned major API Redesign
     114    * #4590 Enhancement request: Changeset and file converter interfaces
     115    * #9937 Enhancement request: Milestone converter interfaces
     116  * Initial tickets leading to the introduction of this interface:
     117    * #1468 Enhancement request: PDF conversion
     118    * #2669 Enhancement request: Excel / CSV conversion
     119    * #2296 Enhancement request: Latex conversion
     120  * #8967 `max_preview_size` setting limits content to be converted to the first bytes
     121  * [query:status=!closed&description=~mime MIME tickets]
     122
     123===  Interface deprecation ===
     124The docstring for this interface notes:
     125> This api will likely change in the future (see #3332)
     126
     127The docstring for IHTMLPreviewRenderer notes:
     128> This interface will be merged with IContentConverter, as
     129> conversion to text/html will simply be a particular content
     130> conversion.
     131>
     132> Note however that the IHTMLPreviewRenderer will still be
     133> supported for a while through an adapter, whereas the
     134> IContentConverter interface itself will be changed.
     135>
     136> So if all you want to do is convert to HTML and don't feel like
     137> following the API changes, you should rather implement this
     138> interface for the time being.
     139
     140The docstring of the `trac.mimeview.api` module notes:
     141> The Mimeview API is quite complex and many things there are
     142> currently a bit difficult to work with (e.g. what an actual
     143> `content` might be, see the last paragraph of this description).
     144>
     145> So this area is mainly in a ''work in progress'' state, which will
     146> be improved along the lines described in :teo:`#3332`.
     147>
     148> In particular, if you are interested in writing `IContentConverter`
     149> and `IHTMLPreviewRenderer` components, note that those interfaces
     150> will be merged into a new style `IContentConverter`.  Feel free to
     151> contribute remarks and suggestions for improvements to the
     152> corresponding ticket (#3332 as well).
     153
     154These 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.
     155
     156See the mailing list discussions above and #3332.
     157
     158=== content: unicode / str / ... ===
     159The docstring of the `trac.mimeview.api` module notes:
     160> The actual `content` to be converted might be a `unicode` object, but
     161> it can also be the raw byte string (`str`) object, or simply an object
     162> that can be `read()`.
     163
     164=== Content-Disposition ===
     165The `Content-Disposition` header controls if and how user agents (i.e., web browser) should download the content as an attachment.
     166`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.
     167See [5274].