Introduction
============

``collective.sendaspdf`` is an open source product for Plone that
allows downloading the page seen by the user as a PDF file. It also
provides a form to send the page by e-mail (a screenshot of the current
page in a PDF format being joined to the e-mail).

It relies on either of two products to generate the PDF files:

- ``xhtml2pdf``: http://www.xhtml2pdf.com/

- ``wkhtmltopdf``: http://wkhtmltopdf.org/

The site manager can easily choose which solution he prefers for
the generation.


Installing
==========

To install the package, you can simply add ``collective.sendaspdf``
to the eggs list in your buildout.
Then install it using Zope's quick installer or Plone's add-on
products manager.

To install ``xhtml2pdf``, add the following to your buildout eggs
directory::

     pisa
     pyPdf
     html5lib
     reportlab

``collective.sendaspdf`` has been tested with development versions of
``pisa`` and ``html5lib``. With the latest releases (when writing this
README - ``html5lib`` 0.9 and ``pisa`` 3.0.33) some pages could not be
rendered.

To install ``wkhtmltopdf``, go to the projects page and download an
executable version for your OS. Install it so the command
``wkhtmltopdf`` is in the PATH.

You can also update your buildout to automatically download and
install ``wkhtmltopdf`` and have it used by your instance.  This may
be tricky.  Look at our own `collective.sendaspdf buildout`_ for how
to do this.

.. _`collective.sendaspdf buildout`: https://github.com/zestsoftware/collective.sendaspdf/

If ``wkhtmltopdf`` is not on your path, you can set an environment
variable in your buildout config::

  [instance]
  ...
  zserver-threads = 7
  environment-vars =
      ...
      WKHTMLTOPDF_PATH /path/to/your/wkhtmltopdf

Additionally, as you can see in this configuration, the
``zserver-threads`` number has been pushed to 7.  This avoids troubles
with threads locks when multiple PDFs are rendered at the same time.
7 threads work fine when rendering 5 PDFs of the same page at the same
time.


jquery.pyproxy dependency
=========================

We have jquery.pyproxy_ as dependency.  It will work without it: we do
not install it by default.  If you install it yourself, the links to
send or download as pdf will use ajax, making the interaction a bit
faster and more userfriendly.

.. _jquery.pyproxy: https://pypi.python.org/pypi/jquery.pyproxy


Configuring
===========

Go to the Plone control panel. You will find a 'Send as PDF' link that
sends you to the products configuration page.

This page proposes a few settings, among which:

- the tool used to render the PDF files.

- the directory where the PDF files are stored.

- the sentence used as salt when hashing the user's emails
  (this hash is used to know which files a user can access)

- the name used in the mail for the PDF file.

- a default title/body for the mails.

- a list of browser for which the attachment name should not be
  given. Somehow, Chrome considers the PDF generated by the tool as
  potentially harmful for the computer if the attachment name is
  specified. Adding Chrome here avoids getting a warning.

For wkhtmltopdf user, two extra options are available:

- always use the print CSS to render the PDF.

- use the print CSS for a given set of objects.

xhtml2pdf always use the print CSS.


Compatibility
=============

This product has been tested with Plone 3 and Plone 4.  Starting at
version 2.6, we will only ensure compatibility with Plone 4, at least
in the tests.


For developers
==============

You can find some extra documentation in
``collective/sendaspdf/tests/adapter.txt``.  It explains how to define
custom options in the request or with an adapter.


Testing
=======

If you want to run the sendaspdf test suite, you need to add
'pdfminer' in the list of eggs in the buildout.

On Plone3, this is my configuration for running the tests (packages do
not seem to be mandatory as the eggs are taken from the zeoclient
section)::

  [test]
  recipe = collective.recipe.z2testrunner
  zope2part = zeoclient
  packages =


And on Plone 4::

  [test]
  recipe = zc.recipe.testrunner
  eggs =
      ${zeoclient:eggs}
  defaults = ['--auto-color', '--auto-progress']
  environment = environment

  [environment]
  WKHTMLTOPDF_PATH=${wkhtmltopdf:location}/wkhtmltopdf

