In addition to users creating their own charts from the grid, charts can also be generated by using the Chart API.
Charts can be created programmatically from a range via the grid's
createRangeChart() API. The
interface is as follows:
|Defines the range of cells to be charted. A range is normally defined with start and end rows and a list of columns. If the start and end rows are omitted, the range covers all rows (i.e. entire columns are selected). The columns can either be defined using a start and end column (the range will cover the start and end columns and all columns in between), or columns can be supplied specifically in cases where the required columns are not adjacent to each other. See Add Cell Range for more information. See cellRange for more details about this configuration object.|
|The type of chart to create.|
|The default theme to use for the created chart. In addition to the default options you listed, you can also provide your own custom chart themes.|
|If the chart is to be displayed outside of the grid then a chart container should be provided. If the chart is to be displayed using the grid's popup window mechanism then leave as |
|By default, when a chart is displayed using the grid, the grid will highlight the range the chart is charting when the chart gets focus. To suppress this behaviour, set |
|The aggregation function that should be applied to all series data. The built-in aggregation functions are |
|Allows specific chart options in the current theme to be overridden. See Overriding Existing Themes.|
Defines the range of cells to be charted. A range is normally defined with start and end rows and a list of columns. If the start and end rows are omitted, the range covers all rows (i.e. entire columns are selected). The columns can either be defined using a start and end column (the range will cover the start and end columns and all columns in between), or columns can be supplied specifically in cases where the required columns are not adjacent to each other. See Add Cell Range for more information.
|The index of the first row in the range.|
|Sets whether the first row is pinned.|
|The index of the last row in the range.|
|Sets whether the last row is pinned.|
|The first column of the range.|
|The last column of the range.|
|The columns in the range. Used instead of |
The API returns a
ChartRef object when a
chartContainer is provided.
This is the same structure that is provided to the
ChartRef provides the application with the
method that is required when the application wants to dispose the chart.
Example: Charts in Grid Popup Window
This example shows how charts can be created in the grid's provided popup window. The following can be noted:
- Clicking 'Gold & Silver, 5 Rows' will chart the first five rows of Gold and Silver by Country.
- Clicking 'Bronze, All Rows' will chart Bronze by Country using all rows (the provided cell range does not specify rows).
Example: Charts in Dashboard
This example passes a
chartContainer to the API to place the chart in a location other
than the grid's popup window. The following can be noted:
- The charts are placed in
divelements outside of the grid.
- The two pie charts are showing aggregations rather than charting individual rows.
- Clicking on a chart highlights the range in the grid for which the chart is based.
- The bar chart is sensitive to changes in the rows. For example if you sort, the chart updates to always chart the first five rows.
- All data is editable in the grid. Changes to the grid data is reflected in the charts.
The two pie charts have legends beneath. This is configured in the
You can also use the API to create a pivot chart. There are fewer parameters available as the pivot chart is always generated from all data in the grid:
The attributes have the same behaviour as described earlier.
Example: Pivot Chart
This is an example showing the pivot chart API in action, using a specified chart container.
Saving and Restoring Charts
You can access models that represent rendered charts using the
getChartModels() API. The models are returned in a format that can be
easily used with the other API methods to later recreate the chart. You can also retrieve a base64 encoded image rendered from the chart in the model.
Example: Saving and Restoring Charts
The example below demonstrates how you can save and then later restore a chart. You can make changes to the chart type, theme, data and formatting options and note how the restored chart looks the same as the chart that was saved.
It also shows how you can retrieve images rendered from the chart in multiple formats.
- Create a range chart from the grid, which will be shown in a container below the grid.
- Change the chart type, theme, data and/or formatting in order to see the changes restored later.
- Click "Save chart" to persist a model of the visible chart into a local variable. An alert will be shown to confirm that this has happened.
- Click "Clear chart" to destroy the existing chart.
- Click "Restore chart" to restore the previously saved chart.
- Click "Open PNG" to open a PNG format image of the chart in a new window.
- Click "Open JPG" to open a JPG format image of the chart in a new window.
Continue to the next section to learn about: Chart Events.