More in this section
Blogs RSS feed

Introduction to ControlsConfig file

by Ivan Osmak

[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




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"?> 
    <!--Provides user interface for displaying a list of bloggers in the blogs module. --> 
        layoutTemplatePath="~/Sitefinity/ControlTemplates/Blogs/BloggersList.ascx" /> 


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 account you can find zip files named “”, 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
In App_Data/Configuration folder you will find the ControlsConfig file with all controls that use embedded templates. This file you can use as a reference for your own mappings.


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




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.


Leave a comment
  1. Joel Mar 08, 2009

    Thank you very  much for the article, I have found it very useful and I'm in the middle of researching these changes. Can you explain in further detail on why some templates are now embedded and others are not? I have found a mix-match of templates now, some embedded and others are readily accessible and fully exposed. I am sure there is a simple explanation here. I am thinking at this point if I were to modify any of the non-embedded templates I still run the risk of having those overwritten with a future release/update. Thanks in advance for your thoughts.
  2. Joel Mar 09, 2009
    Something else I ran into today. I was setting up my website and I noticed when I was using the blog list control (ContentViewItemList.ascx or ContentViewSingleItem.ascx embedded) that the embedded skins were not pulling values from the resource files (ContentViewItemList.ascx.resx and ContentViewSingleItem.ascx.resx). Is that to be expected? I was forced to pull out the skins and the resource files, drop them into the site and modify the controls config just to get them to display as they should to begin with. Perhaps I am missing something here as well. Thanks Ivan.
  3. Daniel Mar 19, 2009
    Why, why, why in the world would this be considered a practical solution? We almost always modify at least three different control templates on a given Sitefinity site. Users always want different meta tags or a different layout. Now I'm trying to set my view setting and Sitefinity seems to be completely ignoring my configuration file (named exactly as instructed). Not only have you made it extremely difficult to change the control templates (why not just set the path in the control designer??), but you have also made it difficult for me to go find a copy of the ascx code so I can make modifications. Embedded templates, fine I get it. But still why cant I have an easier way of setting my control template path? But really I don't understand the reasoning behind this embedded templates mess. Why not instruct users to always copy controltemplate files when customizing them? It seems like the talent at Telerik could have been innovating in some other areas rather than add this conterproductive feature.
  4. Ivan Mar 19, 2009
    Hi Daniel,

    I am sorry that you find this feature counterproductive and I see that it may seem so at first, however, the general feedback on this feature has been overwhelmingly positive. A thing to note about ControlsConfig file is that it is not only a template mapping tool, but also is capable of dynamically replacing parts of Sitefinity with your own implementations.

    As for the user friendliness, you are absolutely right - it's not perfect. However, we have already started the development on configuration manager tool which will provide user friendly way to work with configuration directly from Sitefinity user interface. The feature is planned to be released in Sitefinity 4.0.

    We did not receive and problem reports in regards to this feature, so I'd advise you to open a support ticket and we will surely be able to help you out.
  5. SteveH Mar 06, 2010

    Go easy on the Sitefinity staff. They have always been more than forthcoming with solutions, provided you exercise a bit of patience and diligent study.

    Cheers! :>]
  6. varun Jun 08, 2016

    hi ,

    can you please upload a tutorial on Inter-Page Routing / Subviews , how they are handled in sitefinity .

    Leave a comment