After adding support for widgets in custom themes, it may be useful to create a few custom widgets.
Widgets in Community Server 2008 (internally identified as content fragments) are server-side .net classes implementing the CommunityServer.Components.IContentFragment interface. Community Server will load all classes implementing this interface from all assemblies in the bin/ folder and make them available in the widget selection form (subject to application-type filters) -- there is no additional configuration required to add support for new content fragment types.
To help implement new content fragments, CS2008 includes two base classes: CommunityServer.Components.ContentFragmentBase and CommunityServer.Components.ConfigurableContentFragmentBase. These base classes implement the administrative members of the IContentFragment interface and require that only the content-related members be implemented to complete a new content fragment. Furthermore, the ConfigurableContentFragmentBase base-class adds support for exposing configuration options (via Dynamic Configuration) for new content fragments.
Implementing a Basic Widget
A basic widget is very easy to implement. Simply create a new class library project in Visual Studio and add a reference to CommunityServer.Components.dll and System.Web.dll. Then, create a new class file and inherit from CommunityServer.Components.ContentFragmentBase. Allowing Visual Studio to complete the implementation of this abstract class automatically results in the following:
using System;
using System.Collections.Generic;
using System.Text;
namespace WidgetSamples
{
public class MyWidget : CommunityServer.Components.ContentFragmentBase
{
public override void AddContentControls(System.Web.UI.Control control)
{
throw new Exception("The method or operation is not implemented.");
}
public override string FragmentDescription
{
get { throw new Exception("The method or operation is not implemented."); }
}
public override string FragmentName
{
get { throw new Exception("The method or operation is not implemented."); }
}
}
}
To complete the implementation of this widget, the three required members above must be implemented.
void AddContentControls(Control)
The AddContentControls method is used to populate the content of the widget. All content must be added to the control.Controls collection. To add literal text, the System.Web.UI.LiteralControl can be used, for example:
public override void AddContentControls(System.Web.UI.Control control)
{
control.Controls.Add(new System.Web.UI.LiteralControl("This is my widget!"));
}
Because content fragments use Control objects, the content of widgets can take advantage of all of the existing ASP.Net and Chameleon controls. Controls in widgets participate in the full page lifecycle and can initiate and handle call backs and post backs.
string FragmentDescription
The FragmentDescription returns the description of this content fragment and is rendered in the widget selection control used in theme configuration pages. The description should be a single, concise sentence, such as:
public override string FragmentDescription
{
get { return "Renders 'This is my widget!'"; }
}
string FragmentName
The FragmentName returns the name of this content fragment and is rendered in the widget selection control as well, above the description. The name should be only a few words, such as:
public override string FragmentName
{
get { return "My widget"; }
}
Once these three members are implemented, the class library can be compiled and it's output DLL can be deployed to Community Server's bin/ folder. Then, navigating to a theme configuration page,
Implementing a Configurable Widget
Many widgets benefit from exposing end-user configurable options. To support such options, the alternate CommunityServer.Components.ConfigurableContentFragmentBase base-class can be used. The ConfigurableContentFragmentBase class is similar to the ContentFragmentBase class used in the simple widget example above, but adds support for exposing and using Dynamic Configuration options.
To create a configurable content fragment, create a new class library project in Visual Studio and add a reference to CommunityServer.Components.dll, Telligent.DynamicConfiguration.dll, and System.Web.dll. Then, create a new class file and inherit from CommunityServer.Components.ConfigurableContentFragmentBase. Allowing Visual Studio to complete the implementation of this abstract class automatically results in the following:
using System;
using System.Collections.Generic;
using System.Text;
namespace WidgetSamples
{
public class MyConfigurableWidget : CommunityServer.Components.ConfigurableContentFragmentBase
{
public override void AddContentControls(System.Web.UI.Control control)
{
throw new Exception("The method or operation is not implemented.");
}
public override string FragmentDescription
{
get { throw new Exception("The method or operation is not implemented."); }
}
public override string FragmentName
{
get { throw new Exception("The method or operation is not implemented."); }
}
public override Telligent.DynamicConfiguration.Components.PropertyGroup[] GetPropertyGroups()
{
throw new Exception("The method or operation is not implemented.");
}
}
}
As you can see, the members are the same as with the simple widget with the exception of the new GetPropertyGroups method.
PropertyGroup[] GetPropertyGroups()
The GetPropertyGroups method is used to identify the Dynamic Configuration property groups, sub-groups, properties, selectable values, etc supported by the content fragment. The layout of exposed properties is similar to themes' theme.config files, but instead of using an XML file, the layout is defined programmatically using classes in the Telligent.DynamicConfiguration.Components namespace. For example, to define a simple text entry field (note that I added a "using Telligent.DynamicConfiguration.Components" statement to the top of the class file):
public override Telligent.DynamicConfiguration.Components.PropertyGroup[] GetPropertyGroups()
{
PropertyGroup group = new PropertyGroup("group1", "Options", 0);
Property textToRender = new Property("textToRender", "Text to Render", PropertyType.String, 0, "");
group.Properties.Add(textToRender);
return new PropertyGroup[] { group };
}
This defines a single configuration group (which renders as a tab) named "Options" containing a single string-based property named "Text to Render." A full description of the Dynamic Configuration API is beyond the scope of this article, but the Intellisense for the Telligent.DynamicConfiguration.dll assembly as well as the existing examples of content fragments in the Community Server 2008 SDK should provide ample examples for defining configuration options.
The rendering of the configuration form and storage of the values entered by end-users is handled automatically by Community Server based on the definition of the GetPropertyGroups method.
Using Configuration Options
To use the configuration options defined by the GetPropertyGroups method, the following methods (defined on the ConfigurableContentFragmentBase class) can be used based on the data type defined for the property:
- bool GetBoolValue(string id, bool defaultValue)
- int GetIntValue(string id, int defaultValue)
- double GetDoubleValue(string id, double defaultValue)
- string GetStringValue(string id, string defaultValue)
- string GetHtmlValue(string id, string defaultValue)
- DateTime GetDateValue(string id, DateTime defaultValue)
- DateTime GetTimeValue(string id, DateTime defaultValue)
- DateTime GetDateTimeValue(string id, DateTime defaultValue)
- Guid GetGuidValue(string id, Guid defaultValue)
- System.Drawing.Color GetColorValue(string id, System.Drawing.Color defaultValue)
- System.Web.UI.WebControls.Unit GetUnitValue(string id, System.Web.UI.WebControls.Unit defaultValue)
- Uri GetUrlValue(string id, Uri defaultValue)
In all of these examples, the first parameter is the ID of the property for which a value should be retrieved. In our sample definition of the GetPropertyGroups method above, we defined a single string field with the ID "textToRender." To render that field as the content of the content fragment, the GetStringValue method can be used, for example:
public override void AddContentControls(System.Web.UI.Control control)
{
control.Controls.Add(new System.Web.UI.LiteralControl(this.GetStringValue("textToRender", "")));
}
This will render the user-defined value for the "Text to Render" field as the content of the control.
To finish the implementation of our configurable widget, the FragmentDescription and FragmentName still need to be implemented as with the simple widget:
public override string FragmentDescription
{
get { return "Renders custom text"; }
}
public override string FragmentName
{
get { return "My Configurable Widget"; }
}
The class library can now be compiled and it's output DLL can be deployed to Community Server's bin/ folder. Then, navigating to a theme configuration page,
Additional Options
The base classes implement a few additional IContentFragment members that can be overridden by specific implementations to further customize widget rendering:
string GetFragmentHeader(Control)
By default, the FragmentName is rendered as the header of a rendered widget. This behavior can be modified by overriding the base implementation of the GetFragmentHeader method. This method returns the HTML to render as the content fragment's header.
The control parameter to this method can be used to load contextual data, for example, via the CommunityServer.Controls.CSControlUtility class.
string GetFragmentMoreUrl(Control)
The out-of-the-box themes in Community Server 2008 support rendering a "more URL" for each widget -- for example, viewing all tags for the tag cloud widget or viewing the full list of active posts for the active posts widget. By default, the "more URL" is blank and will not be rendered.
To set a "more URL", the GetFragmentMoreUrl method can be overridden to return the URL to navigate to view additional, related information. Similar to the GetFragmentHeader method, the control parameter is supplied to support retrieving contextual information through Chameleon.
ApplicationType[] GetRelatedApplicationTypes()
As mentioned in the How to Support Widgets in a Custom Theme article, Community Server has built-in support for filtering available widgets by application types. By default, the base classes identify no related application type which results in the content fragment being listed regardless of the application type filter.
To identify the application type or types that relate to a content fragment, the GetRelatedApplicationTypes method can be overridden to return the array of related application types.
Any questions? Please let me know in the comments.
