Customizing Controls using In-Line Templates

Sitefinity ASP.NET CMS can be extended using traditional ASP.NET Custom Controls.  These controls, once compiled, can be distributed and shared between Sitefinity web sites.

However, when sharing controls between web sites, it often becomes necessary to customize the presentation per web site.  If the control supports templates, it’s possible to customize the control’s presentation template.

There are a variety of ways to to specify a custom template.  This blog post demonstrates how to wrap the original control in an ASP.NET User Control and specify an in-line template.  However, another strategy is to create a mapping between a control and a template.

Tip: For information about adding Template support to Custom Controls, refer to Using Templates with Custom Sitefinity Controls.

Create a Custom User Control to wrap the Original Control

In-line templates can be set using the <LayoutTemplate> section of the custom control.  In the example below, the MadLibs Custom Control is included in an ASP.NET User Control and then customized using an in-line template.

Create the following ASP.NET User Control:

~/UserControls/CustomMadLibs.ascx

<%@ Control Language="C#" AutoEventWireup="true" CodeFile="CustomMadLibs.ascx.cs" Inherits="UserControls_CustomMadLibs" %>
<%@ Register Namespace="SitefinityWatch.WebControls" Assembly="SitefinityWatch.WebControls" TagPrefix="sw" %>

<sw:MadLibs ID="MadLibs1" runat="server">
    <LayoutTemplate>
        <p>
            The 
            <strong><asp:Literal ID="NameLiteral" runat="server" /></strong> 
            oppressed the world by 
            <strong><asp:Literal ID="VerbLiteral" runat="server" /></strong>
            the 
            <strong><asp:Literal ID="NounLiteral" runat="server" /></strong>.
        </p>    
    </LayoutTemplate>
</sw:MadLibs>

~/UserControls/CustomMadLibs.ascx.cs

using System;

public partial class UserControls_CustomMadLibs : System.Web.UI.UserControl
{
    public string Name { get; set; }
    public string Verb { get; set; }
    public string Noun { get; set; }

    protected void Page_Load(object sender, EventArgs e)
    {
        MadLibs1.Name = Name;
        MadLibs1.Verb = Verb;
        MadLibs1.Noun = Noun;
    }
}

This method involves wrapping the original MadLibs control in a Custom ASP.NET User Control.  The CustomMadLibs User Control includes an in-line template that is passed to the original MadLibs control. 

Adding the Custom User Control to Sitefinity

Now that the ASP.NET User Control has been created, it must be added to the Sitefinity Toolbox.  Then can be done by adding a toolboxControl item to the ~/web.config:

~/web.config

<configuration>
  <telerik>
    <cms defaultProvider="Sitefinity" pageExtension=".aspx" disabled="false" pageEditorUIMode="Overlay">
      <toolboxControls>
        <add name="CustomMadLibs" section="Sitefinity Watch" url="~/UserControls/CustomMadLibs.ascx" />
      </toolboxControls>
    </cms>
  </telerik>
</configuration>

This new custom MadLibs control should be dropped onto Sitefinity pages instead of the original control.  To ensure that all CMS editors are using the custom control (instead of the original control) it might also be best to remove the original control from the toolbox.

Conclusion

By wrapping the original control in an ASP.NET User Control and then declaring an in-line template, it’s relatively easy to use customized templates with Sitefinity Custom Controls.  However, in addition to providing an in-line template, external template can be mapped to a control.