Create a Static Item
- 4 minutes to read
Important
All custom items are based on the Web Dashboard’s customization using independent modules called extensions. Refer to the following topic for more information on extension concepts: Extensions Overview.
This tutorial shows how to create the simplest custom item that only displays the ‘Hello World!’ text.
Before you begin, create a Web Dashboard project. Then, follow the instructions below:
Create the Custom Item’s Script File
In your project add the HelloWorldItem.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/HelloWorldItem.js"></script>
</asp:Content>
Provide a Toolbox Icon
Encapsulate a custom item in the IIFE function expression to prevent a name conflict with custom items. Then, place an SVG icon into this function. The icon appears in the Custom Items Toolbox group.
var HelloWorldItem = (function() {
var svgIcon = '<svg id="helloWorldItemIcon" viewBox="0 0 24 24"><path stroke="#42f48f" fill="#42f48f" d="M12 2 L2 22 L22 22 Z" /></svg>';
})();
Specify the Custom Item’s Settings
In the HelloWorldItem.js file, add the following options to specify the custom item’s metadata (ICustomItemMetaData):
- The icon option allows you to pass the icon’s identifier specified in the first paragraph.
- The title option specifies the default custom item name.
var HelloWorldItem = (function() {
// ...
var helloWorldItemMetaData = {
icon: 'helloWorldItemIcon',
title: 'Hello World Item'
};
})();
Implement the Custom Item’s Rendering
The CustomItemViewer class specifies visual representation of the custom item. You need to override the renderContent method to display custom item content. Clear the item content and add a “Hello world!” string.
var HelloWorldItem = (function() {
// ...
function HelloWorldItemViewer(model, $container, options) {
DevExpress.Dashboard.CustomItemViewer.call(this, model, $container, options);
}
HelloWorldItemViewer.prototype = Object.create(DevExpress.Dashboard.CustomItemViewer.prototype);
HelloWorldItemViewer.prototype.constructor = HelloWorldItemViewer;
HelloWorldItemViewer.prototype.renderContent = function ($element, changeExisting) {
var element = $element.jquery ? $element[0] : $element;
element.innerText = "Hello World!";
};
})();
Register the Custom Item as an Extension
Create the helloWorldItem function that implements the ICustomItemExtension interface and return it from IIFE. This function is used to register the created custom item as the Web Dashboard’s extension.
var HelloWorldItem = (function() {
// ...
function HelloWorldItem(dashboardControl) {
DevExpress.Dashboard.ResourceManager.registerIcon(svgIcon);
this.name = "helloWorldItem";
this.metaData = helloWorldItemMetaData;
this.createViewerItem = function (model, $element, content) {
return new HelloWorldItemViewer(model, $element, content);
}
}
return HelloWorldItem;
})();
Go to the page containing the Web Dashboard code and pass the created function as the DashboardControl.registerExtension method’s parameter. The dashboardControl variable is the DashboardControl instance:
function onBeforeRender(sender) {
// The dashboardControl variable is the DashboardControl instance.
dashboardControl.registerExtension(new HelloWorldItem(dashboardControl));
};
Refer to the following topics on how to obtain the DashboardControl:
Run the Project to See the Result
Run the project and click the Hello World Item Toolbox item to add the custom item to the dashboard:
This action adds the custom item that displays the ‘Hello World!’ text on its surface:
You can configure only caption settings for this item.
In the next lesson, you will learn how to display grouped data in the custom item and supply users with the capability to specify custom options.