Welcome, guest | Sign In | My Account | Store | Cart

Notice! PyPM is being replaced with the ActiveState Platform, which enhances PyPM’s build and deploy capabilities. Create your free Platform account to download ActivePython or customize Python with the packages you require and get automatic updates.

Download
ActivePython
INSTALL>
pypm install ftw.pdfgenerator

How to install ftw.pdfgenerator

  1. Download and install ActivePython
  2. Open Command Prompt
  3. Type pypm install ftw.pdfgenerator
 Python 2.7Python 3.2Python 3.3
Windows (32-bit)
1.2.1
1.2.7Never BuiltWhy not?
1.2.1 Available View build log
1.1.2 Available View build log
1.0.2 Available View build log
Windows (64-bit)
1.2.1
1.2.7Never BuiltWhy not?
1.2.1 Available View build log
1.1.2 Available View build log
1.0.2 Available View build log
Mac OS X (10.5+)
1.2.7 Available View build log
1.2.1 Available View build log
1.1.2 Available View build log
1.0.2 Available View build log
Linux (32-bit)
1.2.4
1.2.7Never BuiltWhy not?
1.2.4 Available View build log
1.2.3 Available View build log
1.2.2 Available View build log
1.2.1 Available View build log
1.1.2 Available View build log
1.0.2 Available View build log
Linux (64-bit)
1.2.7 Available View build log
1.2.4 Available View build log
1.2.3 Available View build log
1.2.2 Available View build log
1.2.1 Available View build log
1.1.2 Available View build log
1.0.2 Available View build log
 
License
GPL2
Lastest release
version 1.2.7 on Jun 4th, 2013

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.

http://onegov.ch/approved.png/image

System Message: WARNING/2 (<string>, line 10)

Explicit markup ends without a blank line; unexpected unindent.
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:

The package is compatible with Plone 4.x.

Installing

Add ftw.pdfgenerator to your buildout configuration:

[instance]

System Message: ERROR/3 (<string>, line 38)

Inconsistent literal block quoting.

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:

System Message: WARNING/2 (<string>, line 54)

Bullet list ends without a blank line; unexpected unindent.

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

System Message: ERROR/3 (<string>, line 94)

Inconsistent literal block quoting.

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">

System Message: ERROR/3 (<string>, line 109)

Inconsistent literal block quoting.

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
>>> 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

System Message: ERROR/3 (<string>, line 179)

Inconsistent literal block quoting.

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}}

System Message: ERROR/3 (<string>, line 194)

Inconsistent literal block quoting.

% 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.

Customizable layouts

When using multiple, independent addon packages using ftw.pdfgenerator, every package may implement a new, specific layout. This can be painful if there is a need to customize all layouts and add a logo image for example.

For making this easier all customizable layouts can be customized with one single adapter. This only works for layouts subclassing ftw.pdfgenerator.layout.customizable.CustomizableLayout. Those layouts need to follow certain concepts and provide inheritable blocks in the mako template. Ensure you follow the standards by subclassing and running the tests from ftw.pdfgenerator.tests.test_customizable_layout.TestCustomizableLayout.

Implementing customization adapter is very simple when customizable layouts are used. For example we change the logo image (assume the logo is at custom/mylogo.png):

>>> from ftw.pdfgenerator.customization import LayoutCustomization
>>> from ftw.pdfgenerator.interfaces import ILayoutCustomization
>>> from zope.interface import implements
>>>
>>> class MyCustomization(LayoutCustomization):

System Message: ERROR/3 (<string>, line 257)

Inconsistent literal block quoting.

... implements(ILayoutCustomization) ... ... template_directories = ['custom'] ... template_name = 'layout_customization.tex' ... ... def before_render_hook(self): ... self.add_raw_template_file('mylogo.png') ... self.layout.use_package('graphicx') ... ... def get_render_arguments(self, args): ... args['logo'] = r'includegraphics{mylogo.png}' ... return args

