A plugin for using the prawn library seamlessly with rails
Ruby
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib
rails
.gitignore
MIT-LICENSE
README.rdoc
Rakefile
VERSION
init.rb
prawn_rails.gemspec

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.heroku.com

Copyright © 2010 Walton Hoops, released under the MIT license