Skip to main content

ToolboxExtension Class

The Web Dashboard Toolbox extension that provides access to the dashboard menu and allows you to add dashboard items, as well as undo or repeat user actions.

#Declaration

TypeScript
export class ToolboxExtension extends DisposableObject implements IExtension

#Remarks

The ToolboxExtension class provides access to the Toolbox and allows you to customize it using the client-side API.

To get access to the ToolboxExtension settings, call the control’s findExtension(extensionName) method and pass the extension’s name as a parameter.

JavaScript
var ext = dashboardControl.findExtension('toolbox');

To disable the current panel, call the unregisterExtension(extensionNames) method and pass the extension’s unique name as a parameter:

JavaScript
dashboardControl.unregisterExtension('toolbox');

You can also call the control’s option method to change the extension options.

#Implements

IExtension

#Inherited Members

#Inheritance

DisposableObject
ToolboxExtension

#constructor(dashboardControl)

Initializes a new instance of the ToolboxExtension class.

#Declaration

TypeScript
constructor(
    dashboardControl: DevExpress.Dashboard.DashboardControl
)

#Parameters

Name Type Description
dashboardControl DashboardControl

A Web Dashboard control that owns the extension.

#Properties

#addMenuItem Property

Adds a menu item to the dashboard menu.

#Declaration

TypeScript
addMenuItem: (menuItem: DevExpress.Dashboard.Designer.DashboardMenuItem) => void

#Property Value

Type Description
(menuItem: DashboardMenuItem) => void

A function that passes the DashboardMenuItem object to create a dashboard menu item.

#Remarks

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

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

#addToolbarItem Property

Adds a toolbar item to the Toolbox.

#Declaration

TypeScript
addToolbarItem: (groupName: string, toolbarItem: DevExpress.Dashboard.Designer.DashboardToolbarItem) => void

#Property Value

Type Description
(groupName: string, toolbarItem: DashboardToolbarItem) => void

A function that passes the toolbar group name and DashboardToolbarItem object to create a toolbox item.

#Remarks

Create a new DashboardToolbarItem class instance and pass it with a group name to the addToolbarItem property to add a new item to the specified Toolbar‘s group:

JavaScript
var toolbarItem = new DevExpress.Dashboard.Designer.DashboardToolbarItem('toolbarItem1', function () { /* ... */ }, "toolbox-icon");
dashboardControl.findExtension('toolbox').addToolbarItem('undoRedo', toolbarItem);

#addToolboxItem Property

Adds a new item to the Toolbox.

#Declaration

TypeScript
addToolboxItem: (groupName: string, toolboxItem: DevExpress.Dashboard.Designer.DashboardToolboxItem) => void

#Property Value

Type Description
(groupName: string, toolboxItem: DashboardToolboxItem) => void

A function that passes the toolbox group name and DashboardToolboxItem object to create a toolbox item.

#Remarks

Create a new DashboardToolboxItem class instance and pass it with a group name to the addToolboxItem property to add a new item to the specified Toolbox‘ group:

JavaScript
var toolboxItem = new DevExpress.Dashboard.Designer.DashboardToolboxItem('toolboxGroup', function () { /* ... */ }, "toolbox-icon");
dashboardControl.findExtension('toolbox').addToolboxItem("common", toolboxItem);

#designerToViewerAction Property

Specifies an action executed at the moment of switching from Designer to Viewer.

#Declaration

TypeScript
designerToViewerAction: DevExpress.Dashboard.SequenceAction

#Property Value

Type Description
SequenceAction

An action executed at the moment of switching from Designer to Viewer.

#hidePanelAsync Property

Hides the Toolbox asynchronously.

#Declaration

TypeScript
hidePanelAsync: (options: DevExpress.Dashboard.WorkingModeSwitchingOptions) => JQueryPromise<{}>

#Property Value

Type
(options: WorkingModeSwitchingOptions) => JQueryPromise<>

