Prawn is the fastest pure Ruby PDF generation library available. It really is pretty cool and takes most of the ouch out of generating print-ready documents.
One common use of generating PDFs in web applications is to provide ‘Reports’ of some kind or another to your customers. Prawn already has fantastic support for putting tables in your documents; but one part that’s currently missing is the ability to natively add graphs and charts to your documents as easily as you can with a table.
Prawn::Graph aims to add this functionality to Prawn by using the native PDF drawing tools Prawn exposes and a friendly single-method call to draw the graph.
The graphs and the values plotted and drawn are all relatively sized within the bounds of the width and height you have set and should scale pretty well to any size of value. Of course, if things do end up looking too squashed, you can always just make your graph bigger.
At the moment, only Bar and Line charts are implemented, with others coming soon. Both charts work in mostly the same way.
All charts take in data, in the form of a 2D Array much like a table, with the only difference that the first entry in the arrays should be that value’s header and the last entry in the array should be the value itself.
The second argument is a Hash of options. The only mandatory option is :at which should be an Array containing the x and y coordinates of the Origin of the Graph.
The other options are:
At the moment only bar_chart and line_chart are implemented. Of course line_graph and bar_graph are perfectly useable aliases.
data = [ ['Column', 20], ['Column 2', 30], ['Column 3', 40] ] Prawn::Document.generate('bar_chart.pdf') do bar_chart data :at => [10, 10] end
And for a bit of déjà vu, here’s how easy it is to make a line chart:
data = [ ['Column', 20], ['Column 2', 30], ['Column 3', 40] ] Prawn::Document.generate('line_chart.pdf') do line_chart data :at => [10, 10] end
A gem of Prawn::Graph has been cut and published and can be installed directly with the usual:
gem install prawn prawn-graph
Then, in your application:
require 'rubygems' require 'prawn/core' require 'prawn/graph' data = [ ['A',12], ['B',11], ['C', 34] ] Prawn::Document.generate('test.pdf') do text 'Graph Example' bar_chart data, :at => [10,10] end
Aside from prawn, Prawn::Graphs has no external dependancies. Everything it needs it provided to it by Prawn and the standard Ruby libraries.
The Prawn::Graphs project lives on GitHub. You can download or fork the code directly from there. If you have any problems, issues / bugs are also being tracked on GitHub so please make sure to report them.
If you would like to get involved in the project (and I strongly encourage any participation!), please feel free to fork and hack away at features / bugs to your heart’s content.
If you think your changes should be part of Prawn::Graphs, the project follows the same procedure as Prawn:
Any sticky points about the Prawn::Graph implementation will be updated in the wiki and marked out in the project’s documentation. If you’d rather speak to a person than read documentation, feel free to email ryan@ryanstenhouse.eu.
If you’re on IRC, you can find me idling in #prawn on irc.freenode.net under the nickname HHRy