Creating Custom Column Menu Items

Summary

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

Developers can provide bespoke menu items in the Column Menu.

This is done using the customColumnMenu callback in Column Menu Options.

Each item is a UserColumnMenuItem with properties such as label, icon, hidden, disabled, onClick, and subMenuItems.

Deep Dive

Anatomy of a Custom Column Menu Item

The key object is UserColumnMenuItem:

Property	Type	Description
disabled	`boolean`	Whether menu item is disabled
frameworkComponent	`MenuItemFrameworkComponent<ColumnMenuContext>`	Optional Framework Component (React, Angular or Vue) used to render the content of this menu item.
hidden	`boolean`	Whether menu item is hidden
icon	`AdaptableIcon`	Optional icon to display
label	`string`	Text to appear in the Menu Item
menuItemParams	`Record<string, unknown>`	Extra parameters passed through to the Framework Component (alongside `adaptableApi` and `menuContext`).
menuType	`'User'`	Type of Menu - always 'User'
onClick	`(menuContext:ColumnMenuContext) => void`	Function invoked when the Menu Item is clicked
subMenuItems	`CustomColumnMenuItem[]`	Array of Menu Items, enabling limitless levels of menus

The onClick handler receives ColumnMenuContext:

Property	Type	Description
adaptableColumn	`AdaptableColumn<TData>`	Current AdapTable Column
agGridColumn	`Column`	Current AG Grid Column
isRowGroupColumn	`boolean`	Whether current Column is Row Group
adaptableContext	`any`	Custom application Context provided in `AdaptableOptions.adaptableContext`

Developer Guide

Providing a Standard Custom Column Menu Item

A few steps are required to define a standard Column Menu item (no frameworkComponent):

// 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

icon: {
  name: 'theme',
},

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: [
  {
    menuType: 'User',
    label: 'Hide Dashboard',
    onClick: (menuContext: ColumnMenuContext) => {
      menuContext.adaptableApi.dashboardApi.hideDashboard();
    },
  },
  {
    menuType: 'User',
    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 UserColumnMenuItem.

When the Dashboard is visible, use a Dashboard parent with Hide and Float sub items. When it is hidden (dashboardApi.isDashboardHidden()), the demo uses a single Show Dashboard item that calls showDashboard().

// Add custom menu items before default AG Grid and AdapTable blocks
columnMenuOptions: {
  customColumnMenu: (context: CustomColumnMenuContext) => {
    return [
      changeThemeMenuItem,
      dashboardMenuItem,
      '-',
      ...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 items in the desired location in the Column Menu.

Show Dark Theme / Show Light Theme — single action at the top of the Column Menu; hidden on row-group columns; disabled for date columns
Dashboard — Show Dashboard when the Dashboard is hidden; otherwise a sub menu with Hide and Float
Default AG Grid and AdapTable menu items remain below

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(),
      };

      const dashboardMenuItem: UserColumnMenuItem =
        adaptableApi.dashboardApi.isDashboardHidden()
          ? {
              menuType: 'User',
              label: 'Show Dashboard',
              onClick: () => adaptableApi.dashboardApi.showDashboard(),
            }
          : {
              menuType: 'User',
              label: 'Dashboard',
              subMenuItems: [
                {
                  menuType: 'User',
                  label: 'Hide Dashboard',
                  onClick: menuContext =>
                    menuContext.adaptableApi.dashboardApi.hideDashboard(),
                },
                {
                  menuType: 'User',
                  label: 'Float Dashboard',
                  onClick: menuContext =>
                    menuContext.adaptableApi.dashboardApi.floatDashboard(),
                },
              ],
            };

      return [
        changeThemeMenuItem,
        dashboardMenuItem,
        '-',
        ...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,
        },
      ],
    },
  },
};

PreviousConfiguring Column Menu NextDefault Menu Structure