Sparkline Column

Summary

Sparkline Columns are AdapTable Columns which wrap AG Grid's Sparkline Charts functionality
This allows them to be easily created, edited and saved at runtime
Most Sparkline Columns contain an array of numbers, but advanced columns can contain Tuples and Objects

Sparkline Columns allow Sparklines to be easily displayed in Column form and then saved in Layouts.

The Sparklines are the AG Grid Sparklines provided as part of their excellent Charting package.

Sparkline Columns can be provided by developers at Design Time or created / edited by run-time users.

Hint

Sparkline Columns created at design time must have an appropriate Array Cell Data Type
The Column Type has to be numberArray, tupleArray or objectArray

Anatomy

A Sparkline cell consists of:

An inline mini-chart rendered from the cell's array value (numbers, tuples or objects).
One of four chart types — Line, Area, Bar or Column — picked at the column level.
Optional axes, point markers, tooltips and formatters, all driven by the underlying AG Grid Sparkline options.

The cell value must be an array — the column's Cell Data Type must be numberArray, tupleArray or objectArray.

Column-level options on SparklineStyle:

options — AG Grid AgSparklineOptions (type, colours, axis, markers, tooltips, xKey / yKey for object data, etc.)
Cell (optional) — CellBoxStyle drawn behind the chart (background, border, radius). When set, it claims the Cell slice from any matching Format Column

Note

Sparkline columns render on Data rows only — Group, Summary and Total rows are not supported (see Styled Columns Overview).

Sparkline Types

AG Grid Sparkline Columns can be of 4 types:

Each of these types is fully supported by AdapTable.

In the wizard, AG Grid's vertical bar sparkline is labelled Column; the horizontal bar is labelled Bar (both use type: 'bar' with different direction).

A Sparkline Column works on an array of data, rather than a single value.

Caution

To use Sparkline Columns - you must have the AG Grid SparklinesModule Module installed

Numeric Array

Sparkline data most typically takes the form of standard numeric arrays (e.g. history data).

Styled Column: Sparkline

Fork Fork

Overview demo — four sparkline columns share the hidden History source field (numberArray), each with a different AG Grid chart type:
- History - Line — line with markers
- History - Area — area with category axis
- History - Bar — horizontal bar
- History - Column — vertical bar (direction: 'vertical')

Try It Out

Create a Sparkline Column in the Wizard for the History column
Click Edit First Row in the Dashboard to copy another row's history into the first row — all four sparklines update

import {
  AdaptableButton,
  AdaptableOptions,
  CellUpdateRequest,
  CustomToolbarButtonContext,
  GridApi,
} from '@adaptabletools/adaptable';
import {IRowNode} from 'ag-grid-enterprise';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Sparkline Columns Basic',
  dashboardOptions: {
    customToolbars: [
      {
        name: 'ButtonToolbar',
        title: 'Buttons',
        toolbarButtons: [
          {
            label: 'Edit First Row',
            onClick: (
              button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              // Get handle to Grid APi
              const gridApi: GridApi = context.adaptableApi.gridApi;
              const firstNode = gridApi.getFirstRowNode();
              const meteorNode = gridApi.getRowNodeForPrimaryKey(3214406);
              if (firstNode && meteorNode) {
                const cellUpdateRequest: CellUpdateRequest = {
                  columnId: 'history',
                  newValue: meteorNode.data['history'],
                  primaryKeyValue:
                    gridApi.getPrimaryKeyValueForRowNode(firstNode),
                  rowNode: firstNode,
                };
                gridApi.setCellValue(cellUpdateRequest);
              }
            },
            buttonStyle: {
              tone: 'info',
              variant: 'text',
            },
          },
        ],
      },
    ],
  },
  initialState: {
    Dashboard: {
      ModuleButtons: ['StyledColumn', 'SettingsPanel'],
      PinnedToolbars: ['ButtonToolbar'],
    },
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Sparklines',
      Layouts: [
        {
          Name: 'Sparklines',
          TableColumns: [
            'name',
            'historyLine',
            'language',
            'historyArea',
            'github_stars',
            'historyBar',
            'license',
            'historyColumn',
            'history',
          ],
          AutoSizeColumns: true,
        },
      ],
    },
    StyledColumn: {
      StyledColumns: [
        {
          ColumnId: 'historyLine',
          Name: 'historyLine Sparkline',
          SparklineStyle: {
            options: {
              type: 'line',
              stroke: 'rgb(124, 255, 178)',
              strokeWidth: 2,
              padding: {
                top: 5,
                bottom: 5,
              },
              marker: {
                enabled: true,
                size: 3,
                shape: 'diamond',
              },
            },
          },
        },
        {
          ColumnId: 'historyArea',
          Name: 'historyArea Sparkline',
          SparklineStyle: {
            options: {
              type: 'area',
              fill: 'rgba(216, 204, 235, 0.3)',
              stroke: 'rgb(119,77,185)',
              axis: {
                type: 'category',
                stroke: 'rgb(204, 204, 235)',
              },
            },
          },
        },
        {
          ColumnId: 'historyBar',
          Name: 'historyBar Sparkline',
          SparklineStyle: {
            options: {
              type: 'bar',
              direction: 'horizontal',
              fill: '#5470c6',
              stroke: '#91cc75',
            },
          },
        },
        {
          ColumnId: 'historyColumn',
          Name: 'historyColumn Sparkline',
          SparklineStyle: {
            options: {
              type: 'bar',
              direction: 'vertical',
              fill: '#90D5FF',
              stroke: '#90D5FF',
              axis: {
                type: 'category',
                paddingInner: 0.3,
                paddingOuter: 0.1,
              },
            },
          },
        },
      ],
    },
  },
};

