Googlecharts

Get Version

1.3.4

→ ‘Sexy Charts using Google API & Ruby’

What

A nice and simple wrapper for Google Chart API (Fully tested using RSpec, check the specs for more usage examples)

Installing

This project is now hosted at GitHub If you never added GitHub as a gem source, you will need to do the following:

$ gem sources -a http://gems.github.com/
(you only need to do this once)

$ sudo gem install mattetti-googlecharts

or

$ sudo gem install googlecharts

The basics

This gem supports the following types of charts:

Line Gchart.line()

line_xy Gchart.line_xy()

scatter Gchart.scatter()

bar Gchart.bar()

venn Gchart.venn()

pie Gchart.pie()

pie_3d Gchart.pie_3d()

sparklineGchart.sparkline()

google-o-meter Gchart.meter()

Demonstration of usage

install:

sudo gem install mattetti-googlecharts

or use rubyforge:

sudo gem install googlecharts

require:

require 'gchart'

Gchart.line(:size => '200x300', 
            :title => "example title",
            :bg => 'efefef',
            :legend => ['first data set label', 'second data set label'],
            :data => [10, 30, 120, 45, 72])


simple line chart

Gchart.line(:data => [0, 40, 10, 70, 20])

Generate the following url: http://chart.apis.google.com/chart?chs=300×200&chd=s:AiI9R&cht=lc

Inserted in an image tag, it will look like that:

simple line chart

multiple line charts

Gchart.line(:data => [[0, 40, 10, 70, 20],[41, 10, 80, 50]])

multiple lines chart

set line colors

Gchart.line(:data => [[0, 40, 10, 70, 20],[41, 10, 80, 50]], :line_colors => "FF0000,00FF00")

line colors

more info about color settings

sparkline chart

data = [27,25,25,25,25,27,100,31,25,36,25,25,39,25,31,25,25,25,26,26,25,25,28,25,25,100,28,27,31,25,27,27,29,25,27,26,26,25,26,26,35,33,34,25,26,25,36,25,26,37,33,33,37,37,39,25,25,25,25]
Gchart.sparkline(:data => data, :size => '120x40', :line_colors => '0077CC')

sparline

A sparkline chart has exactly the same parameters as a line chart. The only difference is that the axes lines are not drawn for sparklines by default.

bar chart

Gchart.bar(:data => [300, 100, 30, 200])
bars

set the bar chart orientation

Gchart.bar(:data => [300, 100, 30, 200], :orientation => 'horizontal')
bars

multiple bars chart

Gchart.bar(:data => [[300, 100, 30, 200], [100, 200, 300, 10]])

stacked multiple bars

The problem is that by default the bars are stacked, so we need to set the colors:

Gchart.bar(:data => [[300, 100, 30, 200], [100, 200, 300, 10]], :bar_colors => 'FF0000,00FF00')

If you prefer you can use this other syntax:

Gchart.bar(:data => [[300, 100, 30, 200], [100, 200, 300, 10]], :bar_colors => ['FF0000', '00FF00'])

colors

The problem now, is that we can’t see the first value of the second dataset since it’s lower than the first value of the first dataset. Let’s unstack the bars:

Gchart.bar(:data => [[300, 100, 30, 200], [100, 200, 300, 10]], 
           :bar_colors => 'FF0000,00FF00',
           :stacked => false )

grouped bars

bar chart width and spacing

A bar chart can accept options to set the width of the bars, spacing between bars and spacing between bar groups. To set these, you can either provide a string, array or hash.

The Google API sets these options in the order of width, spacing, and group spacing, with both spacing values being optional. So, if you provide a string or array, provide them in that order:

Gchart.bar(:data => @data, :bar_width_and_spacing => '25,6') # width of 25, spacing of 6
Gchart.bar(:data => @data, :bar_width_and_spacing => '25,6,12') # width of 25, spacing of 6, group spacing of 12
Gchart.bar(:data => @data, :bar_width_and_spacing => [25,6]) # width of 25, spacing of 6
Gchart.bar(:data => @data, :bar_width_and_spacing => 25) # width of 25

