ViewerToolbarItem Interface

A toolbar item.

Declaration

export interface ViewerToolbarItem

Remarks

The Web Dashboard allows you to customize the dashboard item caption and dashboard title. For instance, you can add custom command buttons, create additional popup menus, add static texts, etc. Use the DashboardItemCaptionToolbarOptions and DashboardTitleToolbarOptions classes to create a toolbar item of the specified type (like custom buttons or static text). The ViewerToolbarItem object represents a toolbar item.

Use the ViewerApiExtensionOptions.onItemCaptionToolbarUpdated and ViewerApiExtensionOptions.onDashboardTitleToolbarUpdated handlers to customize the dashboard item’s caption and dashboard title.

You can use predefined colors for toolbar icons to make the icons consistent with the entire dashboard application. For example, you can use the predefined color for a new item caption button. In this case, the button’s color depends on the selected Web Dashboard theme.

The table below lists the available predefined color classes:

Add the class="Class Name" attribute to the icon’s svg definition to specify the icon’s color.

<div style="display: none;">
    <svg id="green-circle" class="dx-dashboard-green-icon" viewBox="0 0 24 24" width="48" height="48"><circle cx="12" cy="12" r="11" /></svg>
    <svg id="yellow-circle" class="dx-dashboard-yellow-icon" viewBox="0 0 24 24" width="48" height="48"><circle cx="12" cy="12" r="11" /></svg>
    <svg id="red-circle" class="dx-dashboard-red-icon" viewBox="0 0 24 24" width="48" height="48"><circle cx="12" cy="12" r="11" /></svg>
</div>

For the dx-dashboard-icon class, you can change an icon’s color when it is hovered (like the Maximize or Export to buttons). To do this, add the style="fill: currentColor" attribute to the svg definition:

<div style="display: none;">
    <svg id="base-triangle" class="dx-dashboard-icon" style="fill: currentColor" viewBox="0 0 24 24" width="24" height="24"><path d="M12 3 L3 21 L21 21 Z" /></svg>
    <svg id="base-circle" class="dx-dashboard-icon" style="fill: currentColor" viewBox="0 0 24 24" width="24" height="24"><circle cx="12" cy="12" r="11" /></svg>
</div>

The following example shows how to add a toolbar item to the dashboard item caption: add a new toolbar item, customize the existing toolbar item, and delete a specific element from the toolbar items collection.

The customizeCaptionToolbar function below do the following:

• Creates a custom button for each dashboard item. The itemClick method call returns the item’s component name.
• Creates a custom button with a pop-up menu for the Chart dashboard item. The button belongs to the DashboardItemCaptionToolbarOptions.actionItems collection and is displayed only when the mouse pointer hovers over the dashboard item caption. The pop-up menu contains three icon elements. The itemClick method call returns a name of the clicked item.
• Changes the ListBox caption to ‘Filter’.
• Removes the caption text for the Chart dashboard item.

The image below shows the added toolbar items:

Handle the ViewerApiExtensionOptions.onItemCaptionToolbarUpdated event depending on your platform and call the custom customizeCaptionToolbar function in the event handler:

• JavaScript
• HTML

function customizeCaptionToolbar(e) {
    // Add a new toolbar item to the caption for each dashboard item.
    e.options.actionItems.push({
        type: "button",
        icon: "base-triangle",
        hint: "Show Component Name",
        click: function () {
            DevExpress.ui.notify("The component name of this dashboard item is " + e.itemName, "info");
        }
    });
    // Add a new toolbar item to the caption for the specific Chart item.
    if (e.itemName === "chartDashboardItem1") {
        e.options.actionItems.push({
            type: "menu",
            icon: "base-circle",
            menu: {
                type: "icons",
                items: ["green-circle", "yellow-circle", "red-circle"],
                selectionMode: "none",
                title: "Circles",
                itemClick: function (itemData) {
                    DevExpress.ui.notify("This is " + itemData.toString(), "success");
                }
            }
        });
    }
    // Change the existing toolbar item in the caption.
    if (e.itemName === "listBoxDashboardItem1") {
        var caption = e.options.staticItems.filter(function (item) {
            return item.name === 'item-caption'
        });
        if (caption.length > 0) {
            caption[0].text = 'Filter';
        }
    }
    // Remove the existing toolbar item from the caption.
    if (e.itemName === "chartDashboardItem1") {
        e.options.staticItems = e.options.staticItems.filter(function (item) {
            return item.name !== 'item-caption'
        });
    }
}

<div style="display: none;">
    <svg id="base-circle" class="dx-dashboard-icon" style="fill: currentColor" viewBox="0 0 24 24" width="24" height="24"><circle cx="12" cy="12" r="11" /></svg>
    <svg id="green-circle" class="dx-dashboard-green-icon" viewBox="0 0 24 24" width="48" height="48"><circle cx="12" cy="12" r="11" /></svg>
    <svg id="yellow-circle" class="dx-dashboard-yellow-icon" viewBox="0 0 24 24" width="48" height="48"><circle cx="12" cy="12" r="11" /></svg>
    <svg id="red-circle" class="dx-dashboard-red-icon" viewBox="0 0 24 24" width="48" height="48"><circle cx="12" cy="12" r="11" /></svg>
</div>

Properties

checked Property

Specifies a value indicating whether the toolbar item is enabled.

Declaration

checked?: boolean

Property Value

true , if the toolbar item is enabled; otherwise, false.

|

click Property

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

Declaration

click?: (element: DevExpress.Dashboard.DxElement) => void

Property Value

A function that is executed when a button click occurs.

|

Remarks

The click event is raised for the toolbar item when its ViewerToolbarItem.type is button. For the menu value, use the ViewerToolbarItemMenu.itemClick property to raise the click event for a specific popup menu item.

disabled Property

Specifies whether the current toolbar item is disabled and cannot be clicked.

Declaration

disabled?: boolean

Property Value

true , to disable a toolbar item; otherwise, false.

|

hint Property

Specifies the text displayed as a toolbar item’s hint.

Declaration

hint?: string

Property Value

A string value that is a toolbar item’s hint.

|

Remarks

The hint property displays a simple popup hint with additional information about the item being hovered over. To provide a complex tooltip, use the tooltip property.

icon Property

Specifies the id from the icon’s SVG definition.

Declaration

icon?: string

Property Value

A string that is the id from the icon’s SVG definition.

|

Remarks

Web Dashboard supports icons in the SVG format. To provide an icon for the toolbar item, add the SVG definition onto the page and assign the id value from the definition to the icon property.

See Predefined Colors for information on which color constants you can use to natively embed an icon in the Web Dashboard application.

The recommended icon size is 24 x 24 px.

Note

The dashboard toolbar item is not displayed in the caption / title if neither the text nor icon properties are set.

menu Property

Specifies a toolbar item’s menu.

Declaration

menu?: ViewerToolbarItemMenu

Property Value

A ViewerToolbarItemMenu object that is a toolbar item’s menu.

|

name Property

Specifies a toolbar item’s unique name.

Declaration

name?: string

Property Value

A string value that is a toolbar item’s unique name.

|

Remarks

Go to dashboardToolbarItemNames to get a list of predefined names.

template Property

Specifies a custom template for a toolbar item in the dashboard item caption and dashboard title.

Declaration

template?: () => JQuery | Element | string

Property Value

An object that defines a template or specifies its name.

|

text Property

Specifies a text you can display in the toolbar item.

Declaration

text?: string

Property Value

A string value that is a toolbar item’s title.

|

Remarks

Note

The text property is not in effect if you set the icon property.

Note

The dashboard toolbar item is not displayed in the caption / title if neither the text nor icon properties are set.

tooltip Property

Specifies the text displayed as a toolbar item’s tooltip.

Declaration

tooltip?: ViewerToolbarItemTooltip | string

Property Value

A string value that is a toolbar item’s tooltip.

| | ViewerToolbarItemTooltip |

A ViewerToolbarItemTooltip object that is a tooltip.

|

Remarks

The tooltip property displays a customized popup hint with additional information about the item being hovered over. You can create a specified template to display a complex tooltip.

To provide a simple hint, use the hint property.

type Property

Specifies the type of the dashboard toolbar item.

Declaration

type?: "button" | "menu" | "text"

Property Value

Defines a clickable button.

| | "menu" |

Defines a pop-up menu.

| | "text" |

Defines an additional text you can display in the caption / title.

|

Remarks

The following properties are not in effect for the text dashboard toolbar item:

• ViewerToolbarItem.checked
• ViewerToolbarItem.click
• ViewerToolbarItem.hint
• ViewerToolbarItem.icon
• ViewerToolbarItem.menu
• ViewerToolbarItem.tooltip