Singapore CMS Web Design

Gary Consulting Group - Singapore CMS Web Design

Timely Support and Clarity in your journey to harness the power of the internet
+1 415 300-0019
How to create a simple customized Ektron Widget


A widget consists of three file types.

  .ascx - contains a widget’s source code
  .ascx.cs or .vb - contains widget’s codebehind
  .ascx.jpg - image that represents a widget in the widget selection tool


Your widget might use additional files, such as .css or .js files. Ektron recommends placing these files in a folder within
site root/widgets, and giving the folder the same name as the custom widget.

When creating a widget, you save files to the site root/widgets folder. This folder path is defined in the site root/web.config file, so if Pete needs to change the folder name or path, he must update the following web.config ek_widgetPath element:

<add key=”ek_widgetPath” value=”Widgets/" /> .

The “Hello World” Widget

To get a basic understanding of how to create a widget, Pete will create a simple widget, which will reside in the site root/widgets folder. This widget is based on the Hello World widget that is installed with the Developer Sample site. It uses the following files:

  HelloWorld.ascx - user control file
  HelloWorld.ascx.cs - user control codebehind file
  HelloWorld.ascx.jpg - image that represents this control on the widget menu


Pete will complete these tasks to create a widget.

  Copy, Paste and Rename HelloWorld.ascx and HelloWorld.ascx.jpg
  Update the Class Names in the New Files
  Add Widget in Ektron CMS400.NET Workarea

Copy, Paste and Rename HelloWorld.ascx and HelloWorld.ascx.jpg

1. Open your Web site in Visual Studio.

2. In the Visual Studio Solution Explorer, open the widgets folder.

3. Within that folder, scroll down to and select HelloWorld.ascx.

4. Right click the mouse and select Copy.

5. Scroll up to the widgets folder.

6. Right click the mouse and select Paste.

7. Scroll down until you see Copy of HelloWorld.ascx.

8. Right click the mouse and select Rename.

9. Rename the file new_widget.ascx. Notice that Visual Studio also renames the codebehind file to new_widget.ascx.cs.


The image file is 48 x 48 pixels and 72 dpi

10. Copy, paste, then rename the helloworld.ascx.jpg file to new_widget.ascx.jpg. Ektron CMS400.NET administrators (like Grace) and content authors (like the Marketing team) use a widget’s image to select it, as shown below.


Update the Class Names in the New Files

1. Open new_widget.ascx.

2. On the first line of that file, replace the reference to HelloWorld (circled below) with new_widget.


3. Open the codebehind file, new_widget.ascx.cs.

4. Again, replace the class HelloWorld with new_widget.


5. Save new_widget.ascx and new_widget.ascx.cs.

6. Check both files for errors by clicking Build > Build Page. Correct any errors before proceeding.

Add Widget in Ektron CMS400.NET Workarea

1. Open the Ektron CMS400.NET Workarea.

2. Open Settings > Configuration > Personalizations > Widgets.

3. Click the Synchronize button ().

4. You see the new user control file, new_widget.ascx, at the bottom of the screen.


5. Open Settings > Configuration > Template Configuration.

6. Find the template that you created in Building Pages, PageLayout.aspx. Or, any Wireframe template that you are using to create a PageBuilder page.

7. Click Update.

8. On the Update Template screen, scroll down until you see the new widget.

9. Click the Select All button (circled above).

10. Click Save ().


For directions on creating a PageBuilder page, see Steps to Creating a “PageBuilder” Page

11. Go to Content and select a folder that has a PageBuilder page.

12. Edit the PageBuilder page.

13. Open the widget menu.

14. Make sure your new widget appears on the menu.


Now that you have created a new widget and enabled it in the Ektron CMS400.NET Workarea, you can begin to customize it.

The next sections explain details about the files you copied and renamed above.

  Understanding the User Control (.ascx) File
  Understanding the Codebehind (.ascx.cs) File

Understanding the User Control (.ascx) File

Here is the new_widget.ascx file that Pete uses as the basis of his widget.

<%@ Control Language=”C#” AutoEventWireup=”true” CodeFile=”new_widget.ascx.cs” Inherits=”widgets_new_widget” %>

<%@ Register Assembly="System.Web.Extensions, Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"

Namespace="System.Web.UI" TagPrefix="asp" %>


<asp:MultiView ID="ViewSet" runat="server" ActiveViewIndex="0">


<asp:View ID="View" runat="server">

<!-- You Need To Do .............................. -->

<asp:Label ID="TextLabel" runat="server"></asp:Label><br />

<asp:Label ID="CheckBoxLabel" runat="server"></asp:Label>

<!-- End To Do .............................. -->



<asp:View ID="Edit" runat="server">

<div id="<%=ClientID%>_edit">

<!-- You Need To Do .............................. -->

<asp:TextBox ID="TextTextBox" runat="server" Style="width: 95%"> </asp:TextBox><br />

<asp:CheckBox ID="MyCheckBox" runat="server" Checked="false" /> <br />

<!-- End You Need To Do .............................. -->

<asp:Button ID="CancelButton" runat="server" Text="Cancel" OnClick="CancelButton_Click" />

<asp:Button ID="SaveButton" runat="server" Text="Save" OnClick="SaveButton_Click" />





Pete notices the following elements of the file.

  The asp:MultiView element declares that the control has two possible modes: View and Edit.

<asp:MultiView ID="ViewSet" runat="server" ActiveViewIndex="0">

- in view mode, Pierre and the marketing team can see the control but not change it.

- in edit mode, Pete’s developers can change the control’s content and properties.

  Between the multiview tags is information about the control in view mode. It has two fields: one is a text field, and the other is a check box.

<asp:View ID="View" runat="server">

<asp:Label ID="HelloTextLabel" runat="server"></asp:Label><br />