The hash lets you set these values directly, with the Google default values set for any options you don’t include:

Gchart.bar(:data => @data, :bar_width_and_spacing => {:width => 19})
Gchart.bar(:data => @data, :bar_width_and_spacing => {:spacing => 10, :group_spacing => 12})

pie chart

Gchart.pie(:data => [20, 35, 45])
Pie Chart

3D pie chart

Gchart.pie_3d(:data => [20, 35, 45])
Pie Chart

venn diagram

Google documentation

Data set:

Gchart.venn(:data => [100, 80, 60, 30, 30, 30, 10])
Venn

scatter plot

Google Documentation

Supply two data sets, the first data set specifies x coordinates, the second set specifies y coordinates, the third set the data point size.

Gchart.scatter(:data => [[1, 2, 3, 4, 5], [1, 2, 3, 4 ,5], [5, 4, 3, 2, 1]])

scatter

google-o-meter

Google Documentation

Supply a single label that will be what the arrow points to. It only supports a solid fill for the background.

Gchart.meter(:data => [70], :label => ['Flavor'])


set a chart title

Gchart.bar(:title => "Recent Chart Sexyness", :data => [15, 30, 10, 20, 100, 20, 40, 100])

chart title

set the title size

Gchart.bar(:title => "Recent Chart Sexyness", :title_size => 20, :data => [15, 30, 10, 20, 100, 20, 40, 100])

title size

set the title color

Gchart.bar(:title => "Recent Chart Sexyness", :title_color => 'FF0000', :data => [15, 30, 10, 20, 100, 20, 40, 100])

Title color

set the chart’s size

Gchart.bar(:title => "Recent Chart Sexyness", 
           :data => [15, 30, 10, 20, 100, 20, 40, 100],
           :size => '600x400')

size

set the image background color

Gchart.bar(:title => "Matt's Mojo", 
           :data => [15, 30, 10, 20, 100, 20, 40, 100, 90, 100, 80],
           :background => 'FF9994')

Background

set the chart background color

Gchart.bar(:title => "Matt's Mojo", 
           :data => [15, 30, 10, 20, 100, 20, 40, 100, 90, 100, 80],
           :background => 'FF9994', :chart_background => '000000')

chart background

Set bar/line colors

Gchart.bar(:title => "Matt's Mojo", 
           :data => [15, 30, 10, 20, 100, 20, 40, 100, 90, 100, 80],
           :bar_colors => '76A4FB',
           :background => 'EEEEEE', :chart_background => 'CCCCCC')

bar colors

Gchart.line(:title => "Matt's Mojo", 
            :data => [15, 30, 10, 20, 100, 20, 40, 100, 90, 100, 80],
            :line_colors => '76A4FB')

line colors

legend / labels

Gchart.bar(:title => "Matt vs Rob",
           :data => [[300, 100, 30, 200], [100, 200, 300, 10]], 
           :bar_colors => 'FF0000,00FF00',
           :stacked => false, :size => '400x200',
           :legend => ["Matt's Mojo", "Rob's Mojo"] )
legend

Gchart.line(:title => "Matt vs Rob",
            :data => [[300, 100, 30, 200], [100, 200, 300, 10]], 
            :bar_colors => ['FF0000','00FF00'],
            :stacked => false, :size => '400x200',
            :legend => ["Matt's Mojo", "Rob's Mojo"] )
line legend

Gchart.pie_3d(:title => 'ruby_fu', :size => '400x200',
              :data => [10, 45, 45], :labels => ["DHH", "Rob", "Matt"] )

labels

Display axis labels

Gchart.line(:data => [300, 100, 30, 200, 100, 200, 300, 10], :axis_with_labels => 'x,y,r')

or you can use the other syntax:

Gchart.line(:data => [300, 100, 30, 200, 100, 200, 300, 10], :axis_with_labels => ['x','y','r'])

axis with labels

Gchart.line(:data => [300, 100, 30, 200, 100, 200, 300, 10], :axis_with_labels => 'x',
            :axis_labels => ['Jan|July|Jan|July|Jan'])

or you can use the other syntax:

