Overview

The plugin provides a taglib for the interactive charts of the Google Visualization API.

Features

• Supports the following visualizations: Annotated Time Line, Area Chart, Bar Chart, Column Chart, Gauge, Geo Map, Intensity Map, Line Chart, Map, Motion Chart, Organizational Chart, Pie Chart, Scatter Chart, Table and Tree Map. See the gallery for more information.
• Implements redesigned charts (Area, Bar, Column, Line, Pie, and Scatter Charts) from the Core Chart package as well as the deprecated versions.
• Provides implementations for table formatters TableArrowFormat, TableBarFormat, TableColorFormat, TableDateFormat, TableNumberFormat and TablePatternFormat.
• Visualization event handling.

Usage

1. The page you want to use the visualization in has to import the Google visualization API JavaScript library. You can do so by using the taglib <gvisualization:apiImport/> or by importing it using the HTML script tag.

   <script type="text/javascript" src="http://www.google.com/jsapi"></script>

2. All visualizations in the taglib use the namespace gvisualization.
3. If your data requires the usage of the cell object you can import and populate the class org.grails.plugins.google.visualization.data.Cell.
4. Apart from the configuration options specific to a visualization (see visualization specifications) there are multiple attributes that you have to set for your visualization.

• name (optional) - JavaScript variable name for visualization object (defaults to "visualization").
• version (optional) - API version for visualization object (defaults to "1").
• elementId (required) - HTML div ID used to render visualization.
• dynamicLoading (optional) - Renders visualization over dynamic loading - required when rendered in AJAX response (defaults to false).
• language (optional) - Forces localized version of visualization. The language property is a two-letter ISO 639-1 language code.
• columns (required) - List of column data types and names to be displayed in the visualization.
• data (required) - List of data to be displayed for columns.

Available Visualizations

Working examples for all available visualization can be found on this GSP page. You can find the corresponding code to this page on GitHub.

Interactive Charts:

• Pie Core Chart: <gvisualization:pieCoreChart/>
• Bar Core Chart: <gvisualization:barCoreChart/>
• Bubble Core Chart: <gvisualization:bubbleCoreChart/>
• Column Core Chart: <gvisualization:columnCoreChart/>
• Area Core Chart: <gvisualization:areaCoreChart/>
• Line Core Chart: <gvisualization:lineCoreChart/>
• Scatter Core Chart: <gvisualization:scatterCoreChart/>
• Stepped Area Core Chart: <gvisualization:steppedAreaCoreChart/>
• Candlestick Core Chart: <gvisualization:candlestickCoreChart/>
• Combo Core Chart: <gvisualization:comboCoreChart/>
• Gauge: <gvisualization:gauge/>
• Table: <gvisualization:table/>
• Map: <gvisualization:map/>
• Annotated Time Line: <gvisualization:annotatedTimeLine/>
• Organizational Chart: <gvisualization:orgChart/>
• Intensity Map: <gvisualization:intensityMap/>
• Geo Map: <gvisualization:geoMap/>
• Geo Chart: <gvisualization:geoChart/>
• Motion Chart: <gvisualization:motionChart/>
• Tree Map: <gvisualization:treeMap/>

• Pie Chart (Image): <gvisualization:imagePieChart/>
• Bar Chart (Image): <gvisualization:imageBarChart/>
• Area Chart (Image): <gvisualization:imageAreaChart/>
• Line Chart (Image): <gvisualization:imageLineChart/>
• Sparkline (Image): <gvisualization:imageSparkLine/>
• Candlestick Chart (Image): <gvisualization:imageCandlestickChart/>

• Pie Chart: <gvisualization:pieChart/>
• Bar Chart: <gvisualization:barChart/>
• Column Chart: <gvisualization:columnChart/>
• Area Chart: <gvisualization:areaChart/>
• Line Chart: <gvisualization:lineChart/>
• Scatter Chart: <gvisualization:scatterChart/>

