One of the major improvements Sitefinity 3.6 introduced was Embedded Templates. The use of embedded Control Templates:
- Reduces the overall project size
- Makes it easier to deploy Sitefinity web sites
- Provides clear separation of concerns
- Ensures customizations are never overwritten during upgrades
More information about Embedded Templates
Prior to Sitefinity 3.6 hundreds of Control Template files could be found throughout a Sitefinity installation. Sitefinity customizations were made directly to these ControlTemplates.
Because templates are now embedded, customizations take a few extra steps:
1.) Create an external template by obtaining the embedded template
2.) Map a View to this external template
3.) Customize the external template
There is a KB article that describes how to map a view to an external template
Understanding Sitefinity Views
Roughly speaking, each page encountered in Sitefinity is a View. Click the Blogs module and you encounter a View. Add a new Blog Post and you encounter another View.
Associated with each of these Views is a Control Template. Control Templates look exactly like ASP.NET User Controls; they contain HTML and ASP.NET server tags. However, these Control Templates often lack a "code-behind" file. Instead, they merely represent the front-end. The View handles the "back-end" and operates as the pseudo "code-behind" file for these templates.
Tip: You are free to add a code-behind file to control templates. When code-behind files are added, this code will execute in addition to the View code.
Control Templates can be changed drastically to customize Sitefinity. However, it's important to realize that Sitefinity Views contain some dependencies. Many Views require specific server tags exist in the Control Template. If the required server-side tags do not exist, it can result in errors.
Getting Embedded Templates Out Of Bed (<-- lame title)
Before beginning to customize Control Templates; first obtain the Embedded Template. The embedded templates can be downloaded from the Sitefinity Downloads section. Look for EmbeddedTemplates zip file in the list of available files.
Unzip this file. From here, it's a process of finding the correct template for the View to be altered. Use the ControlsConfigReference.xml file (included in the zip file) to make an educated guess. If you aren't able to locate the correct template (or view), search the Sitefinity forums for the answer. If the answer isn't found, post your question to the forums.
In the case of Sitefinity's Generic Content Control Designer, here are the details:
View: Telerik.Cms.Engine.WebControls.Design.GenericContentDesigner
Template: ~/Sitefinity/Admin/ControlTemplates/Generic_Content/GenericContentDesigner.sft
Copy the template from the EmbeddedTemplates zip file to your Sitefinity web site. This file can be copied anywhere, although I prefer to keep customized files separate from Sitefinity's files. I copied this file to the following location in my web site:
~/Custom/Admin/ControlTemplates/Generic_Content/GenericContentDesigner.ascx
Notice I renamed the file from "sft" to "ascx".
Mapping a View to an External Control Template
The mapping between Views and External Templates is handled in an XML configuration file. This XML configuration file does not exist by default. To get started, create the following file:
~/App_Data/Configuration/Telerik.Sitefinity.Configuration.ControlsConfig.xml
This file contains the following format:
<?xml version="1.0" encoding="utf-8" ?>
<controlsConfig>
<viewMap>
<viewSettings hostType="Path.To.View.Class" layoutTemplatePath="~/Path/To/ControlTemplates/File.ascx" />
</viewMap>
</controlsConfig>
hostType = reference to the View class to be mapped.
layoutTemplatePath = the path to the external Control Template
This XML file can contain multiple <viewSettings> tags. Below is the View mapping for the Generic Content Control Designer:
<?xml version="1.0" encoding="utf-8" ?>
<controlsConfig>
<viewMap>
<viewSettings hostType="Telerik.Cms.Engine.WebControls.Design.GenericContentDesigner" layoutTemplatePath="~/Custom/Admin/ControlTemplates/Generic_Content/GenericContentDesigner.ascx" />
</viewMap>
</controlsConfig>
Note: The View/Template mappings are initialized during the web application's startup. This means the web application might need restarted before changes take effect.
When the Telerik.Sitefinity.Configuration.ControlsConfig.xml file is in place, Sitefinity uses External ControlTemplate instead of the embedded template.
Customizing External Control Templates
Customizations can be made once the external Control Template is in place and the View correctly mapped. The embedded template will no longer be used for the mapped View. In addition, this external Control Template will never be overwritten by future versions of Sitefinity.
In my next post, I'll use an external Control Template to turn-off HTML editing in Sitefinity's RadEditor.
