Creating a Custom Configuration Control in Telligent Community Server 6.0

When creating widgets in Telligent Community Server 6.0 (or previous versions) you may have noticed the use of custom controls that appear in the configuration modal.  Telligent, out of the box, provides several useful controls, but doesn't make it evident how to create your own.  This post will show you how to create a basic Widget Configuration Control that you can then include in the configuration modal.

In this example we will create a simple dropdown control that will allow you to select one of the membership roles that are defined in the control panel.

Step 1:  Configuration Settings for the Widget

When setting the configuration properties of a widget in community server 6.0, you navigate to the configuration tab in widget studio.

Scroll down to the area for "Configuration Content" and add the following:

<propertyGroup id="options" resourceName="Options">
<property id="expertRole" resourceName="CF_ExpertRole" dataType="custom" controlType="Evolution.WidgetExtensions.PropertyControls.RoleSelectionControl, Evolution.WidgetExtensions" width="95%" />
</propertyGroup>

Note the following settings on the "Property" node:
dataType="custom"   Indicates we'll use a custom control type
controlType="Evolution.WidgetExtensions.PropertyControls.RoleSelectionControl, Evolution.WidgetExtensions"  tells the widget which class/namespace and dll to look in

Important!
The format of the controlType attribute is <full class namespace>, <name of dll>

When configured, you will have the value saved to the "expertRole" (set in the id attribute) widget property.

Step 2:  Create the Class for the custom configuration control

The next step is to actually create the class for the new control.  The class you create must inherit from the IPropertyControl interface.  Well create a class called "RoleSelectionControl.cs" in Visual Studio.

Now that we have the class created, we need to reference the proper assemblies:

using System;
using System.Web.UI;
using System.Web.UI.WebControls;
using Telligent.DynamicConfiguration.Components;
using System.Web.UI.HtmlControls;
using Telligent.Evolution.Components;
using Telligent.Evolution.Controls;

Next step is to inherit from IPropertyControl - doing this will ensure we've implemented the proper set of methods and properties so community server can properly render, call methods, and retrieve values from our custom control

namespace Evolution.WidgetExtensions.PropertyControls
{
    public class RoleSelectionControl : Control, IPropertyControl
    {
    }
}

Now if you hover over the "IPropertyControl" name you can use the smart tags in Visual Studio to stub-in the required methods:

After  you implement the interface, you will see the methods have been added to your code:

        public ConfigurationDataBase ConfigurationData
        {
            get
            {
                throw new NotImplementedException();
            }
            set
            {
                throw new NotImplementedException();
            }
        }

        public Property ConfigurationProperty
        {
            get
            {
                throw new NotImplementedException();
            }
            set
            {
                throw new NotImplementedException();
            }
        }

        public event ConfigurationPropertyChanged ConfigurationValueChanged;

        public new Control Control
        {
            get { throw new NotImplementedException(); }
        }

        public object GetConfigurationPropertyValue()
        {
            throw new NotImplementedException();
        }

        public void SetConfigurationPropertyValue(object value)
        {
            throw new NotImplementedException();
        }

