Create a Data-Aware Item for the Web Dashboard
- 9 minutes to read
Important
A custom item is an independent module called the extension. If you are not familiar with the basic concepts of extensions, please review the following topic before you continue: Extensions Overview.
In the previous lesson, you created a custom item that displays text and added a custom property that allows you to change this static text.
This tutorial explains how to create a custom item that is bound to data, and how to display data from a data source. This custom item displays formatted dimension values and allows users to color these values. The custom item also contains an additional option that allows users to change the item’s background color.
You can download the ready-to-use projects:
Prerequisites
A custom item script depends on the platform you use:
- Module script
- Client components (Angular, React, Vue) use imports and classes to define a custom item.
- Classic script
- A script for the ASP.NET Web Forms, ASP.NET MVC, ASP.NET Core, BLazor, and JavaScript controls encapsulates a custom item in the IIFE function expression.
Before you begin, create a Web Dashboard project for the required platform.
Create an External Script
In your project, create an external DataAwareItem.js file, so you can reuse the created extension in other Web Dashboard applications.
Define a Toolbox Icon
In the DataAwareItem.js file, add a 24x24 SVG icon as a string variable:
var svgIcon = '<svg id="dataAwareItemIcon" viewBox="0 0 24 24"><path stroke="#ffffff" fill="#4842f4" d="M12 2 L2 22 L22 22 Z" /></svg>';
The icon will be used to display the custom item in the Toolbox.
Specify the Custom Item’s Settings
Implement the ICustomItemMetaData interface to define this custom item’s settings:
- In the bindings option, configure a dimension to bind a custom item to data. Implement the ICustomItemBinding interface and create an object that defines a dimension. Include the enableColoring option to specify that the created dimension supports coloring.
- In the icon option, pass the SVG icon’s id (
dataAwareItemIcon
). - In the title option, specify the text displayed in the dashboard item caption and as the Toolbox element’s tooltip (
Data Aware Item
).
var dataAwareItemMetaData = {
bindings: [{
propertyName: 'dimensionValue',
dataItemType: 'Dimension',
displayName: 'Dimension',
enableColoring: true
}],
// ...
icon: 'dataAwareItemIcon',
title: 'Data Aware Item'
};
As a result, the following icon is added to the Toolbox:
The Binding menu contains the Dimension section and a user can add one dimension from a data source:
Create a Custom Property
Use the ICustomItemMetaData.customProperties and ICustomItemMetaData.optionsPanelSections properties to define a custom option that allows users to change the item’s background color:
- Create the CustomPropertyMetadata object and define a string
backColorProperty
option. Add the created option to the customProperties collection. - Create the SectionOptions object that defines a section in the dashboard item’s Options menu. The items collection contains editors used to manage custom property values in the UI. Use the FormItemTemplates.buttonGroup property to create the color switcher. Add the created option to the optionsPanelSections collection. Set the created
backColorProperty
option as a data field.
import { CustomItem } from 'devexpress-dashboard/model'
import { FormItemTemplates } from 'devexpress-dashboard/designer'
// ...
var dataAwareItemMetaData = {
// ...
customProperties: [{
owner: CustomItem,
propertyName: 'backColorProperty',
valueType: 'string',
defaultValue: 'None'
}],
optionsPanelSections: [{
title: 'Background',
items: [{
dataField: 'backColorProperty',
label: { text: 'Backcolor' },
template: FormItemTemplates.buttonGroup,
editorOptions: {
items: [{ text: 'None' }, { text: 'Red' }, { text: 'Blue' }]
}
}]
}],
// ...
};
Implement Custom Item Rendering
The CustomItemViewer class specifies visual representation of the custom item. Override the CustomItemViewer.renderContent method to display custom item content.
Create methods that allow you to display dimension values from a data source and implement the following logic for a custom property:
- _getDataSource
- The
_getDataSource
method returns data displayed in the custom item. The iterateData method generates data rows for the custom item. When a user binds the custom item to a data field and enables coloring, theiterateData
method is called for each row in the aggregated data. This method accepts a function as a parameter and allows you to iterate through aggregated data and obtain required values (dimension or measure values, display text, colors, and more). In this data-aware item, theiterateData
method obtains display text and the color for thedimensionValue
data item (the getDisplayText and getColor methods). The enableColoring option enabled in the metadata indicates that dimension values can be colored. - _getBackColorProperty
- The
_getBackColorProperty
method changes the background color according to the Options | Background | Backcolor custom UI option. Use the CustomItemViewer.getPropertyValue method to get the value of the created custom option and change the CSS style of thebackground
HTML element according to the returned value.
Note
Do not set IDs for DOM elements in the CustomItemViewer.renderContent method call. When the custom item is maximized, its viewer part (CustomItemViewer is copied with all its elements and the element ID will not be unique on the page.
import { CustomItemViewer, ResourceManager } from 'devexpress-dashboard/common'
// ...
class DataAwareItemViewer extends CustomItemViewer {
constructor(model, $container, options) {
super(model, $container, options);
}
renderContent(element, changeExisting) {
while (element.firstChild)
element.removeChild(element.firstChild);
var clientData = this._getDataSource();
clientData.forEach(function (item) {
var div = document.createElement('div');
div.style.color = item.color;
div.innerText = item.dimensionDisplayText;
element.appendChild(div);
});
element.style.background = this._getBackColorProperty();
};
_getDataSource() {
var clientData = [];
this.iterateData(function (dataRow) {
clientData.push({
dimensionDisplayText: dataRow.getDisplayText('dimensionValue')[0] || "",
color: dataRow.getColor()[0]
});
});
return clientData;
};
_getBackColorProperty() {
switch (this.getPropertyValue('backColorProperty')) {
case 'None': return "rgb(255,255,255)";
case 'Red': return "rgb(255,220,200)";
case 'Blue': return "rgb(135,206,235)";
}
};
}
Create an Extension
The ICustomItemExtension interface allows you to define a custom item as an extension. Use the ResourceManager.registerIcon static method to register the custom item’s icon. Pass the created metadata to the ICustomItemExtension.metaData property. Call the ICustomItemExtension.createViewerItem method to implement the created custom item.
import { CustomItemViewer, ResourceManager } from 'devexpress-dashboard/common'
// ...
class DataAwareItem {
constructor(dashboardControl) {
ResourceManager.registerIcon(svgIcon);
this.name = "dataAwareItem";
this.metaData = dataAwareItemMetaData;
}
createViewerItem(model, $element, content) {
return new DataAwareItemViewer(model, $element, content);
}
}
export default DataAwareItem;
Register the Custom Item as an Extension
Attach the created DataAwareItem.js script file to the page containing the Web Dashboard code. The external script you created is now available in the application.
You need to register the extension before the control is rendered. Refer to the following topics for information on how to get access to the DashboardControl instance and customize it before any element in the Web Dashboard control has been rendered:
- Manage Extensions in ASP.NET Core
- Manage Extensions in ASP.NET MVC
- Manage Extensions in ASP.NET Web Forms
- Manage Extensions in Angular
- Manage Extensions in React
- Manage Extensions in Vue
- Manage Extensions in the JavaScript Dashboard Control
- JavaScript Customization of Blazor Dashboard Component
Register the created extension in the DashboardControl.registerExtension method call:
function onBeforeRender(e) {
var dashboardControl = e.component;
dashboardControl.registerExtension(new DashboardPanelExtension(dashboardControl));
dashboardControl.registerExtension(new HelloWorldItem(dashboardControl));
dashboardControl.registerExtension(new DataAwareItem(dashboardControl));
// ...
}
Run the Project to See the Result
Run the project and click the Data Aware Item Toolbox item to add the custom item to the dashboard:
This action adds the empty item to the dashboard.
Invoke the Binding menu, click Set Dimension, and select the ProductName field:
Use Options | Coloring to enable coloring for dimensions:
Go to Options | Background and use the Backcolor custom option to change the item’s background color:
In the next lesson, you will create a more “real-world” custom item that uses an external visualization widget that supports data binding, master filtering, and coloring.
Export Limitations
A custom item does not support the default export mechanism. For example, you cannot use WebDashboardExporter / ASPxDashboardExporter to export custom items. In this instance, you need to implement custom export:
- On the client, override the CustomItemViewer.getExportInfo method and pass an object with the
image
field. Encode the image in the ASCII format using the Base64 scheme to display a custom item in the exported document. - If you cannot generate an image on the client, implement your own export logic on the server side. For this, handle the DashboardConfigurator.CustomExport / ASPxDashboard.CustomExport events.