As discussed in Chapter 2, Anatomy of a Visualization, Visualization API code is JavaScript-based and resides within HTML <script>
tags. Unless otherwise noted, it is assumed that all the API code intended for a HTML framework is located within these tags.
For all Google API code, including the Visualization API, there are several general components required. These are:
Inside the first script
tag, a few short lines of HTML indicate the location of the Google Visualization API library, hosted by Google. The second script
tag invokes a call to google.load
, which is the Google Loader. The Google Loader options indicate which API is to be loaded for the application, as well as what packages and options for the API should also be loaded. The google.load
call in the following sample script indicates that Version 1 of the Visualization API is to be loaded. It also indicates that the core chart package from the Visualization API module is to be retrieved. The Google Loader is a common component across all Google APIs, and is generally found shortly after the JavaScript declarations and source information.
After the API source has been set and the API has been specified, the subsequent script
tag set holds the actual API application logic. At the very end of the code, a final common component renders the visualization. The google.setOnLoadCallback(drawVisualization);
line tells the Google Loader to execute drawVisualization
once the page has loaded.
The Google Loader documentation is available at: https://developers.google.com/loader/.
The combination of Visualization API packages and chart types is not particularly intuitive. The corechart
package happens to contain the most types of chart. This is useful knowledge as visualizations that fall under the same package are most likely to be interchangeable, while other types almost certainly require a different data layout. At the time of publication, the following chart is a listing of current packages and chart types pairings. Note that older, depreciated versions of the API may still be available, but are instead covered under a Google depreciation policy.
Package |
Chart type |
Visual example |
---|---|---|
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
|
Depreciated, but available until April 20, 2015 | |
| ||
|
Depreciated, but available until April 20, 2015 | |
|
Depreciated, but available until April 20, 2015 | |
| ||
|
Depreciated, but available until April 20, 2015 | |
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
|
Depreciated, but available until April 20, 2015 | |
| ||
|
The preceding images can be found at http://code.google.com/apis/ajax/playground/.
Just as HTML requires information regarding the location of the API objects, Apps Script requires its own wrapper to encapsulate API code. Depending on the integration with other Google Apps or as a stand-alone entity, the Apps Script wrapper can take several similar yet slightly different forms.
For Google Apps integration, especially with Google Spreadsheets, additional functionality in the GUI is often required. A typical need is an additional drop-down menu item from which the visualization of data is launched. To create a custom menu item in Google Spreadsheets, the Google UI (user interface) service must be used.
Using the Google UI service in Apps Script allows for building a user display, control interface, or an information capture method. The following image illustrates a realization of a custom menu item in the Spreadsheet menu bar.
To create the custom Script Menu item, the following function must be included in the Apps Script attached to the desired Google Spreadsheet file:
functiononOpen() { /* Retrieves the active spreadsheet as a source */ var sheet = SpreadsheetApp.getActiveSpreadsheet(); /* Create the menu entry for a function */ var entries = [{ /* Name of the dropdown list item */ name : "Launch App", functionName : "doGet" }]; /* Create the Spreadsheet Menu tab named "Script Menu" */ sheet.addMenu("Script Menu", entries); };
Another common need is to have the resulting visualization display as a web page. In Apps Script, the designated function name doGet
must be used in order to display the visualization on a web page. This is a specific requirement for the doGet
function, is tied to Apps Script method of handling requests, and is a special, reserved function. Finally, if the visualization is to be rendered as a web page but as a standalone script in Google Drive, the two lines containing reference to the Spreadsheet application can be removed.
functiondoGet() { . . . // Use the UI service to create a UI for the app var ui = UiApp.createApplication(); ui.add(chart); // Retreive information from the open spreadsheet var spreadsheet = SpreadsheetApp.getActiveSpreadsheet(); // Show the UI in the spreadsheet application spreadsheet.show(ui); }
or,
Var ui = UiApp.createApplication(); // No spreadsheet app here so show UI as a web app ui.add(chart);
Apps Script Ui Service documentation is available at https://developers.google.com/apps-script/uiapp.
Information on displaying a User Interface from a Spreadsheet is available at https://developers.google.com/apps-script/uiapp#DisplayingSpreadsheet.