<asp:Label ID="CheckBoxLabel" runat="server"></asp:Label>


  Also between the multiview tags is information about the control in edit mode. In edit mode, a text box, a check box, and a Save button appear. The text box and check box collect end-user input, and the Save button saves that input to the database.

<asp:View ID="Edit" runat="server">

<div id="<%=ClientID%>_edit">

<!-- You Need To Do .............................. -->

<asp:TextBox ID="HelloTextBox" runat="server" Style="width: 95%"> </asp:TextBox><br />

<asp:CheckBox ID="MyCheckBox" runat="server" Checked="false" /> <br />

<!-- End You Need To Do .............................. -->

<asp:Button ID="CancelButton" runat="server" Text="Cancel" OnClick="CancelButton_Click" />

<asp:Button ID="SaveButton" runat="server" Text="Save" OnClick="SaveButton_Click" />

Understanding the Codebehind (.ascx.cs) File

Next, Pete reviews the codebehind file, new_widget.ascx.cs.

  He see a series of using statements at the top of the file, noticing the Ektron ones in particular:

using Ektron.Cms.Widget;

using Ektron.Cms;Marketing team

using Ektron.Cms.API;

using Ektron.Cms.Common;

using Ektron.Cms.PageBuilder;

using System.Text.RegularExpressions;

  Pete then notes a widget host class, which inherits the system.Web.UI.UserControl and IWidget classes.

public partial class widgets_new_widget : System.Web.UI.UserControl, IWidget

The following image summarizes the remaining elements of the codebehind file.



  In the next line, he sees the widget’s properties: a string for the text field, and a boolean for the check box. Here you define the variables and their type. Possible types are string, integer, long and date.

#region properties

private string _HelloString;

private bool _CheckBoxBool;


public bool CheckBoxBool { get { return _CheckBoxBool; } set { _CheckBoxBool = value; } }

[WidgetDataMember("Hello Wolrd")]

public string HelloString { get { return _HelloString; } set { _HelloString = value; } }


  He sees a widget host declaration.

private IWidgetHost _host;

  And the widget’s page_init events.

protected void Page_Init(object sender, EventArgs e)


_host = Ektron.Cms.Widget.WidgetHost.GetHost(this);

_host.Title = "Hello World Widget";

_host.Edit += new EditDelegate(EditEvent);

_host.Maximize += new MaximizeDelegate(delegate() { Visible = true; });

_host.Minimize += new MinimizeDelegate(delegate() { Visible = false; });

_host.Create += new CreateDelegate(delegate() { EditEvent(""); });

PreRender += new EventHandler(delegate(object PreRenderSender, EventArgs Evt) { SetOutput(); });



Comments on the above code

- The gethost method returns a reference to the container widgethost for this widget. This is the case in both Personalization and PageBuilder.

- The Title property is the title of this widget. By setting it in page_init for the widget, we inform the host what text to put in the title bar above the widget. This works in both PageBuilder and Personalization.

- The events below host.Title are raised by the widgethost. It’s up to the widget to subscribe to them. In all cases, if we don’t subscribe to them, the icons don’t show up. This is a method of attaching widget code to button clicks and other events that occur outside the widget.

- For PreRender: Ektron CMS400.NET renders the contents of this widget on pre-render, thus ensuring a single render event. Another option is to call SetOutput on the Load event, but you can only do that if the widget is not in edit mode currently.

- The final line sets the view to display mode.

  He notices the declaration of the widget’s edit events.

void EditEvent(string settings)


string sitepath = new CommonApi().SitePath;

ScriptManager.RegisterClientScriptInclude(this, this.GetType(), "widgetjavascript", sitepath + "widgets/widgets.js");

ScriptManager.RegisterOnSubmitStatement(this.Page, this.GetType(), "gadgetescapehtml", "GadgetEscapeHTML('" + HelloTextBox.ClientID + "');");

HelloTextBox.Text = HelloString;

MyCheckBox.Checked = CheckBoxBool;



Comments on the above code:

Warning! You must register JavaScript and cascading style sheet (css) instructions in an external file. See Working with JavaScript and Cascading Style Sheets

- The Edit event is triggered by the widgethost, and since Pete subscribed to it already, it calls the delegate here.

- sitepath is used to ensure that the correct path for included files is used across installations.

- By calling the scriptmanager to include the script, Pete ensures it works inside update panels. Alternatively, he can use Ektron.Cms.Api.Js.RegisterJSInclude ScriptManager.RegisterOnSubmitStatement(this.Page, this.GetType(), "gadgetescapehtml", "GadgetEscapeHTML('" + HelloTextBox.ClientID + "');");

- The onsubmitstatement is JavaScript that is run when the widget is submitted. It calls escape html, which cleans the submitted text to avoid any XSS.

  Pete notices the editing fields, so users can see the existing data.

HelloTextBox.Text = HelloString;

MyCheckBox.Checked = CheckBoxBool;


  He sees the widget’s save events.

protected void SaveButton_Click(object sender, EventArgs e)


HelloString = ReplaceEncodeBrackets(HelloTextBox.Text);

CheckBoxBool = MyCheckBox.Checked;




  He notes the widget’s SetOutput events.

protected void SetOutput()


HelloTextLabel.Text = HelloString; // client javascript remove brackets, server side adds back

CheckBoxLabel.Text = CheckBoxBool.ToString();


  He notes the widget’s Cancel events.

protected void CancelButton_Click(object sender, EventArgs e)




  Finally, he reviews the encoding of the greater and less than signs.

protected string ReplaceEncodeBrackets(string encodetext)


encodetext = Regex.Replace(encodetext, "<", "<");

encodetext = Regex.Replace(encodetext, ">", ">");

return encodetext;


Thursday, 22nd Jun 2017
Content Management System powered by Gary from