#Remarks

The code below hides the Toolbox asynchronously and then adjusts the left indent of the DashboardControl using the surfaceLeft property.

JavaScript
function hideToolbox() {
  // The dashboardControl variable is the obtained DashboardControl instance.
  var toolbox = dashboardControl.findExtension('toolbox');
  toolbox.hidePanelAsync({}).done(function (e) {
    dashboardControl.surfaceLeft(e.surfaceLeft);
  });
}

#menuItems Property

Provides access to the dashboard menu’s items collection.

#Declaration

TypeScript
menuItems: ko.ObservableArray<DevExpress.Dashboard.Designer.DashboardMenuItem>

#Property Value

Type Description
ObservableArray<DashboardMenuItem>

A collection the DashboardMenuItem objects that are the dashboard menu items.

#Remarks

Use the menuItems property to get a list of the DashboardMenuItem objects and manage the collection. For example, the code below removes the “New…” menu item:

JavaScript
var toolbox = dashboardControl.findExtension('toolbox');
var itemCreate = toolbox.menuItems().filter(item => item.id === "create-dashboard")[0];
toolbox.menuItems.remove(itemCreate);

#menuVisible Property

Gets the visibility status of the dashboard menu.

#Declaration

TypeScript
get menuVisible(): ko.Observable<boolean>

#Property Value

Type Description
Observable<boolean>

true, if the dashboard menu is displayed; otherwise, false.

#Remarks

Use the openMenu / closeMenu methods to open / close the dashboard menu from code.

#name Property

Specifies the unique extension name.

#Declaration

TypeScript
name: string

#Property Value

Type
string

#Remarks

Warning

Do not change the unique name of the extension registered in the Web Dashboard to avoid exceptions.

#removeMenuItem Property

Removes the specified dashboard item from the dashboard menu.

#Declaration

TypeScript
removeMenuItem: (menuItemId: string) => void

#Property Value

Type Description
(menuItemId: string) => void

A DashboardMenuItem.id value that is passed as a parameter.

#Remarks

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

JavaScript
var toolbox = dashboardControl.findExtension('toolbox');
toolbox.removeMenuItem("open-dashboard");

Use the id property value to address the menu item.

#removeToolbarItem Property

Removes the specified toolbar item from the specified toolbar group.

#Declaration

TypeScript
removeToolbarItem: (groupName: string, toolbarItemName: string) => void

#Property Value

Type Description
(groupName: string, toolbarItemName: string) => void

The DashboardToolbarGroup.name and DashboardToolbarItem.name values that are passed as parameters.

#Remarks

Use the name and name property values to obtain the toolbar item and group names, respectively.

#removeToolboxItem Property

Removes the specified toolbox item from the specified toolbox group.

#Declaration

TypeScript
removeToolboxItem: (groupName: string, toolboxItemName: string) => void

#Property Value

Type Description
(groupName: string, toolboxItemName: string) => void

The DashboardToolboxGroup.name and DashboardToolbarItem.name values that are passed as parameters.

#Remarks

The code snippet below shows how to delete the ‘Grid’ item from the Toolbox.

JavaScript
toolbox.removeToolboxItem("common", "Grid");

Use the name and name property values to obtain the toolbox item and group names, respectively.

#selectMenuItem Property

Selects a menu item in the dashboard menu.

#Declaration

TypeScript
selectMenuItem: (menuItem: DevExpress.Dashboard.Designer.DashboardMenuItem) => void

#Property Value

Type Description
(menuItem: DashboardMenuItem) => void

A function that takes a DashboardMenuItem object to be selected.

#Remarks

To show a custom menu item, call the openMenu function of the toolbox extension:

js
function onDashboardInitialized(s, args) {  
    var toolbox = s.GetDashboardControl().findExtension("toolbox");  
    toolbox.openMenu();  
    toolbox.selectMenuItem(toolbox.menuItems().filter(item => item.id === "dashboard-save-as")[0]);  
}  

