Sitefinity ASP.NET CMS can be extended very easily using traditional ASP.NET UserControls.  Once a UserControl is added to Sitefinity, Sitefinity will automatically generate a web admin interface.  This interface allows editors to edit any public properties found in the User Control.

Below is a very simple ASP.NET UserControl with two public properties (Text, Color).  These two properties can be used to display text in a chosen color.

~/Custom/UserControls/ColoredText.ascx

<%@ Control Language="C#" AutoEventWireup="true" CodeFile="ColoredText.ascx.cs" Inherits="Custom_UserControls_ColoredText" %>

<div id="Div1" runat="server"><asp:Literal ID="Literal1" runat="server" /></div>

~/Custom/UserControls/ColoredText.ascx.cs

using System;

public partial class Custom_UserControls_ColoredText : System.Web.UI.UserControl
{
    public string Text { get; set; }
    public string Color { get; set; }

    protected void Page_Load(object sender, EventArgs e)
    {
        Div1.Style.Add("color", Color);
        Literal1.Text = Text;
    }
}

Sitefinity will automatically generate the following web admin interface for this control:

This UserControl causes the following HTML to be generated:

<div style="color:Red;">Hello world</div>

Using Dropdowns to Avoid Mistakes

This UserControl works fine until ...

Sitefinity WebEditors make editing Control Properties easier.  In my last blog post, I demonstrated how to create a VERY basic Custom WebEditor.  In this post I'll create a slightly more advanced WebEditor that lets us pick a color from a RadioButtonList. 

