Create a Data-Aware Item
- 6 minutes to read
Important
All custom items are based on the Web Dashboard’s customization using independent modules called extensions. Learn about extension concepts by referring to the Extensions Overview topic.
This lesson shows you how to create a custom item that displays formatted dimension values and allows end-users to color these values.
The custom item also introduces an additional option that allows end-users to change the item’s background color.
Before you begin, open the project created from the template. Then, perform the steps below:
- Provide a Toolbox Icon
- Create the Custom Item’s Script File
- Specify the Custom Item’s Settings
- Implement the Custom Item’s Rendering
- Register the Custom Item as an Extension
- Run the Project to See the Result
Provide a Toolbox Icon
As for the static custom item, specify an SVG icon appear in the Custom Items Toolbox group. On the BeforeRender event (the window’s load event before the render method for HTML JS control), register the required icon using the ResourceManager.registerIcon method:
function onBeforeRender(sender) {
// ...
var DATAAWARE_ITEM_ICON = '<svg id="dataAwareItemIcon" viewBox="0 0 24 24"><path stroke="#ffffff" fill="#4842f4" d="M12 2 L2 22 L22 22 Z" /></svg>';
DevExpress.Dashboard.ResourceManager.registerIcon(DATAAWARE_ITEM_ICON);
};
The icon’s identifier (dataAwareItemIcon) is used later in this tutorial to initialize a custom item.
Create the Custom Item’s Script File
In your project add the DataAwareItem.js file to the Custom_Items folder. Specify the script file URL in the <body> section to include scripts after the control is rendered:
<asp:Content ID="Content1" ContentPlaceHolderID="MainContent" runat="server">
<script type="text/javascript">
function onBeforeRender(sender) {
//...
}
</script>
<dx:ASPxDashboard ID="ASPxDashboard1" runat="server" Width="100%" Height="100%">
<ClientSideEvents BeforeRender="onBeforeRender" />
</dx:ASPxDashboard>
<script src="Custom_Items/DataAwareItem.js"></script>
</asp:Content>
Specify the Custom Item’s Settings
In the DataAwareItem.js file, specify the custom item’s metadata (ICustomItemMetaData) by adding following options:
- The bindings option allows you to configure a set of dimensions/measures used to bind a custom item to data. The data-aware custom item has only a single dimension in the Binding menu. Data to be displayed is obtained later using the iterateData method.
- The properties option specifies custom properties that can be used by an end-user to configure item’s specific settings. The Data-Aware item provides an option that allows end-users to switch a background color using the created Backcolor property. A logic used to change the background color is implemented later in the renderContent method.
- The icon option allows you to pass the icon’s identifier specified in the first step (dataAwareItemIcon).
- The title option specifies the default custom item name.
var dataAwareItemMetaData = {
bindings: [{
propertyName: 'dimensionValue',
dataItemType: 'Dimension',
displayName: 'Dimension',
enableColoring: true
}],
properties: [{
propertyName: 'backColorProperty',
editor: DevExpress.Dashboard.Metadata.editorTemplates.buttonGroup,
displayName: 'Backcolor',
sectionName: 'Background',
values: {
None: 'None',
Red: 'Red',
Blue: 'Blue'
},
defaultVal: 'None'
}],
icon: 'dataAwareItemIcon',
title: 'Data Aware Item'
};
Implement the Custom Item’s Rendering
The CustomItemViewer class allows you to implement a visual representation of the custom item. You need to override the renderContent method to visualize dimension names as HTML content.
Create two methods that allow you to display dimension values from a data source and implement logic for a custom property.
The _getDataSource method returns data that is displayed in the custom item. Use the getDisplayText method to get dimension names and the iterateData method to generate data rows for the custom item. The iterateData method accepts a function as a parameter and allows you to iterate through aggregated data and obtain required values (dimension or measure values, display texts, colors, etc.). The Data-Aware item has one dimension whose values can be colored (the bindings | enableColoring option in the previous step). When an end-user binds the custom item to the data field and enables coloring, the iterateData method is called for each row in the aggregated data.
The _getBackColorProperty method changes the background color according to the Options | Background | Backcolor option’s value. Use the getPropertyValue(propertyName) method to indicate the background color’s value and change the css style of the ‘background’ element.
var dataAwareItemViewer = (function (_base) {
__extends(dataAwareItemViewer, _base);
function dataAwareItemViewer(model, $container, options) {
_base.call(this, model, $container, options);
}
dataAwareItemViewer.prototype.renderContent = function ($element, changeExisting) {
var clientData = this._getDataSource();
$element.empty();
clientData.forEach(function (item) {
$element.append($('<div/>', {
style: "color:" + item.color
}).html(item.dimensionDisplayText));
});
$element.css("background", this._getBackColorProperty());
};
dataAwareItemViewer.prototype._getDataSource = function () {
var clientData = [];
this.iterateData(function (dataRow) {
clientData.push({
dimensionDisplayText: dataRow.getDisplayText('dimensionValue')[0] || "",
color: dataRow.getColor()[0]
});
});
return clientData;
};
dataAwareItemViewer.prototype._getBackColorProperty = function () {
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)";
}
};
return dataAwareItemViewer;
}(DevExpress.Dashboard.CustomItemViewer));
Register the Custom Item as an Extension
Create the dataAwareItem function that implements the ICustomItemExtension interface. This function is used to register the created custom item as the Web Dashboard’s extension.
function dataAwareItem(dashboardControl) {
return {
name: "dataAwareItem",
metaData: dataAwareItemMetaData,
createViewerItem: function (model, $element, content) {
return new dataAwareItemViewer(model, $element, content);
}
};
}
Go to the page containing the Web Dashboard code and pass the created function as the DashboardControl.registerExtension method’s parameter:
function onBeforeRender(sender) {
// ...
DevExpress.Dashboard.ResourceManager.registerIcon(DATAAWARE_ITEM_ICON);
dashboardControl.registerExtension(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:
