Prawn::Graph - Easy Graphing for Prawn

Gem Version License Code Climate Test Coverage Build Status security

An extension for the prawn pdf library which adds the ability to draw graphs (or charts if you perfer) in PDF documents.

If you're looking for the current stable released version of prawn-graph (0.0.4) - check out the stable branch. Just remmeber that this is not supported by the latest version of prawn and probably shouldn't be used.

Because Prawn::Graph only uses the native PDF drawing functions exposed by Prawn, it removes the need to depend on projects like Gruff to generate heavy PNG / JPG images of such graphs and charts and then include those large blobs in your documents. The results may not be as pretty (yet), but the file-size differences are dramatic.

By default, graphs are drawn in monochrome, as that's likely how they will be printed.

This is free and open source software released under ther terms of the MIT Licence.

Its copyright is held by Ryan Stenhouse and the other contributors and it was first released in 2010.

Compatibility

The gem is only tested against Ruby version 2.0 and greater. Older Ruby versions may work but are not officially supported. We aim for compatibilty with 1.x and 2.x series of prawn. Any incomaptibilities should be treated as bugs and added to the issue tracker.

Unlike previous version of prawn-graph, this version does not at this time include a theme api or the ability to change the colors used to render the graph.

IMPORTANT - READ THIS BEFORE USING

prawn-graph is currently being rewritten to have its internal components replaced with new, properly test-driven bits of code to draw the various cool graphs and charts that people would like to use in their PDFs.

Right now, the "legacy" drawing code is what is ultimately being used to render any graphs being generated. The newness instead is that project is compatible with all modern versions of prawn and therefore are useful again.

This means that for now any existing rendering bugs still remain. If you find any, please be a good citizen and report them.

To use prawn-graph with these caveats, you can add the following to your Gemfile:

 gem 'prawn-graph', '1.0.0.pre1'

Alternatively, you can use Rubygems directly: gem install prawn-graph --pre.

Acknowledgements

With thanks to 株式会社アルム (Allm Inc) for allowing Ryan Stenhouse the time to rebuild this version of prawn-graph. This updated version of prawn-graph was inspired and guided by prawn-svg by Roger Nesbitt. It also uses some of prawn-svg's document size calculation code.

Prawn Graph was originally sponsored by and built for use at Purchasing Card Consultancy Ltd while Ryan Stenhouse was employed there.

Supported graph / chart types

This version of Prawn::Graph supports the following graph / chart types:

  • Bar Charts
  • Line Charts

Is your favourite chart type not supported yet? Please request it, or if you are feeling particularly adventurous - please add it!

Using prawn-graph

  require 'prawn-graph'

  data = [ ['A', 10], ['B', 11], ['C', 12] ]

  Prawn::Document.generate('test.pdf') do
    text 'Graph Example'
    bar_graph data
  end

When called with just a set of data, prawn-graph will do its best to make the graph fit in the available space. For a little more control over how the graphs are rendered in the document you can pass the following options:

Option Data type Description
:at [integer, integer] Specify the location on the page you want the graph to appear.
:width integer Desired width of the graph. Defaults to horizontal space available.
:height integer Desired height of the graph. Defaults to vertical space available.

Example

  require 'prawn-graph'

  data = [ ['A', 10], ['B', 11], ['C', 12] ]

  Prawn::Document.generate('test.pdf') do
    text 'Graph Example'
    bar_graph data, at: [10,20], width: 200
  end

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.