AdapTable Version:

Framework:

Row Grouping Expanded Collapsed Behaviour

Summary

Row Groups in AdapTable can be configured to open as Expanded or Collapsed
Users are able to set exceptions to the default for certain Row Groups
The same functionality is available in both Table and Pivot Layouts

Developers can configure, when a Layout loads, the collapsed / expanded behaviour for Row Groups.

This is done on a per-Layout basis using the RowGroupValues property in the Base Layout object.

This behaviour is available - and identical - in both - Table Layouts and Pivot Layouts.

Note

Something very similar is available for Column Groups using the ColumnGroupValues property

Deep Dive

Understanding the RowGroupValues Object

Row Group Values are set using the RowGroupValues object.

This object consists of 2 alternative properties (only one of which can be chosen):

RowGroupDefaultBehavior - to set consistent behaviour
RowGroupValuesWithExceptionKeys - (optional) to list any specific exceptions

In other words you can choose whether to configure consistent behaviour that never changes, or to list exceptions.

Consistent Behaviour

If you want the behaviour of Row Groups to be consistent (i.e. never change and never save exceptions) then use the RowGroupDefaultBehavior option in RowGroupValues.

The RowGroupDefaultBehavior property consists of 2 possible values:

always-expanded

// Set all row groups always to be expanded
RowGroupValues: {
  RowGroupDefaultBehavior: 'always-expanded',
},

always-collapsed

// Set all row groups always to be collapsed
RowGroupValues: {
  RowGroupDefaultBehavior: 'always-collapsed',
},

List Exceptions

If you wish to provide a default behaviour, but also set or save exceptions, use the RowGroupValuesWithExceptionKeys property in RowGroupValues.

This alllows you to configure the expand / collapse behaviour for each specific combination of row grouped columns.

The RowGroupValuesWithExceptionKeys object contains 2 properties:

RowGroupDefaultBehavior - can be one of 2 possible values, used to set default behaviour:
- expanded
- collapsed
GroupKeys - provides per Row Grouped Column exceptions (listed by key)

Caution

Previously AdapTable provided the ExceptionGroupKeys prop which simply listed all exceptions
This is deprecated and replaced with GroupKeys which enables per Row Grouped Column exceptions

The GroupKeys object is defined as follows:

Property	Description
ExceptionGroupKeys	Exceptions to default behaviour, provided as array or arrays
RowGroupedColumns	Columns that are Row Grouped

// Set all row groups always to be collapsed with exceptions for Language and License columns
RowGroupValues: {
  RowGroupDefaultBehavior: 'collapsed',
  GroupKeys: [
  {
    RowGroupedColumns: ['language'],
    ExceptionGroupKeys: [['TypeScript'],['JavaScript']],
  },
  {
    RowGroupedColumns: ['license'],
    ExceptionGroupKeys: [['MIT License']],
  },
],
},

This allows you to provide exceptions also when using Multi-Row Grouping:

// Set all row groups always to be collapsed with a few exceptions
RowGroupValues: {
  RowGroupDefaultBehavior: 'collapsed',
  GroupKeys: [
  {
    RowGroupedColumns: ['language', 'license'],
    ExceptionGroupKeys: [
      ['TypeScript'],
      ['TypeScript', 'MIT License'],
      ['JavaScript'],
      ['JavaScript', 'Other'],
    ],
  },
],
},

There are 4 posible use cases for setting expanded / collapsed behaviour:

Use Case	Default Behaviour	Provide Exceptions
All Groups are always exanded	`always-expanded`	❌
All Groups are always collapsed	`always-collapsed`	❌
All Groups are expanded, but exceptions listed	`expanded`	✅
All Groups are collapsed, but exceptions listed	`collapsed`	✅

Consistent Behaviour

Each Layout can specify whether all Row Groups are expanded, or are all collapsed, whenever it opens.

This is done via the RowGroupDefaultBehavior property in RowGroupValues which can be set to one of 2 values:

always-expanded - every Row Group is always expanded whenever the Layout is selected
always-collapsed - every Row Group is always collapsed whenever the Layout is selected

Row Grouping: Setting Default Behaviour

