Rails Bar Graph Helper Docs

Rails Bar Graph Helper is a helper module for Ruby on Rails that makes producing good-looking CSS-based bar graphs easy.

Current version: 0.2.

Three caveats:

  1. This release only does plain 'ol vertical bar graphs, and not the horizontal or complex bar graphs... yet.
  2. It only does bar graphs and not lines nor pies. For other types check out the Gruff Graphs plugin.
  3. This manual is crap. I hope to improve it as soon as time permits. Apologies.

A graph is made up of six elements: the data to be graphed, as an array. A definition of the graph background, into which the rest of the graph will be drawn. A definition for the bars, describing their appearance. A definition for the bar labels, describing their appearance. A definition for the graph title, an optional text caption, describing its appearance. A definition for the graph legend, describing its appearance.

To create a graph the only required property is the data though you'll probably want to customize your graph to suit your site.

Installation

I don't yet know how to package things for fancy Rails installation so until then: Bar Graphs Helper source code.

It's a Rails module. In my project I stuck it into
app/helpers/bar_graph_helper.rb.
You could copy the source code and do the same.

To integrate this module, add the following to your controller: helper :bar_graph, ie:

PLAIN TEXT
RUBY:
  1. class ApplicationController <ActionController::Base
  2.   helper :bar_graph
  3.   ...
  4. end

Usage

Until I get a chance to write proper instructions, a few examples with source code. Put this code into your views.

Basic Graph

Bar Graph Helper comes with a default set of graph properties so if you just want to get up and running, this is just about the most basic graph you can have:

PLAIN TEXT
RUBY:
  1. <%=
  2. bar_data = [['cat',10],['dog',20],['',30],['dog',40],['cat4',50],['',60],['cat6',70],['dog',80],['cat8',90],['dog',100],['cat10',80],['dog',60],['cat12',40],['dog',20]]
  3.  
  4. bg_properties = { :width => '710px' }
  5.  
  6. bar_graph bar_data, bg_properties
  7. %>

Pass it data and set the width of the background to something that fits the amount of data you have. This produces a graph that looks like:

default graph

Fancy Graph

Getting a little more fancy with the settings:

PLAIN TEXT
RUBY:
  1. <%=
  2. bar_data = [['',10],['',20],['',30],['',40],['',50],['',60],['',42],['',12],['',67],['',33]]
  3.        
  4. bg_properties = { :width => '418px',
  5.     :border => '2px solid #000',
  6.     :background_color => '#edca48' }
  7.  
  8. bar_properties = { :bottom => '-2px',
  9.     :increment => 42,
  10.     :background_color => ['#692dac','#9d538e'],
  11.     :border => '2px solid #000', :top_offset => 2,
  12.     :left_offset => -2 }
  13.  
  14. label_properties = {}
  15.  
  16. title_properties = { :title => 'Stuff vs. Things',
  17.     :font_weight => 'bold',
  18.     :font_style => 'italic' }
  19.        
  20. bar_graph bar_data, bg_properties, bar_properties, label_properties, title_properties
  21.  
  22. %>

Produces this graph:

fancy graph

Full-Featured Graph

In this graph the data is extracted from a databased and then passed to the graphing function:

PLAIN TEXT
RUBY:
  1. bg_properties = { :title => 'Based on naps of twenty minutes or more',
  2.     :width => '100%',
  3.     :height => '200px',
  4.     :background_color => '#fff',
  5.     :border => '1px solid #000',
  6.     :font_family => '"Lucida Grande", Verdana, Arial' }
  7.  
  8. bar_properties = {  :width => '40px',
  9.     :bottom => '30px',
  10.     :color => '#fff',
  11.     :background_color => '#4e9825',
  12.     :text_align => 'center',
  13.     :font_weight => 'bold',
  14.     :padding => '0px',
  15.     :margin => '0px',
  16.     :top_offset => 30,
  17.     :left_offset => 10,
  18.     :increment => 62,
  19.     :border => '2px solid #306d0d' }
  20.  
  21. label_properties = { :h_offset => 8,
  22.     :height => '25px',
  23.     :bottom => '0px',
  24.     :text_align => 'center',
  25.     :font_weight => 'bold',
  26.     :font_size => '0.8em',
  27.     :color => '#000',
  28.     :background_color => '#fff',
  29.     :padding => '0px',
  30.     :margin => '0px' }
  31.        
  32. title_properties = { :title => 'Naps per Day',
  33.     :font_weight => 'bold' }
  34.        
  35. bar_graph bar_data, bg_properties, bar_properties, label_properties, title_properties

