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. Learn about extension concepts by referring to the Extensions Overview topic.
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 and 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
On the BeforeRender event (the window’s load event before the render method for HTML JS control), specify an SVG icon for your custom item. The icon appears in the Custom Items Toolbox group. Register the required icon using the ResourceManager.registerIcon method:
function onBeforeRender(sender) {
// ...
var HELLOWORLD_ITEM_ICON = '<svg id="helloWorldItemIcon" viewBox="0 0 24 24"><path stroke="#42f48f" fill="#42f48f" d="M12 2 L2 22 L22 22 Z" /></svg>';
DevExpress.Dashboard.ResourceManager.registerIcon(HELLOWORLD_ITEM_ICON);
};
The icon’s identifier (helloWorldItemIcon) is used later in this tutorial to initialize a custom item.
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>
Specify the Custom Item’s Settings
In the HelloWorldItem.js file, specify the custom item’s metadata (ICustomItemMetaData) by adding following options:
- 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 helloWorldItemMetaData = {
icon: 'helloWorldItemIcon',
title: 'Hello World Item'
};
The image below demonstrates how the custom item appears in the Toolbox:
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 helloWorldItemMetaData = {
// ...
};
var helloWorldItemViewer = (function (_base) {
__extends(helloWorldItemViewer, _base);
function helloWorldItemViewer(model, $container, options) {
_base.call(this, model, $container, options);
}
helloWorldItemViewer.prototype.renderContent = function ($element, changeExisting) {
$element.empty();
$element.append("Hello World!");
};
return helloWorldItemViewer;
}(DevExpress.Dashboard.CustomItemViewer));
Register the Custom Item as an Extension
Create the helloWorldItem function that implements the ICustomItemExtension interface. This function is used to register the created custom item as the Web Dashboard’s extension.
// ...
var helloWorldItemViewer = (function (_base) {
// ...
}(DevExpress.Dashboard.CustomItemViewer));
function helloWorldItem(dashboardControl) {
return {
name: "helloWorldItem",
metaData: helloWorldItemMetaData,
createViewerItem: function (model, $element, content) {
return new helloWorldItemViewer(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(HELLOWORLD_ITEM_ICON);
dashboardControl.registerExtension(helloWorldItem(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 learn how to display grouped data in the custom item and supply end-users with the capability to specify custom options.