Creating your own widgets

Step-by-step instructions for creating your own widgets for the dashboard.

There are source files related to this tutorial at the bottom of this page.

1. Your widget class.

If the App_Code folder doesn’t contain the Widgets folder, please create it. Also create a code file with the name SampleWidget (pic. 1.1)

Pic 1.1

Pic 1.1.

Add the class SampleWidget into this file and derive it from the DashboardWidget class. DashboardWidget is an abtract class and you have to implement two properties:

  • ViewPanelPath
  • EditPanelPath

Override the IconPath property to set up your own icon.

Each dashboard widget consists of two parts - the view panel and the edit panel. These parts should be user controls (.ascx files). Accordingly the ViewPanelPath property should return the path to the view panel and the EditPanelPath property should return the path to the edit panel.

Create an inner class with the name Data (or use another name) and mark it as "Serializable2". In the Data class, define the properties you want to use in the widget. The object Data class will be serialized and saved into the database. The full class should look like picture 1.2.

Pic 1.2
Pic 1.2

2. Edit panel

Under Site/Dashboard/WebUserControls/Widgets/Edit there are saved Edit panels for different widgets (if this path doesn’t exist please create it). Create a new user control for your SampleWidget with the name EditSampleWidgetControl (pic. 2.1).

Pic 2.1

  Pic 2.1

Add markup

The EditPanel control should implement the IWidgetEditPanel interface. This interface contains two methods, GetPanelData and SetPanelData (pic. 2.2).

Pic 2.2

Pic 2.2

GetPanelData is called when the user clicks the Save or Cancel buttons. It should return a Data object that will be serialized and saved into the database. It should be the object of the Data class that we defined in step 1 of this tutorial.
SetPanelData is called on widget initialization and gets data as a parameter. This is the data object that was returned from the GetPanelData method. You have to cast it to your object. This object will be "Null" unless you click the Save button or save it from the view panel. Implement this control like in picture 2.3.

Pic 2.3

Pic 2.3.

3. View Panel

Under Site/Dashboard/WebUserControls/Widgets/View (if this path doesn’t exist please create it) there are saved View panels for different widgets. Create a new user control for your SampleWidget with the name ViewSampleWidgetControl (pic. 3.1.).

Pic 3.1

Pic 3.1.

And add markup.


The ViewPanel control should implement the IWidgetViewPanel interface. This interface contains one Initialize method and one WidgetID property (pic. 3.2).

Pic 3.2

Pic 3.2.

Initialize is called at view panel initialization and receives data as a parameter. The Data parameter is the object of the type you declared in step 1 of this tutorial (Data class). This object will be "Null" unless you created and saved it, or clicked the Save button in the edit panel.

WidgetID contains the widget id and you can use it to save or edit data from the view panel. To get the widget use the ModuleDashboard.Instance.DashboardWidgets.Get method.

To save the widget use the SetData method of the returned object. Implement this control like in picture 3.3.

Pic 3.3
Pic 3.3

4. Widget icon

The Widget icon should be 80 px in width and 80 px in height. Create a SampleWidget folder under Site/Dashboard/Images/Widgets and place the icon file in the SampleWidget folder (pic. 4.1).

Pic 4.1

Pic 4.1

5. Module strings

Log in to back office and go to the control panel > System settings > Areas. Select the Dashboard area and click the Text button in the toolbar. Click the New text button. Choose the language in which you want to create the string. In the Name field enter the name SampleWidgetName. This name consists of the widget type name SampleWidget and the word Name ([WidgetTypeName]Name). In the text field, enter the name of the widget you want to see in the GUI. Enter the sample widget name string. Click on Save. Do this operation for all languages.

6. Styles

Create the file SampleWidget.css in the Site/Dashboard/Styles folder. This file will be connected automatically, see picture 6.1.

Pic 6.1

Pic 6.1

There are four zones on the dashboard, - top, left, right and bottom. See pic. 6.2.

Pic 6.2

Pic 6.2.

Widgets may look different depending on which zone they are in. To write the widget style for the top zone use .dropTopContainerForWidget selector, for the left zone .dropLeftContainerForWidget selector, for the right zone .dropRightContainerForWidget selector, and for the bottom zone use .dropBottomContainerForWidget selector.
Add styles to the SampleWidget.css like inn picture 6.3.

Pic 6.3

Pic 6.3

The result on the dashboard will be like in picture 6.4.

Pic 6.4

Pic 6.4.

7. Scripts

You can also add javascript files into Site/Dashboard/Scripts folder (if this path doesn’t exist please create it). They are not connected automatically. The widget behaves as a normal .NET web user control. How to attach a client script is explained in this article.

Go to the Dashboard area and your widget should be there. Drag and drop your widget in the layout.