eea.converter 9.0

SVG, PNG, PDF converters using external tools as ImageMagick

Introduction

This package provides utilities to convert images and PDF files using ImageMagick. It also provides a generic /download.pdf browser view that allow your users to download Plone pages as PDF files with custom PDF cover, disclaimer and back cover (requires wkhtmltopdf and pdftk system-packages installed on your server).

Installation

• Make sure you have wkhtmltopdf 0.12.1+ installed or install it via zc.buildout

• Make sure you have an OS environment called EEACONVERTER_TEMP within your buildout if you have zope instances over more than one physical server.

• Add eea.converter to your eggs section in your buildout and re-run buildout. You can download a sample buildout from https://github.com/collective/eea.converter/tree/master/buildouts/plone4

Getting started

1. Try http://localhost:8080/Plone/front-page/download.pdf

Customize output PDF

Cover

Provide custom browser:page called @@pdf.cover:

<browser:page
  for="my.package.interfaces.ICustomContent"
  name="pdf.cover"
  class=".app.pdfview.Cover"
  template="zpt/pdf.cover.pt"
  permission="zope2.View"
  />

Disclaimer

First page after PDF Cover containing author details and copyrights. Provide custom browser:page called @@pdf.cover:

<browser:page
  for="my.package.interfaces.ICustomContent"
  name="pdf.disclaimer"
  class=".app.pdfview.Disclaimer"
  template="zpt/pdf.disclaimer.pt"
  permission="zope2.View"
  />

Body

Provide custom browser:page called @@pdf.body:

<browser:page
  for="my.package.interfaces.ICustomContent"
  name="pdf.body"
  class=".app.pdfview.Body"
  template="zpt/pdf.body.pt"
  permission="zope2.View"
  />

Back Cover

Provide custom browser:page called @@pdf.cover.back:

<browser:page
  for="my.package.interfaces.ICustomContent"
  name="pdf.cover.back"
  class=".app.pdfview.BackCover"
  template="zpt/pdf.cover.back.pt"
  permission="zope2.View"
  />

Table of contents

To enable Table of contents provide an empty browser:page called @@pdf.toc:

<browser:page
  for="my.package.interfaces.ICustomContent"
  name="pdf.toc"
  template="zpt/pdf.toc.pt"
  permission="zope2.View"
  />

Options

For PDF cover you’ll have to provide a named adapter like:

<adapter
  name="pdf.cover"
  for=" my.package.interfaces.ICustomContent"
  provides="eea.converter.interfaces.IPDFOptionsMaker"
  factory=".adapters.CoverOptionsMaker" />

Same for PDF disclaimer:

<adapter
  name="pdf.disclaimer"
  for=" my.package.interfaces.ICustomContent"
  provides="eea.converter.interfaces.IPDFOptionsMaker"
  factory=".adapters.DisclaimerOptionsMaker" />

Or for PDF back cover:

<adapter
  name="pdf.cover.back"
  for=" my.package.interfaces.ICustomContent"
  provides="eea.converter.interfaces.IPDFOptionsMaker"
  factory=".adapters.BackCoverOptionsMaker" />

For PDF body you’ll have to provide a named adapter like:

<adapter
  name="pdf.body"
  for=" my.package.interfaces.ICustomContent"
  provides="eea.converter.interfaces.IPDFOptionsMaker"
  factory=".adapters.BodyOptionsMaker" />

For global PDF options provide an unamed adapter like:

<adapter
  for=" my.package.interfaces.ICustomContent"
  provides="eea.converter.interfaces.IPDFOptionsMaker"
  factory=".adapters.OptionsMaker" />

Also add custom print.css for your needs. See more at eea.pdf

Restrict access and async

In order to restrict access to /download.pdf you’ll have to provide a multi-adapter named pdf.support with a method called can_download like:

<browser:page
  name="pdf.support"
  for="zope.interface.Interface"
  class=".support.Support"
  permission="zope.Public"
  allowed_interface="eea.converter.interfaces.ISupport"
  />

Same for asynchronous download, define a method called async. See default implementation within eea.converter.browser.app.support or add an environment var called EEACONVERTER_ASYNC within your buildout.cfg:

[instance]
...
environment-vars =
  EEACONVERTER_ASYNC True

Content rules

This package uses Plone Content-rules to notify users by email when an asynchronous job is done. Thus 3 custom content-rules will be added within Plone > Site Setup > Content-rules

Warning

As these content-rules are triggered by an asynchronous job, while you customize the email template for these content-rules, please DO NOT USE OTHER string substitutions that the ones that start with $download_ as you’ll break the download chain. Also if you disable these content-rules the users will never know when the file is ready and what is the link where they can download the output document.

Export succeeded

Notify the person who requested a PDF/ePub export that the document successfully exported and provide a link to the downloadable file.

Export failed

Notify the person who requested a PDF/ePub export that the export failed.

Export failed (admin)

Notify admin that there were issues while exporting PDF/ePub

Content rules email string substitution

In order to be able to easily customize emails sent by this package the following custom email template string substitutions can be made

${download_came_from_url}

The absolute URL of the Plone object which is downloaded as PDF/ePub

${download_email}

Email address of the user that triggered the download as PDF/ePub action

${download_error}

Error traceback when download as PDF/ePub job fails

${download_from_email}

Site Admin email address customizable via Plone > Site Setup > Mail

${download_from_name}

Site Admin name customizable via Plone > Site Setup > Mail

${download_title}

Title of the Plone object which is downloaded as PDF/ePub

${download_url}

The absolute URL where the generated output PDF/ePub can be downloaded

${download_type}

Download type: PDF/ePub

Dependencies

Note

These are not hard dependencies. You can use all features of eea.converter or just the ones that you need.

