README.rdoc

Prawnto (prawnto_2)¶ ↑

<img src=“https://secure.travis-ci.org/forrest/prawnto.png” />

A rails plugin providing templating abilities for generating pdf files leveraging the kick-ass prawn library (prawn.majesticseacreature.com/)

This is my attempt to merge the various forks of the prawnto gem, and update it for Rails 3.1+. I want to thank the many developers who’s code I collected together for the gem. Main credit goes to the developer of the initial Prawnto plugin - smecsia.

I could use some help with the wiki. If you find this helpful, and aren’t up for contributing to the code, I would appreciate some help getting the docs in order.

Note: It has not been tested with earlier versions of Rails.

Installation in Rails 3.1+¶ ↑

In your Gemfile:

gem "prawnto_2", :require => "prawnto"

Then run:

bundle install

Now make a view:

<action name>.pdf.prawn

---

Usage¶ ↑

More Details will be coming to wiki.

As View in Controller¶ ↑

Simply create additional views that end with .pdf.prawn and rails will use the Prawnto template handler to render it properly. The beta has combined the regular .prawn and .prawn_dsl extensions. Now you won’t get tired of typing pdf.method, but instance variables get used. There are a number of options available which are detailed in the wiki (or will be soon).

As Attachment to Email¶ ↑

You can render PDF’s as an attachment to an email very simply with Prawnto.

class PdfEmailer < ActionMailer::Base
  default from: "[email protected]"

  def email_with_attachment
    @var1 = 1
    attachments["hello_world.pdf"] = render("test/default_render", :format => :pdf)
    mail :subject => "Hello", :to => "[email protected]" do |format|
      format.text
    end
  end
end

If you need something more complicated, you may want to consider using the Prawnto::Render.to_string method listed next to create your attachment content.

Gotcha: Something odd happens to the default format handling. You have to include the format block at the bottom, and specify the text, html, etc formats you want included on the body.

From Model (or anywhere else)¶ ↑

Experimental!!! Will be changed

Sometimes you need to be able to render a PDF from anywhere (Background process saving to the File, combining PDFs, etc), but you still want access to your helpers. This feature instantiates the most basic controller, and renders the template to a string for you to use. (more info coming to wiki soon)

class SuperModel
  ...
  def to_pdf
    @x = 1
    Prawnto::ModelRenderer.to_string "test/default_render.pdf", self
  end
end

Gotcha: Rails isn’t always using the correct formatting. If you’re having troubles, add the .pdf to the end of the requested template.

---

Tips & Tricks¶ ↑

Helper methods can be called from within the PDF views. To help keep PDF’s DRY, I would recommend creating a PdfHelper class for complex functionality. Don’t forget to add this helper to your emailer if you generate PDF’s as attachments.

Limited partial support is available. Check out the wiki for details.

Testing¶ ↑

prawnto uses appraisal to run tests for different versions of prawn. In order to run the specs you first need to install the dependencies for each appraisal:

rake appraisal:install

Then you can run the tests for a specifc version of prawn (only 0.12.0 and 0.6.3, but you can add your own version) or all versions:

rake appraisal:prawn0.12.0 spec
rake appraisal:prawn0.6.3 spec
rake appraisal spec # all versions

Contributing & Reporting Issues¶ ↑

Obviously, all code contributions are greatly appreciated. We also need help with testing and the wiki.

While I can’t promise the most speedy response, I do plan to continue to maintain this gem. Please feel free to report any issues, provide feedback, or make suggestions on the Issue Tracker

---

Copyright on Updates - Copyright © 2011 OctopusApp Inc. (getjobber.com), released under the MIT license

Original Copyright - Copyright © 2008 cracklabs.com, released under the MIT license