Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 132 lines (79 sloc) 4.063 kB
85c5eb7 @Whoops Update README to include the :force_download and :filename options
authored
1 = Prawn::Rails
76128a5 @Whoops Update readme file with some useful documentation
authored
2
85c5eb7 @Whoops Update README to include the :force_download and :filename options
authored
3 Prawn::Rails provides a simple way of creating PDF views in Rails 3 using the prawn library.
76128a5 @Whoops Update readme file with some useful documentation
authored
4
85c5eb7 @Whoops Update README to include the :force_download and :filename options
authored
5 To use Prawn::Rails simply add the line
76128a5 @Whoops Update readme file with some useful documentation
authored
6
7 gem 'prawn_rails'
53d2ffc @Whoops Change readme format to rdoc
authored
8
76128a5 @Whoops Update readme file with some useful documentation
authored
9 to your Gemfile and then run
10
11 bundle install
53d2ffc @Whoops Change readme format to rdoc
authored
12
76128a5 @Whoops Update readme file with some useful documentation
authored
13 That's it! You can now create views named
53d2ffc @Whoops Change readme format to rdoc
authored
14
76128a5 @Whoops Update readme file with some useful documentation
authored
15 [action].pdf.prawn
16
17 which will be used whenever the user requests a page with a 'pdf' extension
18
53d2ffc @Whoops Change readme format to rdoc
authored
19 == Usage
76128a5 @Whoops Update readme file with some useful documentation
authored
20
4dcc761 @Whoops add documentation for partials
authored
21 === Basic Usage
22
85c5eb7 @Whoops Update README to include the :force_download and :filename options
authored
23 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.
76128a5 @Whoops Update readme file with some useful documentation
authored
24 For a simple pdf view try:
25
13227dd @Whoops make it clear what are views
authored
26 views/.../simple.pdf.prawn
76128a5 @Whoops Update readme file with some useful documentation
authored
27
53d2ffc @Whoops Change readme format to rdoc
authored
28 prawn_document() do |pdf|
29 pdf.text "Hello World"
30 end
76128a5 @Whoops Update readme file with some useful documentation
authored
31
32 This will create a simple PDF with only the text Hello World.
33
4dcc761 @Whoops add documentation for partials
authored
34 === Partials
35
36 While layouts do not yet work with Prawn::Rails, partials work fine. Rendering a partial is much like in a normal view. For example:
37
38 views/.../partial.pdf.prawn
39
40 prawn_document do |pdf|
41 render "frontpage", :pdf => pdf
42 pdf.text "something else"
43 end
44
45 views/.../_frontpage.pdf.prawn
46
47 pdf.text "frontpage action!!"
48 pdf.start_new_page
49
50 As you might expect this will result in a pdf with a leading page.
51
52 === Instance Variables
53
76128a5 @Whoops Update readme file with some useful documentation
authored
54 Like normal Rails views, instance variables assigned in the controller are made available in the view. For example:
55
56 home_controller.rb
57
53d2ffc @Whoops Change readme format to rdoc
authored
58 class HomeController < ApplicationController
59 def index
60 @people=['Jane','John','Jack']
76128a5 @Whoops Update readme file with some useful documentation
authored
61 end
53d2ffc @Whoops Change readme format to rdoc
authored
62 end
63
13227dd @Whoops make it clear what are views
authored
64 views/.../index.pdf.prawn
76128a5 @Whoops Update readme file with some useful documentation
authored
65
53d2ffc @Whoops Change readme format to rdoc
authored
66 prawn_document(:page_layout => :landscape) do |pdf|
67 @people.each {|person| pdf.text person}
68 end
69
76128a5 @Whoops Update readme file with some useful documentation
authored
70 This will produce a pdf with Jane, John, and Jack all written on seperate lines.
71
4dcc761 @Whoops add documentation for partials
authored
72 === Rendering Options
73
85c5eb7 @Whoops Update README to include the :force_download and :filename options
authored
74 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.
75
76 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:
76128a5 @Whoops Update readme file with some useful documentation
authored
77
13227dd @Whoops make it clear what are views
authored
78 views/.../override.pdf.prawn
53d2ffc @Whoops Change readme format to rdoc
authored
79
80 prawn_document({:renderer => ApplicationHelper::Foo})
81
8cde9fe @Whoops Make it clear which option is not passed to the constructor
authored
82 So for the view above you could have an application helper file that looks like:
76128a5 @Whoops Update readme file with some useful documentation
authored
83
84 application_helper.rb
85
53d2ffc @Whoops Change readme format to rdoc
authored
86 module ApplicationHelper
87 class Foo < Prawn::Document
2bebcbe @huerlisi Add (opts={}) parameter to initialize definition for custom Prawn::Do…
huerlisi authored
88 def initialize(opts={})
53d2ffc @Whoops Change readme format to rdoc
authored
89 super
90 text "Foo"
91 text "Bar"
76128a5 @Whoops Update readme file with some useful documentation
authored
92 end
93 end
53d2ffc @Whoops Change readme format to rdoc
authored
94 end
76128a5 @Whoops Update readme file with some useful documentation
authored
95
96 This would generate a canned report with just the lines Foo and Bar.
97
4dcc761 @Whoops add documentation for partials
authored
98 === Force Saving
99
100 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).
85c5eb7 @Whoops Update README to include the :force_download and :filename options
authored
101 Note: due to problems with the Acrobat Reader plugin, this defaults to true if the :filename option is used.
102
103 views/.../saveas.pdf.prawn
104
105 prawn_document(:force_download=>true) do |pdf|
106 pdf.text "Hello World"
107 end
108
109 The above will cause a 'save as' dialog to appear, even in browsers with a PDF plugin.
110
111 Finally is the :filename option. This allows you to override the default filename to something other than the name of the action.
112 Note: You should include the .pdf extension in the filename. Prawn::Rails will not do this for you.
113
114 views/.../filename.pdf.prawn
115
116 prawn_document(:filename=>'Hello.pdf') do |pdf|
117 pdf.text "Hello World"
118 end
119
120 This will result in the user being promted to download a file named 'Hello.pdf'.
121
53d2ffc @Whoops Change readme format to rdoc
authored
122 == Gotchas
76128a5 @Whoops Update readme file with some useful documentation
authored
123
124 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.
125
53d2ffc @Whoops Change readme format to rdoc
authored
126 == Examples
127
b36428a @Whoops update demo location
authored
128 For examples see: http://prawn-rails-demo.heroku.com
76128a5 @Whoops Update readme file with some useful documentation
authored
129
130
131 Copyright (c) 2010 Walton Hoops, released under the MIT license
Something went wrong with that request. Please try again.