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