• you are running rails 2.2 or 2.1
• you have been git-assimilated
• you've set up a rails app

1. pull in prawnto plugin

   script/plugin install \
     git://github.com/thorny-sun/prawnto.git

3. pull in prawn library

   if you desire stability:

   gem install prawn

   or if you want the latest greatest:

   git submodule add \
     git://github.com:sandal/prawn.git \
     vendor/gems/prawn-0.3.99/

5. set up gem dependency

   insert line into environment.rb at appropriate place

   config.gem "prawn"

   Ideally I could remove this step by getting the plugin to register the dependency on its own, but i couldn't figure out how. Please tell me if you know. init.rb seems to be too late in the initialization process to work.
7. create your view

   give your filename a .pdf.prawn extension and then just code your view using the pdf Prawn::Document object

• format
  Don't forget that by default, rails determines format from the url extension (i.e the .pdf). If you're requesting a url that doesn't have a '.pdf' extension rails will assume a .html.erb extension.
• layouts
  Don't forget to disable where necessary if you don't want them futzing with your '.pdf.prawn' views, unless of course you're using a layout on purpose

If you're a stickler for keeping view stuff in the view, prawn now includes a :skip_page_creation option that can fascilitate this somewhat. To pursue this ideal, you could set prawnto :prawn=>{:skip_page_creation=>true} in the ApplicationController. And then remember to explicitly start a page in the view with pdf.start_new_page(options).

The prawnto plugin gives all controllers access to the prawnto method that controls the prawnto/prawn options. This method is provided as both an instance and a class method to fascilitate complete DRYness. The class method assignment is inherited and can be trumped by child classes just as you would expect, similar to many other rails class level features (layout, filter, etc). And, just as you would expect, the instance method trumps anything specified by the class method.

The prawnto method takes an options hash as its single argument. Prawnto options are specified at the top level, and Prawn::Document options are specified as a subhash under the :prawn key. This is all probably better understood through examples:

Lets say you want all pages created with a particular controller to be landscape and served as attachments, then just invoke prawnto at the controller class level with:

prawnto :prawn=>{:page_layout=>:landscape}, :inline=>false

Lets say that in that same scenario there is one action that should be served inline, then just invoke prawnto within the action to override:

prawnto :inline=>true

Lets say that you know all pages in all controllers will have the same margin, then just specify it in the ApplicationController class:

prawnto :prawn => {
          :left_margin => 48, 
          :right_margin => 48,
          :top_margin => 24,
          :bottom_margin => 24}

Here is the complete list of recognized prawnto options

• :prawn
  the hash passed to the Prawn::Document object. All your normal prawn options are specified here.
• :inline
  controls whether the pdf gets downloaded as an attachment or whether it is viewed inline within the browser. true by default.
• :filename
  filename associated to pdf. defaults to the name given by the url.

If all those pdf.'s in your template are driving you crazy, and you can't be bothered to do a pdf.instance_eval do yourself, then this will do it for you. When you use this extension, the entire template is run inside a pdf.instance_eval. Of course, when you are inside this instance_eval you will lose all access to the view/controller instance variables. To alleviate this issue somewhat, you can assign local variables using the :locals option of the render function. Unfortunately the :locals option is only honored when you use also use the :template option. So you will have to manually specify the template for now. To see this in action just look at the dsl_* prawnto demos.

If you choose to use this alternate template method, just know that it is very brittle, not recommended, and will probably leave you pulling your hair out when it breaks. Having said that, it may save time for those not wanting to convert their ruby prawn files. Simply change the extension on your ruby file that already generates a pdf file to .pdf.prawn_xxx. I'm using .prawn_xxx to serve up all the prawn examples under demos (so I don't have to re-edit them when they change). And it works for all but a couple.