How to create a Widget

• Summary
• Create the widget user control
• Registering the widget

Summary

 A widget is a tool or content area that can be added, arranged or removed from different views in Incentive. Widgets can be used to display images from external services, tag clouds from Incentive, current stockpile of products from an ERP system, register questions from customers etc.

Creating a widget is a two step process. Create the user control that renders the widget and then register the widget within Incentive.

Create the widget user control

In Incentive, widgets are designed as ASP.NET user controls inherited from Mindroute.Incentive.Web.UI.WidgetControlBase. The control is responsible for rendering the widget and handling user input.

Below is an example of a simple widget that displays the current date and time. Users can modify the color of the text.

[DateWidget.ascx]

<%@ Control Language="vb" AutoEventWireup="false" CodeFile="DateWidget.ascx.vb" Inherits="Mindroute.Incentive.Web.Site.UI.Controls.Public.Widgets.DateWidget" %>
<incentive:WidgetHeadZone runat="server" Title="<%$ Resources:Title %>" />
<incentive:WidgetEditZone ID="editZone" runat="server">
    <asp:TextBox ID="txtColor" runat="server" />
</incentive:WidgetEditZone>
<div runat="server" class="wc">
    <asp:Label id=”lblDateTime” runat=”server” CssClass=”widget_datetime” />
</div>

[DateWidget.ascx.vb] 

Imports Mindroute.Incentive.Logic
Namespace Mindroute.Incentive.Web.Site.UI.Controls.Public.Widgets
   Partial Public Class DateWidget
      Inherits Web.UI.Base.WidgetControlBase
      Protected Overrides Sub OnInit(ByVal e As System.EventArgs)
         MyBase.OnInit(e)
         If Not Page.IsPostBack Then
            txtColor.Text = WidgetConfiguration("color")
            DisplayDate()
         End If  
      End Sub
      Private Sub DisplayDate()
         lblDateTime.Text = DateTime.Now.ToString(”yyyy-MM-dd HH:mm”)
         If Not String.IsNullOrEmpty(WidgetConfiguration("color")) Then
            txtColor.Attribute.Add(“style”, String.Format(“color:{0}”, WidgetConfiguration("color")))
         End If
      End Sub
      Protected Sub editZone_Save() Handles editZone.Save
         WidgetConfiguration("color") = txtColor.Text
         DisplayDate()
      End Sub
   End Class
End Namespace

The ascx page consists of some mandatory and optional elements:

• WidgetHeadZone [mandatory] : Enables the drag and drop functionality among other things.
• WidgetEditZone [optional] : Used to enable the edit mode for the widget. When specified the edit link will be visible for the widget and the user can toggle the visibility of the elements contained within. When no WidgetEditZone is present the edit mode will be unavailable.

It is recommended that you enclose all other elements in a div tag with the class attribute of “wc”.

Use the WidgetConfiguration(String) to store or retrieve values. These values are specific to the current user and to the current widget. So even if a user has many widgets of the same type specified they will not share values.

Declare a handler for the WidgetEditZone::Save event to capture the event that is triggered when the user clicks the save button in edit mode. Remember to re-populate the widget depending on the changes the user made.

Please make sure that the build action for both the ascx-file and the codebehind-file is set to “Content”. Otherwise your build will fail.

Place the user control in the directory public\widgets\ and any local resources you may need in \public\widgets\App_LocalResources.
If the widget is relying on separate script files or css files place them in the same directory as the ascx file and name them as you have named the ascx file. Eg. “DateWidget.css”, “DateWidget.js”.

Registering the widget

Open the file “\app_data\settings\widgets.xml” and add a new widget element and specify the attributes:

• id [mandatory]: a unique identifier for the widget.
• Control  [mandatory]: the path to the user control created.
• Enable  [mandatory]: Enter “1” for enabled and “0” for disabled.
• Visible  [mandatory]: Enter “1” for visible and “0” for not visible.
• Type  [mandatory]: A comma separated string defining where the widget should be available. Possible values are “wiki”, ”blog”, ”widgets”, ”search”, ”user”.
• Default  [mandatory]: Indicates if the widget should be added by default. Enter “1” for default and “0” for not default.
• DefaultWiki [optional]: Indicates if the widget should be added by default to widgets on wiki pages. Enter “1” for default and “0” for not default.
• DefaultBlog [optional]: Indicates if the widget should be added by default to widgets on blog pages. Enter “1” for default and “0” for not default.
• DefaultUser [optional]: Indicates if the widget should be added by default to widgets on user pages. Enter “1” for default and “0” for not default.

Add localized description and name for the custom page.

Example: 

<widgets>
   <!-- DateTimeWidget -->
   <widget id="datetime" control="~/public/widgets/datetime.ascx" enable="1" visible="1" default="0" type="widgets,search,wiki,blog" defaultwiki="1" defaultblog="0">
      <name lang="en" description="Displays the current date and time.">Date and time</name>
      <name lang="sv" description="Visar aktuell datum och tid.">Datum och tid</name>
   </widget>
</widgets>