Mapping a control to use external template

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

 

In Sitefinity 3.6 most of the templates have been embedded with the assemblies, which means that you cannot modify them, unless you map the given control to use external template. In this topic we will provide step by step instructions on how to map an embedded template to an external one.

 

Before we start, make sure you have downloaded the ExternalTemplates.zip file from your Client.net account and placed it on your hard drive for reference. You can find out more about ExternalTemplates.zip file in the introductory article of this topic.

• Create a new folder in App_Data folder of your Sitefinity website and name it “Configuration” - it is required that this folder be named “Configuration”
• Add new XML file to this new “Configuration” folder and name it “Telerik.Sitefinity.Configuration.ControlsConfig.xml” - it is required that this file be named like that in order for the configuration to work
• Place following xml in the file:
  

  <?xml version="1.0" encoding="utf-8"?>

  <controlsConfig>

  <viewMap>

  </viewMap>

  </controlsConfig>

• Open the reference controls config file that you have downloaded from your Client.net account (it will be located in the App_Data/Configuration folder and be named “Telerik.Sitefinity.Configuration.ControlsConfig.xml” )
• You will notice a lot of nodes in between viewMap tags, where each node represents one control or View which uses embedded templates. Comments above the nodes will tell you which control or view is represented by that node.  You will also notice that nodes are sorted by modules. Find the viewSetting node which represents the View or control which you wish to use external template and copy that node, then paste it in the ControlsConfig file you have created in the second step of this tutorial, between the viewMap nodes.
• Let us suppose that we decided to map the View for inserting new content items of the Generic Content module. We will copy the following node from our reference controls config file:
  

  <!--Provides user interface for adding a new content item in the Generic Content module.-->

  <viewSettings

  hostType="Telerik.Cms.Engine.WebControls.Admin.ContentItemNew`1[[Telerik.Cms.Engine.WebControls.Admin.ContentItemsView, Telerik.Cms.Engine]]"

  layoutTemplatePath="~/Sitefinity/Admin/ControlTemplates/Generic_Content/ContentNewView.ascx" />

  
  And paste it to our own Controls Config file, which will now look like this:
  

  <?xml version="1.0" encoding="utf-8"?>

  <controlsConfig>

  <viewMap>

  <!--Provides user interface for adding a new content item in the Generic Content module.-->

  <viewSettings

  hostType="Telerik.Cms.Engine.WebControls.Admin.ContentItemNew`1[[Telerik.Cms.Engine.WebControls.Admin.ContentItemsView, Telerik.Cms.Engine]]"

  layoutTemplatePath="~/Sitefinity/Admin/ControlTemplates/Generic_Content/ContentNewView.ascx" />

  </viewMap>

  </controlsConfig>

• The last thing we need to do is to actually provide the external template which we have specified to be located at ~/Sitefinity/Admin/ControlTemplates/Generic_Content/ContentNewView.ascx”. Obviously, there is no requirement for the external template to be at that location, you are free to map it to any folder inside of your website.

 

*** IMPORTANT ***

 

Every time you modify ControlsConfig file it is necessary to restart the application in order for the changes to be applied. While there are numerous ways to restart an application, here are few handy ones - you can restart the IIS server, resave web.config file (e.g. open web.config file, press space, press backspace, save config.file), resave global.asax file (e.g. open global.asax file, press space, press backspace, save global.asax file)…

 

*** END IMPORTANT ***

 

*** NOTE ***

 

If you map to an external template that ends with the .ascx extension, you will be using standard ASP.NET template parser which means you will also need to provide localization file in the App_LocalResources file. Resources files are also part of the package that comes with ExternalTemplates.zip file.

 

If, on the other hand, you decide to use Sitefinity parser, embedded localization resources will be used. Sitefinity parser will be used if template ends in any other extension except .ascx (though the convention is .sft).

 

*** END NOTE