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');

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

Implements

IExtension

Inherited Members

dispose

Inheritance

DisposableObject

ToolboxExtension

constructor(dashboardControl)

Initializes a new instance of the ToolboxExtension class.

Declaration

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

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:

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: 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:

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: 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:

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

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

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.

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

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:

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

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

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

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("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

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

Selects a menu item in the dashboard menu.

Declaration

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:

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

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.

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

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

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

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

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

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: 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

start(): void

stop Method

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

Declaration

stop(): void