-
Notifications
You must be signed in to change notification settings - Fork 101
Scavenged from Google’s cache of cracklabs.com/prawnto/use
-
Initial Assumptions / Requirements
- you are running rails 2.2 or 2.1
- you have been git-assimilated
- you’ve set up a rails app
-
Getting Started
-
pull in prawnto plugin
script/plugin install \ git://github.com/thorny-sun/prawnto.git
-
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/
-
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. -
create your view
give your filename a .pdf.prawn extension and then just code your view using the pdf Prawn::Document object
-
-
Gotchyas
-
formatDon’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.
-
layoutsDon’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
-
-
View/Controller Boundary
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).
-
prawnto Method
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-
:prawnthe hash passed to the Prawn::Document object. All your normal prawn options are specified here.
-
:inlinecontrols whether the pdf gets downloaded as an attachment or whether it is viewed inline within the browser. true by default.
-
:filenamefilename associated to pdf. defaults to the name given by the url.
-
-
.prawn_dsl
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.
-
.prawn_xxx experimental
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.