Gchart.line(:data => [300, 100, 30, 200, 100, 200, 300, 10], :axis_with_labels => 'x',
            :axis_labels => ['Jan','July','Jan','July','Jan'])

x labels

multiple axis labels

Gchart.line(:data => [300, 100, 30, 200, 100, 200, 300, 10], :axis_with_labels => 'x,r',
            :axis_labels => ['Jan|July|Jan|July|Jan', '2005|2006|2007'])

or

Gchart.line(:data => [300, 100, 30, 200, 100, 200, 300, 10], :axis_with_labels => 'x,r',
            :axis_labels => [['Jan','July','Jan','July','Jan'], ['2005','2006','2007']])

multiple axis labels

(This syntax will probably be improved in the future)

custom params

I certainly didn’t cover the entire API, if you want to add your own params:

Gchart.line(:custom => 'chd=s:93zyvneTTOMJMLIJFHEAECFJGHDBFCFIERcgnpy45879,IJKNUWUWYdnswz047977315533zy1246872tnkgcaZQONHCECAAAAEII&chls=3,6,3|1,1,0')

Custom


Save the chart as a file

You might prefer to save the chart instead of using the url, not a problem:

Gchart.line(:data => [0, 26], :format => 'file')

You might want to specify the path and/or the filename used to save your chart:

Gchart.line(:data => [0, 26], :format => 'file', :filename => 'custom_filename.png')

Insert as an image tag

Because, I’m lazy, you can generate a full image tag, with support for the standard html options.

Gchart.line(:data => [0, 26], :format => 'image_tag')

<img src="http://chart.apis.google.com/chart?chs=300x200&chd=s:A9&cht=lc" width="300" height="200" alt="Google Chart" />

Here are a few more examples:

Gchart.line(:data => [0, 26], :format => 'image_tag')
Gchart.line(:data => [0, 26], :format => 'image_tag', :id => "sexy")
Gchart.line(:data => [0, 26], :format => 'image_tag', :class => "chart")
Gchart.line(:data => [0, 26], :format => 'image_tag', :alt => "Sexy Chart")
Gchart.line(:data => [0, 26], :format => 'image_tag', :title => "Sexy Chart")

Image dimensions will be automatically set based on your chart’s size.


Encoding

Google Chart API offers 3 types of data encoding

By default this library uses the simple encoding, if you need a different type of encoding, you can change it really easily:

default / simple: chd=s:9UGoUo9C

  Gchart.line(:data => [300, 100, 30, 200, 100, 200, 300, 10] )

extended: chd=e:..VVGZqqVVqq..CI

Gchart.line(:data => [300, 100, 30, 200, 100, 200, 300, 10], :encoding => 'extended' )

text: chd=t:300,100,30,200,100,200,300,10

Gchart.line(:data => [300, 100, 30, 200, 100, 200, 300, 10], :encoding => 'text' )

(note that the text encoding doesn’t use a max value and therefore should be under 100)

Max value

Simple and extended encoding support the max value option.

The max value option is a simple way of scaling your graph. The data is converted in chart value with the highest chart value being the highest point on the graph. By default, the calculation is done for you. However you can specify your own maximum or not use a maximum at all.

Gchart.line(:data => [300, 100, 30, 200, 100, 200, 300, 10] )

Title

Gchart.line(:data => [300, 100, 30, 200, 100, 200, 300, 10], :max_value => 500 )

max 500

Gchart.line(:data => [100, 20, 30, 20, 10, 14, 30, 10], :max_value => false )

real size

Repository

The trunk repository is http://github.com/mattetti/googlecharts/ for anonymous access.

People reported using this gem

github
  • http://github.com

  • stafftool
  • Takeo(contributor)

  • graffletopia
  • http://graffletopia.com Mokolabs(contributor)

  • gumgum
  • http://gumgum.com Mattetti(contributor)

  • gumgum
  • http://feedflix.com/

  • License

    This code is free to use under the terms of the MIT license.

    Contact

    Comments are welcome. Send an email to Matt Aimonetti

    Contributors

    David Grandinetti Toby Sterrett Patrick Crowley

    Matt Aimonetti, 26th June 2008
    Theme extended from Paul Battley