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

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.

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:

dashboardControl.unregisterExtension('toolbox');

Implements

IDisposable

IExtension

Inherited Members

dispose

Inheritance

DisposableObject

ToolboxExtension

constructor(dashboardControl)

Initializes a new instance of the ToolboxExtension class.

Declaration

constructor(
    dashboardControl: 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

addMenuItem: (menuItem: 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:

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

addToolbarItem: (groupName: string, toolbarItem: 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:

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

addToolboxItem: (groupName: string, toolboxItem: 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:

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

designerToViewerAction Property

Declaration

designerToViewerAction: SequenceAction

Property Value

Type
SequenceAction

hidePanelAsync Property

Hides the Toolbox asynchronously.

Declaration

hidePanelAsync: (options: 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.

function hideToolbox() {
  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

menuItems: ko.ObservableArray<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:

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

readonly 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

name: string

Property Value

Type	Description
string	The unique extension name. The return value is `toolbox`.

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

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:

var toolbox = dashboardControl.findExtension('toolbox');
toolbox.removeMenuItem("openDashboard");

Use the id property value to address the menu item.

removeToolbarItem Property

Removes the specified toolbar item from the specified toolbar group.

Declaration

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

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.

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

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

selectMenuItem Property

Declaration

selectMenuItem: (menuItem: DashboardMenuItem) => void

Property Value

Type
(menuItem: DashboardMenuItem) => void

showPanelAsync Property

Shows the Toolbox asynchronously.

Declaration

showPanelAsync: (options: 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.

function showToolbox() {
  var toolbox = dashboardControl.findExtension('toolbox');
  toolbox.showPanelAsync({}).done(function (e) {
    dashboardControl.surfaceLeft(e.surfaceLeft);
  });
}

template Property

Declaration

template: KnockoutTemplate

Property Value

Type
KnockoutTemplate

toolbarGroups Property

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

Declaration

toolbarGroups: ko.ObservableArray<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

toolboxGroups: ko.ObservableArray<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

Declaration

viewerToDesignerAction: SequenceAction

Property Value

Type
SequenceAction

Methods

closeMenu Method

Closes the dashboard menu.

Declaration

closeMenu(): void

Remarks

The following code shows how to close a dashboard menu:

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

openMenu(): void

Remarks

The following code shows how to open a dashboard menu:

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

processKeyEvent(
    keyEventType: KeyEventType,
    eventArgs: JQueryKeyEventObject
): boolean

Parameters

Name	Type	Description
keyEventType	KeyEventType	The KeyEventType object that identifies a user interaction with the keyboard.
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

start(): void

stop Method

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

Declaration

stop(): void