In my current Rails projects (
Gradesheet &
MynaStuff) I have the need to create reports as PDFs. Prawn is a relatively new library that does just what I need in pure Ruby. There are a couple of really good tutorials on how to integrate Prawn into your Rails project on the web but I wanted to do something a little different. There's even a plugin (
PrawnTo) that makes Prawn look like a native Rails construct and allows you build PDFs without leaving your views. Neat!
However, this is not really how I wanted to implement reporting in my applications. So I created a directory in lib and filled it with self-contained reports. In my view, this makes reports easier to build and maintain. Let's get started. First, you need a Rails project.
strutter$ rails HelloPrawn
create
create app/controllers
...
create log/server.log
create log/production.log
create log/development.log
create log/test.log
Now, we need to get the Prawn & Prawn-layout plugins. Since they are pretty new and constantly changing I like to get the latest version straight from GitHub. Just clone them in the usual way. Note that you have to get a couple of subcollections when you get Prawn this way.
$cd vendor/plugins
$git clone git://github.com/sandal/prawn.git
Initialized empty Git repository in /Rails/HelloPrawn/vendor/plugins/prawn/.git/
remote: Counting objects: 6716, done.
remote: Compressing objects: 100% (2762/2762), done.
Receiving objects: 21% (1459/6716), 6.31 MiB | 220 KiB/s
...
$git clone git://github.com/sandal/prawn-layout.git
Initialized empty Git repository in /Rails/HelloPrawn/vendor/plugins/prawn-layout/.git/
remote: Counting objects: 271, done.
remote: Compressing objects: 100% (232/232), done.
remote: Total 271 (delta 111), reused 0 (delta 0)
...
Since we are running Prawn from Git we have to do a couple of extra things.
$cd vendor/plugins/prawn
$git submodule init
Submodule 'vendor/pdf-inspector' (git://github.com/sandal/pdf-inspector.git) registered for path 'vendor/pdf-inspector'
Submodule 'vendor/ttfunk' (git://github.com/sandal/ttfunk.git) registered for path 'vendor/ttfunk'
$git submodule update
Initialized empty Git repository in /Users/richardhurt/Rails/HelloPrawn/vendor/plugins/prawn/vendor/pdf-inspector/.git/
remote: Counting objects: 16, done.
remote: Compressing objects: 100% (14/14), done.
...
Now we have to tell Rails to load Prawn-layout as well as Prawn. I do this with a simple initializer.
# config/initializers/prawn.rb
require "prawn/core"
require "prawn/layout"
Next we'll create a report. First build a new directory to hold all your reports.
mkdir lib/reports
Then add this new path to your Rails load_path. Look for the following section in you config/environment.rb file and make it look similar to this.
# Add additional load paths for your own custom dirs config.load_paths += %W({RAILS_ROOT}/extras )
config.load_paths += %W( #{RAILS_ROOT}/lib/reports )
and add a new PDF mime type.
#config/initializers/mime_types.rb
Mime::Type.register_alias "application/pdf", :pdf
Now that most of the setup is out of the way we're ready to get to work. Let's create a simple report and then show the controller that goes along with it. This report doesn't do much but it shows the basics.
# lib/reports/hello_prawn.rb
class HelloPrawn
# Build the parameter screen for this report.
def self.get_params()
# This report has no parameters
end
# Build the report in PDF form and sent it to the users browser
def self.draw(params)
# Create a new document
pdf = Prawn::Document.new(:page => "LETTER")
# Make it so we don't have to use pdf. everywhere. :)
pdf.instance_eval do
# Print something
text "Hello Prawn", :align => :center, :size => 20
# Render the page and send it back to the controller
render
end
end
end
Finally we'll build a controller to either build the parameter screen or render the PDF itself.
class ReportsController < ApplicationController
def show
# Since we are building the report object on the fly we need to make sure
# that it is a valid report before we try to build/show it.
begin
# Try to make the report into an 'object'
@report = params[:id].classify.constantize
rescue NameError
# This is not a valid report or some other error happened
flash[:error] = "Unknown Report '#{params[:id]}'"
redirect_to :action => :index
else
respond_to do |format|
format.html do
# display the parameters screen
end
format.pdf do
# Send the PDF back to the browser for viewing
send_data @report.draw(params),
:filename => params[:id].titleize + '.pdf',
:type => 'application/pdf',
:disposition => 'inline'
end
end
end
end
end
Lets test it out. Start up your Rails server and go to
http://localhost:3000/reports/hello_prawn.pdf and you should get an inline PDF report in return. The cool thing about this is that each report can generate its own parameters screen on demand. See that self.get_params() function up in the report? That's where you can put your ERB stuff and have it render when you hit
http://localhost:3000/reports/hello_prawn. Neato!
def self.get_params()
# Get the homeroom information
homerooms = Student.find_homerooms()
# Build the parameter screen
params = <<-EOS
EOS
Posts