#showPanelAsync Property

Shows the Toolbox asynchronously.

#Declaration

TypeScript
showPanelAsync: (options: DevExpress.Dashboard.WorkingModeSwitchingOptions) => JQueryPromise<{}>

#Property Value

Type Description
(options: WorkingModeSwitchingOptions) => JQueryPromise<>

The WorkingModeSwitchingOptions object that returns a JQuery promise.

#Remarks

The code below shows the Toolbox asynchronously and then adjusts the left indent of the DashboardControl using the surfaceLeft property.

JavaScript
function showToolbox() {
    // The dashboardControl variable is the obtained DashboardControl instance.
  var toolbox = dashboardControl.findExtension('toolbox');
  toolbox.showPanelAsync({}).done(function (e) {
    dashboardControl.surfaceLeft(e.surfaceLeft);
  });
}

#template Property

Specifies a custom template for the Toolbox.

#Declaration

TypeScript
template: DevExpress.Dashboard.KnockoutTemplate

#Property Value

Type Description
KnockoutTemplate

An object that defines a template.

#toolbarGroups Property

Provides an access to the toolbar groups collection obtained from the Toolbox.

#Declaration

TypeScript
toolbarGroups: ko.ObservableArray<DevExpress.Dashboard.Designer.DashboardToolbarGroup>

#Property Value

Type Description
ObservableArray<DashboardToolbarGroup>

A collection of the DashboardToolbarGroup objects that are the toolbar groups.

#Remarks

Use the toolbarGroups property to get a list of the DashboardToolbarGroup objects.

#toolboxGroups Property

Provide an access to the collection of toolbox groups obtained from the Toolbox.

#Declaration

TypeScript
toolboxGroups: ko.ObservableArray<DevExpress.Dashboard.Designer.DashboardToolboxGroup>

#Property Value

Type Description
ObservableArray<DashboardToolboxGroup>

A collection of the DashboardToolboxGroup objects that are the toolbox groups.

#Remarks

Use the toolboxGroups property to get a list of the DashboardToolboxGroup objects.

#viewerToDesignerAction Property

Specifies an action executed at the moment of switching from Viewer to Designer.

#Declaration

TypeScript
viewerToDesignerAction: DevExpress.Dashboard.SequenceAction

#Property Value

Type Description
SequenceAction

An action executed at the moment of switching from Viewer to Designer.

#Methods

#closeMenu Method

Closes the dashboard menu.

#Declaration

TypeScript
closeMenu(): void

#Remarks

The following code shows how to close a dashboard menu:

JavaScript
var toolbox = dashboardControl.findExtension('toolbox');
toolbox.closeMenu();

Use the openMenu method to show the dashboard menu. The menuVisible property indicates whether the menu is opened.

#openMenu Method

Opens the dashboard menu.

#Declaration

TypeScript
openMenu(): void

#Remarks

The following code shows how to open a dashboard menu:

JavaScript
var toolbox = dashboardControl.findExtension('toolbox');
toolbox.openMenu();

Use the closeMenu method to hide the dashboard menu. The menuVisible property indicates whether the menu is opened.

#processKeyEvent(keyEventType, eventArgs) Method

Allows you to process which key was pressed.

#Declaration

TypeScript
processKeyEvent(
    keyEventType: DevExpress.Dashboard.KeyEventType,
    eventArgs: JQueryKeyEventObject
): boolean

#Parameters

Name Type Description
keyEventType KeyEventType
eventArgs JQueryKeyEventObject

A JQueryKeyEventObject object that identifies a key.

#Returns

Type Description
boolean

true, if a key used to open the dashboard menu; otherwise, false.

#start Method

Contains code that is executed when you register the dashboard extension.

#Declaration

TypeScript
start(): void

#stop Method

Contains code that is executed when you unregister the dashboard extension.

#Declaration

TypeScript
stop(): void