• pdfinfo to parse pdf metadata (part of the xpdf package):

  yum install xpdf (fedora)
  apt-get install xpdf (debian)

• pdftk to generate a cover image from a pdf file:

  yum install pdftk (fedora)
  apt-get install pdftk (debian)

• ImageMagick (6.3.7+):

  yum install ImageMagick
  apt-get install imagemagick

• wkhtmltopdf (0.12.1+):

  Download and install

• eea.pdf (optional for advanced PDF export)

• eea.epub (optional for ePub export)

Source code

Latest source code (Zope 2 compatible):

• Plone Collective on Github

• EEA on Github

Documentation

See the doc directory in this package.

API Doc

http://apidoc.eea.europa.eu/eea.converter-module.html

Copyright and license

The Initial Owner of the Original Code is European Environment Agency (EEA). All Rights Reserved.

The EEA Exhibit (the Original Code) is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

More details under docs/License.txt

Funding

EEA - European Environment Agency (EU)

Changelog

9.0 - (2015-02-25)

• Bug fix: Fixed UnicodeDecodeError within download.pdf template [voineali refs #23338]

• Cleanup: Remove deprecated make_pdf_cover from download.pdf [voineali refs #22971]

• Change: Moved async API from eea.pdf to eea.converter in order to reuse it for other async jobs (e.g. eea.epub) [voineali refs #22971]

8.7 - (2015-02-16)

• Feature: Update ISupport API with async and email methods [voineali refs #22971]

• Feature: Added possibility to use specific ZPT macro while exporting PDF body (e.g. content-core) [voineali refs #22686]

8.6 - (2014-12-23)

• Bug fix: Use with statement with temporary files in order to ensure that they are safely closed before exit [voineali refs #22080]

• Bug fix: While creating authentication cookie-jar, also be aware of CDN resources [voineali refs #22080]

8.5 - (2014-12-02)

• Bug fix: Added possibility to define shared temporary directory using os.env EEACONVERTER_TEMP in order to avoid surprises while using together with zc.async [voineali refs #21958]

8.4 - (2014-11-28)

• Bug fix: Fixed duplicate cookies when printing collection header/footer by using wkhtmltopdf more stable –cookie-jar option than –cookie. This also fixed blank page at the beginning of PDF introduced in previous version [voineali refs #21958]

8.3 - (2014-11-20)

• Bug fix: Fixed table of contents page alignment [voineali refs #21628]

• Bug fix: Fixed duplicate cookies when printing collection header/footer [voineali refs #21628]

8.2 - (2014-10-15)

• Bug fix: Protect against random wkhtmltopdf Segmentation fault errors and retry 3 times to re-generate PDF [voineali refs #21149]

8.1 - (2014-10-01)

• Change: Prefix temporary files with package name: eea.converter. [voineali refs #21100]

8.0 - (2014-09-15)

• Feature: Possibility to run a PDF conversion job in safe mode (default) or not (raise all errors) [voineali refs #20845]

• Change: Changed download.pdf API in order to allow dry-run used by async jobs [voineali refs #20843]

• Change: Made @@pdf.support/can_download accessible from URL [voineali refs #20846]

7.1 - (2014-08-12)

• Bug fix: Align PDF Table of Contents trailing dotted with page number [voineali refs #20431]

• Bug fix: Fix long PDF header and footer texts and align left or right according with page parity [voineali refs #20431]

• Feature: Added i18n translations [voineali refs #20431]

• Feature: Added possibility to avoid truncated sentences in description [voineali refs #20456]

• Feature: Enabled javascript by default within PDF export. [voineali refs #20459]

• Feature: Added API to restrict access to download.pdf [voineali refs #20436]

7.0 - (2014-07-15)

• Feature: Added Table of Contents support [voineali refs #20268]

• Cleanup: Remove collective.sendaspdf dependency [voineali refs #20268]

6.8 - (2014-06-06)

• Feature: Added PDF Back Cover support [voineali refs #19882]

• Feature: Added PDF Disclaimer support (the first page after cover containing author details and copyrights) [voineali refs #19882]

6.7 - (2014-03-10)

• Bug fix: Do not add table of content on PDF cover [voineali refs #18630]

• Change: pass a doctype to the header pdf template in order to workaround wkhtmltopdf 0.12 issue which fails to insert the header without it [ichim-david refs #18550]

6.6 - (2014-01-21)

• Bug fix: removed wrongly added blockquotes within README.rst [ichim-david refs #18064]

• Feature: adding Sphinx-generated documentation in Page Template format [batradav refs #9502]

6.5 - (2013-10-22)

• Bug fix: return first page on pdf to image conversion; refactor cover [simiamih refs #16799]

6.4 - (2013-10-07)

• Feature: Added utility method to truncate text by the number of characters without cutting words at the end [voineali refs #16946]

• Feature: Added utility method to convert relative urls to absolute urls [voineali refs #16946]

6.3 - (2013-10-04)

• Bug fix: Fixed PDF cover asking for credentials for non-published documents [voineali refs #14904]

• Feature: Added custom PDF html-header and html-footer in order to easily customize them (just override @@pdf.header and @@pdf.footer for your contexts) [voineali refs #16802]

6.2 - (2013-09-23)

• Feature: Export HTML to PDF with custom cover (requires collective.sendaspdf) [voineali refs #14904]

6.1 - (2013-02-25)

• Feature: added information for contributors [ciobabog refs #13892]

• Add Windows support for close_fds parameter of Popen [erral #1]

6.0 - (2012-10-08)

• Fixed dependencies, cleanup and make the package run on a clean Zope [ghicaale #5426]

1.1 - (2012-06-12)

• Added watermark utility [szabozo0]

1.0 - (2012-03-05)

• Initial release [voineali]