Dashboard Item Caption in the Web Dashboard

  • 7 minutes to read

Each dashboard item has a caption that is displayed at the top of this item. The caption can contain static text, svg images, and command buttons. These elements are called toolbar items:

wdd-dashboard-item-caption

Caption Overview

You can control the dashboard item caption’s visibility.

  • When the caption is on, it is always displayed at the top of the dashboard item. Some command buttons are displayed when you hover the mouse pointer over them.
  • When the caption is off, it is not visible by default. Some command buttons are displayed in a floating panel when you hover the mouse pointer over them. On touch-based devices, you need to do extra click to show the caption elements when the caption is hidden.

Go to the dashboard item Options menu and use the Show Caption option to control the caption visibility:

wdd-di-caption-options

Use the DashboardItem.showCaption property to control the caption visibility in code.

Note

The Range Filter dashboard item’s caption is not visible by default.

The dashboard item caption consists of the following collections:

  • A static item is visible only if the caption is enabled (for example, the item caption or data reducing icon).
  • An action item is displayed only when the mouse pointer hovers over the dashboard item caption (for instance, the Export To and Values buttons).
  • A state item is displayed only in specific dashboards states (for example, the Drill Up and Clear Master Filter buttons).
  • A navigation item allows you to navigate through different dashboard screens (for example, Dashboards and Back buttons in mobile layout).

The table below lists the default information and buttons that are displayed in the dashboard item caption:

Static items

web-dashboard-item-caption-data-reduced-icon

Data Reducing icon

Shows that visible data is limited.

Text

Drill-Down Text

Shows a value or values from the current drill-down hierarchy. See Drill-Down for more details.

Text

Caption Text

Shows a static text in the caption. Use the DashboardItem.name property to set a caption text.

Action items

web-dashboard-item-caption-maximize-item-icon

Maximize button

Expands any dashboard item to fit the whole dashboard and allows you to view data in greater detail. Refer to Dashboard Layout in the Web Dashboard for more information.

web-dashboard-item-caption-restore-down-icon

Restore button

Restores the expanded item to its initial state.

web-dashboard-item-caption-export-icon

Export to button

Invokes the export menu for a dashboard item. For information on how to export individual dashboard items, see Exporting.

web-dashboard-item-caption-data-inspector-icon

Inspect Data button

Invokes the Data Inspector that contains two grids that display raw and aggregated data for the current dashboard item.

web-dashboard-item-caption-values-icon

Values button

Invokes a drop-down menu that allows you to switch between provided values (in the pie, card, gauge, and maps dashboard items). For more information, see the Providing Data topic for the corresponding dashboard item.

web-dashboard-item-caption-multiselection-icon

Multi-Select button

Allows you to filter data by selecting multiple elements in dashboard items.

web-dashboard-item-caption-range-time-periods-icon

Select Date Time Period menu / button

Allows you to select date-time periods for the RangeFilter and DateFilter items.

web-dashboard-item-caption-filters-icon

Filters button

Displays filters affecting the current dashboard item or entire dashboard. This button is only available in mobile layout.

State items

web-dashboard-item-caption-clear-master-filter-icon

Clear Master Filter button

Allows you to reset filters when a dashboard item acts as the Master Filter. For more information, see Master Filtering.

web-dashboard-item-caption-drill-up-icon

Drill Up button

Allows you to return to the previous detail level when this item’s drill-down capability is enabled.

web-dashboard-item-caption-clear-selection-icon

Clear Selection button

Allows you to clear the selection inside an item.

web-dashboard-item-caption-map-initial-extent-icon

Initial Extent button

Restores the default size and position of the Map dashboard items.

Navigation items

Dashboards

Dashboards button

Displays a list of available dashboards.

web-dashboard-item-caption-back-icon

Back button

Returns to the dashboard items list.

Customization

The Web Dashboard allows you to customize the dashboard item’s caption and dashboard title. For instance, you can add custom command buttons, create additional menus, add static texts, and so on.

Handle the ItemCaptionToolbarUpdated event to customize the dashboard item caption. The e.options property provides access to the caption’s options (DashboardItemCaptionToolbarOptions). The DashboardItemCaptionToolbarOptions object allows you to access a specific toolbar item’s collection (like static or action items) and get the available toolbar items in each collection. A toolbar item is the ViewerToolbarItem object.

Use the e.dashboardItem and e.itemName properties to identify a dashboard item for which the event is raised.

Predefined Colors

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:

Class Name Description
dx-dashboard-icon The theme’s primary color.
dx-dashboard-contrast-icon The theme’s additional color.
dx-dashboard-accent-icon The theme’s accent color.
dx-dashboard-green-icon A green hue based on the theme.
dx-dashboard-red-icon A red hue based on the theme.
dx-dashboard-yellow-icon A yellow hue based on the theme.

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>

Tip

You can call the ResourceManager.registerIcon method and pass the icon’s id as an alternative variant to add an icon to the page. See the Custom Item tutorials for an example: Create a Static Custom Item for the Web Dashboard.

Example

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:

dashboard-ViewerToolbarItemMenu-example

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

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

See the following topic for more information about available client-side customization capabilities: DashboardControl’s Client-Side API Overview.

Refer to the Array documentation for information on how to manage the collection of toolbar items.