A library for generating PDF representations of Plone objects with LaTeX.
Project description
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.
Requirements
ftw.pdfgenerator requires a TeX distribution with a pdflatex executable to be installed.
These TeX distributions are recommended:
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"> ... ... <adapter factory=".views.SessionLaTeXView" ... provides="ftw.pdfgenerator.interfaces.ILaTeXView" /> ... ... </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.
Links
Main github project repository: https://github.com/4teamwork/ftw.pdfgenerator
Issue tracker: https://github.com/4teamwork/ftw.pdfgenerator/issues
Package on pypi: http://pypi.python.org/pypi/ftw.pdfgenerator
Continuous integration: https://jenkins.4teamwork.ch/job/ftw.pdfgenerator/
Copyright
This package is copyright by 4teamwork.
ftw.pdfgenerator is licensed under GNU General Public License, version 2.
Changelog
1.0.2 (2012-03-08)
Table converter: add css classes for aligning cells (“right”, “center”, “left”). [jone]
Table converter: add cell-border functionality, using css classes “border-right”, “border-left”, “border-top” and “border-bottom”. [jone]
Table converter: improve grid border, add classes “border-grid” and “listing” for enabling grid borders. [jone]
Table converter: use “tabular” for small tables. #3 [jone]
1.0.1 (2012-03-05)
Add use_babel function to layout, enabling the preferred language. [jone]
1.0b2 (2012-02-28)
Added missing MANIFEST.in. [phgross]
1.0b1 (2012-02-24)
Added a “debug-pdf” view, enabling the pdf debug mode temporarily. [jone]
Added some French translations [ttschanz]
Implement hyperlink converter. [jone]
Implement convertion of definition lists. [jone]
Rename as_pdf view to export_pdf. [jone]
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.