Customizing Widgets

Working with JavaScript and Cascading Style Sheets

You can use JavaScript or a cascading style sheet to add custom functionality or styling to a widget. To do this, place the JavaScript or cascading style sheet (css) instructions in an external file, then register it in the code-behind file.

Example of including a JavaScript file.

void EditEvent(string settings)
JS.RegisterJSInclude(this, _api.SitePath + 
  "widgets/contentblock/jquery.cluetip.js", "EktronJqueryCluetipJS");

Example of including a .css file.

Css.RegisterCss(this, _api.SitePath + "widgets/contentblock/CBStyle.css","CBWidgetCSS");

WARNING! You must register JavaScript and .css files in an external file, as shown above. If you do not, the OnSubmit event places HTML in the TextArea field in encoded brackets (< >) and generates a dangerous script error.

The JS.RegisterJSInclude and Css.RegisterCss functions take 3 arguments.

• 1—A reference to the control that needs the script or style sheet on the page. Typically, ‘this’ or ‘me’. For example:
  • this
• 2—The URL of the script or style sheet being included. You should prefix the URL with a site path so it can be used with URLs like http://localhost/ektrontech and http://ektrontech. For example:
  • _api.SitePath + "widgets/contentblock/jquery.cluetip.js"
  • _api.SitePath + "widgets/contentblock/CBStyle.css"
• 3—A unique key. Only include the script specified by a key once. Your organization should develop a standard way to define JavaScript and .css keys. For example:
  • "EktronJqueryCluetipJS"
  • “CBWidgetCSS”

NOTE: Widgets use an update panel for partial postbacks. As a result, the ASP.NET tree view and file upload controls do not work with widgets. Ektron has workarounds for these functions. For an example of a tree view, see the content block widget (siteroot/widgets/contentblock.ascx). For an Ajax file uploader, see the flash widget (siteroot/widgets/flash.ascx).

Verifying that a Page is a PageBuilder Page

Whenever your code is interacting with a widget, you need to verify that it is on a page builder page (as opposed to another Ektron page that hosts widgets, such as personalization).

To check for this, insert the following code:

Ektron.Cms.PageBuilder.PageBuilder p = (Page as PageBuilder);
If(p==null) // then this is not a wireframe
When you want to check the mode, use code like this.
If(p.status == Mode.Edit) // we are in edit mode

Applying Global and Local Properties to Widgets

Global and local widget properties reduce your development effort by eliminating settings data classes. While you can still use these classes and manage your own serialization, for the vast majority of types, the built-in engine performs all the work necessary.

Global properties apply to every instance of a widget. Local properties apply to one instance. If both local and global values are assigned to a property, local overrides global.

As an example of using a local property to override a global, consider a ListSummary widget. You may want its sort mostly by modified date in descending order, but in certain instances you want to sort by title in ascending order.

The following table explains how to set the different property types.

[GlobalWidgetData()]
public string NewWidgetTextData {
get {return _NewWidgetTextData;} 
set {_NewWidgetTextData = value;
}}

[WidgetDataMember()]
public string NewWidgetTextData { 
get { return _NewWidgetTextData; } 
set { _NewWidgetTextData = value;
 } }

Setting a widget's global properties

Setting a Widget’s Global Properties

A global property lets an Ektron developer or administrator assign properties and values that apply to all instances of a widget. You apply a global property to the widget’s code-behind page. Administrators could then set or update the property’s value in the Workarea’s Widgets screen.

For example, the Brightcove Video widget requires a player ID. You could insert that in the widget’s code-behind file. Then, an administrator could review and possibly update that information in the Workarea widgets screen. Whenever a user drops a Brightcove Video widget onto a page, the player ID is already assigned.

If the developer does not set a default value in code-behind, an administrator must set one on the Workarea’s Widgets screen.

If the developer does set a default value in code-behind, it will be applied unless changed by an administrator on the Workarea’s Widgets screen.

Steps for Setting a Global Property

Follow these steps to set a global property.

