Chart API

This section covers how to use the chart range API in your applications.

Charting Range API

Charts can be created programmatically via the grid's chartRange() API. The interface is as follows:

function chartRange(params: ChartRangeParams): ChartRef | undefined { cellRange: CellRangeParams; chartType: string; chartContainer?: HTMLElement; suppressChartRanges?: boolean; aggregate?: boolean; processChartOptions?: (params: ProcessChartOptionsParams) => ChartOptions; } interface CellRangeParams { // start row rowStartIndex?: number; rowStartPinned?: string; // end row rowEndIndex?: number; rowEndPinned?: string; // columns columnStart?: string | Column; columnEnd?: string | Column; columns?: (string | Column)[]; } export interface ProcessChartOptionsParams { type: string; options: ChartOptions; }

The provided params contains the following attributes:

  • cellRange: 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 (ie 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 details.
  • chartType: The type of chart to create; i.e. 'groupedBar', 'stackedBar', 'pie', 'doughnut' or 'line'.
  • chartContainer: If the chart is to be displayed outside of the grid then provide a chart container. If the chart is to be displayed using the grid's popup window mechanism then leave undefined.
  • suppressChartRanges: Normally 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 suppressChartRanges=true.
  • aggregate: When set to true, series values will be summed for each category before charting.
  • processChartOptions: Options for changing the display of the chart. This works the same as the grid callback processChartOptions described in Chart Customisation.

The API returns a ChartRef object when a chartContainer is provided. This is the same structure that is provided to the createChartContainer() callback. The ChartRef provides the application with the destroyChart() method that is required when the application wants to dispose the chart.

API Example 1 - Chart Range in Grid Window

This example gets the grid to chart data 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).

API Example 2 - 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 div elements 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 legend on the bottom. This is configured in the processChartOptions().

Next Up

Continue to the next section to learn how to: Provide a Chart Container.