ShufflePoint blog readers know that I love Google Visualization Gadgets and the Visualization API. The standardized HTTP/JSON handshake of the library allows any visualization gadget - including iGoogle gadgets - to consume data which adheres to the visualization API specification. Up to now our examples have used Google-provided gadgets. But for a recent project, I needed something special. Fortunately, custom gadgets are really simple to create because one merely has to implement a simple JavaScript interface to get a custom gadget.
To cut to the chase, here is a link to the sample.
The custom gadget I wanted was something which will be recognizable to anyone using YouTube or other social media sites. Our need was for a gadget which displayed top page visits for the week, month, and year. Most web sites could benefit from such a gadget since it allow you to point out to visitors the "hot" content on the site. And since Google Analytics has this information, it should be relatively easy.
The GAQL query for top pages
The query I will use for this is show below
SELECT METRICS ga:visits ON COLUMNS DIMENSIONS ga:pagePath, ga:pageTitle ON ROWS TOP 10 NoOther BY ga:visits FROM default WHERE TIMEFRAME lastMonth
It retrieves the page path and page title for the top 10 pages by visits. The "NoOther" qualifier is present to prevent the addition of an "other" row. This is needed because the default GAQL interpretation will turn
TOP 10 BY ga:visits
into
TOP 10 BottomOther BY ga:visits
which adds a bottom row which aggregates all values not in the "top N".
The gadget design
The desired presentation of this gadget is as a small panel which could be added to a narrow left or right callout column of the web site - perhaps below the navigation menu. The query includes the ga:pagePath and ga:pageTitle dimensions to allow the gadget to display a list of page titles where each entry is a link to that page.
The final result is shown in the screenshot below.
Implementing the gadget interface
A gadget is merely a JavaScript class which has two methods. The constructor method takes a single "container" parameter. The container is the HTML element into which the gadget will draw its presentation of the data. The other method has the signature
draw(data, options)
The data parameter is a DataTable (http://code.google.com/apis/visualization/documentation/reference.html#DataTable) object. The options parameter is an associative array. The user of the gadget can pass in arbitrary (but documented by the gadget author) presentation options.
Our gadget implementation (see TopPagesGoogleVis.js) is pretty straight forward. The draw() method builds an HTML table and then places it in the innerHTML of the container obtained in the constructor. The whole gadget class is less than 50 lines of code (excluding comments).
Using the custom gadget
The code for an HTML page to use this gadget looks pretty much the same as our previous gadget examples. That is because the Google Visualization logic is all the same: a) specify a provider, b) specify and run a query, and c) pass the query results to the gadget.
The gadget containing page has the logic to display a list of timeframes: Last week, Last month, and Last year. It also has an event handler which reruns the query with the selected timeframe. An alternative implementation would be to move this logic into the gadget, but this being my first gadget, I wanted to keep it simple.
Demo: top pages gadget to the sample.
