Column Menu - Custom Items

AdapTable Version:

Framework:

Column Menu

Summary

Bespoke Menu Items can be added to the Column Menu by developers

Developers can provide bespoke Menu Items to add to the Column Menu.

Like all Column Menu manipulation, it is done using the customColumnMenu property in Column Menu Options.

A number of properties can be provided for a bespoke Menu Item, including:

label - the text that appears in the Menu Item
icon - an Icon to display
disabled - whether Menu Item is disabled
hidden - whether Menu Item is visible
onClick - what happens when the Menu Item is clicked
subMenuItems - lower levels of Menu Items (enables the Menu Item to be as deeply nested as required)

This example showws how to add a Custom Column Menu Item (to change the Theme)
We place the item at the top of the Column Menu - and leave the default AG Grid and AdapTable Menu Items in place
The custom Column Menu Item is hidden when opening the Column Menu in a Row-Grouped Column and disabled for Date Columns

Expand to see the Menu Options configuration

columnMenuOptions: {
  customColumnMenu: (context: CustomColumnMenuContext) => {
    const {
      defaultAgGridMenuStructure,
      defaultAdaptableMenuStructure,
      isRowGroupColumn,
      adaptableColumn,
      adaptableApi,
    } = context;

    const changeThemeMenuItem: UserColumnMenuItem = {
      menuType: 'User',
      label:
        adaptableApi.themeApi.getCurrentTheme() == 'light'
          ? 'Show Dark Theme'
          : 'Show Light Theme',
      icon: {
        name: 'theme',
      },
      hidden: isRowGroupColumn,
      disabled: adaptableColumn?.dataType == 'Date',
      onClick: () =>
        adaptableApi.themeApi.getCurrentTheme() == 'light'
          ? adaptableApi.themeApi.loadDarkTheme()
          : adaptableApi.themeApi.loadLightTheme(),
    };

    return [
      changeThemeMenuItem,
      '-',
      ...defaultAgGridMenuStructure,
      '-',
      ...defaultAdaptableMenuStructure,
    ];
  },
},

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

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Custom Column Menu Items',
  columnMenuOptions: {
    customColumnMenu: (context: CustomColumnMenuContext) => {
      const {
        defaultAgGridMenuStructure,
        defaultAdaptableMenuStructure,
        isRowGroupColumn,
        adaptableColumn,
        adaptableApi,
      } = context;

      const changeThemeMenuItem: UserColumnMenuItem = {
        menuType: 'User',
        label:
          adaptableApi.themeApi.getCurrentTheme() == 'light'
            ? 'Show Dark Theme'
            : 'Show Light Theme',
        icon: {
          name: 'theme',
        },
        hidden: isRowGroupColumn,
        disabled: adaptableColumn?.dataType == 'date',
        onClick: () =>
          adaptableApi.themeApi.getCurrentTheme() == 'light'
            ? adaptableApi.themeApi.loadDarkTheme()
            : adaptableApi.themeApi.loadLightTheme(),
      };

      return [
        changeThemeMenuItem,
        '-',
        ...defaultAgGridMenuStructure,
        '-',
        ...defaultAdaptableMenuStructure,
      ];
    },
  },
  initialState: {
    Dashboard: {
      Tabs: [{Name: 'Demo', Toolbars: ['SystemStatus', 'Export']}],
    },
    StatusBar: {
      StatusBars: [
        {
          Key: 'Center Panel',
          StatusBarPanels: ['SystemStatus'],
        },
      ],
    },
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Grouped Layout',
      Layouts: [
        {
          TableColumns: [
            'name',
            'language',
            'github_stars',
            'open_issues_count',
            'week_issue_change',
            'updated_at',
            'license',
            'created_at',
            'has_wiki',
            'pushed_at',
            'open_issues_count',
            'description',
          ],
          Name: 'Grouped Layout',
          RowGroupValues: {
            RowGroupDefaultBehavior: 'collapsed',
            GroupKeys: [
              {
                RowGroupedColumns: ['language'],
                ExceptionGroupKeys: [['JavaScript']],
              },
            ],
          },
          RowGroupedColumns: ['language'],
          AutoSizeColumns: true,
        },
      ],
    },
  },
};

