Configuring Charts

View as Markdown

Summary

  • AG Grid Charts can be defined and saved with AdapTable State
  • Locations can be provided where AG Grid Charts can be displayed

Defining Charts

AdapTable allows developers to define Charts and save them in Adaptable State.

Each Chart Definition contains just 2 properties:

  • Name - how the Chart appears in the AdapTable Charting UI
  • Model - the AG Grid chart model returned by getChartModels()
Developer Guide

Providing Chart Definitions in Initial State

const adaptableOptions: AdaptableOptions = {
  initialState: {
    Charting: {
      ChartDefinitions: [
        {
          Name: 'Top Frameworks',
          Model: {
            /* AG Grid ChartModel — prefer registering via Charting API */
          },
        },
      ],
    },
  },
};
1
Add ChartDefinitions under Charting State

Use when definitions are stable and you accept maintaining the model across AG Grid upgrades — or seed State once from an exported model.

2
Choose a Name

Provide a Name - this must be unique

3
Set Model

Model must match the AG Grid version in use

Dynamic Definitions

AG Grid chart models frequently change between AG Grid / AG Charts versions.

This can result in a saved Chart Definition in Initial State getting out of date.

A good way to avoid this is to leverage the add / edit Chart Definitions functions in Charting API.

Hint

  • Register definitions from a live chart (createRangeChart → addChartDefinition)
  • The demos on this page seed chart definitions in Adaptable Ready for that reason
Developer Guide

Registering Chart Definitions (recommended)

export const onAdaptableReady = ({
  adaptableApi,
  agGridApi,
}: AdaptableReadyInfo) => {
  const chartRef = agGridApi.createRangeChart({
    chartType: 'pie',
    chartThemeName: 'ag-vivid-dark',
    cellRange: {
      rowStartIndex: 0,
      rowEndIndex: 4,
      columns: ['name', 'github_stars'],
    },
  });
  const model = agGridApi
    .getChartModels()
    .find(m => m.chartId === chartRef?.chartId);
  if (model) {
    adaptableApi.chartingApi.addChartDefinition({
      Name: 'Top Frameworks',
      Model: model,
    });
  }
  if (chartRef) {
    chartRef.destroyChart();
  }
};
1
Create a range chart in AG Grid

Use agGridApi.createRangeChart with chartType, cellRange, and optional theme.

2
Add an AdapTable Chart Definition

Read the model from agGridApi.getChartModels(), then call chartingApi.addChartDefinition.

Destroy the temporary chart if it should not stay open.

Charts on Grouped Data

When the Layout has Row Grouping, a range Chart uses the Row Group Column as its category if either:

  • the Row Group Column (ag-Grid-AutoColumn) is in the Chart's cell range (e.g. the user selected group cells when creating the Chart)
  • useGroupColumnAsCategory is set to true

Otherwise the category is a column from the Chart's cell range (e.g. model).

useGroupColumnAsCategory is saved in the Chart's Model, so a Chart Definition keeps it when the Chart is reopened.

Hint

To always chart grouped rows by their group, set useGroupColumnAsCategory: true in createRangeChart, or in the Model of a Chart Definition in Initial State

const chartRef = agGridApi.createRangeChart({
  chartType: 'groupedColumn',
  cellRange: {
    columns: ['model', 'price'],
  },
  // category is the Row Group Column whenever the Layout is grouped
  useGroupColumnAsCategory: true,
});

Providing Chart Locations

AdapTable also allows developers to provide details of Chart Locations.

This is done through the chartContainers property of Charting Options.

Each location contains a Name and a reference to the Div element where Charts can be displayed.

Deep Dive

Understanding Chart Containers

The default Chart Container is the one provided by AG Grid and named 'AG Grid Window' by AdapTable

Hint

Use the agGridContainerName property in Charting Options to provide a different name for this container

Opening Charts Automatically

There are 2 main use cases where AdapTable might open a Chart automatically:

  • when the application loads
  • when a Layout is selected

On Startup

Use this when you want saved chart definitions opened as soon as AdapTable is ready, without listing charts on the active Layout.

restoreChartsOnReady

Default: undefined (no charts opened automatically)
boolean | 'all' | string[]
Open saved AG Grid charts when AdapTable loads

Per Layout

Add OpenCharts to a Table Layout or Pivot Layout:

OpenCharts: [
  { ChartName: 'Top Frameworks', ContainerName: 'Above Grid' },
  { ChartName: 'Summary Chart' }, // optional — uses the AG Grid chart window
],

Chart names must be unique across all AG Grid and external chart definitions.

The chart wizard enforces this when saving or editing.

When the layout is selected, AdapTable closes other open AG Grid charts and opens the listed charts in the given containers.

Use an empty array (OpenCharts: []) to close all charts for that layout.

Find Out More

See Using Charts for a demo that re-opens charts via Application State and Layouts

Chart Locations
Fork
  • This example demonstrates how to define Charts and Chart Locations
  • 2 Charts are registered in Adaptable Ready (onAdaptableReady.ts / seedChartDefinitions.ts):
    • Top Frameworks - a Pie Chart
    • Issues & PRs - a 100% stacked Bar Chart
  • 2 Chart locations are provided in the chartContainers property of Charting Options:
    • Above Grid - appears above the Grid
    • Below Grid - appears below the Grid
  • Additionally the agGridContainerName property has been set to 'Over Grid' - which overrides the default label of 'AG Grid Window'
Try It Out
  • Open Top Frameworks in the Above Grid chart location
  • Open Issues & PRs in the Below Grid chart location
Loading demo…

Multiple Charts in a Location

By default AdapTable will display one chart in each provided Location.

This means that loading a new chart will displace any currently displayed Chart.

This behaviour can be changed by setting chartsDisplay to 'multiple' on a ChartContainer in chartContainers.

When chartsDisplay is 'multiple', charts are appended to that container's element.

Caution

  • To place multiple charts in a container, it needs a fixed height - e.g. max-height or display: flex
  • Without this the charts will grow inside the Div infinitely
Multiple Charts in Location
Fork
  • This example demonstrates how to show multiple charts in the same location:
    • The Above Grid chart container has chartsDisplay: 'multiple' (see adaptableOptions.ts and onAdaptableReady.ts in the demo tabs)
    • Two chart definitions are registered in Adaptable Ready
    • The container uses display: flex in CSS so multiple charts can share the div
    • In the Adaptable Ready Event, Charting API methods open both charts in that container
Try It Out
  • Use the Charting toolbar to open each chart in Above Grid and confirm both can remain visible
Loading demo…

agGridContainerName

Default: AG Grid Window
String
Name of AG Grid Chart Container

chartContainers

Locations to display saved Charts

saveChartBehaviour

Default: none
'auto' | 'manual' | 'none'
Behaviour for saving Charts into AdapTable State