Cell Style

Optional SparklineStyle.Cell styles the cell box behind the chart — useful when you want a bordered or tinted panel around the sparkline without affecting the chart options themselves.

Sparkline: Cell Style

Fork Fork

History - Line — SparklineStyle.Cell (background, border, radius) plus a line sparkline with markers
The chart options and cell Cell styling are independent — same pattern as Badge Style cell chrome

Advanced Array Types

More advanced Sparkline Columns can use complex, rather than numeric, arrays.

These arrays can be of 3 types:

Tuple Array

In a Tuple Array the data is provided in a array of arrays each of which has 2 values:

[ [14, 22], [5, 13], [19, 30] ]

Note

Tuple Arrays should provide a Cell Data Type of tupleArray

Standard Object Array

AG Grid Sparklines can also receive objects.

These objects, by convention, will contain 2 properties: x and y:

[ {x: 14, y: 22}, {x: 5, y: 13},  {x: 19, y: 30} ]

Note

Standard Object Arrays should provide a Cell Data Type of objectArray

Non-Standard Object Array

AG Grid Sparklines can also be created with objects that do not have the standard x and y properties.

However they are still required to contain 2 properties, which are needed for the 2 axes:

[ {xVal: 14, yVal: 22}, {xVal: 5, yVal: 13},  {xVal: 19, yVal: 30} ]

Note

Non-Standard Object Arrays should also provide a Cell Data Type of objectArray

Styled Column: Sparkline Advanced

Fork Fork

Three sparkline columns show the same history data in non-numeric array shapes:
- History - Tuple — tupleArray data, vertical bar (Column) sparkline
- History - Object — standard { x, y } objects, area sparkline
- History - Object Non Standard — custom property names via xKey / yKey on the line sparkline

import {AdaptableOptions} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Sparkline Columns Advanced',
  initialState: {
    Dashboard: {
      ModuleButtons: ['StyledColumn', 'SettingsPanel'],
    },
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Sparklines',
      Layouts: [
        {
          Name: 'Sparklines',
          TableColumns: [
            'name',
            'historyTuple',
            'historyObject',
            'historyObjectNonStandard',
            'language',
            'github_stars',
            'license',
          ],
          AutoSizeColumns: true,
        },
      ],
    },
    StyledColumn: {
      StyledColumns: [
        {
          ColumnId: 'historyTuple',
          Name: 'historyTuple Sparkline',
          SparklineStyle: {
            options: {
              type: 'bar',
              direction: 'vertical',
              fill: '#91cc75',
              stroke: '#91cc75',
              highlight: {
                highlightedItem: {
                  fill: 'orange',
                  strokeWidth: 0,
                },
              },
              axis: {
                type: 'category',
                paddingInner: 0.3,
                paddingOuter: 0.1,
              },
            },
          },
        },
        {
          ColumnId: 'historyObject',
          Name: 'historyObject Sparkline',
          SparklineStyle: {
            options: {
              type: 'area',
              fill: 'rgba(216, 204, 235, 0.3)',
              stroke: 'rgb(119,77,185)',
              highlight: {
                highlightedItem: {
                  fill: 'rgb(143,185,77)',
                  strokeWidth: 0,
                },
              },
              axis: {
                type: 'category',
                stroke: 'rgb(204, 204, 235)',
              },
            },
          },
        },

        {
          ColumnId: 'historyObjectNonStandard',
          Name: 'historyObjectNonStandard Sparkline',
          SparklineStyle: {
            options: {
              stroke: 'rgb(234, 221, 202)',
              strokeWidth: 2,
              type: 'line',
              xKey: 'xVal',
              yKey: 'yVal',
            },
          },
        },
      ],
    },
  },
};

Sparkline Calculated Columns

Sparkline Columns can be used by Calculated Columns to render Array data.

Most typically the Calculated Column will use the TO_ARRAY Expression Function to create the data.

Sparkline Columns: Calculated

Fork Fork

