HeaderMenu

Right click column header or focus it and press SPACE key to show the context menu for headers.

Default header menu items

The Header menu has no default items provided by the HeaderMenu feature, but there are other features that populate the header menu with the following items:

Reference Text Weight Feature Description
filter Filter 100 Filter Shows the filter popup to add a filter
filterEdit Edit filter 100 Filter Shows the filter popup to change/remove a filter
filterRemove Remove filter 110 Filter Stops filtering by selected column field
toggleFilterBar Hide filter bar / Show filter bar 120 FilterBar Toggles filter bar visibility
columnPicker Columns 200 ColumnPicker Shows a submenu to control columns visibility
>column.id* column.text* ColumnPicker Check item to hide/show corresponding column
pinColumn Pin column 250 PinColumns Shows a submenu to pin/unpin the column
hideColumn Hide column 210 ColumnPicker Hides selected column
rename Rename column text 215 ColumnRename Edits the header text of the column
toggleCollapse Collapse column / Expand column 215 This feature Expands or collapses a collapsible column
movePrev Move previous 220 This feature Moves selected column before its previous sibling
moveNext Move next 230 This feature Moves selected column after its next sibling
sortAsc Sort ascending 300 Sort Sort by the column field in ascending order
sortDesc Sort descending 310 Sort Sort by the column field in descending order
multiSort Multi sort 320 Sort Shows a submenu to control multi-sorting
>addSortAsc Add ascending sorting 330 Sort Adds ascending sorter using the column field
>addSortDesc Add descending sorting 340 Sort Adds descending sorter using the column field
>removeSorter Remove sorter 350 Sort Stops sorting by selected column field
groupAsc Group ascending 400 Group Group by the column field in ascending order
groupDesc Group descending 410 Group Group by the column field in descending order
groupRemove Stop grouping 420 Group Stops grouping
mergeCells Merge cells 500 MergeCells Merge cells with same value in a sorted column
*
items that are generated dynamically
>
first level of submenu

Customizing the menu items

The menu items in the Header menu can be customized, existing items can be changed or removed, and new items can be added. This is handled using the items config of the feature.

Add extra items for all columns:

const grid = new Grid({
  features : {
    headerMenu : {
      items : {
        extraItem : { text: 'My header item', icon: 'fa fa-car', weight: 200, onItem : () => ... }
      }
    }
  }
});

It is also possible to add items using columns config. See examples below.

Add extra items for a single column:

const grid = new Grid({
  columns: [
    {
      field: 'name',
      text: 'Name',
      headerMenuItems: {
        columnItem : { text: 'My unique header item', icon: 'fa fa-flask', onItem : () => ... }
      }
    }
  ]
});

Remove built-in item:

const grid = new Grid({
  features : {
    headerMenu : {
      items : {
         // Hide 'Stop grouping'
         groupRemove : false
      }
    }
  }
});

Customize built-in item:

const grid = new Grid({
  features : {
    headerMenu : {
      items : {
         hideColumn : {
             text : 'Bye bye column'
         }
      }
    }
  }
});

Remove nested menu item:

const grid = new Grid({
    features : {
        headerMenu : {
            items : {
                multiSort : {
                    menu : { removeSorter : false }
                }
            }
        }
    }
});

It is also possible to manipulate the default items and add new items in the processing function:

const grid = new Grid({
  features : {
    headerMenu : {
      processItems({items, record}) {
          if (record.cost > 5000) {
             items.myItem = { text : 'Split cost' };
          }
      }
    }
  }
});
The `processItems` implementation may be an `async` function which `awaits` a result to mutate the `items` object.

Full information of the menu customization can be found in the "Customizing the Cell menu and the Header menu" guide.

This feature is enabled by default.

Keyboard shortcuts

This feature has the following default keyboard shortcuts:

Keys Action Action description
Space showContextMenuByKey Shows context menu for currently focused header
Ctrl+Space showContextMenuByKey Shows context menu for currently focused header
Please note that Ctrl is the equivalent to Command and Alt is the equivalent to Option for Mac users

For more information on how to customize keyboard shortcuts, please see our guide

Header menu
//<code-header>
fiddle.title = 'Header menu';
//</code-header>
targetElement.innerHTML = '<p>Right click a header to display a context menu</p>';
const grid = new Grid({
    appendTo : targetElement,

    // makes grid as high as it needs to be to fit rows
    autoHeight : true,

    features : {
        // this feature is enabled by default,
        // so no need for this unless you have changed defaults
        headerMenu : true
    },

    data : DataGenerator.generateData(5),

    columns : [
        { field : 'name', text : 'Name', flex : 1 },
        { field : 'score', text : 'Score', flex : 1 }
    ]
});

Configs

19

Common

disabledInstancePlugin
listenersEvents

Accessibility

moveColumns: Boolean

Configure as true to show two extra menu options to move the selected column to either before its previous sibling, or after its next sibling.

This is a keyboard-accessible version of drag/drop column reordering.

Other

items: Object<String, MenuItemEntry>

This is a preconfigured set of items used to create the default context menu.

The items provided by this feature are listed in the intro section of this class. You can configure existing items by passing a configuration object to the keyed items.

To remove existing items, set corresponding keys to null:

const scheduler = new Scheduler({
    features : {
        headerMenu : {
            items : {
                filter        : null,
                columnPicker  : null
            }
        }
    }
});

See the feature config in the above example for details.

keyMap: Object<String, KeyMapConfig>

See Keyboard shortcuts for details

processItems: function

