Last time, in our ‘do it in less than 5 minutes’ series, we saw how to add quickly and simply add Ajax pagination.

This time we’ll see how to add some sexy/fancy charts to your rails app.

The goal is to end up with something like:

Various options

You might have heard or even tried solution such as Gruff or JFreeChart.

While these solutions are great, they are certainly a pain in the butt. Gruff requires RMagick (avoid RMagick as much as can) and creates static files (a real pain when your graphs change all the time) JFreeChart on the other hand requires Java, Java skills and I hate the way you create graphs:

1
2
3
4
5

  def CreateChart
         pipe = IO.popen "java -cp C:\\InstantRails\\rails_apps\\project\\jfree\\src;C:\\InstantRails\\rails_apps\\project\\jfree\\lib\\jcommon-1.0.0-rc1.jar;C:\\InstantRails\\rails_apps\\project\\jfree\\lib\\jfreechart-1.0.0-rc1.jar; CreateChart" 
         pipe.close
         redirect_to "/graph/report" 
      end

Anyway, none of these solutions would let us create our charts in less than 5 minutes so let’s cut the story short. The best solution IMHO is to use Flash. But wait, you don’t need to know ActionScript or to own a license of Flash or Flex, we have libraries available for us to use without any Flash knowledge

XML/SWF is cool Flash library which should fulfill our needs, you can even find a rails plugin to make things easier.

amCharts

But, to be honest I’d like to have something a bit “cleaner/sexy/fancy” and easier to setup. So we’re going to use amCharts Don’t get me wrong, XML/SWF is a great library and you can make your graphs look nice (but you have to pay for support).
Since we are running out of time let’s see how to implement a nice graph using *my* favorite library.