Fork Fork

This demo defines 2 Table Layouts in which Row Group behaviour is set, to show no exceptions, when the Layout opens, by configuring the RowGroupValues property:
- Always Expanded has RowGroupDefaultBehavior set to always-expanded so all Row Groups are open
- Always Collapsed has RowGroupDefaultBehavior set to always-collapsed so all Row Groups are closed

Listing Exceptions

Layouts also offer a more fine-grained approach to Row Group expanded and collapsed behaviour.

Developers can configure the default behaviour, while saving exceptions on a per-Row Grouped Column basis.

This is also using the RowGroupValues object, but this time 2 properties are required:

RowGroupDefaultBehavior: can be set to expanded or collapsed
GroupKeys: contains RowGroupedColumns (array of ColIds) and ExceptionGroupKeys (array of Col values)

One Row Group Column

When there is just one Column being Row-Grouped, it is straightforward to set the Exceptions.

// Set default behaviour of collapsed with 2 exceptions when grouping by Language
RowGroupValues: {
  RowGroupDefaultBehavior: 'collapsed',
  GroupKeys: [
  {
    RowGroupedColumns: ['language'],
    ExceptionGroupKeys: [['TypeScript'],['JavaScript']],
  }],
}

Row Grouping Behaviour: Single Row Grouping

Fork Fork

In this demo we set the RowGroupDefaultBehavior with exceptions for single Row Grouped Columns:
Single Grouping Collapsed Layout has behaviour set to collapsed with exceptions for 2 Columns:
- Language column - exceptions for "JavaScript" and "HTML"
- License column - exception for "Other"
Single Grouping Expanded Layout has behaviour set to expanded with exception in Language column: "JavaScript"

Try It Out

In Single Grouping Collapsed Layout ungroup by Language and then group by License and note that the exception for "Other" is applied

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

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Row Grouping Behaviour Exceptions Single',
  initialState: {
    Dashboard: {
      Tabs: [{Name: 'Demo', Toolbars: ['Layout']}],
    },
    StatusBar: {
      StatusBars: [
        {
          Key: 'Center Panel',
          StatusBarPanels: ['Layout'],
        },
      ],
    },
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Single Grouping Collapsed',
      Layouts: [
        {
          Name: 'Single Grouping Collapsed',
          RowGroupedColumns: ['language'],
          RowGroupValues: {
            RowGroupDefaultBehavior: 'collapsed',
            GroupKeys: [
              {
                RowGroupedColumns: ['language'],
                ExceptionGroupKeys: [['JavaScript'], ['HTML']],
              },
              {
                RowGroupedColumns: ['license'],
                ExceptionGroupKeys: [['Other']],
              },
            ],
          },
          TableColumns: [
            'name',
            'github_stars',
            'language',
            'github_watchers',
            'updated_at',
            'license',
            'description',
            'created_at',
          ],
          AutoSizeColumns: true,
        },
        {
          Name: 'Single Grouping Expanded',
          RowGroupedColumns: ['language'],
          RowGroupValues: {
            RowGroupDefaultBehavior: 'expanded',
            GroupKeys: [
              {
                RowGroupedColumns: ['language'],
                ExceptionGroupKeys: [['JavaScript']],
              },
              {
                RowGroupedColumns: ['license'],
                ExceptionGroupKeys: [['Other']],
              },
            ],
          },
          TableColumns: [
            'name',
            'github_stars',
            'language',
            'github_watchers',
            'updated_at',
            'license',
            'description',
            'created_at',
          ],
          AutoSizeColumns: true,
        },

        {
          Name: 'Standard Layout',
          TableColumns: [
            'name',
            'github_stars',
            'language',
            'github_watchers',
            'updated_at',
            'description',
            'created_at',
          ],
          AutoSizeColumns: true,
        },
      ],
    },
  },
};

Many Row Group Columns

When there is more than one Column being Row-Grouped, the Exceptions need to be set differently.

The ExceptionGroupKeys should contain a comma separated list to match the columns.

Note

This use case deals with multi row grouped columns in one "Group" Column (i.e. RowGroupDisplayType is single)
See below for setting exceptions when each Row Group is in its own Column (i.e. RowGroupDisplayType is multi)

