[This post is part of the developer's manual preview published on this blog. You can find temporary TOC here.]
[This article requires Sitefinity 3.6 hotfix to be installed]
ControlsConfig file is a new configuration file introduced in Sitefinity 3.6 which allows developers to
- Map embedded templates to external templates
- Add new Subviews to Views
- Remove existing Subviews to Views
- Replace existing Subview with a new Subview
*** NOTE ***
If you are unfamiliar with Views and Subviews, please refer to the articles giving Architectural Overview and explaining what are Views.
*** END NOTE ***
How does one activate controls configuration
Controls configuration is defined by a special file named
Telerik.Sitefinity.Configuration.ControlsConfig.xml
which needs to be placed in the ~/App_Data/Configuration folder of your site. The name of the file and its location are crucial for the configuration to work.
What is the structure of the controls configuration file
The root node of configuration file is <controlsConfig>, which is followed by the <viewMap> node, inside of which all the current configurations are being defined. Let us take a look at the example controls config file, which maps BloggersList (public control of Blogs module) to use an external template instead of an embedded one.
| <?xml version="1.0" encoding="utf-8"?> |
| <controlsConfig> |
| <viewMap> |
| <!--Provides user interface for displaying a list of bloggers in the blogs module. --> |
| <viewSettings |
| hostType="Telerik.Blogs.WebControls.BloggersList" |
| layoutTemplatePath="~/Sitefinity/ControlTemplates/Blogs/BloggersList.ascx" /> |
| </viewMap> |
| </controlsConfig> |
How to get the list of all possible configurations and where to find template files
Since the key of the viewSettings element is the full type of the control for which the setting is being set, it may not always be easy to find out what type should we specify. Also, sometimes one would just like to create an external template from the embedded one and make only few modifications.
For this purposes, in your Client.net account you can find zip files named “Version_ExternalTemplates.zip”, where Version of course is the name of the version for which you wish to download External templates.
*** NOTE ***
External templates zip file is available from Sitefinity 3.6 1870 version.
*** END NOTE ***
Once you download and extract the file, you will notice that you have two folders inside:
- App_Data and
- Sitefinity
*** WARNING ***
Do not simply copy the ControlsConfig files in your App_Data/Configuration folder because you will effectively map all the templates to external ones. Map only the controls for which you wish to make modifications, because this will greatly simplify your upgrade process on the next releases.
*** END WARNING ***
In Sitefinity folder, on the other hand, you will find all the templates we have embedded in version Sitefinity 3.6, which you can use as a starting point for your modifications.