Skip to content
edgerunner edited this page Sep 12, 2010 · 1 revision

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
    1. pull in prawnto plugin
      script/plugin install \
      git://github.com/thorny-sun/prawnto.git
    2. 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/
    3. 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.
    4. create your view

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

  • Gotchyas
    • 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
  • 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

    • :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.
  • .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.

Clone this wiki locally