README.rdoc

Prawn::Rails¶ ↑

Prawn::Rails provides a simple way of creating PDF views in Rails 3 using the prawn library.

To use Prawn::Rails simply add the line

gem 'prawn_rails'

to your Gemfile and then run

bundle install

That’s it! You can now create views named

[action].pdf.prawn

which will be used whenever the user requests a page with a ‘pdf’ extension

Usage¶ ↑

Basic Usage¶ ↑

Prawn::Rails is designed to provide only a very thin wrapper around Prawn itself. A Prawn::Rails view should consist of only a call to the function prawn_document and a block. This will create an instance of Prawn::Document and yield it to the block. For a simple pdf view try:

views/…/simple.pdf.prawn

prawn_document() do |pdf|
  pdf.text "Hello World"
end

This will create a simple PDF with only the text Hello World.

Partials¶ ↑

While layouts do not yet work with Prawn::Rails, partials work fine. Rendering a partial is much like in a normal view. For example:

views/…/partial.pdf.prawn

prawn_document do |pdf|
  render "frontpage", :pdf => pdf
  pdf.text "something else"
end

views/…/_frontpage.pdf.prawn

pdf.text "frontpage action!!"
pdf.start_new_page

As you might expect this will result in a pdf with a leading page.

Instance Variables¶ ↑

Like normal Rails views, instance variables assigned in the controller are made available in the view. For example:

home_controller.rb

class HomeController < ApplicationController
  def index
    @people=['Jane','John','Jack']
  end
end

views/…/index.pdf.prawn

prawn_document(:page_layout => :landscape) do |pdf|
  @people.each {|person| pdf.text person}
end

This will produce a pdf with Jane, John, and Jack all written on seperate lines.

Rendering Options¶ ↑

Notice we passed a hash into prawn_document. Any parameters placed in this hash will be passed to the constructor of Prawn::Document, with a few exceptions. The :renderer, :force_download, and :filename options will not be passed on, but instead will be used as described below.

The :renderer option will be removed before creating the document and can be used to override the class to be used for rendering with a subclass of Prawn::Document like so:

views/…/override.pdf.prawn

prawn_document({:renderer => ApplicationHelper::Foo})

So for the view above you could have an application helper file that looks like:

application_helper.rb

module ApplicationHelper
  class Foo < Prawn::Document
    def initialize(opts={})
      super
      text "Foo"
      text "Bar"
    end
  end
end

This would generate a canned report with just the lines Foo and Bar.

Force Saving¶ ↑

The :force_download option makes the browser display a ‘save as’ dialog rather than attempting to display the content in browser (this is achieved by setting the Content-Dispoition header). Note: due to problems with the Acrobat Reader plugin, this defaults to true if the :filename option is used.

views/…/saveas.pdf.prawn

prawn_document(:force_download=>true) do |pdf|
  pdf.text "Hello World"
end

The above will cause a ‘save as’ dialog to appear, even in browsers with a PDF plugin.

Finally is the :filename option. This allows you to override the default filename to something other than the name of the action. Note: You should include the .pdf extension in the filename. Prawn::Rails will not do this for you.

views/…/filename.pdf.prawn

prawn_document(:filename=>'Hello.pdf') do |pdf|
  pdf.text "Hello World"
end

This will result in the user being promted to download a file named ‘Hello.pdf’.

Gotchas¶ ↑

The one major gotcha at this point is that layouts do not work. Do not attempt to make an app/views/layouts/application.pdf.prawn. All your pdf views will quit. This is something I hope to fix in a later release. In the meantime I recommend using custom classes like the one above to achieve a similair effect.

Examples¶ ↑

For examples see: prawn-rails-demo.herokuapp.com

Copyright © 2010 Walton Hoops, released under the MIT license