Events

If you want to register an event handler for your visualization you can by adding an event attribute. The value you give that attribute is the name of the JavaScript function acting as callback handler. Please check the visualization specification for available event names. The variable name of the visualization JavaScript object by default is "visualization", the name of the google.visualization.DataTable object is "visualization_data". You can always change the names by setting the taglib attribute "name".

Example:

<%
   def employeeColumns = [['string', 'Name'], ['string', 'Salary'], ['boolean', 'Full Time Employee']]
   def employeeData = [['Mike', '$10,000', true], ['Jim', '$8,000', false], ['Alice', '$12,500', true], 
   ['Bob', '$7,000', true]]   
%>
<script type="text/javascript">
   function selectHandler(e) {
      alert('A table row was selected');
   }
</script>
<gvisualization:table elementId="table" width="${400}" height="${130}" columns="${employeeColumns}" 
 data="${employeeData}" select="selectHandler" />
<div id="table"></div>

Formatters

You can apply formatters to all visualizations using the "formatters" taglib attribute as the underlying implementation is a google.visualization.DataTable. However, using formatters makes the most sense for the Table visualization. A full set of examples can be found on this GSP page. You can find the corresponding code to this page on GitHub.The value you have to pass in is a list of classes implementing the org.grails.plugins.google.visualization.formatter.Formatter interface. The implementations you can apply are the following:

org.grails.plugins.google.visualization.formatter.PatternFormatter
org.grails.plugins.google.visualization.formatter.NumberFormatter
org.grails.plugins.google.visualization.formatter.DateFormatter
org.grails.plugins.google.visualization.formatter.ColorRange
org.grails.plugins.google.visualization.formatter.ColorFormatter
org.grails.plugins.google.visualization.formatter.BarFormatter
org.grails.plugins.google.visualization.formatter.ArrowFormatter

Example:

<%@ page import="org.grails.plugins.google.visualization.formatter.BarFormatter" %>
<%
   def departmentRevenueColumns = [['string', 'Department'], ['number', 'Revenues']]
   def departmentRevenueData = [['Shoes', 10700], ['Sports', -15400], ['Toys', 12500], ['Electronics', -2100], 
   ['Food', 22600], ['Art', 1100]]
   def barFormatter = new BarFormatter(1)
   barFormatter.width = 120
   def barFormatters = [barFormatter]
%>
<gvisualization:table elementId="barformat_div" allowHtml="${true}" showRowNumber="${true}" 
 columns="${departmentRevenueColumns}" data="${departmentRevenueData}" formatters="${barFormatters}"/>
<div id="barformat_div"></div>

Examples

1. Rendering a visualization in a GSP

<%
   def myDailyActivitiesColumns = [['string', 'Task'], ['number', 'Hours per Day']]
   def myDailyActivitiesData = [['Work', 11], ['Eat', 2], ['Commute', 2], ['Watch TV', 2], ['Sleep', 7]]
%>
<gvisualization:pieCoreChart elementId="piechart" title="My Daily Activities" width="${450}" height="${300}" 
 columns="${myDailyActivitiesColumns}" data="${myDailyActivitiesData}" />
<div id="piechart"></div>

2. Rendering a visualization in a AJAX response

GSP (grails-app/views/index.gsp):

<input type="button" value="Render Pie Chart" 
 onclick="${remoteFunction(controller:'visualization',action:'render',update:'chart')}">
<br>
<div id="chart"></div>

Controller (grails-app/controllers/VisualizationController.groovy):

class VisualizationController {
    def render = {
        def myDailyActivitiesColumns = [['string', 'Task'], ['number', 'Hours per Day']]
        def myDailyActivitiesData = [['Work', 11], ['Eat', 2], ['Commute', 2], ['Watch TV', 2], ['Sleep', 7]]
        render template: "chart", model: ["myDailyActivitiesColumns": myDailyActivitiesColumns, 
                                          "myDailyActivitiesData": myDailyActivitiesData]
    }
}

