Configuring Charts
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 UIModel- the AG Grid chart model returned bygetChartModels()
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 */
},
},
],
},
},
};Use when definitions are stable and you accept maintaining the model across AG Grid upgrades — or seed State once from an exported model.
Provide a Name - this must be unique
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();
}
};Use agGridApi.createRangeChart with chartType, cellRange, and optional theme.
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) useGroupColumnAsCategoryis set totrue
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[]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
- 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 ChartIssues & PRs- a 100% stacked Bar Chart
- 2 Chart locations are provided in the
chartContainersproperty of Charting Options:Above Grid- appears above the GridBelow Grid- appears below the Grid
- Additionally the
agGridContainerNameproperty has been set to 'Over Grid' - which overrides the default label of 'AG Grid Window'
- Open Top Frameworks in the
Above Gridchart location - Open Issues & PRs in the
Below Gridchart location
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-heightordisplay: flex - Without this the charts will grow inside the Div infinitely
- This example demonstrates how to show multiple charts in the same location:
- The Above Grid chart container has
chartsDisplay: 'multiple'(seeadaptableOptions.tsandonAdaptableReady.tsin the demo tabs) - Two chart definitions are registered in Adaptable Ready
- The container uses
display: flexin CSS so multiple charts can share the div - In the Adaptable Ready Event, Charting API methods open both charts in that container
- The Above Grid chart container has
- Use the Charting toolbar to open each chart in Above Grid and confirm both can remain visible
agGridContainerName
Default: AG Grid WindowStringchartContainers
saveChartBehaviour
Default: none'auto' | 'manual' | 'none'