Tutorial: Manage custom control templates through the designer

You just finished building your custom Sitefinity CMS widget and a designer for it. It is either part of a module or you published it as a standalone widget in the Sitefinity CMS marketplace. Your first customer downloads it and is very happy with it, except one thing – the template cannot be edited through the user interface (UI), like the built-in templates can. This article explains how to manage the widget templates through the control designer.

For more information, see:

• Tutorial: Enable template editing through the UI
• Create a new custom widget
• Create a simple widget designer

1. Create the template of the designer
   
   The template contains the UI of the designer. It is represented by an .ascx file built as an embedded resource. In order to manage widget templates, you must use the TemplateSelector control provided by Sitefinity CMS. Use the code below to register the control in the markup:
   
   
   <%@ Control Language="C#" %>

    

   <%@ Register Assembly="Telerik.Sitefinity" TagPrefix="sf" Namespace="Telerik.Sitefinity.Web.UI" %>

   <%@ Register Assembly="Telerik.Sitefinity" TagPrefix="sf" Namespace="Telerik.Sitefinity.Web.UI.Fields" %>

   <%@ Register Assembly="Telerik.Sitefinity" TagPrefix="sf" Namespace="Telerik.Sitefinity.Web.UI.ControlDesign.Selectors" %>

    

   <div>

       <h2>

           <asp:Literal ID="literal" runat="server" Text="<%$Resources:CustomControlResources, CustomWidgetTemplate %>" />

       </h2>

       <sf:TemplateSelector runat="server" ID="templatesSelector" />

   </div>
    
   NOTE: Mark the template as embedded resource by opening the Properties pane and set the BuildAction field to EmbeddedResource.
   
   
2. Create the class for the designer
   
   To create the class for the designer, you must inherit the ControlDesignerBase class:
   
   
   public class CustomWidgetDesigner : ControlDesignerBase

      {

          . . .

       }
   
   
3. Implement the ControlDesignerBase class
   
   You must override the following members:
   
   LayoutTemplatePath:
   
   
   public override string LayoutTemplatePath

           {

               get

               {

                   return CustomWidgetDesigner.layoutTemplatePath;

               }

           }

    

    #region Private members & constants

    

           public static readonly string layoutTemplatePath = "~/CustomPrefix/SitefinityWebApp.Controls.CustomWidgetDesigner.ascx";

    

           #endregion
   
   NOTE: "CustomPrefix" is a virtual path provider prefix. You must add it in the VirtualPathSettingsConfig.config in order to register the prefix as shown here:
   
   
   <add resourceLocation="SitefinityWebApp" resolverName="EmbeddedResourceResolver" virtualPath="~/CustomPrefix/*" />
   
   For more information, see Taking advantage of the virtual path provider.
   
   InitializeControls:
   
   In this override, you must set the default mode of the designer - in this case Simple and the designer control type of the template selector:
   
   
   protected override void InitializeControls(Telerik.Sitefinity.Web.UI.GenericContainer container)

          {

              base.DesignerMode = ControlDesignerModes.Simple;

              this.TemplateSelectorControl.DesignedControlType = this.PropertyEditor.Control.GetType().FullName;

          }
   
   GetScriptReferences:
   
   In this method you must reference the script for the client component:
   
   
   
   public override IEnumerable<System.Web.UI.ScriptReference> GetScriptReferences()

           {

               var scripts = new List<ScriptReference>(base.GetScriptReferences());

               var assemblyName = typeof(CustomWidgetDesigner).Assembly.GetName().ToString();

    

               scripts.Add(new ScriptReference(CustomWidgetDesigner.scriptReference, assemblyName));

               return scripts;

           }
   
   GetScriptDescriptors:
   
   
In order to register the template selector control in the client component of the designer, you must override the GetScriptDescriptors method as shown below:


public override IEnumerable<System.Web.UI.ScriptDescriptor> GetScriptDescriptors()
        {
            var scriptDescriptors = new List<ScriptDescriptor>(base.GetScriptDescriptors());
            var descriptor = (ScriptControlDescriptor)scriptDescriptors.Last();
 
            descriptor.AddComponentProperty("templatesSelector", this.TemplateSelectorControl.ClientID);
 
            return scriptDescriptors;
        }
 
        #region Private members & constants
 
        public static readonly string layoutTemplatePath = "~/CustomPrefix/SitefinityWebApp.Controls.CustomWidgetDesigner.ascx";
        public const string scriptReference = "SitefinityWebApp.Controls.CustomWidgetDesigner.js";
 
        #endregion


4. Implement the client component of the designer
   
   To implement the client component of the designer, you must add new .js file with name CustomWidgetDesigner and mark it as embedded resource. Define the client class as follows:
   
   
   Type.registerNamespace("SitefinityWebApp.Controls");

    

    

   SitefinityWebApp.Controls.CustomWidgetDesigner = function (element) {

    

       this._templatesSelector = null;

       

       /* Calls the base constructor */

        

       SitefinityWebApp.Controls.CustomWidgetDesigner.initializeBase(this, [element]);

   }
   
   In the code above, the namespace for the client code is created first. This is done by calling the registerNamespace of Type class. 
   
   Next step is to define the prototype for the class:
   
   
   
   SitefinityWebApp.Controls.CustomWidgetDesigner.prototype = {

       /* --------------------------------- set up and tear down --------------------------------- */

       initialize: function () {

           /* Here you can attach to events or do other initialization */

         

           SitefinityWebApp.Controls.CustomWidgetDesigner.callBaseMethod(this, 'initialize');

    

       },

       dispose: function () {

           /* this is the place to unbind/dispose the event handlers created in the initialize method */

    

           SitefinityWebApp.Controls.CustomWidgetDesigner.callBaseMethod(this, 'dispose');

       },

    

       /* --------------------------------- public methods ---------------------------------- */

    

       /* Called when the designer window gets opened and here is place to "bind" your designer to the control properties */

       refreshUI: function () {

           var controlData = this._propertyEditor.get_control(); /* JavaScript clone of your control - all the control properties will be properties of the controlData too */

    

           /* RefreshUI Message */

           this.get_templatesSelector().refreshUI();

       },

    

       /* Called when the "Save" button is clicked. Here you can transfer the settings from the designer to the control */

       applyChanges: function () {

           var controlData = this._propertyEditor.get_control();

    

           /* ApplyChanges Message */

           this.get_templatesSelector().applyChanges();

       },

    

    

       /* --------------------------------- properties -------------------------------------- */

       get_templatesSelector: function () { return this._templatesSelector; },

       set_templatesSelector: function (value) { this._templatesSelector = value; }

   }

    

   SitefinityWebApp.Controls.CustomWidgetDesigner.registerClass('SitefinityWebApp.Controls.CustomWidgetDesigner', Telerik.Sitefinity.Web.UI.ControlDesign.ControlDesignerBase);

For more information, see For developers: Implement the client component for the simple widget designer.


5. Assign the designer to the custom control
   
   You must add a ControlDesigner attribute in order to register the designer to the custom control:
   
   
   [ControlDesigner(typeof(CustomWidgetDesigner))]

      public class CustomWidget : SimpleView
   
   With this step, you are now ready to manage templates through the designer of the custom control.