John McCaffrey

Rails PDF Generation

What we’re going to cover

Agenda★ PDF Types and Libraries★ Prawn★ General PDF Testing★ Advanced Prawn examples★ Prawn-to★ Q&A

Intro:after_me

John McCaffreyPresented at WindyCityRails 08

Using Prawn since 10/08

http://www.pathf.com/blogs/author/john-mccaffrey/

And you are?:include => :first_name

Col 1 Col 2 Col 3 Col 4

Why users Love PDFs

They are great for:★ Reports★ Static data★ Forms★ Invoices★ Tightly controlled formatting★ Print friendly★ Portable★ Looks the same for everyone

PDF types and libraries

PDF Library types

•HTML to PDF•PDF Template binding•Dynamic

What type should I use?

★ What is the content? (tax form, invoice, eBook, product list) ★ How large will the files be?★ How complex is the formatting?★ Do they need to be generated ‘on demand’, or would it be a

batch or background job?★ Do you mind calling out to a library or command line tool?★ Character encoding, utf-8, internationalization, etc★ Who will be in charge of maintaining them? (developer or

designer?)

Use HTML to PDF if..

★ You already have an html view that is structured the way you want it.

★ You don’t want to mess with any ‘pdf syntax’★ Don’t mind requiring a native library, or command line

invocation.★ Don’t mind the licensing agreements or cost of commercial

tools★ Your team skill set is more aligned with HTML/CSS

HTML to PDF Libraries

PrinceXML★ Best in class html to pdf. Passes Acid2 test★ Princely ruby wrapper ★ Commercial: $3800 server license

HTMLDOC★ Has been around for awhile★ Supports a subset of html (no css, no xhtml or html 4.0)★ Supports basic UTF-8/Unicode for ‘western’ languages

wkhtmltopdf★ Based on WebKit rendering engine★ Might be some issues in different OSes (windows)★ Relatively new library

Use PDF Templates if..

★ The document is a form to be filled in (text fields, checkboxes, etc)

★ The structure is mostly static★ The document is very large★ The formatting is complex★ You don’t mind calling out to a library

PDF Template binding

pdftk★ Build document with any tool that can output as pdf★ Add in the form fields with Acrobat editor★ Bind fdf data against pdf template★ Very powerful pdf manipulation features

iText★ Java library★ Very powerful★ Well known with lots of examples/tutorials, and books★ Can also merge/split pdf files, add watermarks, etc

Pdf Form Binding example

Use PDF Generation if..

★ The content/structure is dynamic★ The document is not too large★ The formatting is not too complex★ You prefer a pure ruby library★ You prefer an open source solution

PDF Generation Libraries

JasperReports★ Well known java library, multiple outputs★ May complicate dev/deployment dependencies

PDF::WRITER★ Pure Ruby. Has been around for awhile★ Many examples out there★ Powerful, but ‘tedious’ syntax for positioning, styling, etc

Prawn★ Lightweight, easy to learn syntax★ Newer library, still in alpha, but very promising ★ Faster than PDF::Writer★ Continues to get faster and better

I chose Prawn

Because…★ Lots of clear examples★ Worked well for the report style that I needed (dynamic

structure, simple table-based layout)★ Quick to generate pdfs on demand★ Fastest pure ruby pdf tool out there★ Code was well tested and easy to follow★ Forum/mailing list was active and helpful

Prawn history

Gregory Brown★ Mendicant project, raised $10k to work on open-source

projects★ Goal was to improve report and pdf generation for ruby★ Ruport reporting framework (multiple report types)★ Prawn★ Just released Ruby Best Practices book

Prawn 101

What it can’t do★ Complex formatting, nested tables★ Edit existing pdfs★ Encryption/security (coming soon – 9/15)

What it can do★ Very easy to learn syntax★ Easy Image embedding★ Easy to manage table-based layouts★ Simplified positioning commands

Prawn examples

Examples

Install★ Gem install prawn ★ Or git clone git://github.com/sandal/prawn.git ★ Make sure the tests pass

• May have to install another submodule or two

Examples

Methods★ PDF★ Text★ Bounding_box★ Font★ Move_down★ Mask★ Page★ Image★ Stroke

Examples

Basic syntax examples★Text★Images★Overflow★Orientation

Text & Image

Text_image_sample

Text overflow

Text_overflow_sample

Page Orientation

orientation sample

Examples

Intermediate★ Table★ Utf-8★ Drawing★ Bounding box

Install★ Gem install prawn-layout

Tables

table sample

Utf-8

UTF-8 sample

Drawing & bounding_box

bounding

Prawn Performance

Numbers★ Around 20 times faster than PDF::Writer★ Even faster on ruby 1.9★ Well designed (seems to scale linearly)★ Images are only loaded once

PDF TESTING

How do I test a PDF?

Tools★ Basic file and attachment testing★ PDF::Reader★ PDF::Inspector★ Oragami library★ Convert to Image and do a bit diff

How do I test a PDF?

Poor-man techniques★ Nothing blew up★ File is present★ Mocks were invoked as expected★ Generate your pdfs and look at them

PDF toolkits★ Assert page size★ Open PDF and read its contents★ Grep for objects★ Assert order of objects

Testing PDF structure

Testing PDF contents

Prawn-to

Prawn in your view

All the good stuff★ script/plugin install git://github.com/thorny-sun/prawnto.git ★ Render pdf template with .pdf.prawn extension★ DRY up common pdf configuration settings★ Access to helpers (useful for currency, dates, text)

Prawn-to: controller

Prawn-to: view

Prawn-to sample

Advanced Prawnwith_reckless_abandon

Advanced examples

What else can we do?★ Grid based layout★ Labels & Calendars★ Annotations & Links★ Google charts

Grid Layout

Grid sample

Grids & Labels

Labels sample

Google Charts api

Charts sample

Prawn-FormatNice and easy, just got nicer, and easier

Prawn-format

Use HTML and style syntax ★ Basic tags★ Alter existing styles★ Create new styles★ Links

Prawn-format: html and style

Format

Putting it all together

Mash up ★ Prawn, prawn-layout★ Prawn-to★ Prawn-format★ Google charts api ★ Twitter- search★ Heroku & git

Twitter_Timelines

More to come

Roadmap & projects ★ Security & encryption (prawn-security)★ Prawn-js★ Clean up ★ Improved grid/table support★ Improved docs and examples

Questions?

speakerrate.com/jmccaffrey

Links

Prawn: prawn.majesticseacreature.com/

Prawn-to: cracklabs.com/prawnto

Google Charts: chart.apis.google.com/

Twitter-Search: github.com/dancroak/twitter-search

Blog: http://www.pathf.com/blogs/author/john-mccaffrey/

PDF Generation in Rails

John McCaffrey