It is also possible to change the template and fill predefined slots (example: custom/layout_customization.tex):

<%inherit file="original_layout" />
<%block name="documentTop">

System Message: ERROR/3 (<string>, line 277)

Inconsistent literal block quoting.

my branding </%block>

The layout customization adapter adapts context, request and the original layout.

Tables

ftw.pdfgenerator is able to convert HTML-Tables to LaTeX. Since HTML and LaTeX have completely different presentation concepts the convertion is limitted.

For getting the best results theese rules should be followed:

  • Define the width of every column. The table will be streched to the text width in

System Message: WARNING/2 (<string>, line 293)

Bullet list ends without a blank line; unexpected unindent.

the defined proportions. Without defining the widths LaTeX is unable to insert newlines dynamically.

  • Use relative widths (%).
  • Define table headings using <thead> for long tables which may be splitted over

System Message: WARNING/2 (<string>, line 299)

Bullet list ends without a blank line; unexpected unindent.

multiple pages.

CSS classes:

page-break (<table>) Force the longtable environment, allowing LaTeX to split up the table over multiple pages.

no-page-break (<table>) Force the tabular environment, prohibiting LaTeX from splitting the table up over multiple pages. If the table is longer than the page it is truncated - content may be missing in this case.

border-grid / listing (<table>) Display the table in a grid: every cell has a border on every side.

notListed (<table>) When using a <caption>, do not list the table in the list of tables.

border-left (<td>, <th>) Display a border on the left side of the cell.

border-right (<td>, <th>) Display a border on the right side of the cell.

border-top (<td>, <th>) Display a border on the top side of the cell.

border-bottom (<td>, <th>) Display a border on the bottom side of the cell.

right (<td>, <th>) Right align the content of the cell.

left (<td>, <th>) Left align the content of the cell.

center (<td>, <th>) Center the content of the cell.

indent2 (<td>, <th>) Indent the content by 0.2 cm.

indent10 (<td>, <th>) Indent the content by 1 cm.

bold (<td>, <th>) Display cell contents in bold font.

grey (<td>, <th>) Display cell content with grey text color.

footnotesize (<td>, <th>) Display cell content with smaller font size (\footnotesize).

scriptsize (<td>, <th>) Display cell content with smaller font size (\scriptsize).

Changelog

1.2.7 (2013-05-24)
  • Table width calculation: treat "px" the same as widths without measure units.

System Message: WARNING/2 (<string>, line 393)

Bullet list ends without a blank line; unexpected unindent.

[jone]

1.2.6 (2013-04-17)
  • Update package classifiers.

System Message: WARNING/2 (<string>, line 400)

Bullet list ends without a blank line; unexpected unindent.

[jone]

1.2.5 (2013-01-24)
  • Use local text formatting commands, such as textbf instead of {bf }. #13

System Message: WARNING/2 (<string>, line 407)

Bullet list ends without a blank line; unexpected unindent.

[jone]

  • onegov.ch approved: add badge to readme.

System Message: WARNING/2 (<string>, line 410)

Bullet list ends without a blank line; unexpected unindent.

[jone]

  • Declare missing dependencies.

System Message: WARNING/2 (<string>, line 413)

Bullet list ends without a blank line; unexpected unindent.

[jone]

  • Make layout annotatable.

System Message: WARNING/2 (<string>, line 416)

Bullet list ends without a blank line; unexpected unindent.

This allows to store certain informations while building the PDF. [jone]

  • Plone 4.3 compatibility.

System Message: WARNING/2 (<string>, line 420)

Bullet list ends without a blank line; unexpected unindent.

[jone]

1.2.4 (2012-08-21)
  • Tables: fix wrong indentation when using combined css classes

System Message: WARNING/2 (<string>, line 427)

Bullet list ends without a blank line; unexpected unindent.

"right" and "bold". [jone]

  • Tables: support width definition in "style" attribute of cells. #10

System Message: WARNING/2 (<string>, line 431)

