The requested page is not available for the requested platform. You are viewing the content for Default platform.

Create a Static 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 Extensions Overview topic.

This tutorial shows how to create the simplest custom item that only displays the 'Hello World!' text.

StaticItemExample

Before you begin, create a Web Dashboard project and perform the steps below:

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:

CustomItem_Static_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:

CustomItem_Static_Toolbox

This action adds the custom item that displays the 'Hello World!' text on its surface:

CustomItem_Static_Menu

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.