Template (grails-app/views/visualization/_chart.gsp):

<div id="piechart"></div>
<gvisualization:pieCoreChart dynamicLoading="${true}" elementId="piechart" title="My Daily Activities" 
 width="${450}" height="${300}" columns="${myDailyActivitiesColumns}" data="${myDailyActivitiesData}"/>

Plugin Version History

• May 26, 2012 (version 0.5.2)
• Added isStacked attribute for ComboCoreChart.
• May 17, 2012 (version 0.5.1)
• Provided support for marker style in GeoChart (see GPGOOGLEVISUALIZATIONAPI-7)
• Upgrade to Grails 2.0.1 and Release plugin 2.0.0.
• January 29, 2012 (version 0.5)
• Added new visualizations: Bubble Chart, Stepped Area Chart.
• Allow all visualizations to use String data type for the attributes height and width (see GPGOOGLEVISUALIZATIONAPI-5).
• Allow all visualizations to use formatters (see GPGOOGLEVISUALIZATIONAPI-6).
• Provided taglib for Google JavaScript API import.
• December 3, 2011 (version 0.4.3)
• Ready event has to be defined before calling draw on visualization (see GPGOOGLEVISUALIZATIONAPI-3).
• October 2, 2011 (version 0.4.2)
• Ready event has to be defined before calling draw on visualization (see GPGOOGLEVISUALIZATIONAPI-2).
• August 27, 2011 (version 0.4.1)
• Updated core chart parameters (see Google's release notes).
• May 20, 2011 (version 0.4)
• Added new visualizations: Geo Chart, Candlestick Chart and Combo Chart.
• Exposed visualization parameter to set API version.
• May 17, 2011 (version 0.3.1)
• Updated core chart parameters (see Google's release notes).
• March 20, 2011 (version 0.3)
• Updated core chart parameters (see Google's release notes).
• Added Candlestick image chart.
• November 10, 2010 (version 0.2.4)
• Updated core chart parameters (see Google's release notes).
• Improved String data type handling (see GPGOOGLEVISUALIZATIONAPI-1).
• August 26, 2010 (version 0.2.3)
• Updated core chart parameters (see Google's release notes).
• August 4, 2010 (version 0.2.2)
• Exposed visualization data JavaScript object (google.visualization.DataTable).
• Bugfixes: String parameters and cell labels needed to be escaped.
• July 8, 2010 (version 0.2.1)
• Added onmouseover/onmouseout events to treemap.
• Support for dynamic loading.
• June 5, 2010 (version 0.2)
• Added new visualization Tree Map.
• Added image charts: Pie Chart, Bar Chart, Area Chart, Line Chart and Sparkline.
• Map now provides the Terrain type.
• Support for cell object.
• May 27, 2010 (version 0.1)
• Initial version.

Development

To report issues or request improvements and new features please add a ticket in Jira or send me an email.

A: Make sure the page you are trying to render the visualization in imports the Google's visualization API JavaScript from http://www.google.com/jsapi. This script has to be accessible over your network.

Q: When I try to render a visualization in a AJAX response my page is blank. How do I fix it?

A: Rendering a visualization in an AJAX response requires dynamic loading. To enable dynamic loading you have to set your taglib attribute "dynamicLoading" to true. Furthermore, the HTML div you want to render the visualization in has to be defined before the taglib. Please check the plugin description tab for a full example.

Q: How do I set values for a visualization object data type like the column core chart's "hAxis"?

A: You can easily do this by using an Expando or a custom bean class. "textColor", "title" and "titleColor" are fields of this object.

Example:

hAxis="${new Expando(title: 'Year', titleColor: 'red', textColor: 'blue')}"

Q: How do I render a chart from the corechart package and a deprecated chart on the same page?

A: It's not possible. Google encourages you to start using the new chart versions from the corechart package.