I highly recommend reading my previous blog posts (post #1, post #2) before proceeding.

WebEditors Can Return Any Type

To get started, create a new class that inherits the WebUITypeEditor class.  When implementing the WebUITypeEditor class, pass the data type the WebEditor will return. 

For example, if the WebEditor will return a string use the following code:

public class StringWebEditor : Telerik.Cms.Web.UI.WebUITypeEditor<string>
{
    public override string Value
    {
        get { return "Hello world!"; }
        set {  }
    }
}

If the WebEditor will instead return a Guid, use the following code:

using System;

public class GuidWebEditor : Telerik.Cms.Web.UI.WebUITypeEditor<Guid>
{
    public override Guid Value
    {
        get { return Guid.NewGuid(); ...

Sitefinity is very easy to extend using basic ASP.NET User Controls.  Once a control is added to your web site, Sitefinity will automatically generate an admin-interface for it.  This admin-interface will contain input fields for public properties found in the ASP.NET User Control.  You can then organize these properties using Design-Time attributes.

Editing properties can be made easier by decorating your control properties with a WebEditor attribute.  WebEditors allow you to associate a user-friendly dialog window with the underlying property.  Sitefinity comes with several built-in WebEditors, but you can create your own.

In this post we'll take a very basic look at creating a Custom Sitefinity WebEditor.

Getting Started / Hello World!

To create a new WebEditor, create a class that implements the WebUITypeEditor interface.  To inherit from this interface, implement the Value property.  Here is a very basic example:

Create ~/App_Code/BasicWebEditor.cs

public class BasicWebEditor : ...

In my last post, I demonstrated how to use Sitefinity's WebEditor attribute to make control property editing a bit more user friendly.  I used Sitefinity's built-in CmrUrlWebEditor for this previous example. 

Sitefinity comes with many more built-in WebEditors that can be used in your project.

Demo Magic / Confession

Before I proceed, I need to make a confession.  I deliberately choose the CmsUrlWebEditor for my introductory WebEditor blog post because it is very easy to use.  An earlier draft used the DhlIdEditor (example shown below). 

DhlIdEditor isn't as easy or intuitive as CmsUrlWebEditor.  During the writing process, I became mired in the specifics of DhlIdEditor, rather than the broader WebEditor concepts.  Because I wanted to write an introductory article, I ditched DhlIdEditor and went with an easier WebEditor.

I'm telling this story as a warning. 

Some built-in Sitefinity WebEditors have very specific usage requirements.  Sometimes these requirements ...

Sitefinity is very easy to extend using normal ASP.NET user controls.  After a user control is added to the Sitefinity toolbox, Sitefinity will automatically generate input fields for any public properties found in the control. 

For example, the following ASP.NET user control contains two public properties (LinkText, LinkUrl):

<%@ Control Language="C#" AutoEventWireup="true" CodeFile="HyperLink.ascx.cs" Inherits="UserControls_HyperLink" %>

<asp:HyperLink ID="HyperLink1" runat="server" />

using System;

public partial class UserControls_HyperLink : System.Web.UI.UserControl
{
    private string _linkText = "Here is my link";
    private string _linkUrl = "~/";

    public string LinkText
    {
        get { return _linkText;  }
        set { _linkText = value; }
    }

    public string LinkUrl
    {
        get { return _linkUrl; }
        set { _linkUrl = value; }
    }

    protected void Page_Load(object sender, EventArgs e)
    {
        HyperLink1.NavigateUrl = LinkUrl;
        HyperLink1.Text = LinkText;
    }
}

Sitefinity will generate two input fields (LinkText, LinkUrl) for this ASP.NET user control:

This works fine.  In addition, by using Design-Time Attributes we can hide and/or ...

I wanted to display my Twitter status on the side of this blog.  To do this, I created a small custom Sitefinity ASP.NET user control.  I'm making it available to everyone below.  To add this control to your Sitefinity web site, simply follow the instructions below.  (Click here for basic information about extending Sitefinity with ASP.NET user controls.)

Create & Install the Twitter Status ASP.NET User Control

1. Create ~/UserControls/TwitterStatus.aspx:

<%@ Control Language="C#" AutoEventWireup="true" CodeFile="TwitterStatus.ascx.cs" Inherits="UserControls_TwitterStatus" EnableViewState="false" %>

<div class="TwitterStatus">
    <h2>Twitter - <a id="Link" href="http://twitter.com/sitefinitywatch" runat="server">more</a></h2>
    <p><asp:Literal ID="Status" runat="server" /></p>
</div>

2. Create ~/UserControls/TwitterStatus.aspx.cs:

using System;
using System.ComponentModel;
using System.Data;
using System.IO;
using System.Net;
using System.Text.RegularExpressions;
using System.Web;
using System.Web.UI;
using System.Web.UI.HtmlControls;
using System.Web.UI.WebControls;

[DefaultProperty("TwitterRssUrl")]
public partial class UserControls_TwitterStatus : System.Web.UI.UserControl
{
    private string _twitterrssurl;
    private double MinutesCached = 30;
    private string TwitterUrl;
    private string TwitterStatus;

    /// <summary>
    /// Gets & sets the Twitter RSS URL 
    /// </summary>
    [Category("Main")]
    [Description("The URL to the Twitter RSS")]
    public string TwitterRssUrl
    {
        get ...

The Sitefinity CMS can be easily extended with regular ASP.NET User Controls.  Sitefinity will automatically generate input fields for any public properties found in these controls.  This empowers content editors to easily modify control properties using only their web browser.

In this example, only the Title property is defined in my user control.  The other properties were inherited from the System.Web.UI.UserControl base class.

Using design-time attributes we can hide these properties from Sitefinity.  Alternately, we can organize these properties into categories and designate our Title property as the default.

Using Property Categories and Setting Defaults

Design-time attributes are not a Sitefinity-specific feature.  These attributes are used by design-time developer tools (such as Visual Studio).  Sitefinity, wherever possible, utilizes existing .NET conventions rather than "re-invent the wheel".  This prevents developers from needing to learn a new system.

The design-time attributes reside in the System.ComponentModel namespace.  Use the Category...

By default, the Sitefinity CMS will automatically generate input fields for any public properties found in a control.  Look at the following code:

private string _test1;
private string _test2;
private string _test3;

public string Test1
{
    get { return _test1; }
    set { _test1 = value; }
}

public string Test2
{
    get { return _test2; }
    set { _test2 = value; }
}

public string Test3
{
    get { return _test3; }
    set { _test3 = value; }
}

In this example I've defined 3 public properties (Test1, Test2, Test3).  If this code were used in a custom User Control, Sitefinity would automatically generate 3 input fields for these properties:

This happens automatically for any public control properties.  Furthermore, Sitefinity will generate input fields for not only your public properties, but also public properties inherited from the System.Web.UI.UserControl base class.

Depending on how many public properties your control has, this can become a bit overwhelming. 

Hiding Properties with Design-Time ...

Sitefinity is based on traditional ASP.NET technologies.  If you know ASP.NET, then you already know how to extend Sitefinity.  In this blog post we'll take a very basic ("Hello World") look at extending Sitefinity with regular ASP.NET UserControls.

Create your UserControl

To begin, create a new ~/UserControls folder within your Sitefinity web site.  This step is optional.  UserControls can be put anywhere.

Right-click the ~/UserControls folder and click Add New Item.

For the Template select Web User Control and for the Name type CustomControl.ascx.

Adding a UserControl to the Sitefinity Toolbox

We've not done anything to this new User Control, but we can already make it available to Sitefinity. 

Open the ~/web.config file and look for the <toolboxControls> section.  This section contains tags for each tool that exists in Sitefinity.  To add a reference to this UserControl add the following tag to the <toolboxControls> section:

<add ...