Ryan Stenhouse, Writes and Codes - Prawn::Graph

Prawn::Graph - Simple Graphing for Prawn

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.

Drawing a Chart

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:

:width The width of the grid to be drawn, default is 500 points.
:height The height of the grid to be drawn, default is 200 points.
:spacing The amount of space between each square of the grid being drawn, default is 20 points.
:theme The theme you would like to use, defaults to Prawn::Chart::Themes.monochrome. See Themes below for more details.

At the moment only bar_chart and line_chart are implemented. Of course line_graph and bar_graph are perfectly useable aliases.

Simplest Bar Char Example

  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:

Simplest Line Chart Example

  data =    [
                ['Column', 20],
                ['Column 2', 30],
                ['Column 3', 40]
            ]

  Prawn::Document.generate('line_chart.pdf') do
    line_chart data :at => [10, 10]
  end

Installing Prawn::Graph

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

External Requirements

Aside from prawn, Prawn::Graphs has no external dependancies. Everything it needs it provided to it by Prawn and the standard Ruby libraries.

Getting the Code & Hacking

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:

Fork the prawn-graph repo
Make your changes
Update or Update an issue summarising your changes
Send HHRy a pull request

Support / Help

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