Produces this graph, with the tool-tip showing in the screen cap:

tooltip graph

Graph With Legend

PLAIN TEXT
RUBY:
  1. bar_data = [['cat',10],['dog',20],['cat2',30],['dog2',40],['cat3',50],['dog3',60],['cat4',70],['dog4',80],['cat5',90]]
  2.        
  3. bg_properties = { :width => '600px' }
  4. bar_properties = { :color => '#000',
  5.     :background_color => ['#D6FFE0', '#DED4FF'],
  6.     :border_top => '3px solid #000',
  7.     :border_right => '3px solid #000',
  8.     :text_floor => 14 }
  9.  
  10. label_properties = { }
  11.  
  12. title_properties = { :title => 'Dogs vs. Cats: Fight!',
  13.     :text_shadow => '#ccc -3px 5px 5px' }
  14.  
  15. legend_properties = { :data => [['#D6FFE0', 'Cats - meow'], ['#DED4FF', 'Dogs - woof']],
  16.     :font_weight => 'bold',
  17.     :left => '470px',
  18.     :top => "5px" }
  19.        
  20. bar_graph bar_data, bg_properties, bar_properties, label_properties, title_properties, legend_properties

Produces this graph:

legend graph

Some Things to Note

  1. The background colours for bars can be defined either as a string '#ff0000' or as an array of colors ['#ff0000','#0000ff']. When an array of colours is defined, the graph generator will cycle through the colours, painting each bar in the next available colour, wrapping if there are less colours than bars.

Changelog

version 0.2

  • Many more supported CSS properties for graph components, including comprehensive border support (and it is now trivial to add your own CSS property support
  • Support for a graph legend
  • Support for the use of images in the background div of a graph

version 0.1

  • First release, it's all new!

chris on February 16th 2007

7 Responses to “Rails Bar Graph Helper Docs”

  1. Binary Code » Rails Bar Graph Helper 0.2 responded on 16 Feb 2007 at 4:24 pm #

    [...] the docs here or view the source code [...]

  2. Shane Zadrozny responded on 07 Aug 2007 at 8:56 am #

    Hi,
    This looks like a great little helper….
    … I pasted the code in to the bar_graph_help.rb file as suggested but things dont go according to plan…

    An error is highlighted in the line after html=”style”.

    When the helper :bar_graph is added to a controller a rails application error results.

    I was wondering if the code is presented correctly on the site?

    Best Regards,

    Shane

  3. chris responded on 07 Aug 2007 at 9:56 pm #

    The phrase “html=”style”" doesn’t appear in my code anywhere, so where does that come from? Perhaps you could post the error you’re getting or just email me directly with your code and I’ll take a look.

  4. ferrisoxide responded on 11 Aug 2007 at 3:05 pm #

    Hi Chris

    I think Shane is pointing to line 11, where the ‘”
    11: html

  5. ferrisoxide responded on 11 Aug 2007 at 3:16 pm #

    Hey Chris

    Hmm.. I think WordPress is munging comments in interesting ways. Trying again.

    The simplified version of what I said is - Shane is right, there is a problem from about line 11 on. Putting spaces on either side of the

  6. chris responded on 11 Aug 2007 at 3:24 pm #

    I’m not too sure what’s causing the problem you’re having so to simplify things I’ve uploaded the bar_graph_helper.rb file I’m using in my current Rails project here:

    http://www.postal-code.com/binarycode/wp-content/uploads/bar_graph_helper.rb

    You should be able to grab that verbatim and use it, see if that helps. Let me know how it goes.

  7. Shane Zadrozny responded on 14 Sep 2007 at 4:01 am #

    Chris,
    Thanks for the postings - chris and ferrisoxide.
    Appologies for the delay, I have been working away.
    I will try the uploaded .rb file and post my findings later..
    TTFN,
    Shane

Trackback URI | Comments RSS

Leave a Reply