[DISCLAIMER: amCharts is NOT open source and NOT free. But, it's cheap (85 euros per site) especially when you think of how much time you will save. AND there is a FREE version. The Free version is the same as the full version but with a link back to amcharts.com]

Setup

Let’s go ahead and download one of the package: http://www.amcharts.com/column/download/ for instance.

Unpack the files and put them in their own folder in your public folder.
Make sure you have the .swf file (amcolumn.swf for instance), a XML settings file and the fonts folder.
(You might want to also create an empty amcharts_key.txt in the same folder since the plugin tries to load the key and you don’t want to pollute your logs.)

Usage

Now you need to understand how amCharts works.

After being loaded, amCharts expects a datastream. The datastream is then parsed and displayed as a chart.
You can modify the aspect of any chart by changing its settings.
Settings are set at runtime and/or in a setting file.

Great! I won’t cover the settings file. It’s a well documented XML file you just copied in your public folder. (or check the documentation)

What we want to focus on, is the datastream. Basically we just need to create a XML file that can be parsed by amCharts.

Let’s imagine that we have a reports_controller.rb file We want to display the population of the cities in California.

let’s add a new action to render our XML file:

1
2
3
4
5
6
7
8

  def population
    @cities = City.find(:all)
    @population_data_link = formatted_population_reports_url(  ml)
    respond_to do |format|
      format.html
      format.xml  { render :action => "population.xml.builder", :layout => false }
    end
  end

(notice that I’m using rails 2.0 and that’s why my XML template is not RXML)

As you can see, we have 2 values: @cities and @populationdatalink

@cities contains all the City records, including their population etc..

@populationdatalink contains the url to retrieve the datastream.

If you wonder how I got this url? I’m simply using a named route defined in my routes.rb:

  map.resources :reports, :collection => {:population => :get}

(note that you don’t need to create a restful route for that, a simple named route would have worked too)

Flash detection

Since we are going to use Flash, we want to make sure that people have the Flash plugin installed on their browser. For that we will use swfobject. Simply make sure to add swfobject.js (available in any amChart package) to your public/javascript folder. Then make sure you linked the javascript in your header:

  <%= javascript_include_tag 'swfobject' %>

We now need to create our 2 views: population.html.erb and population.xml.builder

population.html.erb

Basically, this view only loads amCharts and provides it with the details of the datastream:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

  <div id="population_chart" class='chart'>
    <strong>Text displayed when the user doesn't have Flash. You might want to display a simple table with the population, search engines and visitor without flash would love that.</strong>
    <p> To see this page properly, you need to upgrade your Flash Player, please visit the Adobe web site</p>
  </div>

  <script type="text/javascript">
    // <![CDATA[    
    var so = new SWFObject("/amcolumn/amcolumn.swf", "population_chart", "800", "380", "8", "#000000");
    so.addVariable("path", "/amcolumn/");
    so.addVariable("settings_file", escape("/amcolumn/column_settings.xml"));
    so.addVariable("data_file", escape("<%= @population_data_link %>"));
    so.addVariable("additional_chart_settings", "<settings><labels><label><x>250</x><y>25</y><text_size>18</text_size><text><![CDATA[<b>California Population as of <%= Time.now.to_s(:db) %></b>]]></text></label></labels></settings>");
    so.addVariable("preloader_color", "#000000");
    so.write("population_chart");
    // ]]>
  </script>

As you can see, we have a div called population_chart. This div is replaced at load time by the Flash object if the visitor has Flash setup locally. Think about providing some data in case the user doesn’t have Flash.

The rest is simple Javascript. I unpacked the amchart column lib in mypublic/amcolumn folder and that’s why I setup the path as “amcolumn”

  so.addVariable("path", "/amcolumn/");

My settings file is called column_settings.xml :

  so.addVariable("settings_file", escape("/amcolumn/column_settings.xml"));

and the most important part:

  so.addVariable("data_file", escape("<%= @population_data_link %>"));

Finally, I added some dynamic settings just to show you how easy it is:

1
2

  so.addVariable("additional_chart_settings",
  "<settings><labels><label><x>250</x><y>25</y><text_size>18</text_size><text><![CDATA[<b>California Population as of <%= Time.now.to_s(:db) %></b>]]></text></label></labels></settings>");

Ok, let’s now create our XML view:

population.xml.builder

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

  xml.instruct!   ml, :version=>"1.0", :encoding=>"UTF-8"
  xml.chart do
    # xml.message "You can broadcast any message to chart from data XML file", :bg_color => "#FFFFFF", :text_color => "#000000"
    xml.series do    
      @cities.each_with_index do |city, index|
        xml.value city.name,   id => index
      end
    end

    xml.graphs do
     #the gid is used in the settings file to set different settings just for this graph
      xml.graph :gid => 'population' do
        @cities.each_with_index do |city, index|
          population = city.population
          case population
            # When the population is > 1 million, show the bar in red/pink
            when > 100000
              xml.value value,   id => index, :color => "#ff43a8", :gradient_fill_colors => "#960040,#ff43a8", :description => level
            else
              xml.value value,   id => index, :color => "#00C3C6", :gradient_fill_colors => "#009c9d,#00C3C6", :description => level
            end
        end
      end
    end

  end

Nothing fancy, we first created a series with all the city names:

1
2
3
4
5

  xml.series do    
    @cities.each_with_index do |city, index|
      xml.value city.name,   id => index
    end
  end

Then we created another node with the values for each city.
Since it would be cool to display some bars in a different color, we used a case-switch statement:

1
2
3
4
5
6
7
8
9
10
11
12

    xml.graph :gid => 'population' do
      @cities.each_with_index do |city, index|
        population = city.population
        case population
          # When the population is > 1 million, show the bar in red/pink
          when > 100000
            xml.value value,   id => index, :color => "#ff43a8", :gradient_fill_colors => "#960040,#ff43a8", :description => level
          else
            xml.value value,   id => index, :color => "#00C3C6", :gradient_fill_colors => "#009c9d,#00C3C6", :description => level
          end
      end
    end

Depending on what you want to display, you might need to have different colors or a different tooltip text, or load an animation or image… and as you can see, it’s REALLY easy.

Got to http://yoursite.com/reports/population to enjoy your new fancy graph.

That’s it, you are done!

Time to tweak your settings file to make your graph look awesome.
Since you now have a lot of free time, you can start re-factoring your code and make sure you have a good test coverage.

Good luck!