ftw.pdfgenerator

HomePage: https://github.com/4teamwork/ftw.pdfgenerator

Author: 4teamwork GmbH

Download: https://pypi.python.org/packages/source/f/ftw.pdfgenerator/ftw.pdfgenerator-1.3.0.zip

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

``ftw.pdfgenerator`` is meant to be used for generating PDFs from structured
data using predefined `LaTeX`_ views. It is not useful for converting
full HTML pages into `LaTeX`_ / PDFs, although it is able to convert small HTML
chunks into `LaTeX`_.

.. figure:: http://onegov.ch/approved.png/image
   :align: right
   :target: http://onegov.ch/community/zertifizierte-module/ftw.pdfgenerator

   Certified: 01/2013


Requirements
============

``ftw.pdfgenerator`` requires a TeX distribution with a ``pdflatex`` executable to be installed.

These TeX distributions are recommended:

- Mac OS: `MacTeX`_
- Linux / Unix: `TeX Live`_
- Windows: `MiKTeX`_

The package is compatible with `Plone`_ 4.x.


Installing
==========

Add ``ftw.pdfgenerator`` to your buildout configuration:

::

  [instance]
  eggs =
    ftw.pdfgenerator

Usage
=====

The pdfgenerator uses LaTeX for generating the PDF. You need to provide a
layout and a view for your context for being able to create a PDF.


Real world examples
-------------------

Some packages using ``ftw.pdfgenerator``:

- ``ftw.meeting`` has a PDF export of the meeting minutes:
  https://github.com/4teamwork/ftw.meeting/tree/master/ftw/meeting/latex
- ``ftw.book`` produces a PDF of the book recursively:
  https://github.com/4teamwork/ftw.book/tree/master/ftw/book/latex


Defining a layout
-----------------

A layout is a multi adapter addapting ``context, request, builder``. You can
easily define a new layout using the `mako`_ templating engine
(example: ``layout.py``):

::

    >>> from example.conference.session import ISession
    >>> from ftw.pdfgenerator.interfaces import IBuilder
    >>> from ftw.pdfgenerator.interfaces import ICustomizableLayout
    >>> from ftw.pdfgenerator.layout.customizable import CustomizableLayout
    >>> from zope.component import adapts
    >>> from zope.interface import Interface
    >>> from zope.interface import implements

    >>> class SessionLayout(MakoLayoutBase):
    ...     adapts(ISession, Interface, IBuilder)
    ...     implements(ICustomizableLayout)
    ...
    ...     template_directories = ['session_templates']
    ...     template_name = 'layout.tex'
    ...
    ...     def before_render_hook(self):
    ...         self.use_babel()
    ...         self.use_package('inputenc', options='utf8')
    ...         self.use_package('fontenc', options='T1')


Register the layout with zcml (example: ``configure.zcml``):

::

    <configure
        xmlns="http://namespaces.zope.org/zope"
        xmlns:browser="http://namespaces.zope.org/browser">

        <adapter factory=".layout.SessionLayout"
                 provides="ftw.pdfgenerator.interfaces.ILaTeXLayout" />

    </configure>


Create a template as defined in ``SessionLayout.template_name``
(example: ``session_templates/layout.tex``):

::

    <%block name="documentclass">
    \documentclass[a4paper,10pt]{article}
    </%block>

    <%block name="usePackages">
      ${packages}
    </%block>

    <%block name="beneathPackages">
    </%block>


    <%block name="aboveDocument">
    </%block>

    \begin{document}

    <%block name="documentTop">
      % if logo:
        ${logo}
      % endif
    </%block>

    ${content}

    <%block name="documentBottom">
    </%block>

    \end{document}


There are more methods on the layout, see the definition in
``ftw.pdfgenerator.interfaces.ILaTeXLayout``.


Defining a LaTeX view
---------------------

For every context for which a PDF is generated a LaTeX view (``ILaTeXView``)
is rendered. The view is a multi adapter adapting ``context, request, layout``.
There is a view based on the `mako`_ templating engine which can be extended
(example: ``views.py``):

::

    >>> from example.conference.session import ISession
    >>> from ftw.pdfgenerator.interfaces import ILaTeXLayout
    >>> from ftw.pdfgenerator.interfaces import ILaTeXView
    >>> from ftw.pdfgenerator.view import MakoLaTeXView
    >>> from zope.component import adapts
    >>> from zope.interface import Interface
    >>> from zope.interface import implements

    >>>