DashboardMenuItem Class

A dashboard menu item.

Declaration

export class DashboardMenuItem

Remarks

Create a new DashboardMenuItem class instance and pass it to the ToolboxExtension.addMenuItem property to add a new item to the dashboard menu:

var customMenuItem = new DevExpress.Dashboard.DashboardMenuItem('customItem1', 'New Menu Item', 0, 20, function () { /* ... */ });
dashboardControl.findExtension('toolbox').addMenuItem(customMenuItem);

constructor(id, title, index, hotKey)

Initializes a new instance of the DashboardMenuItem class.

Declaration

constructor(
    id: string,
    title: string,
    index: number,
    hotKey: number,
    click?: () => void
)

Parameters

Name	Type	Description
id	string	A unique identifier of a dashboard menu item.
title	string	A dashboard menu item title.
index	number	A zero-based index that identifies an item’s position within the dashboard menu.
hotKey	number	An integer value that specifies a key code used in the keyboard shortcut.
click	() => void	A function that is executed when a click occurs.

Properties

click Property

Specifies a custom function that is executed when a click occurs.

Declaration

click: () => void

Property Value

Type	Description
() => void	A function that is executed when a click occurs.

Remarks

This property executes a click on a dashboard menu item as if the user manually clicked on it and handles a custom function that is invoked on a click.

data Property

Specifies data that is used by a menu item.

Declaration

data: any

Property Value

Type	Description
any	An object that contains data used by a menu item.

disabled Property

Gets whether a dashboard menu item is disabled.

Declaration

disabled: ko.Subscribable<boolean>

Property Value

Type	Description
Subscribable<boolean>	true, if a dashboard menu item should be disabled; otherwise, false.

Remarks

The property can accept the computed observables. To learn more, see KnockoutComputed.

For example, the function in the code below returns true when your application does not have any dashboards. In this case, the saveAsItem menu item is disabled.

function onBeforeRender(sender) {
    var dashboardControl = sender.GetDashboardControl();
    var toolbox = dashboardControl.findExtension("toolbox");

    var saveAsItem = {
        id: this.name,
        title: "Save As",
        // ... 
        disabled: ko.computed(function () { return !dashboardControl.dashboard(); })
    }
    toolbox.addMenuItem(saveAsItem);
}

hasSeparator Property

Specifies whether a dashboard menu item has a separator.

Declaration

hasSeparator: boolean

Property Value

Type	Description
boolean	true, if a dashboard menu item has a separator; otherwise, false.

hotKey Property

Specifies a code of the key used in the keyboard shortcut. This shortcut allows you to invoke the current menu item.

Declaration

hotKey: number

Property Value

Type	Description
number	An integer value that specifies a key code.

Remarks

You can use keyboard shortcuts to execute the dashboard menu commands. In the Web Dashboard, the ALT key is used as a modifier key to create a shortcut. To create a shortcut, assign the code of the required key to the hotKey property.

The table below shows the Web Dashboard’s default shortcuts and related hotKey property values:

Menu Item	Shortcut	Key code
New…	Alt+N	78
Open	Alt+O	79
Save…	Alt+S	83
Data Sources	Alt+A	65
Title	Alt+T	84
Currency	Alt+C	67
Parameters	Alt+P	80

The following example demonstrates the code of a custom menu item which can be invoked using the Alt+I hotkey combination:

function onBeforeRender(sender, args) {
    var dashboardControl = sender.GetDashboardControl();
    var toolbox = dashboardControl .findExtension('toolbox');

    var newMenuItem = {
        title: "Custom Menu Item",
        // ... 
        hotKey: 73        
    }
    toolbox.addMenuItem(newMenuItem);
}

id Property

Specifies a unique identifier of a dashboard menu item.

Declaration

id: string

Property Value

Type	Description
string	A string value that is a menu item’s unique identifier.

Remarks

Use the id property value to address to the dashboard menu item by id.

The following code snippet shows you how to remove the Open… item from the dashboard menu.

function onBeforeRender(sender, args) {
    var dashboardControl = sender.getDashboardControl();
    var toolbox = dashboardControl.findExtension('toolbox');

    // Removes the dashboard menu item by its id. 
    toolbox.removeMenuItem("open-dashboard");
}

index Property

Specifies the position of the dashboard menu item within the dashboard menu.

Declaration

index: number

Property Value

Type	Description
number	A zero-based integer specifying the position of the current dashboard menu item.

Remarks

The following table illustrates indexes of the dashboard menu items.

Menu Item	Index
New…	105
Open…	108
Save	110
Data Sources	210
Title	220
Currency	230
Parameters	240
Color Scheme	250

selected Property

Specifies whether the dashboard menu item is selected.

Declaration

selected: ko.Subscribable<boolean>

Property Value

Type	Description
Subscribable<boolean>	true, if the dashboard menu item is selected; otherwise, false;

template Property

Specifies a knockout template for the extension.

Declaration

template: string

Property Value

Type	Description
string	A string value that is an id of the knockout template.

Remarks

The code sample below shows you how to create a sample template for the dashboard menu item using the knockout ‘’template’’ binding. This template has a “sample-form” id and consists of a text box and button.

<script type="text/html" id="sample-form">
    <div>Dashboard Name:</div>
    <div style="margin: 10px 0" data-bind="dxTextBox: { value: newName }"></div>
    <div data-bind="dxButton: { text: 'Save', onClick: saveAs }"></div>        
</script>

To use this template for a dashboard menu item, assign the id of the template to the template property.

To learn more about knockout templates, refer to Knockout Documentation.

title Property

Specifies a dashboard menu item title.

Declaration

title: string

Property Value

Type	Description
string	A string value that is a dashboard menu item title.