RowGroupValues: {
  RowGroupDefaultBehavior: 'collapsed',
  GroupKeys: [
    {
      RowGroupedColumns: ['language', 'license'],
      ExceptionGroupKeys: [['HTML'], ['HTML', 'Other'], ['JavaScript'] ],
    },
  ],
}

Row Grouping Behaviour: Multiple Row Grouping

Fork Fork

In this demo we set the RowGroupDefaultBehavior with exceptions for multiple Row Grouped Columns
The Multiple Grouping Collapsed Layout groups by Language & Licence and behaviour set to collapsed with 3 exceptions: 'JavaScript', 'JavaScript/Other', 'HTML'

Display Type Multi

Row Group exceptions are also available when using Multi Display Types.

This is when each Row Grouped Column is displayed in its own separate Column.

The syntax for GroupKeys is the same as that used when using Multi Column Grouping.

Row Grouping Behaviour: Display Type Multi

Fork Fork

In this demo we have provided 2 Layouts with RowGroupDisplayType of 'multi', with grouping on Language and License columns, and default behaviour of "collapsed":
- In Multi TypeScript Layout we provide an exception for ["TypeScript"] (so that just that is expanded)
- In Multi HTML Other Layout we provide an exceptions for ["HTML"] and ["HTML", "Other"] (so that just they are expanded)

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

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Row Grouping Behaviour RowGroupDisplayType multi',
  initialState: {
    Dashboard: {
      Tabs: [{Name: 'Demo', Toolbars: ['Layout']}],
    },
    StatusBar: {
      StatusBars: [
        {
          Key: 'Center Panel',
          StatusBarPanels: ['Layout'],
        },
      ],
    },
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Multi TypeScript',
      Layouts: [
        {
          Name: 'Multi TypeScript',
          RowGroupedColumns: ['language', 'license'],
          RowGroupDisplayType: 'multi',
          RowGroupValues: {
            RowGroupDefaultBehavior: 'collapsed',
            GroupKeys: [
              {
                RowGroupedColumns: ['language', 'license'],
                ExceptionGroupKeys: [['TypeScript']],
              },
            ],
          },
          TableColumns: [
            'name',
            'github_stars',
            'github_watchers',
            'updated_at',
            'description',
            'created_at',
            'topics',
          ],
          AutoSizeColumns: true,
        },
        {
          Name: 'Multi HTML Other',
          RowGroupedColumns: ['language', 'license'],
          RowGroupDisplayType: 'multi',
          RowGroupValues: {
            RowGroupDefaultBehavior: 'collapsed',
            GroupKeys: [
              {
                RowGroupedColumns: ['language', 'license'],
                ExceptionGroupKeys: [['HTML'], ['HTML', 'Other']],
              },
            ],
          },
          TableColumns: [
            'name',
            'github_stars',
            'github_watchers',
            'updated_at',
            'description',
            'created_at',
            'topics',
          ],
          AutoSizeColumns: true,
        },
        {
          Name: 'Standard Layout',
          TableColumns: [
            'name',
            'github_stars',
            'language',
            'github_watchers',
            'updated_at',
            'description',
            'created_at',
          ],
          AutoSizeColumns: true,
        },
      ],
    },
  },
};

Pivot Layouts

The expand / collapse behaviour is exactly the same for Pivot Layouts.

You can either set a consistent behaviour or allow (and provide) exceptions to be saved.

Row Grouping Behaviour: Pivot Layouts

Fork Fork

In this demo we have provided Pivot 2 Layouts with grouping on Language and License columns:
- Pivot Layout Consistent has default behaviour of "always-expanded" so every group is expanded
- Pivot Layout Exceptions has default behaviour of "collapsed" but with initial exceptions for JavaScript and HTML (so that they are both expanded)

Try It Out

Close some groups in Pivot Layout Consistent and then switch Layouts and back and note that the Groups are expanded again when the Layout is reloaded
Close /expand some groups in Pivot Layout Expanded and note that these changes are re-rendered when the Layout is reloaded

PreviousRow Groups NextFormatting and Styling

Framework: