== 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 [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].