Step 2.1 - Define our custom dropdown control
With the interface now implemented, we can get to work and add our control.  We will declare our dropdown control and an HTML Generic control to use as a wrapper.  Add this directly below the class name

    public class RoleSelectionControl : Control, IPropertyControl
    {

        DropDownList _roleDropdown = null;
        HtmlGenericControl _roleDropdownWrapper = null;

Step 2.2 - Control Overrides
This step is what actually will add our dropdown to the parent control and make it render in the configuration modal.  We need to override two methods:
OnInit
CreateChildControls

        protected override void CreateChildControls()
        {
            base.CreateChildControls();

            _roleDropdown = new DropDownList();

            _roleDropdownWrapper = new HtmlGenericControl("div");
            _roleDropdownWrapper.ID = this.ClientID + "_role";
            _roleDropdownWrapper.Style["display"] = "block";
            Controls.Add(_roleDropdownWrapper);

            _roleDropdownWrapper.Controls.Add(_roleDropdown);

            // Get the roles
            var roles = Roles.GetRoles();
            _roleDropdown.Items.Clear();

            // Populate the dropdown
            foreach (Role role in roles)
            {
                _roleDropdown.Items.Add(new ListItem(role.Name, String.Format("{0}={1}&{2}={3}", "RoleId", role.Id.ToString(), "RoleName", role.Name)));
            }

            Controls.Add(new JQuery());
        }

        protected override void OnInit(EventArgs e)
        {
            base.OnInit(e);
            EnsureChildControls();
        }

Step 2.3 - Update Interface Methods

The following section will show you how to properly implement each of the interface members for this control:

ConfigurationDataBase

        private ConfigurationDataBase _configurationData = null;
        public ConfigurationDataBase ConfigurationData
        {
            get { return _configurationData; }
            set { _configurationData = value; }
        }

ConfigurationProperty

        private Property _configurationProperty = null;
        public Property ConfigurationProperty
        {
            get { return _configurationProperty; }
            set { _configurationProperty = value; }
        }

ConfigurationPropertyChanged

        public event ConfigurationPropertyChanged ConfigurationValueChanged
        {
            add { throw new NotSupportedException(); }
            remove { }
        }

Control

        public Control Control
        {
            get { return this; }
        }

GetConfigurationPropertyValue
When the modal "save" button is clicked, this method will be invoked and will return the value to be stored for this widget property.  We'll just return a string of the selected value of our dropdown list.

        public object GetConfigurationPropertyValue()
        {
            EnsureChildControls();

            return _roleDropdown.SelectedValue.ToString();
        }

SetConfigurationPropertyValue
When the widget configuration modal is opened, if the widget already has a value configured, this method will select the proper list item in our dropdown list.

        public void SetConfigurationPropertyValue(object value)
        {
            EnsureChildControls();

            // Attempt to select the initial config'd value
            if (_roleDropdown.Items.FindByValue(value.ToString()) != null)
            {
                _roleDropdown.Items.FindByValue(value.ToString()).Selected = true;
            }
            
        }

The Entire class now looks like this:

using System;
using System.Web.UI;
using System.Web.UI.WebControls;
using Telligent.DynamicConfiguration.Components;
using System.Web.UI.HtmlControls;
using Telligent.Evolution.Components;
using Telligent.Evolution.Controls;

namespace Evolution.WidgetExtensions.PropertyControls
{
    public class RoleSelectionControl : Control, IPropertyControl
    {

        DropDownList _roleDropdown = null;
        HtmlGenericControl _roleDropdownWrapper = null;

        #region Control Overrides

        protected override void CreateChildControls()
        {
            base.CreateChildControls();

            _roleDropdown = new DropDownList();

            _roleDropdownWrapper = new HtmlGenericControl("div");
            _roleDropdownWrapper.ID = this.ClientID + "_role";
            _roleDropdownWrapper.Style["display"] = "block";
            Controls.Add(_roleDropdownWrapper);

            _roleDropdownWrapper.Controls.Add(_roleDropdown);

            // Get the roles
            var roles = Roles.GetRoles();
            _roleDropdown.Items.Clear();

            // Populate the dropdown
            foreach (Role role in roles)
            {
                _roleDropdown.Items.Add(new ListItem(role.Name, String.Format("{0}={1}&{2}={3}", "RoleId", role.Id.ToString(), "RoleName", role.Name)));
            }

            Controls.Add(new JQuery());
        }

        protected override void OnInit(EventArgs e)
        {
            base.OnInit(e);
            EnsureChildControls();
        }

        #endregion

        #region IPropertyControl Members

        private ConfigurationDataBase _configurationData = null;
        public ConfigurationDataBase ConfigurationData
        {
            get { return _configurationData; }
            set { _configurationData = value; }
        }

        private Property _configurationProperty = null;
        public Property ConfigurationProperty
        {
            get { return _configurationProperty; }
            set { _configurationProperty = value; }
        }

        public event ConfigurationPropertyChanged ConfigurationValueChanged
        {
            add { throw new NotSupportedException(); }
            remove { }
        }

        public Control Control
        {
            get { return this; }
        }

        public object GetConfigurationPropertyValue()
        {
            EnsureChildControls();

            return _roleDropdown.SelectedValue.ToString();
        }

        public void SetConfigurationPropertyValue(object value)
        {
            EnsureChildControls();

            // Attempt to select the initial config'd value
            if (_roleDropdown.Items.FindByValue(value.ToString()) != null)
            {
                _roleDropdown.Items.FindByValue(value.ToString()).Selected = true;
            }
            
        }

        #endregion
    }
}

Step 3:  Re-Build / deploy the dll

We now have a complete custom control that we can use in the widget configuration modal.  So, re-build your solution (and deploy your dll to your bin folder if it's not already part of your build process).

Step 4:  Test the new configuration control
We've already configured our widget and deployed the dll, so now we can check to see if it all worked.  Drop your widget on a page, enter edit mode and click the pencil to configure the widget.

As you can see, we have an "Expert role" dropdown list that displays all available roles configured in the control panel.  Note, this is not an actual screenshot, but another widget configuration that utilizes this control.  Based on this example, you won't see the "Widget Title" or "Group" config options.

Step 5:  Access the value of the dropdown
The final step is to access the value of the widget configuration control.  The way we coded the widget, we know the value of the dropdown list will be in the format: {RoleId={id}&RoleName={rolename}

Using velocity scripting, we can easily access the role information for use in our widget:

#set ($roleQueryString = $core_v2_widget.getStringValue("expertRole",""))
#set ($roleName = "")
#set ($roleId = "")

#if($roleQueryString != "")
    #set ($roleValues = $core_v2_page.ParseQueryString($roleQueryString))
    #set ($roleName = $roleValues.Value("RoleName"))
    #set ($roleId = $roleValues.Value("RoleId"))
#end