`
on the page.
```
Google Visualization API Sample
```
## Data Manipulation Methods
The `google.visualization.data` namespace holds static methods to perform SQL-like
operations on `DataTable` objects, for example joining them or grouping by column
value.
The `google.visualization.data` namespace exposes the following methods:
| Method | Description |
|---|---|
| `https://developers.google.com/chart/interactive/docs/reference#google_visualization_data_group` | Performs a SQL GROUP BY action to return a table grouped by values in specified columns. |
| `https://developers.google.com/chart/interactive/docs/reference#google_visualization_data_join` | Joins two data tables on one or more key columns. |
### group()
Takes a populated `DataTable` object and performs a SQL-like GROUP BY operation,
returning a table with rows grouped by the specified column values. Note that this does not modify
the input `DataTable`.
The returned table includes one row for each combination of values in the specified key columns.
Each row includes the key columns, plus one column with an aggregated column value over all rows
that match the key combination (for example, a sum or count of all values in the specified
column).
The `google.visualization.data` namespace includes several useful aggregation values
(for example, [sum](https://developers.google.com/chart/interactive/docs/reference#data_aggregation_functions) and
[count](https://developers.google.com/chart/interactive/docs/reference#data_aggregation_functions)), but you can define your own (for example,
standardDeviation or secondHighest). Instructions on how to define your own aggregator are given
after the method description.
**Syntax**
```
google.visualization.data.group(data_table, keys, columns)
```
*data_table*
:
The input `DataTable`. This will not be modified by calling `group()`.
*keys*
:
An array of numbers and/or objects specifying which columns to group by. The result table
includes every column in this array, as well as every column in *columns* . If a number,
this is a column index of the input `DataTable` to group by. If an object, it will
include a function that can modify the specified column (for example, add 1 to the value in that
column). The object must have the following properties:
- **column** - A number that is a column index from *dt* to apply the transformation to.
- **modifier** - A function that accepts one value (the cell value in that column for each row), and returns the modified value. This function is used to modify the column value to assist in the grouping: for example, by calling a whichQuarter function that calculates a quarter from a date column, so the API can group rows by quarter. The calculated value is displayed in the key columns in the returned table. This function can be declared inline inside this object, or it can be a function that you define elsewhere in your code (it must be within the calling scope). The API provides [one simple modifier function](https://developers.google.com/chart/interactive/docs/reference#data_modifier_functions); [here are instructions](https://developers.google.com/chart/interactive/docs/reference#creating_a_modifier_function) on how to create your own, more useful functions. You must know the data type that this function can accept, and call it only on columns of that type. You must also know the return type of this function, and declare it in the **type** property described next.
- **type** - The type returned by the function *modifier*. This should be a JavaScript string type name, for example: 'number' or 'boolean'.
- **label** - \[*Optional* \] A string label to assign this column in the returned `DataTable`.
- **id** - \[*Optional* \] A string ID to assign this column in the returned `DataTable`.
**Examples:** `[0]`, `[0,2]`, `[0,{column:1,
modifier:myPlusOneFunc, type:'number'},2]`
*columns*
:
\[*Optional* \] Lets you specify which columns, in addition to key columns, to include in
the output table. Because all rows in the row group are compressed into a single output row,
you must determine what value to display for that row group. For example, you could choose to
show the column value from the first row in the set, or an average of all rows in that group.
*columns* is an array of objects, with the following properties:
- **column** - A number specifying the index of the column to show.
- **aggregation** - A function that accepts an array of all values of this column in this row group and returns a single value to display in the result row. The return value must be of the type specified by the object's **type** property. Details on creating your own aggregation function are given below. You must know what data types this method accepts and only call it on columns of the appropriate type. The API provides several useful aggregation functions. See [Provided Aggregation
Functions](https://developers.google.com/chart/interactive/docs/reference#data_aggregation_functions) below for a list, or [Creating an
aggregation function](https://developers.google.com/chart/interactive/docs/reference#creating_an_aggregation_function) to learn how to write your own aggregation function.
- **type** - The return type of the aggregation function. This should be a JavaScript string type name, for example: 'number' or 'boolean'.
- **label** - \[*Optional*\] A string label to apply to this column in the returned table.
- **id** - \[*Optional*\] A string ID to apply to this column in the returned table.
**Return Value**
A `DataTable` with one column for each column listed in *keys* and one column
for each column listed in *columns*. The table is sorted by key rows, from left to right.
**Example**
```
// This call will group the table by column 0 values.
// It will also show column 3, which will be a sum of
// values in that column for that row group.
var result = google.visualization.data.group(
dt,
[0],
[{'column': 3, 'aggregation': google.visualization.data.sum, 'type': 'number'}]
);
*Input table*
1 'john' 'doe' 10
1 'jane' 'doe' 100
3 'jill' 'jones' 50
3 'jack' 'jones' 75
5 'al' 'weisenheimer' 500
*Output table*
1 110
3 125
5 500
```
#### Provided Modifier Functions
The API provides the following modifier functions that you can pass into the *keys* .
**modifier** parameter to customize grouping behavior.
| Function | Input Array Type | Return Type | Description |
|---|---|---|---|
| `google.visualization.data.month ` | Date | number | Given a date, it will return the zero-based month value (0, 1, 2, and so on). |
#### Provided Aggregation Functions
The API provides the following aggregation functions that you can pass into the *columns* .
**aggregation** parameter array.
| Function | Input Array Type | Return Type | Description |
|---|---|---|---|
| `google.visualization.data.avg` | number | number | The average value of the array passed in. |
| `google.visualization.data.count` | any type | number | The count of rows in the group. Null and duplicate values are counted. |
| `google.visualization.data.max` | number, string, Date | number, string, Date, null | The maximum value in the array. For strings, this is the first item in an lexicographically sorted list; for Date values, it is the latest date. Nulls are ignored. Returns null if there is no maximum. |
| `google.visualization.data.min` | number, string, Date | number, string, Date, null | The minimum value in the array. For strings, this is the last item in an lexicographically sorted list; for Date values, it is the earliest date. Nulls are ignored. Returns null if if there is no minimum. |
| `google.visualization.data.sum` | number | number | The sum of all values in the array. |
#### Creating a modifier function
You can create a modifier function to perform a simple transformation onkey values before the
`group()` function groups your rows. This function takes a single cell value, performs
an action on it (for example, adds 1 to the value), and returns it. The input and return types
need not be the same type, but the caller must know the input and output types. Here's an example
of a function that accepts a date and returns the quarter:
```
// Input type: Date
// Return type: number (1-4)
function getQuarter(someDate) {
return Math.floor(someDate.getMonth()/3) + 1;
}
```
#### Creating an aggregation function
You can create an aggregation function that accepts a set of column values in a row group and
returns a single number: for example, returning a count or average of values. Here is an
implementation of the provided count aggregation function, which returns a count of how many rows
are in the row group:
```
// Input type: Array of any type
// Return type: number
function count(values) {
return values.length;
}
```
### join()
This method joins two data tables (`DataTable` or `DataView` objects) into a
single results table, similar to a SQL JOIN statement. You specify one or more column pairs
(*key* columns) between the two tables, and the output table includes the rows according to
a join method that you specify: only rows where both keys match; all rows from one table; or all
rows from both tables, whether or not the keys match. The results table includes only the key
columns, plus any additional columns that you specify. Note that *dt2* cannot have
duplicate keys, but *dt1* can. The term "key" means the combination of all key
column values, not a specific key column value; so if a row has cell values A \| B \| C and columns
0 and 1 are key columns, then the key for that row is AB.
**Syntax**
```
google.visualization.data.join(dt1, dt2, joinMethod,
keys, dt1Columns, dt2Columns);
```
*dt1*
: A populated `DataTable` to join with *dt2*.
*dt2*
:
A populated `DataTable` to join with *dt1*. This table cannot have multiple
identical keys (where a key is a combination of key column values).
*joinMethod*
:
A string specifying the join type. If *dt1* has multiple rows that match a *dt2*
row, the output table will include all matching *dt1* rows. Choose from the following
values:
- 'full' - The output table includes all rows from both tables, regardless of whether keys match. Unmatched rows will have null cell entries; matched rows are joined.
- 'inner' - The full join filtered to include only rows where the keys match.
- 'left' - The output table includes all rows from *dt1* , whether or not there are any matching rows from *dt2*.
- 'right' - The output table includes all rows from *dt2* , whether or not there are any matching rows from *dt1*.
*keys*
:
An array of key columns to compare from both tables. Each pair is a two element array, the first
is a key in *dt1* , the second is a key in *dt2* . This array can specify columns
by their index, id, or label, see
`https://developers.google.com/chart/interactive/docs/reference#DataTable_getColumnIndex`.
Columns must be the same type in both tables. All specified keys must match according to the
rule given by *joinMethod* in order to include a row from the table. Key columns are
always included in the output table. Only *dt1* , the left-hand table, can include
duplicate keys; keys in *dt2* must be unique. The term "key" here means a
unique set of key columns, not individual column values. For example, if your key columns were
A and B, the following table would have only unique key values (and could thus be used as
*dt2* ):
| A | B |
|---|---|
| Jen | Red |
| Jen | Blue |
| Fred | Red |
**Example:** `[[0,0], [2,1]]` compares values from the first column in
both tables as well as the third column from *dt1* with the second column from
*dt2*.
*dt1Columns*
:
An array of columns from *dt1* to include in the output table, in addition to
*dt1* 's key columns. This array can specify columns by their index, id, or label, see
`https://developers.google.com/chart/interactive/docs/reference#DataTable_getColumnIndex`.
*dt2Columns*
:
An array of columns from *dt2* to include in the output table, in addition to
*dt2* 's key columns. This array can specify columns by their index, id, or label, see
`https://developers.google.com/chart/interactive/docs/reference#DataTable_getColumnIndex`.
**Return Value**
A `DataTable` with the key columns, *dt1Columns* , and *dt2Columns* . This
table is sorted by the key columns, from left to right. When *joinMethod* is 'inner', all
key cells should be populated. For other join methods, if no matching key is found, the table will
have a null for any unmatched key cells.
**Examples**
```
*Tables*
dt1 dt2
bob | 111 | red bob | 111 | point
bob | 111 | green ellyn | 222 | square
bob | 333 | orange jane | 555 | circle
fred | 555 | blue jane | 777 | triangle
jane | 777 | yellow fred | 666 | dodecahedron
* Note that right table has duplicate Jane entries, but the key we will use is
* columns 0 and 1. The left table has duplicate key values, but that is
* allowed.
*Inner join* google.visualization.data.join(dt1, dt2, 'inner', [[0,0],[1,1]], [2], [2]);
bob | 111 | red | point
bob | 111 | green | point
jane | 777 | yellow | triangle
* Note that both rows from dt1 are included and matched to
* the equivalent dt2 row.
*Full join* google.visualization.data.join(dt1, dt2, 'full', [[0,0],[1,1]], [2], [2]);
bob | 111 | red | point
bob | 111 | green | point
bob | 333 | orange | null
ellyn | 222 | null | square
fred | 555 | blue | null
fred | 666 | null | dodecahedron
jane | 555 | null | circle
jane | 777 | yellow | triangle
*Left join* google.visualization.data.join(dt1, dt2, 'left', [[0,0],[1,1]], [2], [2]);
bob | 111 | red | point
bob | 111 | green | point
bob | 333 | orange | null
fred | 555 | blue | null
jane | 777 | yellow | triangle
*Right join* google.visualization.data.join(dt1, dt2, 'right', [[0,0],[1,1]], [2], [2]);
bob | 111 | red | point
bob | 111 | green | point
ellyn | 222 | null | square
fred | 666 | null | dodecahedron
jane | 555 | null | circle
jane | 777 | yellow | triangle
```
## Formatters
The Google Visualization API provides formatters that can be used to
reformat data in a visualization. These formatters change the
formatted value of the specified column in all rows. Note that:
- Formatters modify only the formatted values, not the underlying values. For example, the displayed value would be "$1,000.00" but the underlying value would still be "1000".
- Formatters only affect one column at a time; to reformat multiple columns, apply a formatter to each column that you want to change.
- If you also use user-defined formatters, certain Google Visualization formatters will override all user-defined formatters.
- The actual formatting applied to the data is derived from the locale the API has been loaded with. For more details, see [loading charts with a specific locale](https://developers.google.com/chart/interactive/docs/library_loading_enhancements#loadwithlocale).
- **Important** : Formatters can only be used with a `DataTable`; they cannot be used with a `DataView` (`DataView` objects are read-only).
- Here are the general steps for using a formatter:
1. Get your populated `DataTable` object.
2. For each column that you want to reformat:
1. Create an object that specifies all the options for your formatter. This is a basic JavaScript object with a set of properties and values. Look at your formatter's documentation to see what properties are supported. (Optionally, you can pass in an object literal notation object specifying your options.)
2. Create your formatter, passing in your options object.
3. Call *`formatter`* `.format(table,
colIndex)`, passing in the `DataTable` and the (zero-based) column number of the data to reformat. Note that you can only apply a single formatter to each column; applying a second formatter will simply overwrite the effects of the first.
***Important:*** Many formatters require HTML tags to display special formatting; if your visualization supports an `allowHtml` option, you should set it to true.
- Here is an example of changing the formatted date values of a date column to use a long date format ("January 1, 2009"):
```
var data = new google.visualization.DataTable();
data.addColumn('string', 'Employee Name');
data.addColumn('date', 'Start Date');
data.addRows(3);
data.setCell(0, 0, 'Mike');
data.setCell(0, 1, new Date(2008, 1, 28));
data.setCell(1, 0, 'Bob');
data.setCell(1, 1, new Date(2007, 5, 1));
data.setCell(2, 0, 'Alice');
data.setCell(2, 1, new Date(2006, 7, 16));
// Create a formatter.
// This example uses object literal notation to define the options.
var formatter = new google.visualization.DateFormat({formatType: 'long'});
// Reformat our data.
formatter.format(data, 1);
// Draw our data
var table = new google.visualization.Table(document.getElementById('dateformat_div'));
table.draw(data, {showRowNumber: true});
```
- Most formatters expose the following two methods:
| Method | Description |
|---|---|
| `google.visualization.formatter_name(options)` | Constructor, where *formatter_name* is a specfic formatterclass name. - *options* - A generic JavaScript object that specifies the options for that formatter. This object is a generic object with property/value pairs with properties specific to that formatter. See the documentationfor your specific formatter to learn what options are supported. Here are two example ways to call the constructor for the DateFormat object, passing in two properties: ``` // Object literal technique var formatter = new google.visualization.DateFormat({formatType: 'long', timeZone: -5}); // Equivalent property setting technique var options = new Object(); options['formatType'] = 'long'; options['timeZone'] = -5; var formatter = new google.visualization.DateFormat(options); ``` |
| `format(data, colIndex)` | Reformats the data in the specified column. - *data* - A `https://developers.google.com/chart/interactive/docs/reference#DataTable` containing the data to reformat. You cannot use a DataView here. - *colIndex* - The zero-based index of the column to format. To format multiple columns, you must call this method multiple times, with different colIndex values. |
-
- The Google Visualization API provides the following formatters:
| Formatter Name | Description |
|---|---|
| [ArrowFormat](https://developers.google.com/chart/interactive/docs/reference#arrowformatter) | Adds an up or down arrow, indicating whether the cell value is above or below a specified value. |
| [BarFormat](https://developers.google.com/chart/interactive/docs/reference#barformatter) | Adds a colored bar, the direction and color of which indicates whether the cell value is above or below a specified value. |
| [ColorFormat](https://developers.google.com/chart/interactive/docs/reference#colorformatter) | Colors a cell according to whether the values fall within a specified range. |
| [DateFormat](https://developers.google.com/chart/interactive/docs/reference#dateformatter) | Formats a Date or DateTime value in several different ways, including "January 1, 2009," "1/1/09" and "Jan 1, 2009." |
| [NumberFormat](https://developers.google.com/chart/interactive/docs/reference#numberformatter) | Formats various aspects of numeric values. |
| [PatternFormat](https://developers.google.com/chart/interactive/docs/reference#patternformatter) | Concatenates cell values on the same row into a specified cell, along with arbitrary text. |
### ArrowFormat
- Adds an up or down arrow to a numeric cell, depending on whether the value is above or below a specified base value. If equal to the base value, no arrow is shown.
#### Options
- `ArrowFormat` supports the following options, passed in to the constructor:
| Option | Description |
|---|---|
| `base` | A number indicating the base value, used to compare against the cell value. If the cell value is higher, the cell will include a green up arrow; if the cell value is lower, it will include a red down arrow; if the same, no arrow. |
#### Sample code
```
var data = new google.visualization.DataTable();
data.addColumn('string', 'Department');
data.addColumn('number', 'Revenues Change');
data.addRows([
['Shoes', {v:12, f:'12.0%'}],
['Sports', {v:-7.3, f:'-7.3%'}],
['Toys', {v:0, f:'0%'}],
['Electronics', {v:-2.1, f:'-2.1%'}],
['Food', {v:22, f:'22.0%'}]
]);
var table = new google.visualization.Table(document.getElementById('arrowformat_div'));
var formatter = new google.visualization.ArrowFormat();
formatter.format(data, 1); // Apply formatter to second column
table.draw(data, {allowHtml: true, showRowNumber: true});
```
### BarFormat
- Adds a colored bar to a numeric cell indicating whether the cell value is above or below a specified base value.
#### Options
- `BarFormat` supports the following options, passed in to the constructor:
| Option | #### Example Description |
|---|---|
| `base` | A number that is the base value to compare the cell value against. If the cell value is higher, it will be drawn to the right of the base; if lower, it will be drawn to the left. Default value is 0. |
| `colorNegative` | A string indicating the negative value section of bars. Possible values are 'red', 'green' and 'blue'; default value is 'red'. |
| `colorPositive` | A string indicating the color of the positive value section of bars. Possible values are 'red', 'green' and 'blue'. Default is 'blue'. |
| `drawZeroLine` | A boolean indicating if to draw a 1 pixel dark base line when negative values are present. The dark line is there to enhance visual scanning of the bars. Default value is 'false'. |
| `max` | The maximum number value for the bar range. Default value is the highest value in the table. |
| `min` | The minimum number value for the bar range. Default value is the lowest value in the table. |
| `showValue` | If true, shows values and bars; if false, shows only bars. Default value is true. |
| `width` | Thickness of each bar, in pixels. Default value is 100. |
#### Sample code
```
var data = new google.visualization.DataTable();
data.addColumn('string', 'Department');
data.addColumn('number', 'Revenues');
data.addRows([
['Shoes', 10700],
['Sports', -15400],
['Toys', 12500],
['Electronics', -2100],
['Food', 22600],
['Art', 1100]
]);
var table = new google.visualization.Table(document.getElementById('barformat_div'));
var formatter = new google.visualization.BarFormat({width: 120});
formatter.format(data, 1); // Apply formatter to second column
table.draw(data, {allowHtml: true, showRowNumber: true, width: '100%', height: '100%'});
```
### ColorFormat
- Assigns colors to the foreground or background of a numeric cell, depending on the cell value. This formatter is an unusual, in that it doesn't take its options in the constructor. Instead, you should call `addRange()` or `addGradientRange()` as many times as you want, to add color ranges, before calling `format()`. Colors can be specified in any acceptable HTML format, for example "black", "#000000", or "#000".
#### Methods
- `ColorFormat` supports the following methods:
| Method | Description |
|---|---|
| `google.visualization.ColorFormat()` | Constructor. Takes no arguments. |
| `addRange(from, to, color, bgcolor)` | Specifies a foreground color and/or background color to a cell, depending on the cell value. Any cell with a value in the specified *from* ---*to* range will be assigned *color* and *bgcolor*. It is important to realize that the range is non-inclusive, because creating a range from 1---1,000 and a second from 1,000--- 2,000 will not cover the value 1,000! - *from* - \[*String, Number, Date, DateTime, or TimeOfDay*\] The lower boundary (inclusive) of the range, or null. If null, it will match -∞. String boundaries are compared alphabetically against string values. - *to* - \[*String, Number, Date, DateTime, or TimeOfDay*\] The high boundary (non-inclusive) of the range, or null. If null, it will match +∞. String boundaries are compared alphabetically against string values. - *color* - The color to apply to text in matching cells. Values can be either '#RRGGBB' values or defined color constants, (example: '#FF0000' or 'red'). - *bgcolor* - The color to apply to the background of matching cells. Values can be either '#RRGGBB' values or defined color constants, (example: '#FF0000' or 'red'). |
| `addGradientRange(from, to,color, fromBgColor, toBgColor)` | Assigns a background color from a range, according to the cell value. The color is scaled to match the cell's value within a range from a lower boundary color to an upper boundary color. Note that this method cannot compare string values, as `addRange()` can. *Tip*: Color ranges are often hard for viewers to gauge accurately; the simplest and easiest to read range is from a fully saturated color to white (e.g., #FF0000---FFFFFF). - *from* - \[*Number, Date, DateTime, or TimeOfDay*\] The lower boundary (inclusive) of the range, or null. If null, it will match -∞. - *to* - \[*Number, Date, DateTime, or TimeOfDay*\] The higher boundary (non-inclusive) of the range, or null. If null, it will match +∞. - *color* - The color to apply to text in matching cells. This color is the same for all cells, no matter what their value. - *fromBgColor* - The background color for cells holding values at the low end of the gradient. Values can be either '#RRGGBB' values or defined color constants, (example: '#FF0000' or 'red'). - *toBgColor* - The background color for cells holding values at the high end of the gradient. Values can be either '#RRGGBB' values or defined color constants, (example: '#FF0000' or 'red'). |
| `format(dataTable, columnIndex)` | The standard `format()` method to apply formatting to the specified column. |
#### Sample code
```
var data = new google.visualization.DataTable();
data.addColumn('string', 'Department');
data.addColumn('number', 'Revenues');
data.addRows([
['Shoes', 10700],
['Sports', -15400],
['Toys', 12500],
['Electronics', -2100],
['Food', 22600],
['Art', 1100]
]);
var table = new google.visualization.Table(document.getElementById('colorformat_div'));
var formatter = new google.visualization.ColorFormat();
formatter.addRange(-20000, 0, 'white', 'orange');
formatter.addRange(20000, null, 'red', '#33ff33');
formatter.format(data, 1); // Apply formatter to second column
table.draw(data, {allowHtml: true, showRowNumber: true, width: '100%', height: '100%'});
```
### DateFormat
- Formats a JavaScript `Date` value in a variety of ways, including "January 1, 2016," "1/1/16" and "Jan 1, 2016".
#### Options
- `DateFormat` supports the following options, passed in to the constructor:
| Option | Description |
|---|---|
| `formatType` | A quick formatting option for the date. The following string values are supported, reformatting the date February 28, 2016 as shown: - 'short' - Short format: e.g., "2/28/16" - 'medium' - Medium format: e.g., "Feb 28, 2016" - 'long' - Long format: e.g., "February 28, 2016" You cannot specify both `formatType` and `pattern`. |
| `pattern` | A custom format pattern to apply to the value, similar to the [ICU date and time format](http://userguide.icu-project.org/formatparse/datetime). For example: `var formatter3 = new google.visualization.DateFormat({pattern: "EEE, MMM d, ''yy"});` You cannot specify both `formatType` and `pattern`. You can read more details about patterns in the next section. |
| `timeZone` | The time zone in which to display the date value. This is a numeric value, indicating GMT + this number of time zones (can be negative). Date object are created by default with the assumed time zone of the computer on which they are created; this option is used to display that value in a different time zone. For example, if you created a Date object of 5pm noon on a computer located in Greenwich, England, and specified timeZone to be -5 (`options['timeZone'] = -5`, or Eastern Pacific Time in the US), the value displayed would be 12 noon. |
#### Methods
- `DateFormat` supports the following methods:
| Method | Description |
|---|---|
| `google.visualization.DateFormat(options)` | Constructor. See the options section above for more info. |
| `format(dataTable, columnIndex)` | The standard `format()` method to apply formatting to the specified column. |
| `formatValue(value)` | Returns the formatted value of a given value. This method does not require a `DataTable`. |
#### Sample code
```
function drawDateFormatTable() {
var data = new google.visualization.DataTable();
data.addColumn('string', 'Employee Name');
data.addColumn('date', 'Start Date (Long)');
data.addColumn('date', 'Start Date (Medium)');
data.addColumn('date', 'Start Date (Short)');
data.addRows([
['Mike', new Date(2008, 1, 28, 0, 31, 26),
new Date(2008, 1, 28, 0, 31, 26),
new Date(2008, 1, 28, 0, 31, 26)],
['Bob', new Date(2007, 5, 1, 0),
new Date(2007, 5, 1, 0),
new Date(2007, 5, 1, 0)],
['Alice', new Date(2006, 7, 16),
new Date(2006, 7, 16),
new Date(2006, 7, 16)]
]);
// Create three formatters in three styles.
var formatter_long = new google.visualization.DateFormat({formatType: 'long'});
var formatter_medium = new google.visualization.DateFormat({formatType: 'medium'});
var formatter_short = new google.visualization.DateFormat({formatType: 'short'});
// Reformat our data.
formatter_long.format(data, 1);
formatter_medium.format(data,2);
formatter_short.format(data, 3);
// Draw our data
var table = new google.visualization.Table(document.getElementById('dateformat_div'));
table.draw(data, {showRowNumber: true, width: '100%', height: '100%'});
}
```
- **More About Date Patterns**
- Here are some more details on what patterns are supported:
- The patterns are similar to the [ICU
date and time format](http://userguide.icu-project.org/formatparse/datetime), but the following patterns are not yet supported: A e D F g Y u w W. To avoid collision with patterns, any literal text you want to appear in the output should be surrounded by single quotes, except for the single quote, which should be doubled: e.g., `"K 'o''clock.'"`.
| Pattern | Description | Example Output |
|---|---|---|
| GG | Era designator. | "AD" |
| yy or yyyy | year. | 1996 |
| M | Month in year. For January: - M produces 1 - MM produces 01 - MMM produces Jan - MMMM produces January | "July" "07" |
| d | Day in month. Extra 'd' values will add leading zeros. | 10 |
| h | Hour in 12 hour scale. Extra 'h' values will add leading zeros. | 12 |
| H | Hour in 24 hour scale. Extra Hk' values will add leading zeros. | 0 |
| m | Minute in hour. Extra 'M' values will add leading zeros. | 30 |
| s | Second in minute. Extra 's' values will add leading zeros. | 55 |
| S | Fractional second. Extra 'S' values will be padded on the right with zeros. | 978 |
| E | Day of week. Following outputs for "Tuesday": - E produces T - EE or EEE Produce Tu or Tues - EEEE Produces Tuesday | "Tues" "Tuesday" |
| aa | AM/PM | "PM" |
| k | Hour in day (1\~24). Extra 'k' values will add leading zeros. | 24 |
| K | Hour in AM/PM (0\~11). Extra 'k' values will add leading zeros. | 0 |
| z | Time zone. For time zone 5, produces "UTC+5" | "UTC+5" |
| Z | Time zone in RFC 822 format. For time zone -5: Z, ZZ, ZZZ produce -0500 ZZZZ and more produce "GMT -05:00" | "-0800" "GMT -05:00" |
| v | Time zone (generic). | "Etc/GMT-5" |
| ' | escape for text | 'Date=' |
| '' | single quote | ''yy |
### NumberFormat
- Describes how numeric columns should be formatted. Formatting options include specifying a prefix symbol (such as a dollar sign) or the punctuation to use as a thousands marker.
#### Options
- `NumberFormat` supports the following options, passed in to the constructor:
| Option | Description |
|---|---|
| `decimalSymbol` | A character to use as the decimal marker. The default is a dot (.). |
| `fractionDigits` | A number specifying how many digits to display after the decimal. The default is 2. If you specify more digits than the number contains, it will display zeros for the smaller values. Truncated values will be rounded (5 rounded up). |
| `groupingSymbol` | A character to be used to group digits to the left of the decimal into sets of three. Default is a comma (,). |
| `negativeColor` | The text color for negative values. No default value. Values can be any acceptable HTML color value, such as "red" or "#FF0000". |
| `negativeParens` | A boolean, where true indicates that negative values should be surrounded by parentheses. Default is true. |
| `pattern` | A format string. When provided, all other options are ignored, except `negativeColor`. The format string is a subset of the [ICU pattern set](http://icu-project.org/apiref/icu4c/classDecimalFormat.html#_details). For instance, `{pattern:'#,###%'}` will result in output values "1,000%", "750%", and "50%" for values 10, 7.5, and 0.5. |
| `prefix` | A string prefix for the value, for example "$". |
| `suffix` | A string suffix for the value, for example "%". |
#### Methods
- `NumberFormat` supports the following methods:
| Method | Description |
|---|---|
| `google.visualization.NumberFormat(options)` | Constructor. See the options section above for more info. |
| `format(dataTable, columnIndex)` | The standard `format()` method to apply formatting to the specified column. |
| `formatValue(value)` | Returns the formatted value of a given value. This method does not require a `DataTable`. |
#### Sample code
```
var data = new google.visualization.DataTable();
data.addColumn('string', 'Department');
data.addColumn('number', 'Revenues');
data.addRows([
['Shoes', 10700],
['Sports', -15400],
['Toys', 12500],
['Electronics', -2100],
['Food', 22600],
['Art', 1100]
]);
var table = new google.visualization.Table(document.getElementById('numberformat_div'));
var formatter = new google.visualization.NumberFormat(
{prefix: '$', negativeColor: 'red', negativeParens: true});
formatter.format(data, 1); // Apply formatter to second column
table.draw(data, {allowHtml: true, showRowNumber: true, width: '100%', height: '100%'});
```
### PatternFormat
- Enables you to merge the values of designated columns into a single column, along with arbitrary text. So, for example, if you had a column for first name and a column for last name, you could populate a third column with {last name}, {first name}. This formatter does not follow the conventions for the constructor and the `format()` method. See the Methods section below for instructions.
#### Methods
- `PatternFormat` supports the following methods:
| Method | Description |
|---|---|
| `google.visualization.PatternFormat(pattern)` | Constructor. Does not take an options object. Instead, it takes a string *pattern* parameter. This is a string that describes which column values to put into the destination column, along with any arbitrary text. Embed placeholders in your string to indicate a value from another column to embed. The placeholders are `{#}`, where # is a the index of a source column to use. The index is an index in the *srcColumnIndices* array from the `format()` method below. To include a literal { or } character, escape it like this: \\{ or \\}. To include a literal \\ mark, escape it as \\\\. #### Sample code The following example demonstrates a constructor for a pattern that creates an anchor element, with the first and second elements taken from the `format()` method: ``` var formatter = new google.visualization.PatternFormat( '
{0}'); ``` |
| ` format(dataTable, srcColumnIndices, opt_dstColumnIndex) ` | The standard formatting call, with a few additional parameters: - *dataTable* - The DataTable on which to operate. - *srcColumnIndices* - An array of one or more (zero-based) column indices to pull as the sources from the underlying DataTable. This will be used as a data source for the *pattern* parameter in the constructor. The column numbers do *not* have to be in sorted order. - *opt_dstColumnIndex* - \[*optional* \] The destination column to place the output of the *pattern* manipulation. If not specified, the first element in *srcColumIndices* will be used as the destination. See the formatting examples after the table. |
- Here are a few example inputs and outputs for a four-column table.
```
Row before formatting (4 columns, last is blank):
John | Paul | Jones | [empty]
var formatter = new google.visualization.PatternFormat("{0} {1} {2}");
formatter.format(data, [0,1,2], 3);
Output:
John | Paul | Jones | John Paul Jones
var formatter = new google.visualization.PatternFormat("{1}, {0}");
formatter.format(data, [0,2], 3);
Output:
John | Paul | Jones | Jones, John
```
#### Sample code
- The following example demonstrates how to combine data from two columns to create an email address. It uses a [DataView](https://developers.google.com/chart/interactive/docs/reference#DataView) object to hide the original source columns:
```
var data = new google.visualization.DataTable();
data.addColumn('string', 'Name');
data.addColumn('string', 'Email');
data.addRows([
['John Lennon', 'john@beatles.co.uk'],
['Paul McCartney', 'paul@beatles.co.uk'],
['George Harrison', 'george@beatles.co.uk'],
['Ringo Starr', 'ringo@beatles.co.uk']
]);
var table = new google.visualization.Table(document.getElementById('patternformat_div'));
var formatter = new google.visualization.PatternFormat(
'
{0}');
// Apply formatter and set the formatted value of the first column.
formatter.format(data, [0, 1]);
var view = new google.visualization.DataView(data);
view.setColumns([0]); // Create a view with the first column only.
table.draw(view, {allowHtml: true, showRowNumber: true, width: '100%', height: '100%'});
```
## GadgetHelper
- A helper class to simplify writing [Gadgets](https://developers.google.com/gadgets) that use the Google Visualization API.
### Constructor
```
google.visualization.GadgetHelper()
```
### Methods
| Method | Return Value | Description |
|---|---|---|
| `createQueryFromPrefs(prefs)` | [google.visualization.Query](https://developers.google.com/chart/interactive/docs/reference#Query) | Static. Create a new instance of `google.visualization.Query` and set its properties according to values from the gadget preferences. The type of parameter `prefs` is [_IG_Prefs](https://developers.google.com/gadgets/docs/xml_reference#Userprefs_Ref) 1. Preference `_table_query_url` is used to set the Query data source URL. 2. Preference `_table_query_refresh_interval` is used to set the Query refresh interval (in seconds). |
| `validateResponse(response)` | Boolean | Static. Parameter `response` is of type [google.visualization.QueryResponse](https://developers.google.com/chart/interactive/docs/reference#QueryResponse). Returns `true` if the response contains data. Returns `false` if the query execution failed and the response does not contain data. If an error occurred, this method displays an error message. |
## Query Classes
- The following objects are available to send queries for data to an external data source, such as Google Spreadsheets.
- [Query](https://developers.google.com/chart/interactive/docs/reference#Query) - Wraps the outgoing data request.
- [QueryResponse](https://developers.google.com/chart/interactive/docs/reference#QueryResponse) - Handles the response from the data source.
## Query
- Represents a query that is sent to a data source.
### Constructor
```
google.visualization.Query(dataSourceUrl, opt_options)
```
- **Parameters**
*dataSourceUrl*
:
\[*Required* , *String* \] URL to send the query to. See the
[Charts and Spreadsheets documentation](https://developers.google.com/chart/interactive/docs/spreadsheets) for
Google Spreadsheets.
*opt_options*
:
\[*Optional, Object* \] A map of options for the request. **Note:** If you are
accessing a
[restricted data source](https://developers.google.com/chart/interactive/docs/dev/implementing_data_source#security_considerations),
you should not use this parameter. Here are the supported properties:
- **sendMethod** - \[*Optional, String* \] Specifies the method to use to send the query. Choose one of the following string values:
- **'xhr'** - Send the query using [XmlHttpRequest](http://en.wikipedia.org/wiki/XMLHttpRequest).
- **'scriptInjection'** - Send the query using script injection.
- **'makeRequest'** - \[*Available only for gadgets, which are
deprecated* \] Send the query using the Gadget API `https://developers.google.com/gadgets/docs/reference#gadgets.io.makeRequest` method. If specified, you should also specify **makeRequestParams**.
- **'auto'** - Use the method specified by the `tqrt` URL parameter from the data source URL. `tqrt` can have the following values: 'xhr', 'scriptInjection', or 'makeRequest'. If `tqrt` is missing or has an invalid value, the default is 'xhr' for same-domain requests and 'scriptInjection' for cross-domain requests.
- **makeRequestParams** - \[*Object* \] A map of parameters for a `makeRequest()` query. Used and required only if **sendMethod** is 'makeRequest'.
### Methods
| Method | Return Value | Description |
|---|---|---|
| `abort()` | None | Stops the automated query sending that was started with `setRefreshInterval()`. |
| `setRefreshInterval(seconds)` | None | Sets the query to automatically call the `send` method every specified duration (number of seconds), starting from the first explicit call to `send`. `seconds` is a number greater than or equal to zero. If you use this method, you should call it before calling the `send` method. Cancel this method either by calling it again with zero (the default), or by calling `abort()`. |
| `setTimeout(seconds)` | None | Sets the number of seconds to wait for the data source to respond before raising a timeout error. `seconds` is a number greater than zero. The default timeout is 30 seconds. This method, if used, should be called before calling the `send` method. |
| `setQuery(string)` | None | Sets the query string. The value of the `string` parameter should be a valid query. This method, if used, should be called before calling the `send` method. [Learn more about the Query language](https://developers.google.com/chart/interactive/docs/querylanguage). |
| `send(callback)` | None | Sends the query to the data source. `callback` should be a function that will be called when the data source responds. The callback function will receive a single parameter of type [google.visualization.QueryResponse](https://developers.google.com/chart/interactive/docs/reference#QueryResponse). |
## QueryResponse
- Represents a response of a query execution as received from the data source. An instance of this class is passed as an argument to the callback function that was set when [Query.send](https://developers.google.com/chart/interactive/docs/reference#Query_send) was called.
### Methods
| Method | Return Value | Description |
|---|---|---|
| `getDataTable()` | [DataTable](https://developers.google.com/chart/interactive/docs/reference#DataTable) | Returns the data table as returned by the data source. Returns `null` if the query execution failed and no data was returned. |
| `getDetailedMessage()` | String | Returns a detailed error message for queries that failed. If the query execution was successful, this method returns an empty string. The message returned is a message that is intended for developers, and may contain technical information, for example 'Column {salary} does not exist'. |
| `getMessage()` | String | Returns a short error message for queries that failed. If the query execution was successful, this method returns an empty string. The message returned is a short message that is intended for end users, for example 'Invalid Query' or 'Access Denied'. |
| `getReasons()` | Array of strings | Returns an array of zero of more entries. Each entry is a short string with an error or warning code that was raised while executing the query. Possible codes: - `access_denied` The user does not have permissions to access the data source. - `invalid_query` The specified query has a syntax error. - `data_truncated` One or more data rows that match the query selection were not returned due to output size limits. (warning). - `timeout` The query did not respond within the expected time. |
| `hasWarning()` | Boolean | Returns `true` if the query execution has any warning messages. |
| `isError()` | Boolean | Returns `true` if the query execution failed, and the response does not contain any data table. Returns \
if the query execution was successful and the response contains a data table. |
## Error Display
- The API provides several functions to help you display custom error messages to your users. To use these functions, provide a container element on the page (typically a ``), into which the API will draw a formatted error message. This container can be either the visualization container element, or a container just for errors. If you specify the visualization containe element, the error message will be displayed above the visualization. Then call the appropriate function below to show, or remove, the error message.
- All functions are static functions in the namespace `google.visualization.errors`.
- Many visualizations can throw an error event; see error event below to learn more about that.
- You can see an example custom error in the [Query Wrapper Example](https://developers.google.com/chart/interactive/docs/examples#querywrapper).
| Function | Return Value | Description |
|---|---|---|
| `addError(container, message, opt_detailedMessage, opt_options)` | String ID value that identifies the error object created. This is a unique value on the page, and can be used to remove the error or find its containing element. | Adds an error display block to the specified page element, with specified text and formatting. - *container* - The DOM element into which to insert the error message. If the container cannot be found, the function will throw a JavaScript error. - *message* - A string message to display. - *opt_detailedMessage* - An optional detailed message string. By default, this is mouseover text, but that can be changed in the *opt_options*.showInToolTip property described below. - *opt_options* - An optional object with properties that set various display options for the message. The following options are supported: - **showInTooltip** - A boolean value where true shows the detailed message only as tooltip text, and false shows the detailed message in the container body after the short message. Default value is true. - **type** - A string describing the error type, which determines which css styles should be applied to this message. The supported values are 'error' and 'warning'. Default value is 'error'. - **style** - A style string for the error message. This style will override any styles applied to the warning type (opt_options.type). Example: `'background-color: #33ff99; padding: 2px;'` Default value is an empty string. - **removable** - A boolean value, where true means that the message can be closed by a mouse click from the user. Default value is false. |
| `addErrorFromQueryResponse(container, response)` | String ID value that identifies the error object created, or null if the response didn't indicate an error. This is a unique value on the page, and can be used to remove the error or find its containing element. | Pass a query response and error message container to this method: if the query response indicates a query error, displays an error message in the specified page element. If the query response is null, the method will throw a JavaScript error. Pass your [QueryResponse](https://developers.google.com/chart/interactive/docs/reference#QueryResponse) received in your query handler to this message to display an error. It will also set the style of the display appropriate to the type (error or warning, similar to `addError(opt_options.type)`) - *container* - The DOM element into which to insert the error message. If the container cannot be found, the function will throw a JavaScript error. - *response* - A [QueryResponse](https://developers.google.com/chart/interactive/docs/reference#QueryResponse) object received by your query handler in response to a [query](https://developers.google.com/chart/interactive/docs/reference#Query). If this is null, the method will throw a JavaScript error. |
| `removeError(id) ` | Boolean: true if the error was removed; false otherwise. | Removes the error specified by ID from the page. - *id* - The string ID of an error created using `addError()` or `addErrorFromQueryResponse()`. |
| `removeAll(container) ` | None | Removes all error blocks from a specified container. If the specified container does not exist, this will throw an error. - *container* - The DOM element holding the error strings to remove. If the container cannot be found, the function will throw a JavaScript error. |
| `getContainer(errorId) ` | Handle to a DOM element holding the error specified, or null if it could not be found. | Retrieves a handle to the container element holding the error specified by *errorID*. - *errorId* - String ID of an error created using `addError()` or `addErrorFromQueryResponse()`. |
## Events
- Most visualizations fire events to indicate something has occurred. As a user of the chart, you would often want to listen to these events. If you [code your own visualization](https://developers.google.com/chart/interactive/docs/dev), you might also want to trigger such events on your own.
- The following methods enable developers to listen to events, remove existing event handlers or trigger events from inside a visualization.
- [google.visualization.events.addListener()](https://developers.google.com/chart/interactive/docs/reference#addlistener) and [google.visualization.events.addOneTimeListener()](https://developers.google.com/chart/interactive/docs/reference#addonetimelistener) listen for events.
- [google.visualization.events.removeListener()](https://developers.google.com/chart/interactive/docs/reference#removelistener) removes an existing listener
- [google.visualization.events.removeAllListeners()](https://developers.google.com/chart/interactive/docs/reference#removealllisteners) removes all listeners of a specific chart
- [google.visualization.events.trigger()](https://developers.google.com/chart/interactive/docs/reference#trigger) fires an event.
### addListener()
- Call this method to register to receive events fired by a visualization hosted on your page. You should document what event arguments, if any, will be passed to the handling function.
```
google.visualization.events.addListener(source_visualization,
event_name, handling_function)
```
*source_visualization*
: A handle to the source visualization instance.
*event_name*
:
The string name of the event to listen for. A visualization should document which events it
throws.
*handling_function*
:
The name of the local JavaScript function to call when source_visualization fires the
event_name event. The handling function will be passed any event arguments as parameters.
- **Returns**
- A listener handler for the new listener. The handler can be used to later remove this listener if needed by calling [google.visualization.events.removeListener()](https://developers.google.com/chart/interactive/docs/reference#removelistener).
- **Example**
- Here is an example of registering to receive the selection event
```
var table = new google.visualization.Table(document.getElementById('table_div'));
table.draw(data, options);
google.visualization.events.addListener(table, 'select', selectHandler);
function selectHandler() {
alert('A table row was selected');
}
```
### addOneTimeListener()
- This is identical to `addListener()`, but is intended for events that should only be listened to once. Subsequent throws of the event will not invoke the handling function.
- An example of when this is useful: every draw causes a `ready` event to be thrown. If you want only the first `ready` to execute your code, you'll want `addOneTimeListener` rather than `addListener`.
### removeListener()
- Call this method to unregister an existing event listener.
```
google.visualization.events.removeListener(listener_handler)
```
*listener_handler*
:
The listener handler to remove, as returned by
[google.visualization.events.addListener()](https://developers.google.com/chart/interactive/docs/reference#addlistener).
### removeAllListeners()
- Call this method to unregister all event listeners of a specific visualization instance.
```
google.visualization.events.removeAllListeners(source_visualization)
```
*source_visualization*
:
A handle to the source visualization instance from which all event listeners should be removed.
### trigger()
- Called by visualization *implementers*. Call this method from your visualization to fire an event with an arbitrary name and set of values.
```
google.visualization.events.trigger(source_visualization, event_name,
event_args)
```
*source_visualization*
:
A handle to the source visualization instance. If you are calling this function from within a
method defined by the sending visualization, you can simply pass in the `this`
keyword.
*event_name*
:
A string name to call the event. You can choose any string value that you want.
*event_args*
:
\[*optional*\] A map of name/value pairs to pass to the receiving method. For example:
{message: "Hello there!", score: 10, name: "Fred"}. You can pass null if no
events are needed; the receiver should be prepared to accept null for this parameter.
- **Example**
- Here is an example of a visualization that throws a method named "select" when its onclick method is called. It does not pass back any values.
```
MyVisualization.prototype.onclick = function(rowIndex) {
this.highlightRow(this.selectedRow, false); // Clear previous selection
this.highlightRow(rowIndex, true); // Highlight new selection
// Save the selected row index in case getSelection is called.
this.selectedRow = rowIndex;
// Trigger a select event.
google.visualization.events.trigger(this, 'select', null);
}
```
## Standard Visualization Methods and Properties
- Every visualization *should* expose the following set of required and optional methods and properties. However, note that there is no type checking to enforce these standards, so you should read the documentation for each visualization.
- [Constructor](https://developers.google.com/chart/interactive/docs/reference#visconstructor)
- [draw()](https://developers.google.com/chart/interactive/docs/reference#visdraw)
- getAction() \[*optional*\]
- [getSelection()](https://developers.google.com/chart/interactive/docs/reference#visgetselection) \[*optional*\]
- [removeAction()](https://developers.google.com/chart/interactive/docs/reference#visremoveaction) \[*optional*\]
- [setAction()](https://developers.google.com/chart/interactive/docs/reference#vissetaction) \[*optional*\]
- [setSelection()](https://developers.google.com/chart/interactive/docs/reference#vissetselection) \[*optional*\]
- **Note:** These methods are in the namespace of the visualization, *not* the google.visualization namespace.
### Constructor
- The constructor should have the name of your visualization class, and return an instance of that class.
```
visualization_class_name(dom_element)
```
*dom_element*
: A pointer to a DOM element where the visualization should be embedded.
- **Example**
```
var org = new google.visualization.OrgChart(document.getElementById('org_div'));
```
### draw()
- Draws the visualization on the page. Behind the scenes this can be fetching a graphic from a server or creating the graphic on the page using the linked visualization code. You should call this method every time the data or options change. The object should be drawn inside the DOM element passed into the constructor.
```
draw(data[, options])
```
*data*
:
A [`DataTable`](https://developers.google.com/chart/interactive/docs/reference#DataTable) or
`https://developers.google.com/chart/interactive/docs/reference#DataView` holding the data to use to draw the chart. There
is no standard method for extracting a `DataTable` from a chart.
*options*
:
\[*Optional* \] A map of name/value pairs of custom options. Examples include height and
width, background colors, and captions. The visualization documentation should list which
options are available, and should support default options if you do not specify this parameter.
You can use the JavaScript object literal syntax to pass in an options map: e.g.,
`{x:100, y:200, title:'An Example'}`
- **Example**
```
chart.draw(myData, {width: 400, height: 240, is3D: true, title: 'My Daily Activities'});
```
### getAction()
- This is optionally exposed by visualizations that have [tooltips](https://developers.google.com/chart/interactive/docs/customizing_tooltip_content) and allow [tooltip actions](https://developers.google.com/chart/interactive/docs/customizing_tooltip_content#tooltip_actions).
- Returns the tooltip action object with the requested `actionID`.
- **Example:**
```
// Returns the action object with the ID 'alertAction'.
chart.getAction('alertAction');
```
### getSelection()
- This is optionally exposed by visualizations that want to let you access the currently selected data in the graphic.
```
selection_array getSelection()
```
- **Returns**
- *selection_array* An array of selected objects, each one describing a data element in the underlying table used to create the visualization (a `DataView` or a `DataTable`). Each object has properties `row` and/or `column`, with the index of the row and/or column of the selected item in the underlying `DataTable`. If the `row` property is null, then the selection is a column; if the `column` property is null, then the selection is a row; if both are non-null, then it is a specific data item. You can call the `https://developers.google.com/chart/interactive/docs/reference#DataTable_getValue` method to get the value of the selected item. The retrieved array can be passed into `https://developers.google.com/chart/interactive/docs/reference#vissetselection`.
- **Example**
```
function myClickHandler(){
var selection = myVis.getSelection();
var message = '';
for (var i = 0; i < selection.length; i++) {
var item = selection[i];
if (item.row != null && item.column != null) {
message += '{row:' + item.row + ',column:' + item.column + '}';
} else if (item.row != null) {
message += '{row:' + item.row + '}';
} else if (item.column != null) {
message += '{column:' + item.column + '}';
}
}
if (message == '') {
message = 'nothing';
}
alert('You selected ' + message);
}
```
### removeAction()
- This is optionally exposed by visualizations that have [tooltips](https://developers.google.com/chart/interactive/docs/customizing_tooltip_content) and allow [tooltip actions](https://developers.google.com/chart/interactive/docs/customizing_tooltip_content#tooltip_actions).
- Removes the tooltip action object with the requested `actionID` from your chart.
- **Example:**
```
// Removes an action from chart with the ID of 'alertAction'.
chart.removeAction('alertAction');
```
### setAction()
- This is optionally exposed by visualizations that have [tooltips](https://developers.google.com/chart/interactive/docs/customizing_tooltip_content) and allow [tooltip actions](https://developers.google.com/chart/interactive/docs/customizing_tooltip_content#tooltip_actions). It works only for core charts (bar, column, line, area, scatter, combo, bubble, pie, donut, candlestick, histogram, stepped area).
- Sets a tooltip action to be executed when the user clicks on the action text.
```
setAction(action object)
```
- The `setAction` method takes an object as its action parameter. This object should specify 3 properties: `id`--- the ID of the action being set, `text` ---the text that should appear in the tooltip for the action, and `action` --- the function that should be run when a user clicks on the action text.
- Any and all tooltip actions should be set prior to calling the chart's `draw()` method.
- **Example:**
```
// Sets a tooltip action which will pop an alert box on the screen when triggered.
chart.setAction({
id: 'alertAction',
text: 'Trigger Alert',
action: function() {
alert('You have triggered an alert');
}
});
```
- The `setAction` method can also define two additional properties: `visible` and `enabled`. These properties should be functions that return `boolean` values indicating if the tooltip action will be visible and/or enabled.
- **Example:**
```
// The visible/enabled functions can contain any logic to determine their state
// as long as they return boolean values.
chart.setAction({
id: 'alertAction',
text: 'Trigger Alert',
action: function() {
alert('You have triggered an alert');
},
visible: function() {
return true;
},
enabled: function() {
return true;
}
});
```
### setSelection()
- Optionally selects a data entry in the visualization---for example, a point in an area chart, or a bar in a bar chart. When this method is called, the visualization should visually indicate what the new selection is. The implementation of `setSelection()` *should not* fire a "select" event. Visualizations may ignore part of the selection. For example, a table that can show only selected rows may ignore cell or column elements in its `setSelection()` implementation, or it can select the entire row.
- Every time this method is called, all selected items are deselected, and the new selection list passed in should be applied. There is no explicit way to deselect individual items; to deselect individual items, call `setSelection()` with the items to *remain selected* ; to deselect all elements, call `setSelection()`, `setSelection(null)`, or `setSelection([])`.
```
setSelection(selection_array)
```
*selection_array*
:
An array of objects, each with a numeric row and/or column property. `row` and
`column` are the zero-based row or column number of an item in the data table to
select. To select a whole column, set `row` to null; to select a whole row, set
`column` to null. **Example:**
`setSelection([{row:0,column:1},{row:1, column:null}])` selects the cell at (0,1)
and the entire row 1.
## Assorted Static Methods
- This section contains various useful methods exposed in the `google.visualization` namespace.
### arrayToDataTable()
- This method takes in a two-dimensional array and converts it to a DataTable.
- The column data types are determined automatically by the data provided. Column data types can also be specified using the object literal notation in the first row (the column header row) of the array (i.e. `{label: 'Start Date', type: 'date'}`). [Optional data roles](https://developers.google.com/chart/interactive/docs/roles) may be used as well, but they must be defined explicitly using object literal notation. Object literal notation may also be used for any cell, allowing you to define [Cell Objects](https://developers.google.com/chart/interactive/docs/reference#cell_object)).
- **Syntax**
```
google.visualization.arrayToDataTable(twoDArray, opt_firstRowIsData)
```
*twoDArray*
:
A two-dimensional array, where each row represents a row in the data table. If
*opt_firstRowIsData* is false (the default), the first row will be interpreted as
header labels. The data types of each column are interpreted automatically from the data given.
If a cell has no value, specify a null or empty value as appropriate.
*opt_firstRowIsData*
:
Whether the first row defines a header row or not. If true, all rows are assumed to be data. If
false, the first row is assumed to be a header row, and the values are assigned as column
labels. *Default is false.*
- **Returns**
- A new `DataTable`.
- **Examples**
- The following code demonstrates three ways to create the same `DataTable` object:
```javascript
// Version 1: arrayToDataTable method
var data2 = google.visualization.arrayToDataTable([
[{label: 'Country', type: 'string'},
{label: 'Population', type: 'number'},
{label: 'Area', type: 'number'},
{type: 'string', role: 'annotation'}],
['CN', 1324, 9640821, 'Annotated'],
['IN', 1133, 3287263, 'Annotated'],
['US', 304, 9629091, 'Annotated'],
['ID', 232, 1904569, 'Annotated'],
['BR', 187, 8514877, 'Annotated']
]);
// Version 2: DataTable.addRows
var data3 = new google.visualization.DataTable();
data3.addColumn('string','Country');
data3.addColumn('number','Population');
data3.addColumn('number','Area');
data3.addRows([
['CN', 1324, 9640821],
['IN', 1133, 3287263],
['US', 304, 9629091],
['ID', 232, 1904569],
['BR', 187, 8514877]
]);
// Version 3: DataTable.setValue
var data = new google.visualization.DataTable();
data.addColumn('string','Country');
data.addColumn('number', 'Population');
data.addColumn('number', 'Area');
data.addRows(5);
data.setValue(0, 0, 'CN');
data.setValue(0, 1, 1324);
data.setValue(0, 2, 9640821);
data.setValue(1, 0, 'IN');
data.setValue(1, 1, 1133);
data.setValue(1, 2, 3287263);
data.setValue(2, 0, 'US');
data.setValue(2, 1, 304);
data.setValue(2, 2, 9629091);
data.setValue(3, 0, 'ID');
data.setValue(3, 1, 232);
data.setValue(3, 2, 1904569);
data.setValue(4, 0, 'BR');
data.setValue(4, 1, 187);
data.setValue(4, 2, 8514877);
```
### drawChart()
- This method creates a chart in a single call. The advantage of using this method is that it requires slightly less code, and you can serialize and save visualizations as text strings for reuse. This method does not return a handle to the created chart, so you cannot assign method listeners to catch chart events.
- **Syntax**
```
google.visualization.drawChart(chart_JSON_or_object)
```
*chart_JSON_or_object*
:
Either a [JSON](http://www.json.org/) literal string or a JavaScript object, with
the following properties (case-sensitive):
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
| chartType | String | Required | none | The class name of the visualization. The `google.visualization` package name can be omitted for Google charts. If the appropriate visualization library has not already been loaded, this method will load the library for you if this is a Google visualization; you must load third party visualizations explicitly. **Examples:** `Table`, `PieChart`, `example.com.CrazyChart`. |
| containerId | String | Required | none | The ID of the DOM element on your page that will host the visualization. |
| options | Object | Optional | none | An object describing the options for the visualization. You can use either JavaScript literal notation, or provide a handle to the object. **Example:** `"options": {"width": 400, "height": 240, "is3D": true, "title": "Company Performance"}` |
| dataTable | Object | Optional | None | A `DataTable` used to populate the visualization. This can be a literal JSON string representation of a DataTable, as described [above](https://developers.google.com/chart/interactive/docs/reference#dataparam), or a handle to a populated `google.visualization.DataTable` object, or a 2-dimensional array like that accepted by ` https://developers.google.com/chart/interactive/docs/reference#google.visualization.arraytodatatable `. You must specify either this property or the `dataSourceUrl` property. |
| dataSourceUrl | String | Optional | None | A data source query to populate the chart data (for example, a [Google Spreadsheet](https://developers.google.com/chart/interactive/docs/spreadsheets)). You must specify either this property or the `dataTable` property. |
| query | String | Optional | None | If specifying `dataSourceUrl`, you can optionally specify a SQL-like query string using the [Visualization query language](https://developers.google.com/chart/interactive/docs/querylanguage) to filter or manipulate the data. |
| refreshInterval | Number | Optional | None | How often, in seconds, the visualization should refresh its query source. Use this only when specifying `dataSourceUrl`. |
| view | Object OR Array | Optional | None | Sets a `DataView` initializer object, which acts as a filter over the underlying data, as defined by either the `dataTable` or `dataSourceUrl` parameter. You can pass in either a string or `DataView` initializer object, like that returned by `https://developers.google.com/chart/interactive/docs/reference#DataView_toJSON`. **Example:** `"view": {"columns": [1, 2]}` You can also pass in an array of `DataView` initializer objects, in which case the first `DataView` in the array is applied to the underlying data to create a new data table, and the second `DataView` is applied to the data table resulting from application of the first `DataView`, and so on. |
- **Examples**
- Creates a table chart based on a spreadsheet data source, and includes the query SELECT A,D WHERE D \> 100 ORDER BY D
```javascript
```
- This next example creates the same table, but creates a `DataTable` locally:
```javascript
```
- This example passes in a JSON string representation of the chart, which you might have loaded from a file:
```javascript
```
### drawToolbar()
- This is the constructor for the toolbar element that can be attached to many visualizations. This toolbar enables the user to export the visualization data into different formats, or to provide an embeddable version of the visualization for use in different places. See the [toolbar page](https://developers.google.com/chart/interactive/docs/gallery/toolbar) for more information and a code example.