Deep Dive

Anatomy of a Custom Column Menu Item

The key object which is provided is the User Column Menu Item and it is defined as follows:

Property	Description
disabled	Whether menu item is disabled
hidden	Whether menu item is hidden
icon	Optional icon to display
label	Text to appear in the Menu Item
menuType	Type of Menu - always 'User'
onClick	Function invoked when the Menu Item is clicked
subMenuItems	Array of Menu Items, enabling limitless levels of menus

The onClick property is in the form of a function which receives a ColumnMenuContext object (and returns void):

Property	Description
adaptableColumn	Current AdapTable Column
agGridColumn	Current AG Grid Column
isRowGroupColumn	Whether current Column is Row Group
adaptableContext	Custom application Context provided in `AdaptableOptions.adaptableContext`

Developer Guide

Providing a Custom Column Menu Item

A few steps are required to define a Column Menu item:

// Provide Menu Type of 'User'
// Set the Label to Expand or Collapse based on current state
menuType: 'User',
label: (menuContext: ColumnMenuContext) => {
  return menuContext.adaptableApi.dashboardApi.isDashboardCollapsed()
    ? 'Expand Dashboard'
    : 'Collapse Dashboard';
}

Provide a Label and Menu Type

The menuType is always 'User'.

The label property provides the Custom Menu Item's text.

It returns either a string directly or a function which receives ColumnMenuContext and returns a string

// Expand or Collapse the Dashboard as required
onClick: (menuContext: ColumnMenuContext) => {
  menuContext.adaptableApi.dashboardApi.isDashboardCollapsed()
    ? menuContext.adaptableApi.dashboardApi.expandDashboard()
    : menuContext.adaptableApi.dashboardApi.collapseDashboard();
},

Supply an onClick function

The onClick function is invoked by AdapTable when the menu item is selected by the user.

It receives a ColumnMenuContext object and returns void.

// Make the Menu item hidden for Row Group Columns
hidden: menuContext.isRowGroupColumn,
// Make the Menu Item disabled for Date Columns
disabled: menuContext.adaptableColumn?.dataType == 'Date',

Specify whether Menu Item should be Hidden or Disabled

Use hidden and disabled properties to set visibility and if enabled

Note

In earlier versions of AdapTable, these 2 properties were functions that could be set dynamically each time the menu opened
However this same logic can now be more flexibly set when configuring the Column Menu

// Provide an Icon
icon: {
  src: 'https://img.icons8.com/flat-round/344/traffic-light--v1.png',
},

Provide an Icon

The Icon can be an object, URL or HTML Element

Find Out More

See Guide to Adaptable Icons for full details on the different types of Icons that can be used

// Provide 2 sub menu items to hide and float the Dashboard
subMenuItems: [
{
  label: 'Hide Dashboard',
  onClick: (menuContext: ColumnMenuContext) => {
    menuContext.adaptableApi.dashboardApi.hideDashboard();
  },
},
{
  label: 'Float Dashboard',
  onClick: (menuContext: ColumnMenuContext) => {
    menuContext.adaptableApi.dashboardApi.floatDashboard();
  },
},
],

Add Sub Menu Items (if required)

Each Menu Item can have Sub Menu Items allowing you to provide nested Menus as deep as required.

Each Sub Menu Item is simply another Menu Item object.

// Add custom menu Item before AG Grid and AdapTable menu items
columnMenuOptions: {
  customColumnMenu: (context: CustomColumnMenuContext) => {
    return [
      customDashboardMenuItem,
      '-',
      ...context.defaultAgGridMenuStructure,
      '-',
      ...context.defaultAdaptableMenuStructure,
    ];
  },
},

Add the custom Menu Item to Column Menu

The customColumnMenu property receives all AG Grid and AdapTable menu items as context, both a full list and the default structure.

Place the custom menu item in the desired location in the Context Menu.

PreviousConfiguring Column Menu NextTechnical Reference

Framework: