| 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 | |
| 6 | The ''IContentConverter'' allows converting content to different MIME types. |
| 7 | |
| 8 | == Purpose == |
| 9 | |
| 10 | 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. |
| 11 | Plugins can add support for additional formats by implementing IContentConverter. |
| 12 | |
| 13 | == Usage == |
| 14 | |
| 15 | Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment]. |
| 16 | |
| 17 | The implementation has to report any supported MIME types when queried. It might then be called when such a conversion is requested. |
| 18 | |
| 19 | 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: |
| 20 | {{{#!python |
| 21 | conversions = Mimeview(self.env).get_supported_conversions('text/x-trac-wiki') |
| 22 | for 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 | |
| 28 | The (same / linked) `IRequestHandler.handle_request` method would check for a `format` argument and send the appropriately formatted content: |
| 29 | {{{#!python |
| 30 | format = req.args.get('format') |
| 31 | if 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 | |
| 40 | The following minimal example converts Wiki pages to all caps plain text: |
| 41 | {{{#!python |
| 42 | from trac.core import implements, Component |
| 43 | from trac.mimeview.api import IContentConverter |
| 44 | |
| 45 | class 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 | |
| 59 | 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.) |
| 60 | {{{#!python |
| 61 | from trac.core import implements, Component |
| 62 | from trac.mimeview.api import IContentConverter |
| 63 | |
| 64 | class 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 == |
| 86 | In 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 | |
| 91 | In 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 === |
| 124 | The docstring for this interface notes: |
| 125 | > This api will likely change in the future (see #3332) |
| 126 | |
| 127 | The 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 | |
| 140 | The 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 | |
| 154 | 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. |
| 155 | |
| 156 | See the mailing list discussions above and #3332. |
| 157 | |
| 158 | === content: unicode / str / ... === |
| 159 | The 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 === |
| 165 | The `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. |
| 167 | See [5274]. |