6/2/2014 Building a Charts Dashboard - Google Apps Script — Google Developers

https://developers.google.com/apps-script/articles/charts_dashboard 1/3

Building a Charts Dashboard

Roee Eilat, Google Charts Team

Eric Koleda, Google Apps Script Team

July, 2012

Goal

Time to complete

Prerequisites

Overview

Step 1: Create the data source.

Step 2: Create the charts and controls

Step 3: Create and bind dashboard

Step 4: Create application and add dashboard

Step 5: Deploy as web app

What exactly are the Filter and Dashboard objects?

Complete script

Goal

This tutorial will demonstrate how to create a charts dashboard, with controls that allow you to instantly filter the data displayed in the charts.

Time to complete

Approximately 15 minutes.

Prerequisites

Before you begin this tutorial, you should ensure that:

You have a basic understanding of programming in JavaScript or similar languages.

You are comfortable using the Script Editor, as covered in Building your first script.

Overview

A dashboard is a visual structure that lets you organize and manage multiple charts that share the same underlying data. The three building blocks of a dashboard

are the data source, charts, and controls. Controls are user interface widgets (category pickers, range sliders, or autocompleting text boxes) that someone can

interact with in order to drive the data managed by a dashboard to the charts that are part of it.

Because of its interactive nature, a dashboard is built in a Google Apps Script UI application. A UI application can be embedded in a Google Spreadsheet, Google

Site or served as HTML using the "Deploy as webapp" option. They are perfect for creating interactive reports, where users can gain extra insight through exploring

the data.

Step 1: Create the data source.

function doGet() {

var data = Charts.newDataTable()

.addColumn(Charts.ColumnType.STRING, "Name")

.addColumn(Charts.ColumnType.STRING, "Gender")

.addColumn(Charts.ColumnType.NUMBER, "Age")

.addColumn(Charts.ColumnType.NUMBER, "Donuts eaten")

.addRow(["Michael", "Male", 12, 5])

.addRow(["Michael", "Male", 12, 5])

.addRow(["Elisa", "Female", 20, 7])

.addRow(["Robert", "Male", 7, 3])

.addRow(["John", "Male", 54, 2])

.addRow(["Jessica", "Female", 22, 6])

.addRow(["Aaron", "Male", 3, 1])

.addRow(["Margareth", "Female", 42, 8])

.addRow(["Miranda", "Female", 33, 6])

.build();

Products Google Apps Script

0:00 / 3:54

Building a Charts Dashboard - Apps Script Tutorial

6/2/2014 Building a Charts Dashboard - Google Apps Script — Google Developers

https://developers.google.com/apps-script/articles/charts_dashboard 2/3

This is the same as when using charts normally. In the example, we created and populated a DataTable; alternatively, we could have retrieved a Spreadsheet range

and used it as a data source for the dashboard.

Step 2: Create the charts and controls

var ageFilter = Charts.newNumberRangeFilter()

.setFilterColumnLabel("Age")

.build();

var genderFilter = Charts.newCategoryFilter()

.setFilterColumnLabel("Gender")

.build();

var pieChart = Charts.newPieChart()

.setDataViewDefinition(Charts.newDataViewDefinition()

.setColumns([0,3]))

.build();

var tableChart = Charts.newTableChart()

.build();

Notice that when creating the controls and charts objects we don't set a data table for them, we'll set the data table for the dashboard object which will behind the

scenes driving the data through the controls (which will filter it according to their state) to the charts. Additionally, a DataViewDefinition is added to the pie chart,

which specifies that it should only consider the first and fourth column (Name and Donuts eaten) when rendering that chart.

Step 3: Create and bind dashboard

var dashboard = Charts.newDashboardPanel()

.setDataTable(data)

.bind([ageFilter, genderFilter], [pieChart, tableChart])

.build();

When a control is bound to a chart, the chart will display only the part of the data that complies with the control's current state. The binding of controls to charts can

be one to one or many to many as seen in the example above.

Step 4: Create application and add dashboard

var uiApp = UiApp.createApplication();

dashboard.add(uiApp.createVerticalPanel()

.add(uiApp.createHorizontalPanel()

.add(ageFilter).add(genderFilter)

.setSpacing(70))

.add(uiApp.createHorizontalPanel()

.add(pieChart).add(tableChart)

.setSpacing(10)));

uiApp.add(dashboard);

return uiApp;

}

The dashboard object itself is a panel container, but we use vertical and horizontal panels to have greater control over the dashboard's layout.

Step 5: Deploy as web app

Follow the steps in the Web Apps guide to deploy the script as a web app.

What exactly are the Filter and Dashboard objects?

A Filter object does exactly as its name implies: it filters the data table over a specific column so that only the rows that comply with its constraints are left. The

widget is initiated with the entire range of optional values, and changes its constraint as the user interacts with it. In the example, the number range filter is set on the

"Age" column and initially shows the whole range (3-54). When the user changes the range by interacting with it, only the rows with age values in that range will be

displayed.

6/2/2014 Building a Charts Dashboard - Google Apps Script — Google Developers

https://developers.google.com/apps-script/articles/charts_dashboard 3/3

The Dashboard object has two purposes. One is managing the data flow, the other being a visual container. Driving data from the data source through the controls to

the charts is done according to the binding definition. When a control is bound to a chart the dashboard first pass the data table through the control which in turn

filters it and then passes it to the chart. When one or more controls are bound to one or more charts, the dashboard passes the intersection of the filtered data table

to the charts. As a visual container a dashboard holds a single panel that contains all the controls and charts managed by it.

Complete script

function doGet() {

var data = Charts.newDataTable()

.addColumn(Charts.ColumnType.STRING, "Name")

.addColumn(Charts.ColumnType.STRING, "Gender")

.addColumn(Charts.ColumnType.NUMBER, "Age")

.addColumn(Charts.ColumnType.NUMBER, "Donuts eaten")

.addRow(["Michael", "Male", 12, 5])

.addRow(["Michael", "Male", 12, 5])

.addRow(["Elisa", "Female", 20, 7])

.addRow(["Robert", "Male", 7, 3])

.addRow(["John", "Male", 54, 2])

.addRow(["Jessica", "Female", 22, 6])

.addRow(["Aaron", "Male", 3, 1])

.addRow(["Margareth", "Female", 42, 8])

.addRow(["Miranda", "Female", 33, 6])

.build();

var ageFilter = Charts.newNumberRangeFilter()

.setFilterColumnLabel("Age")

.build();

var genderFilter = Charts.newCategoryFilter()

.setFilterColumnLabel("Gender")

.build();

var pieChart = Charts.newPieChart()

.setDataViewDefinition(Charts.newDataViewDefinition()

.setColumns([0,3]))

.build();

var tableChart = Charts.newTableChart()

.build();

var dashboard = Charts.newDashboardPanel()

.setDataTable(data)

.bind([ageFilter, genderFilter], [pieChart, tableChart])

.build();

var uiApp = UiApp.createApplication();

dashboard.add(uiApp.createVerticalPanel()

.add(uiApp.createHorizontalPanel()

.add(ageFilter).add(genderFilter)

.setSpacing(70))

.add(uiApp.createHorizontalPanel()

.add(pieChart).add(tableChart)

.setSpacing(10)));

uiApp.add(dashboard);

return uiApp;

}

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the

Apache 2.0 License. For details, see our Site Policies.

Last updated December 5, 2013.