How to: Create a Configurable Widget

This article describes how to create or update a widget that supports user-configurable options.

Create a New Configurable Widget

Create a new class with the following:

Ensure the class inherits from ExternallyImplementedConfigurableContentFragmentBase.
Override GetPropertyGroups().
When you load the widget onto one of your pages, you can click the Configure link, which opens a configuration window.

The configuration window contains tabbed panes.Each tabbed pane is a Telligent.DynamicConfiguration.Components.PropertyGroup and each configurable item inside a group is a Telligent.DynamicConfiguration.Components.Property.

If, for example, you want one tab with four items in the window, the GetPropertyGroups() override looks like this:

public override PropertyGroup[] GetPropertyGroups()
{
    PropertyGroup group = new PropertyGroup("group1", "My Options", 1);

    group.Properties.Add(new Property("Title", "Widget Title", PropertyType.String, 1, FragmentName));
    group.Properties.Add(new Property("Name", "Name", PropertyType.String, 3, "Your Name"));
    group.Properties.Add(new Property("Location", "Location", PropertyType.String, 4, "Your Location"));
    group.Properties.Add(new Property("Occupation", "Occupation", PropertyType.String, 5, "Your Occupation"));

    return new PropertyGroup[] { group };
}

To keep the header of the widget editable, you will want to override GetFragmentHeader(Control). You can pull the configured value from your PropertyGroups with the following code:

public override string GetFragmentHeader(Control control)
{
    return GetStringValue("Title", FragmentName);
}

Title is the key of the value being retrieved. This matches the property created in GetPropertyGroups().

Create a new user control.
Use Telligent Evolution controls to pull the values set in the configuration window. To do this, use the following in your user control:

<CSControl:ConfigurableContentFragmentData Property="Name" runat="server" />

The value for Property must match the key you set in the GetPropertyGroups() override, for example:

<%@ Control Language="C#" AutoEventWireup="true" %>

<div>
    <p><b>Name:</b>
        <CSControl:ConfigurableContentFragmentData Property="Name" runat="server" /></p>
    <p><b>Location:</b>
        <CSControl:ConfigurableContentFragmentData Property="Location" runat="server" /></p>
    <p><b>Occupation:</b>
        <CSControl:ConfigurableContentFragmentData Property="Occupation" runat="server" /></p>
</div>

Recompile the assembly. You can now customize your site pages with the new widget.

Add configuration options to an existing widget

Next you need to add configuration options to an existing widget.

Update the base class and expose configuration options

As outlined in Widget Base Classes and Interfaces, some base classes add support for exposing configuration options. To update the basic widget to support configuration, change the base class fromCommunityServer.Components.ExternallyImplementedContentFragmentBase toCommunityServer.Components.ExternallyImplementedConfigurableContentFragmentBase. When this is done, a new method, GetPropertyGroups(), will be required in order to identify the groups, subgroups, and properties exposed by this widget. For example,

using System;
using System.Collections.Generic;
using System.Text;
using Telligent.DynamicConfiguration.Components;

namespace WidgetTest
{
 public class MyWidget : CommunityServer.Components.ExternallyImplementedConfigurableContentFragmentBase
 {
  public MyWidget()
   : base("~/CustomWidgets/MyWidget.ascx")
  {
  }

  public override string FragmentDescription
  {
   get { return "This is my widget's description"; }
  }

  public override string FragmentName
  {
   get { return "My Widget"; }
  }

  public override PropertyGroup[] GetPropertyGroups()
  {
   PropertyGroup group = new PropertyGroup("group1", "My Options", 1);

   group.Properties.Add(
    new Property("textToRender", "Text to Render", PropertyType.String, 1, "Customize me!")
    );

   return new PropertyGroup[] { group };
  }
 }
}

In this example, a new group of properties (which will be rendered as a tab in the widget configuration window) was added named "My Options." In that group/tab, a single property was added calledtextToRender and labeled "Text to Render."

When this widget is deployed and included in a page, users can click the configure icon and set the string value of "Text to Render," which defaults to "Customize me!"

Render configuration options

Now that the value of textToRender can be collected from users, the widget should use this value. For this example, the user control representing the content of the widget is updated to directly render the value oftextToRender.

Update the user control referenced by the information class, ~/CustomWidgets/MyWidget.ascx, to the following.

<%@ Control Language="C#" AutoEventWireup="true" %>

You entered: <CSControl:ConfigurableContentFragmentData 
       Property="textToRender" runat="server" />

By default, the widget will render "You entered: Customize me!" Configuring the widget will enable changing the "Customize me!" text to any custom value.

Deploy the updated widget

Just as with the Hello World widget example, you need to deploy the DLL and enable the widget for use in the site.

Developer Space