Context Menu - Custom Items

AdapTable Version:

Framework:

Context Menu

Summary

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

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

Like all Context Menu manipulation, it is done using the customContextMenu property in Context Menu Options.

A number of properties can be provided for the 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 Context Menu Item (to change the Theme)
We place the item at the top of the Context Menu - and leave the default AG Grid and AdapTable Menu Items in place
The custom Context 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

menuOptions: {
  customContextMenu: (context: CustomContextMenuContext) => {
    const {
      defaultAgGridMenuStructure,
      defaultAdaptableMenuStructure,
      isRowGroupColumn,
      adaptableColumn,
      adaptableApi,
    } = context;

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

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

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

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Custom Context Menu Items',
  contextMenuOptions: {
    customContextMenu: (context: CustomContextMenuContext) => {
      const {
        defaultAgGridMenuStructure,
        defaultAdaptableMenuStructure,
        isRowGroupColumn,
        adaptableColumn,
      } = context;

      const changeThemeMenuItem: UserContextMenuItem = {
        menuType: 'User',
        label:
          context.adaptableApi.themeApi.getCurrentTheme() == 'light'
            ? 'Show Dark Theme'
            : 'Show Light Theme',
        icon: {
          name: 'theme',
        },
        hidden: isRowGroupColumn,
        disabled: adaptableColumn?.dataType == 'date',
        onClick: () =>
          context.adaptableApi.themeApi.getCurrentTheme() == 'light'
            ? context.adaptableApi.themeApi.loadDarkTheme()
            : context.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',
          ],
          AutoSizeColumns: true,
          Name: 'Grouped Layout',
          RowGroupValues: {
            RowGroupDefaultBehavior: 'collapsed',
            GroupKeys: [
              {
                RowGroupedColumns: ['language'],
                ExceptionGroupKeys: [['JavaScript']],
              },
            ],
          },
          RowGroupedColumns: ['language'],
        },
      ],
    },
  },
};

Deep Dive

Anatomy of a Custom Context Menu Item

The key object which is provided is the User Context 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 ContextMenuContext object (and returns void):

Property	Description
adaptableColumn	Current AdapTable Column
agGridColumn	Current AG Grid Column
gridCell	Cell that has been clicked; contains cell value
isGroupedNode	Whether current AG Grid row node is grouped
isRowGroupColumn	Whether current Column is Row Grouped
isSelectedCell	Whether cell that was clicked is also currently selected
isSelectedRow	Whether cell that was clicked is in a Row that is currently selected
isSingleSelectedCell	Whether the clicked cell is the only selected cell
isSingleSelectedColumn	Whether Column that was clicked is only column with selected cells
primaryKeyValue	Value of Primary Key column in current row
rowNode	Current AG Grid row node
selectedCellInfo	Currently selected cells in the grid
selectedRowInfo	Currently selected rows in the grid
adaptableContext	Custom application Context provided in `AdaptableOptions.adaptableContext`

Developer Guide

Providing a Custom Context Menu Item

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

// Provide Menu Type of 'User'
// Set the Label to Expand or Collapse based on current state
menuType: 'User',
label: (menuContext: ContextMenuContext) => {
  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 ContextMenuContext and returns a string

// Expand or Collapse the Dashboard as required
onClick: (menuContext: ContextMenuContext) => {
  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 ContextMenuContext object and returns void.

// Make the Menu item visible but disabled
hidden: false,
disabled: true

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 Context 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: ContextMenuContext) => {
    menuContext.adaptableApi.dashboardApi.hideDashboard();
  },
},
{
  label: 'Float Dashboard',
  onClick: (menuContext: ContextMenuContext) => {
    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
  menuOptions: {
  customContextMenu: (context: CustomContextMenuContext) => {
    return [
      customDashboardMenuItem,
      '-',
      ...context.defaultAgGridMenuStructure,
      '-',
      ...context.defaultAdaptableMenuStructure,
    ];
  },
},

Add the custom Menu Item to Context Menu

The customContextMenu 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 Context Menu NextDefault Menu Structure

Framework: