Source files: There are source files related to this tutorial, you find them at the bottom of this page.
1. Your widget class.
If the App_Code folder doesn’t contain Widgets folder, please create it. And also create a code file with the name SampleWidget (pict. 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
Also override IconPath property to set up your own icon.
Each dashboard widget consists of two parts - View panel and Edit panel. These parts should be User Controls(ascx files). Accordingly the ViewPanelPath property should return path to View panel and EditPanelPath property should return path to Edit panel.
Also 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
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 our SampleWidget with the name EditSampleWidgetControl (pic 2.1).
Pic 2.1
Add markup
EditPanel control should implement IWidgetEditPanel interface. This interface contains two methods; GetPanelData and SetPanelData (pic.2.2).
Pic 2.2
GetPanelData is called when the user presses 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 Chapter 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.
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 our SampleWidget with the name ViewSampleWidgetControl (pic 3.1.).
Pic 3.1.
And add markup
The ViewPanel control should implement the IWidgetViewPanel interface. This interface contains one method Initialize and property WidgetID (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 Chapter1 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
4. Widget icon
The Widget icon should be 80 px in width and 80 px in height. Create SampleWidget folder under Site/Dashboard/Images/Widgets (if the path doesn’t exist please create it) and put the icon file in the SampleWidget folder (pic 4.1).
Pic 4.1
5. Module strings
Log into back office and go to the Control panel -> System settings -> Modules. Choose the Dashboard module and click the Text button in the toolbar. Create a new module string (click the "New text" button). Choose language in which you want to create a string. In the Name field put the name SampleWidgetName. This name consists of the Widget type name SampleWidget and word Name ([WidgetTypeName]Name). In the text field put the name of the widget you want to see in the GUI. Put the Sample widget name string. Click on the "Save" button. Do this operation for all languages.
6. Styles
Create SampleWidget.css file under Site/Dashboard/Styles folder. This file will be connected automatically, see picture 6.1.
Pic 6.1
On the dashboard there are four zones - Top, Left,Right and Bottom. See pic 6.2.
Pic 6.2.
In different zones widgets may look different. 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
The result on the dashboard will be like in picture 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, and attaching client script is explained in this article.
Go to the Dashboard module and your widget should be there. Drag and drop your widget in the layout.