Customizing Controls by Mapping a new Template

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 map a control to a custom external template.  However, another strategy is to wrap the control in an ASP.NET User Control and provide an in-line template.

For information and a video describing how to create a Custom Control that supports Templates, refer to Using Templates with Custom Sitefinity Controls.

Create a Customized External Template

Before a control can be mapped to an external template the customized template must first be created.  In the example below, the MadLibs Control will be mapped to a custom template.

Create the customized template that should be used by the original control. 

~/Custom/Templates/MadLibs.ascx

<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>

This template can be treated like an ASP.NET User Control.  The template can contain HTML, Javascript, CSS and ASP.NET server tags.  However, in most cases it won’t be necessary to do anything with the code-behind file of this User Control.

Configuring a Control to use a Customized External Template

Once the custom template is created, the next step is to configure the MadLibs control to use this external template.  There are two methods that can be used to map an external template to a control: 

1. Use an XML configuration file to map ALL instances of a control to an external template.
2. Manually configure templates on a per control basis.

Each of these methods are described below.

Map ALL instances of a Control to use an External Template

A special XML configuration file can be created in Sitefinity to declare an external template mapping for ALL instances of a control.  To do this, create the following directory and XML file.

~/App_Data/Configuration/Telerik.Sitefinity.Configuration.ControlsConfig.xml

<?xml version="1.0" encoding="utf-8" ?>
<controlsConfig>
  <viewMap>
    <viewSettings hostType="SitefinityWatch.WebControls.MadLibs" layoutTemplatePath="~/Custom/Templates/MadLibs.ascx" />
  </viewMap>
</controlsConfig>

The <viewSettings> option associates a template-supporting control with an external template.  This will configure Sitefinity to use this external template for all instances of a control.

This XML configuration file is processed during Application Start.  Consequently, after making changes to this file it will be necessary to restart your web application before changes will take effect.

For more information on this topic or to learn how to customize Sitefinity control templates refer to Customizing Sitefinity Embedded Templates.

Map individual instances of a Control to use an External Template

To change the template used by an individual control edit the Sitefinity page that contains the instance for the control.  Then click Edit for the control to access the control properties.

Change the LayoutTemplatePath property to contain the path to the external template:

Click I’m done and save the changes to the page.  Changes will take effect immediately.

Conclusion

My mapping controls to templates, it’s relatively easy to use customized templates with Sitefinity Custom Controls.  However, in addition to mapping customized templates, customized templates can also be declared in-line.