Extension Point : IContentConverter

Interface	IContentConverter	Since	0.10
Module	trac.mimeview	Source	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 TracDev/ComponentArchitecture and of course 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:

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 ITemplateStreamFilter.)

The (same / linked) IRequestHandler.handle_request method would check for a format argument and send the appropriately formatted content:

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:

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.)

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:

WikiModule​	Converts Wiki pages to plain text format.
TicketModule​	Converts tickets to CSV or RSS feed format.
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: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

• ​API Reference
• Related to the trac.mimeview.api.IHTMLPreviewRenderer interface
• Mailing list discussions:
  • In ​early May 2006: Initial discussion about merging IHTMLPreviewRenderer into IContentConverter (then still preliminarily called IMIMETypeConverter).
  • In ​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
  • 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 ​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].