ftw.pdfgenerator 1.2.5

ftw.pdfgenerator is a Plone product 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.

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 ILaTeXLayout
>>> from ftw.pdfgenerator.layout.makolayout import MakoLayoutBase
>>> from zope.component import adapts
>>> from zope.interface import Interface
>>> from zope.interface import implements

>>> class SessionLayout(MakoLayoutBase):
... adapts(ISession, Interface, IBuilder)
... implements(ILaTeXLayout)
...
... 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 >
...
... \begin{document}
... ${content}
... \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

>>> class SessionLaTeXView(MakoLaTeXView):
... adapts(ISession, Interface, ILaTeXLayout)
... implements(ILaTeXView)
...
... template_directories = ['session_templates']
... template_name = 'view.tex'
...
... def get_render_arguments(self):
... return {'title': self.convert(self.context.Title()),
... 'description': self.convert(self.context.description),
... 'details': self.convert(self.context.details)}

Register the view with zcml (example: configure.zcml):

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

Create a template with the name defined in the class (example: session_templates/view.tex):

>>> \section*{${title}}
... % if description:
... \small ${description}
... % endif
... \normalsize ${details}

Generating a PDF

When a layout and a view for the context are registered the PDF can be generated by simply calling the view @@export_pdf on the context.

Recursive views

When extending from ftw.pdfgenerator.view.RecursiveLaTeXView and inserting the variable latex_content in your template, the view automatically renders all children for which a ILaTeXView is found.

HTML to LaTeX conversion

ftw.pdfgenerator comes with a simple but powerful HTML to LaTeX converter which is optimized for the common WYSIWYG-Editors used in Plone.

The converter can be used:

- in views, using self.convert(html)
- in layouts, using self.get_converter().convert(html)

It uses regular expressions for the simple conversions and python subconverters for the more complicated conversions. The converter is heavily customizable.


Product's homepage

Requirements:

· Python
· Plone CMS
· A TeX distribution with a pdflatex executable to be installed

What's New in This Release: [ read full changelog ]

· Use local text formatting commands, such as textbf instead of {bf }. #13 [jone]
· onegov.ch approved: add badge to readme. [jone]
· Declare missing dependencies. [jone]
· Make layout annotatable. This allows to store certain informations while building the PDF. [jone]
· Plone 4.3 compatibility. [jone]