A function called before displaying the menu that allows manipulations of its items. Returning false from this function prevents the menu being shown.

  features         : {
      headerMenu : {
          processItems({ column, items }) {
              // Add or hide existing items here as needed
              items.myAction = {
                  text   : 'Cool action',
                  icon   : 'fa fa-fw fa-ban',
                  onItem : () => console.log('Some coolness'),
                  weight : 300 // Move to end
              };

              // Hide column picker
              items.columnPicker.hidden = true;
          }
      }
  },
ParameterTypeDescription
contextObject

An object with information about the menu being shown.

context.featureHeaderMenu

A reference to this feature.

context.domEventEvent

The initiating event.

context.eventEvent

DEPRECATED: The initiating event.

context.pointNumber[]

The client X and Y position of the initiating event.

context.targetElementHTMLElement

The target to which the menu is being applied.

context.columnColumn

The current column.

context.itemsObject<String, MenuItemEntry>

An object containing the menu item configs keyed by their id.

Returns: Boolean | null -

Returning false from this function prevents the menu being shown.

clickTriggerSelectorContextMenuBase
menuContextMenuBase
namedItemsContextMenuBase
preventNativeMenuContextMenuBase
triggerEventContextMenuBase
typeContextMenuBase

Misc

clientInstancePlugin
localeClassLocalizable
localizableLocalizable

Properties

19

Common

disabledInstancePlugin

Class hierarchy

isHeaderMenu: Boolean= truereadonly
Identifies an object as an instance of HeaderMenu class, or subclass thereof.
isHeaderMenu: Boolean= truereadonlystatic
Identifies an object as an instance of HeaderMenu class, or subclass thereof.
isContextMenuBaseContextMenuBase
isEventsEvents
isInstancePluginInstancePlugin
isLocalizableLocalizable

Lifecycle

configBase

Misc

clientInstancePlugin
localeHelperLocalizable
localeManagerLocalizable

Other

menuContextMenuBase
menuContextContextMenuBase
preventNativeMenuContextMenuBase

Functions

29

Configuration

applyDefaultsstaticBase

Events

Lifecycle

destroystaticBase

Misc

doDisableInstancePlugin
initClassstaticBase
isOfTypeNamestaticBase
mixinstaticBase
optionalLstaticLocalizable

Other

LstaticLocalizable
onEvents
relayAllEvents
showContextMenuContextMenuBase
triggerEvents
unEvents

Events

11

This event fires on the owning Grid before the context menu is shown for a header. Allows manipulation of the items to show in the same way as in the processItems.

Returning false from a listener prevents the menu from being shown.

// Adding a listener using the "on" method
headerMenu.on('headerMenuBeforeShow', ({ source, menu, items, column }) => {

});
ParameterTypeDescription
sourceGrid

The grid

menuMenu

The menu

itemsObject<String, MenuItemEntry>

Menu item configs

columnColumn

Column

This event fires on the owning Grid when an item is selected in the header context menu.

// Adding a listener using the "on" method
headerMenu.on('headerMenuItem', ({ source, menu, item, column }) => {

});
ParameterTypeDescription
sourceGrid

The grid

menuMenu

The menu

itemMenuItem

Selected menu item

columnColumn

Column

This event fires on the owning Grid after the context menu is shown for a header

// Adding a listener using the "on" method
headerMenu.on('headerMenuShow', ({ source, menu, items, column }) => {

});
ParameterTypeDescription
sourceGrid

The grid

menuMenu

The menu

itemsObject<String, MenuItemEntry>

Menu item configs

columnColumn

Column

This event fires on the owning Grid when a check item is toggled in the header context menu.

// Adding a listener using the "on" method
headerMenu.on('headerMenuToggleItem', ({ source, menu, item, column, checked }) => {

});
ParameterTypeDescription
sourceGrid

The grid

menuMenu

The menu

itemMenuItem

Selected menu item

columnColumn

Column

checkedBoolean

Checked or not

catchAllEvents
contextMenuItemContextMenuBase
contextMenuToggleItemContextMenuBase
destroyEvents
disableInstancePlugin
enableInstancePlugin

Event handlers

11

This event called on the owning Grid before the context menu is shown for a header. Allows manipulation of the items to show in the same way as in the processItems.

Returning false from a listener prevents the menu from being shown.

new HeaderMenu({
    onHeaderMenuBeforeShow({ source, menu, items, column }) {

    }
});
ParameterTypeDescription
sourceGrid

The grid

menuMenu

The menu

itemsObject<String, MenuItemEntry>

Menu item configs

columnColumn

Column

This event called on the owning Grid when an item is selected in the header context menu.

new HeaderMenu({
    onHeaderMenuItem({ source, menu, item, column }) {

    }
});
ParameterTypeDescription
sourceGrid

The grid

menuMenu

The menu

itemMenuItem

Selected menu item

columnColumn

Column

This event called on the owning Grid after the context menu is shown for a header

new HeaderMenu({
    onHeaderMenuShow({ source, menu, items, column }) {

    }
});
ParameterTypeDescription
sourceGrid

The grid

menuMenu

The menu

itemsObject<String, MenuItemEntry>

Menu item configs

columnColumn

Column

This event called on the owning Grid when a check item is toggled in the header context menu.

new HeaderMenu({
    onHeaderMenuToggleItem({ source, menu, item, column, checked }) {

    }
});
ParameterTypeDescription
sourceGrid

The grid

menuMenu

The menu

itemMenuItem

Selected menu item

columnColumn

Column

checkedBoolean

Checked or not

onContextMenuItemContextMenuBase
onDestroyEvents
onDisableInstancePlugin
onEnableInstancePlugin

Typedefs

3
MenuContextContextMenuBase
MenuItemEntryContextMenuBase