Bullet list ends without a blank line; unexpected unindent.

[jone]

  • Fix ampersand escaping in urls. #11

System Message: WARNING/2 (<string>, line 434)

Bullet list ends without a blank line; unexpected unindent.

[jone]

  • Templating: fix template lookup for five based browser views which

System Message: WARNING/2 (<string>, line 437)

Bullet list ends without a blank line; unexpected unindent.

are wrapped into a meta class. [jone]

  • List conversion: handle empty list items.
  • Removing them in ordered and unordered lists.
  • Keep them in definition lists, since two tags result in one item.

[jone]

1.2.3 (2012-06-13)
  • Table converter: fix centering of cell contents by using correct

System Message: WARNING/2 (<string>, line 452)

Bullet list ends without a blank line; unexpected unindent.

LaTeX (centering instead of centervspace{-1.5em}). [jone]

  • Hyperlink:
  • Support resolveUid (with upper U) resolution.
  • Remove "./" from concatenated relative urls.
  • Support hyphenation in urls.

[jone]

1.2.2 (2012-06-11)
  • Improve support for mathematic characters (utf8 and html-entities).

System Message: WARNING/2 (<string>, line 468)

Bullet list ends without a blank line; unexpected unindent.

[jone]

  • Table: support "summary" attribute as caption (TinyMCE support).

System Message: WARNING/2 (<string>, line 471)

Bullet list ends without a blank line; unexpected unindent.

[jone]

  • Handle hyphenation characters and entities.

System Message: WARNING/2 (<string>, line 474)

Bullet list ends without a blank line; unexpected unindent.

[jone]

  • Hyperlinks: handle underscores and hash keys in urls.

System Message: WARNING/2 (<string>, line 477)

Bullet list ends without a blank line; unexpected unindent.

[jone]

  • Fix centering of table captions which used to affect contents beneath.

System Message: WARNING/2 (<string>, line 480)

Bullet list ends without a blank line; unexpected unindent.

[jone]

  • Fix quotation marks around bold text.

System Message: WARNING/2 (<string>, line 483)

Bullet list ends without a blank line; unexpected unindent.

[jone]

1.2.1 (2012-05-10)
  • Table converter: fix TypeError when using colspan without defining any widths.

System Message: WARNING/2 (<string>, line 490)

Bullet list ends without a blank line; unexpected unindent.

[jone]

1.2 (2012-05-09)
  • HTML to LaTeX: escape $ charactor. Otherwise it enables math-mode.

System Message: WARNING/2 (<string>, line 497)

Bullet list ends without a blank line; unexpected unindent.

[jone]

  • Tables: use seperate caption implementation for non-floating environments.

System Message: WARNING/2 (<string>, line 500)

Bullet list ends without a blank line; unexpected unindent.

[jone]

  • Tables: fix border collapse bug when using rowspan.

System Message: WARNING/2 (<string>, line 503)

Bullet list ends without a blank line; unexpected unindent.

[jone]

  • Tables: calculate widths properly respecting tabcolsep.

System Message: WARNING/2 (<string>, line 506)

Bullet list ends without a blank line; unexpected unindent.

[jone]

  • Tables: support plone css classes (grid, listing, vertical).

System Message: WARNING/2 (<string>, line 509)

Bullet list ends without a blank line; unexpected unindent.

[jone]

1.1.2 (2012-05-02)
  • Add convert_plain method to converter and view.

System Message: WARNING/2 (<string>, line 516)

Bullet list ends without a blank line; unexpected unindent.

[phgross]

  • Add encode_htmlentities utils function.

System Message: WARNING/2 (<string>, line 519)

Bullet list ends without a blank line; unexpected unindent.

[phgross]

1.1.1 (2012-04-30)
  • Listing converter: limit nested lists to four levels since LaTeX has this limit.

System Message: WARNING/2 (<string>, line 526)

Bullet list ends without a blank line; unexpected unindent.

[jone]

  • Listing converter: fix bug when nested lists are not within a item.

System Message: WARNING/2 (<string>, line 529)

Bullet list ends without a blank line; unexpected unindent.

[jone]

  • Add provide_request_layer util method to directly provide an interface on the request

System Message: WARNING/2 (<string>, line 532)

Bullet list ends without a blank line; unexpected unindent.

[eschmutz]

1.1 (2012-03-22)
  • Improve testing speed by using ftw.testing.

System Message: WARNING/2 (<string>, line 539)

Bullet list ends without a blank line; unexpected unindent.

[jone]

  • Add table converter css classes:

System Message: WARNING/2 (<string>, line 542)

Bullet list ends without a blank line; unexpected unindent.

indent2 -> indent the content 0.2cm indent10 -> indent the content 1cm bold -> display content with bold font grey -> Display cell content with grey text color. footnotesize -> Display cell content with smaller font size. scriptsize -> Display cell content with smaller font size. [jone]

  • Listing converter: cleanup bad html in case when lists are nested without list items.

System Message: WARNING/2 (<string>, line 551)

Bullet list ends without a blank line; unexpected unindent.

FCKEditor somehow produces that sometimes. [jone]

  • Implement customizable layouts.

System Message: WARNING/2 (<string>, line 555)

Bullet list ends without a blank line; unexpected unindent.

[jone]

1.0.2 (2012-03-08)
  • Table converter: add css classes for aligning cells ("right", "center", "left").

System Message: WARNING/2 (<string>, line 562)

Bullet list ends without a blank line; unexpected unindent.

[jone]

  • Table converter: add cell-border functionality, using css classes "border-right",

System Message: WARNING/2 (<string>, line 565)

Bullet list ends without a blank line; unexpected unindent.

"border-left", "border-top" and "border-bottom". [jone]

  • Table converter: improve grid border, add classes "border-grid" and "listing" for enabling grid borders.

System Message: WARNING/2 (<string>, line 569)

Bullet list ends without a blank line; unexpected unindent.

[jone]

  • Table converter: use "tabular" for small tables. #3

System Message: WARNING/2 (<string>, line 572)

Bullet list ends without a blank line; unexpected unindent.

[jone]

1.0.1 (2012-03-05)
  • Add use_babel function to layout, enabling the preferred language.

System Message: WARNING/2 (<string>, line 579)

Bullet list ends without a blank line; unexpected unindent.

[jone]

1.0b2 (2012-02-28)
  • Added missing MANIFEST.in.

System Message: WARNING/2 (<string>, line 586)

Bullet list ends without a blank line; unexpected unindent.

[phgross]

1.0b1 (2012-02-24)
  • Added a "debug-pdf" view, enabling the pdf debug mode temporarily.

System Message: WARNING/2 (<string>, line 593)

Bullet list ends without a blank line; unexpected unindent.

[jone]

  • Added some French translations

System Message: WARNING/2 (<string>, line 596)

Bullet list ends without a blank line; unexpected unindent.

[ttschanz]

  • Implement hyperlink converter.

System Message: WARNING/2 (<string>, line 599)

Bullet list ends without a blank line; unexpected unindent.

[jone]

  • Implement convertion of definition lists.

System Message: WARNING/2 (<string>, line 602)

Bullet list ends without a blank line; unexpected unindent.

[jone]

  • Rename as_pdf view to export_pdf.

System Message: WARNING/2 (<string>, line 605)

Bullet list ends without a blank line; unexpected unindent.

[jone]

Subscribe to package updates

Last updated Jun 4th, 2013

Download Stats

Last month:1

What does the lock icon mean?

Builds marked with a lock icon are only available via PyPM to users with a current ActivePython Business Edition subscription.

Need custom builds or support?

ActivePython Enterprise Edition guarantees priority access to technical support, indemnification, expert consulting and quality-assured language builds.

Plan on re-distributing ActivePython?

Get re-distribution rights and eliminate legal risks with ActivePython OEM Edition.