Creating a Basic Sitefinity User Control

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 name="Custom Control" section="My Controls" url="~/UserControls/CustomControl.ascx" />

• Name - This name will be displayed for the control.
• Section - The control will appear within this section.  (You can use existing section names or a new section name)
• Url - The path to the user control.

Save your changes.  You can now edit a Sitefinity page and see your new control in the Toolbox:

You can drag & drop your new control onto a Sitefinity page; although it won't yet do anything.

Making your UserControl Do Something

Create the following UserControl at ~/UserControls/CustomControl.ascx:

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

<p>
    Here is some text:
    <asp:Label ID="Label1" Font-Bold="true" runat="server" />
</p>

Create the following ~/UserControls/CustomControl.ascx.cs code-behind file:

using System;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;

public partial class UserControls_CustomControl : System.Web.UI.UserControl
{
    private string _labeltext;

    /// <summary>
    /// All public properties will automatically be made available in the Sitefinity control editor.
    /// </summary>
    public string LabelText
    {
        get { return _labeltext; }
        set { _labeltext = value; }
    }

    protected void Page_Load(object sender, EventArgs e)
    {
        Label1.Text = LabelText;
    }
}

Drag & drop an instance of this user control onto a Sitefinity page.  Click Edit for the control:

Using reflection Sitefinity will automatically generate input fields for any public properties.  Our small user control contains a public string property called LabelText.  The other properties you see (ID, EnableViewState, EnableTheming, Visible) belong to the System.Web.UI.UserControl base class that our custom user control is inheriting from.  In my next post we'll look at how to hide properties from Sitefinity.

Type "Hello World" into the LabelText input field and then click I'm done.

This control is obviously very simple.  The text we entered was used to populate an ASP.NET Label.

Aside from adding a mapping to this User Control, none of these instructions are specific to Sitefinity.  Anything you can do with an ASP.NET User Control can now be used to extend Sitefinity. 

Custom User Controls are a very simple yet powerful way to customize and extend Sitefinity.