1. Open the widget’s code-behind file, which is located in the siteroot/widgets folder.
2. In the properties section, insert the GlobalWidgetData attribute (shown below) to set the global property’s name and type.

   [GlobalWidgetData()]
   public string NewWidgetTextData { get { return _NewWidgetTextData; } set { _NewWidgetTextData = value; } }

   Here is an example.

   

   The supported types for GlobalWidgetData are

   • Date Time
   • int
   • long
   • double
   • boolean
   • string
   • any enumeration
3. Save the code-behind file.
4. In the Ektron Workarea, go to Settings > Configuration > Widgets.
5. Click Edit for the widget whose code-behind file you edited in Step 1. A dialog box lets you view and edit global properties set in code-behind.
   

   

Setting a widget's local properties

Setting a Widget’s Local Properties

A local property lets an Ektron user assign property values that apply to a particular instance of a widget. For example, the Brightcove Video widget requires a Video ID, which identifies the video that appears where you drop the widget.

To set a local property:

1. Open the widget’s code-behind file, which is located in the site root/widgets folder.
2. In the properties section, insert the WidgetDataMember attribute to set the property. See example below.

   [WidgetDataMember(150530105432)]1
   public long VideoID { get { return _VideoID; } set { _VideoID = value; } }

3. If you want to set a default value for the widget, use the attribute’s optional argument, which follows [WidgetDataMember. In the example above, the value is 150530105432.
4. Save the settings in your properties by populating them as you normally would.
5. In the Save event, call _host.SaveWidgetDataMembers();.
   

   

Adding a Field to a Widget

This section provides an example of adding a Content type drop-down to the List Summary widget. The drop-down lets the person dropping the widget on the page select from these choices.

• all types of content
• HTML content only
• assets only

Here is what the drop-down looks like once it is implemented.

To add this drop-down to the List Summary widget:

1. In Visual Studio, open the ListSummary widget, siteroot/widgets/ListSummary.ascx.
2. Find the text DisplaySelectedContent.
3. Below DisplaySelectedContent, add the following code to create a drop-down list for the ContentType property.
   

   <tr>
   <td>
   DisplaySelectedContent:</td>
   <td>
   <asp:CheckBox ID="DisplaySelectedContentCheckBox" runat="server" />
   </td>
   </tr>
   <tr>
   <td>
   ContentType:
   </td>
   <td>
   <asp:DropDownList ID="ContentTypeList" runat="server">
   <asp:ListItem Value="AllTypes">AllTypes</asp:ListItem>
   <asp:ListItem Value="Content">Content</asp:ListItem>
   <asp:ListItem Value="Assets">Assets</asp:ListItem>
   </asp:DropDownList>
   </td>
   </tr>

4. Save the ListSummary.ascx file.
5. Open the code-behind file, ListSummary.ascx.cs.
6. In the properties region, declare a string variable for the ContentType property:

   private string _ContentType;

7. Create a local property with default setting of AllTypes:

   [WidgetDataMember("AllTypes")]
   public string ContentType { get { return _ContentType; } set { _ContentType = value; } }

8. In the EditEvent area, set the select list's value to ContentType:

   ContentTypeList.SelectedValue = ContentType;

9. In the SaveButton_Click event, set ContentType as the select list's value:

   ContentType = ContentTypeList.SelectedValue;

10. In the SetListSummary() function, set the List Summary server control's ContentType to the CMSContentType property:

    ListSummary1.ContentType = (CMSContentType)Enum.Parse(typeof(CMSContentType), ContentType);

11. Save the ListSummary.ascx.cs file.

Including Help for a Widget

You can include help for any widget that has the help icon ().

The help icon only appears when a user is editing a PageBuilder page. The icon appears both when a user is viewing a widget and editing its properties. It is not available to a page’s site visitors.

To create a widget’s help file:

1. Create an HTML file with information for users who will drop the widget on the PageBuilder page.

   You could create a content block within Ektron then switch to source view, copy the content into a word processor (like Notepad), and save it with an HTML extension.

2. Save the help file to the folder that contains the widget.
3. Add the WidgetHost’s HelpFile property to the code-behind of the page that hosts the widget. See example below.

   protected void Page_Init(object sender, EventArgs e)
   {
   _host = Ektron.Cms.Widget.WidgetHost.GetHost(this);
   _host.HelpFile = "~/widgets/myWidget/help.html";