Creating a Data-Aware Item

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 Working with Extensions topic.

This lesson shows you how to create a custom item that displays formatted dimension values and allows end-users to color these values.

DataAwareItem_Main

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

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 HTML5 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 method to indicates 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:

CustomItem_DataAware_Toolbox

This action adds the empty item to the dashboard.

DataAwareItem_Empty

Invoke the Binding menu, click Set Dimension and select the ProductName field:

DataAwareItem_Bound

Use Options | Coloring to enable coloring for dimensions:

DataAwareItem_Colored

Go to Options | Background and use the Backcolor custom option to change the item's background color:

DataAwareItem_BackColorProperty