AdapTable Version:

Framework:

Selecting using Grid API Functions

Summary

Methods in Grid API allow cells and rows to be selected programatically
Cell Ranges, Columns and Rows can all be selected
Additionally selection can be done using Expressions

The Grid API section of AdapTable API can be used for both selection and highlighting.

The selection and highlighting related functions include:

selecting cell ranges using row indexes, primary key values or AdapTableQL Expressions
selecting whole columns
unselecting cells or columns

Selecting Ranges

It is straightforward to select a range of Cells in AdapTable by using the selectCellRange function in Grid API.

The range can be uniquely defined in 2 main ways:

using row indexes - i.e. the index of the row as currently positioned in the Grid
using Primary Key Column values

Hint
This ensures the same range is always selected irrespective of current Grid sorting

Selecting Cell Ranges

Fork Fork

In this demo we use the range selection methods in Grid API to:
- select a groups of cells across the Name and Language columns using row index
- select another group of cells across the Github Stars and License columns using primary keys
- deselect all selected cells

Expand to see the Grid API methods used

// Select some cells using Row Indexing
const rowIndexCellRange: GridCellRange = {
  columnIds: ['name', 'language'],
  rowIndexStart: 0,
  rowIndexEnd: 4,
};
adaptableApi.gridApi.selectCellRange(rowIndexCellRange);

// Select some cells using Primary Keys
const primaryKeyCellRange: GridCellRange = {
  columnIds: ['github_stars', 'license'],
  primaryKeyValueStart: 76694515,
  primaryKeyValueEnd: 5532320,
};
adaptableApi.gridApi.selectCellRange(primaryKeyCellRange);

import {
  AdaptableButton,
  AdaptableOptions,
  CustomToolbarButtonContext,
  GridCellRange,
} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Range Selection API',
  dashboardOptions: {
    customToolbars: [
      {
        name: 'ButtonToolbar',
        title: 'Buttons',
        toolbarButtons: [
          {
            label: 'Select Name/Language Range',
            onClick: (
              button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              const rowIndexCellRange: GridCellRange = {
                columnIds: ['name', 'language'],
                rowIndexStart: 0,
                rowIndexEnd: 4,
              };
              context.adaptableApi.gridApi.selectCellRange(rowIndexCellRange);
            },
            buttonStyle: {
              tone: 'info',
              variant: 'text',
            },
          },
          {
            label: 'Select Stars / License Range',
            onClick: (
              button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              const primaryKeyCellRange: GridCellRange = {
                columnIds: ['github_stars', 'license'],
                primaryKeyValueStart: 76694515,
                primaryKeyValueEnd: 5532320,
              };
              context.adaptableApi.gridApi.selectCellRange(primaryKeyCellRange);
            },
            buttonStyle: {
              tone: 'success',
              variant: 'text',
            },
          },
          {
            label: 'Select Watchers',
            onClick: (
              button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              const primaryKeyCellRange: GridCellRange = {
                columnIds: ['github_watchers'],
                primaryKeyValueStart: 76694515,
                primaryKeyValueEnd: 5532320,
              };
              context.adaptableApi.gridApi.selectCellRange(primaryKeyCellRange);
            },
            buttonStyle: {
              tone: 'warning',
              variant: 'text',
            },
          },
          {
            label: 'Clear Selection',
            onClick: (
              button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              context.adaptableApi.gridApi.deselectAll();
            },
            buttonStyle: {
              tone: 'error',
              variant: 'text',
            },
          },
        ],
      },
    ],
  },
  initialState: {
    Dashboard: {
      PinnedToolbars: ['ButtonToolbar'],
    },
    StatusBar: {
      StatusBars: [
        {
          Key: 'Center Panel',
          StatusBarPanels: ['CellSummary'],
        },
      ],
    },
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          TableColumns: [
            'name',
            'language',
            'github_stars',
            'license',
            'created_at',
            'github_watchers',
            'has_wiki',
            'updated_at',
            'pushed_at',
            'description',
            'open_issues_count',
            'closed_issues_count',
            'open_pr_count',
            'closed_pr_count',
            'has_projects',
            'has_pages',
            'week_issue_change',
          ],
          Name: 'Standard Layout',
          AutoSizeColumns: true,
        },
      ],
    },
  },
};

Selecting using Expressions

An alternative way to select Rows and Cells in AdapTable is by an Expression.

The selectCellRangeByQuery function in Grid API receives a Standard Expression.

The Expression is evaluated by AdapTableQL and those rows that match the query are selected.

Note

This means by default the whole Row will be selected if the Query returns true.

Hint

To select cells only, pass in a Range to the function
Only cells which are contained in that Range will be selected by AdapTable

Selecting using Expressions

Fork Fork

In this demo we use the Grid API to select rows and cells using Expressions, (via 5 Custom Toolbar Buttons) as follows:
- First button selects cells where License is Other - we use a range to limit the selection of cells to just the License column
- Second button selects whole row where Language is "HTML" (using Expression [language]="HTML")
- Third button creates a "Big Starts" Range so that the the Name, Github Stars and Github Watchers Columns are selected (using Expression [github_stars]>40000)
- Fourth button calls ExportApi to run the Selected Data Report sending currently selected data to Excel
- Final button calls Clear Selection - which clears the current selection

import {
  AdaptableButton,
  AdaptableOptions,
  CustomToolbarButtonContext,
  DashboardButtonContext,
  GridCellRange,
} from '@adaptabletools/adaptable';
import {rowData, WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Expression Selection API',
  dashboardOptions: {
    customToolbars: [
      {
        name: 'ButtonToolbar',
        title: 'Buttons',
        toolbarButtons: [
          {
            label: 'Select Licence is "Other"',
            onClick: (
              button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              // Select cells where licencse is 'Other'
              const otherLicenseQuery: string = '[license]="Other"';
              // Create range for the column to ensure just cells in license are selected
              const licenseCellRange: GridCellRange = {
                columnIds: ['license'],
                rowIndexStart: 0,
                rowIndexEnd: 24,
              };

              context.adaptableApi.gridApi.selectCellRangeByQuery(
                otherLicenseQuery,
                licenseCellRange
              );
            },
            buttonStyle: {
              tone: 'info',
              variant: 'text',
            },
          },
          {
            label: 'Select HTML Rows',
            onClick: (
              button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              const isHTMLQuery: string = '[language]="HTML"';
              context.adaptableApi.gridApi.selectCellRangeByQuery(isHTMLQuery);
            },
            buttonStyle: {
              tone: 'success',
              variant: 'text',
            },
          },
          {
            label: 'Select Big Stars',
            onClick: (
              button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              const bigStars: string = '[github_stars]>40000';
              const cellRange: GridCellRange = {
                columnIds: ['name', 'github_stars', 'github_watchers'],
                rowIndexStart: 0,
                rowIndexEnd: 24,
              };

              context.adaptableApi.gridApi.selectCellRangeByQuery(
                bigStars,
                cellRange
              );
            },
            buttonStyle: {
              tone: 'warning',
              variant: 'text',
            },
          },
          {
            label: 'Export Selection',
            onClick: (
              button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              context.adaptableApi.exportApi.exportReport(
                'Selected Cells',
                'Excel'
              );
            },
            buttonStyle: {
              tone: 'accent',
              variant: 'text',
            },
          },
          {
            label: 'Clear Selection',
            onClick: (
              button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              context.adaptableApi.gridApi.deselectAll();
            },
            buttonStyle: {
              tone: 'error',
              variant: 'text',
            },
          },
        ],
      },
    ],
  },

  initialState: {
    Dashboard: {
      Tabs: [
        {
          Name: 'Demo',
          Toolbars: ['ButtonToolbar'],
        },
      ],
    },
    StatusBar: {
      StatusBars: [
        {
          Key: 'Center Panel',
          StatusBarPanels: ['CellSummary'],
        },
      ],
    },
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          TableColumns: [
            'name',
            'language',
            'github_stars',
            'license',
            'created_at',
            'has_wiki',
            'github_watchers',
            'updated_at',
            'pushed_at',
            'description',
            'open_issues_count',
            'closed_issues_count',
            'open_pr_count',
            'closed_pr_count',
            'has_projects',
            'has_pages',
            'week_issue_change',
          ],
          Name: 'Standard Layout',
          AutoSizeColumns: true,
        },
      ],
    },
  },
};

Selecting Columns

There are 2 functions in Grid API which enable Columns in AdapTable to be selected programatically:

selectColumn - selects a single Column
selectColumns - selects a given array of Columns

Note

Both these functions will replace whatever is currently selected

Hint

Use the addColumnToSelection function in Column API to programatically add a Column to current selection

Selecting Columns

Fork Fork

This example uses the column selection methods in Grid API via 4 Custom Toolbar buttons:
- First Button selects the Langueage and License columns using selectColumns
- Second Button selects the Github Watchers column using selectColumn (this replaces the current selection)
- Third Button selects the Github Stars column using addColumnToSelection in Column API (this keeps the current selection)
- Fourth Button clears all selected columns

import {
  AdaptableButton,
  AdaptableOptions,
  CustomToolbarButtonContext,
  GridCellRange,
} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Column Selection API',
  dashboardOptions: {
    customToolbars: [
      {
        name: 'ButtonToolbar',
        title: 'Buttons',
        toolbarButtons: [
          {
            label: 'Select Language & License',
            onClick: (
              button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              context.adaptableApi.gridApi.selectColumns([
                'language',
                'license',
              ]);
            },
            buttonStyle: {
              tone: 'info',
              variant: 'text',
            },
          },
          {
            label: 'Select Github Stars (Replace)',
            onClick: (
              button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              context.adaptableApi.gridApi.selectColumn('github_stars');
            },
            buttonStyle: {
              tone: 'success',
              variant: 'text',
            },
          },
          {
            label: 'Select Github Watchers (Keep)',
            onClick: (
              button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              context.adaptableApi.columnApi.addColumnToSelection(
                'github_watchers'
              );
            },
            buttonStyle: {
              tone: 'warning',
              variant: 'text',
            },
          },
          {
            label: 'Clear Selection',
            onClick: (
              button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              context.adaptableApi.gridApi.deselectAll();
            },
            buttonStyle: {
              tone: 'error',
              variant: 'text',
            },
          },
        ],
      },
    ],
  },
  initialState: {
    Dashboard: {
      Tabs: [
        {
          Name: 'Demo',
          Toolbars: ['ButtonToolbar'],
        },
      ],
    },
    StatusBar: {
      StatusBars: [
        {
          Key: 'Center Panel',
          StatusBarPanels: ['CellSummary'],
        },
      ],
    },
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          TableColumns: [
            'name',
            'language',
            'github_stars',
            'license',
            'created_at',
            'has_wiki',
            'github_watchers',
            'updated_at',
            'pushed_at',
            'description',
            'open_issues_count',
            'closed_issues_count',
            'open_pr_count',
            'closed_pr_count',
            'has_projects',
            'has_pages',
            'week_issue_change',
          ],
          Name: 'Standard Layout',
          AutoSizeColumns: true,
        },
      ],
    },
  },
};

Selecting Rows

There are 4 primary functions in Grid API which enable Rows in AdapTable to be selected programatically:

selectRow - selects a single Row (using a Primary Key value)
selectRows - selects a given array of Row (using a Primary Key value)
selectNode - selects a given AG Grid RowNode
selectNodes - selects a given array of AG Grid RowNodes

Selecting Rows

Fork Fork

This example demonstrates the Row and RowNode selection methods in Grid API using Custom Toolbar buttons:
- First Button uses selectRows method to select the 1st and 3rd rows
- Second Button uses selectNode method to select the 5th row

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

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Row Selection API',
  dashboardOptions: {
    customToolbars: [
      {
        name: 'ButtonToolbar',
        title: 'Buttons',
        toolbarButtons: [
          {
            label: 'Select 1st & 3rd Rows',
            onClick: (
              button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              // Select first and third rows using primary key
              context.adaptableApi.gridApi.selectRows(
                [10270250, 11730342],
                false
              );
            },
            buttonStyle: {
              tone: 'info',
              variant: 'text',
            },
          },
          {
            label: 'Select 5th Node',
            onClick: (
              button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              // Get the row node for 5th row and then select it
              const rowNode =
                context.adaptableApi.gridApi.getRowNodeForPrimaryKey(224663696);
              context.adaptableApi.gridApi.selectNode(rowNode, false);
            },
            buttonStyle: {
              tone: 'success',
              variant: 'text',
            },
          },
          {
            label: 'Clear Selection',
            onClick: (
              button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              context.adaptableApi.gridApi.deselectAll();
            },
            buttonStyle: {
              tone: 'error',
              variant: 'text',
            },
          },
        ],
      },
    ],
  },
  initialState: {
    Dashboard: {
      Tabs: [
        {
          Name: 'Demo',
          Toolbars: ['ButtonToolbar'],
        },
      ],
    },
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          TableColumns: [
            'name',
            'language',
            'github_stars',
            'license',
            'created_at',
            'has_wiki',
            'github_watchers',
            'updated_at',
            'pushed_at',
            'description',
            'open_issues_count',
            'closed_issues_count',
            'open_pr_count',
            'closed_pr_count',
            'has_projects',
            'has_pages',
            'week_issue_change',
          ],
          Name: 'Standard Layout',
          AutoSizeColumns: true,
        },
      ],
    },
  },
};

Selecting Whole Grid

There are 2 functions in Grid API relating to whole Grid selection (or deselection):

selectAll - selects everything in the Grid
deselectAll - deselects everything in the Grid

Selecting whole Grid

Fork Fork

This example provides 2 Custom Toolbar Buttons which call the selectAll and deselectAll functions in Grid API

Selection using AdapTable API

(Recorded with AdapTable v16.2)

PreviousSelecting NextSelection Changed Events

Framework: