Dashboard Title in the Web Dashboard

• Oct 04, 2023
• 4 minutes to read

The Dashboard Title is located at the top of the dashboard surface and can contain static text, svg images, and command buttons. These elements are called toolbar items:

Change Title in the UI

To change title settings, invoke the dashboard menu and open the Title page.

You can specify the following options on this page:

Option	Description
Text	Specifies the dashboard title text.
Visible	Specifies whether the dashboard title is visible.
Alignment	Specifies the alignment of the dashboard title.
Include Master Filter	Specifies whether to show the state of master filter items in the dashboard title. When a user hovers over the filter icon (), all master filters applied to the dashboard are displayed in the invoked popup.
Image	Allows you to specify the image displayed within the dashboard title.

The dashboard title can contain command buttons.

Command Button	Description
Export To	Allows end-users to export the dashboard. To learn more about exporting, see Exporting.
Parameters	Allows end-users to modify dashboard parameter values. To learn more about parameters, see Parameters.

Change Title in Code

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

Handle the ViewerApiExtensionOptions.onDashboardTitleToolbarUpdated event to customize the dashboard title. The e.options property provides access to the title’s options (DashboardTitleToolbarOptions). Use it to get access to a specific toolbar item’s collection in the dashboard title (like static or action items). A toolbar item is the ViewerToolbarItem object.

Use the e.dashboard property to identify a dashboard 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 manage the dashboard title: add a new toolbar item, customize the existing toolbar item, and delete a specific element from the toolbar items collection.

The customizeTitleToolbar function below do the following:

• Creates a custom button with a popup menu. The button belongs to the actionItems collection and is displayed with the Export To and Parameters buttons. The itemClick method call returns a name of the clicked item.
• Changes text displayed in the dashboard title to ‘Custom Dashboard Title’.
• Removes the ‘Export To’ button from the dashboard title.

The image below shows the added toolbar item:

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

JavaScript

function customizeTitleToolbar(e) {
    // Add a new toolbar item to the title for each dashboard.
    e.options.actionItems.push({
        icon: 'gray-triangle',
        type: "menu",
        menu: {
            title: 'Custom Menu',
            type: 'list',
            items: ['First item', 'Second item', 'Third item'],
            selectionMode: 'single',
            itemClick: function (itemData) {
                DevExpress.ui.notify("You click on the " + itemData.toString(), "success");
            }
        }
    });
    // Customize the title text.
    let caption = e.options.contentItems.filter(function (item) {
        return item.name === 'dashboard-title'
    });
    if (caption.length > 0) {
        caption[0].text = 'Custom Dashboard Title';
    }
    // Remove the Export to button.
    e.options.actionItems = e.options.actionItems.filter(function (item) {
        return item.name !== 'export-menu'
    });
}

HTML

<div style="display: none;">
    <svg id="gray-triangle" class="dx-dashboard-icon" viewBox="0 0 24 24" style="fill: currentColor"><path d="M12 3 L3 21 L21 21 Z" /></svg>
</div>

See the following help topic for more information on how to customize the dashboard control on the client side: DashboardControl’s Client-Side API Overview.