Two Calculated Columns use TO_ARRAY and render as sparklines:
- Statistics — area sparkline over [Open PRs, Closed PRs, Open Issues, Closed Issues]
- Github — horizontal bar sparkline over [GitHub Stars, GitHub Watchers × 30]

import {AdaptableOptions} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Sparkline Calculated Columns',
  initialState: {
    Dashboard: {
      ModuleButtons: ['CalculatedColumn', 'StyledColumn', 'SettingsPanel'],
    },
    StatusBar: {
      StatusBars: [
        {
          Key: 'Center Panel',
          StatusBarPanels: ['Layout', 'CalculatedColumn'],
        },
      ],
    },
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          TableColumns: [
            'name',
            'stats',
            'open_pr_count',
            'closed_pr_count',
            'open_issues_count',
            'closed_issues_count',
            'github',
            'github_stars',
            'github_watchers',
            'language',
            'license',
            'created_at',
            'has_wiki',
            'updated_at',
            'pushed_at',
            'has_projects',
            'has_pages',
            'week_issue_change',
          ],
          Name: 'Standard Layout',
          ColumnSizing: {
            name: {Width: 100},
            open_pr_count: {Width: 120},
            closed_pr_count: {Width: 120},
            open_issues_count: {Width: 130},
            closed_issues_count: {Width: 130},
          },
        },
      ],
    },
    CalculatedColumn: {
      CalculatedColumns: [
        {
          ColumnId: 'stats',
          FriendlyName: 'Statistics',
          Query: {
            ScalarExpression:
              'TO_ARRAY([open_pr_count], [closed_pr_count], [open_issues_count], [closed_issues_count])',
          },
          CalculatedColumnSettings: {
            Resizable: true,
            DataType: 'numberArray',
          },
        },
        {
          ColumnId: 'github',
          FriendlyName: 'Github',
          Query: {
            ScalarExpression:
              'TO_ARRAY([github_stars], [github_watchers] * 30)',
          },
          CalculatedColumnSettings: {
            Resizable: true,
            DataType: 'numberArray',
          },
        },
      ],
    },
    StyledColumn: {
      StyledColumns: [
        {
          ColumnId: 'stats',
          Name: 'stats Sparkline',
          SparklineStyle: {
            options: {
              type: 'area',
              fill: 'rgba(216, 204, 235, 0.3)',
              stroke: 'rgb(119,77,185)',
              axis: {
                type: 'category',
                stroke: 'rgb(204, 204, 235)',
              },
            },
          },
        },
        {
          ColumnId: 'github',
          Name: 'github Sparkline',
          SparklineStyle: {
            options: {
              type: 'bar',
              direction: 'horizontal',
              fill: '#5470c6',
              stroke: '#91cc75',
            },
          },
        },
      ],
    },
  },
};

Defining Sparkline Columns

Sparkline Styles are provided at design-time through Styled Column Initial State.

Developer Guide

Providing a Sparkline Style in Styled Column State

const initialState: InitialState = {
  StyledColumn: {
    StyledColumns: [
      {
        ColumnId: 'historyLine',
        Name: 'History Line',
        SparklineStyle: {
          options: {
            type: 'line',
            stroke: 'rgb(124, 255, 178)',
            strokeWidth: 2,
            marker: { enabled: true, size: 3 },
          },
          Cell: {
            BackColor: 'rgba(255, 255, 255, 0.06)',
            BorderColor: 'rgba(124, 255, 178, 0.35)',
            BorderRadius: 6,
          },
        },
      },
    ],
  },
};

Provide ColumnId, Name and SparklineStyle

ColumnId — must reference a column with numberArray, tupleArray or objectArray data type
Name — unique styled column name
SparklineStyle — wrapper for chart options and optional cell chrome

Set AG Grid sparkline options

SparklineStyle.options is passed through to AG Grid — set type (line, area, bar), colours, axis, markers, tooltips, and for object arrays xKey / yKey when properties are not x / y.

Find Out More

See AG Grid Sparklines for the full options surface.

(Optional) Cell chrome

SparklineStyle.Cell — optional CellBoxStyle behind the chart. When set, matching Format Column cell-box properties are stripped for that column.

Creating Sparkline Columns

Sparkline Styles can be created at run-time using the Styled Column UI Wizard.

UI Step by Step Guide

Creating a Sparkline Style using the Styled Column Wizard

FAQ

Can we export Sparkline Columns when using the VisualExcel Report Format? Not currently, but we plan to look at this in a forthcoming release

I cannot see the Sparkline Column in my Grid? Make sure you have the AG Grid SparklinesModule Module installed

Why are there no columns visible in the Wizard when I try to create a sparkline? AdapTable will only display columns which have an appropriate Cell Data Types for a Sparkline Column. This needs to be one of numberArray, tupleArray or objectArray

PreviousBadge Style NextBullet Chart Style