Creating simple control designers
The simple control designer uses a single view to display its UI. The designer is represented by a custom control that inherits the ControlDesignerBase class and implements a client component. Following is a screenshot of a simple control designer:
To create a simple control designer for your control, you must perform the following:
-
Create a custom control
-
Create a template
-
Implement the ControlDesignerBase class
-
Reference the template
-
Implement the client component
-
Reference the client script
For more information about creating controls with client component, see Adding Ajax Functionality to ASP.NET Controls.
Creating a custom control
The backbone of the designer is a custom control. It wires up the template and the client component and allows you to assign the designer to the desired control in the code. To create the class for the designer, perform the following.
-
Add a new class to the project of the control that the designer will be applied to.
For example, if the control is named Rotator, create a class named RotatorDesigner.
-
Add a reference to the Telerik.Sitefinity assembly.
-
From the context menu of the project, click Add Reference...
-
In the Browse tab, navigate to the folder C:\Program Files (x86)\Telerik\Sitefinity 4.0\Libraries.
-
Select the assembly and click OK.
-
Add a reference to the System.Web.Extensions assembly.
-
From the context menu of the project, click Add Reference...
-
In the .NET tab, select the assembly and click OK.
- Add the using Telerik.Sitefinity.Web.UI.ControlDesign; statement to the RotatorDesigner class.
-
Make the RotatorDesigner class inherit the ControlDesignerBase class.
public class RotatorDesigner : ControlDesignerBase
{
}
Creating a template
The template contains the UI of the designer. It is represented by an .ascx file built as an embedded resource. To create a template, perform the following:
-
Add an empty .ascx file to the project structure of the control you want to apply the designer to.
For example, you can place it under Resources/Views/ folder.
- From the context menu of the .ascx file, click Properties.
- In the Properties pane set the BuildAction field to EmbeddedResource.
-
Open the .ascx file and create the UI for the designer.
Following is an example of a template that contains a single field for Title.
<div>
<span>Title:</span><br />
<input type="text" id="txtTitle" />
</div>
Implementing the ControlDesignerBase class
To implement the ControlDesignerBase class in your designer, you must override the following members:
-
InitializeControls
In this override you can set, for example, the default mode of the designer to Simple or Advanced.
-
LayoutTemplateName
This property must return the name of the template of the designer.
-
GetScriptReferences
In this method, the script for the client component is referenced.
Following is the code for the RotatorDesigner class:
public class RotatorDesigner : ControlDesignerBase
{
protected override void InitializeControls(Telerik.Sitefinity.Web.UI.GenericContainer container)
{
base.DesignerMode = ControlDesignerModes.Simple;
}
protected override string LayoutTemplateName
{
get
{
return string.Empty;
}
}
public override IEnumerable<System.Web.UI.ScriptReference> GetScriptReferences()
{
return base.GetScriptReferences();
}
}
Referencing the template
To wire up the template with the designer, you must return its name via the LayoutTemplateName property. It specifies the path to the embedded resource following the naming convention <Namespace>.<ResourceFolderPath>.<TemplateName>, where you must replace path slashes inside the resource folder path with dots. For example, if you have project called NewsRotator and the path to the template file is Resources/Views/RotatorDesigner.ascx, the LayoutTemplateName property must return the following:
protected override string LayoutTemplateName
{
get
{
return "NewsRotator.Resources.Views.RotatorDesigner.ascx";
}
}
Implementing the client component
You must store the client component in a .js file in the project, where the designer resides. To implement the client component, you must do the following:
-
Add a new .js to the project of your designer.
You can name the file the same way as the class. For example, if the class is named RotatorDesigner, name the file RotatorDesigner.js.
- From the context menu of the .js file, click Properties.
- In the Properties pane, set the BuildAction field to EmbeddedResource.
- Open the .js file.
-
In the .js file, create the namespace for the client code.
This is done by calling the registerNamespace of the Type class.
Type.registerNamespace("NewsRotator");
NOTE:You must use the same namespace throughout the entire client code in this file.
-
Define the client class in the following way:
NewsRotator.RotatorDesigner = function (element) {
NewsRotator.RotatorDesigner.initializeBase(this, [element]);
}
-
Define the prototype for the class by including the following methods:
-
initialize
This method is called when an instance of the class is created. In it, you must call the initialize method of the ControlDesignerBase class.
-
dispose
This method is called when the instance of the class is no longer used. In it, you must call the dispose method of the ControlDesignerBase class.
-
refreshUI
This method is called when the designer is opened. In it you must get an instance of the control and populate the UI with the values of the properties of the control.
-
applyChanges
This method is called when the changes must be applied to the control. In it you must get an instance of the control and set its properties to the new values in the UI.
NewsRotator.RotatorDesigner.prototype = {
initialize: function () {
NewsRotator.RotatorDesigner.callBaseMethod(this, 'initialize');
},
dispose: function () {
NewsRotator.RotatorDesigner.callBaseMethod(this, 'dispose');
},
refreshUI: function () {
var controlData = this.get_controlData();
jQuery("#txtTitle").val(controlData.Title);
},
applyChanges: function () {
var controlData = this.get_controlData();
controlData.Title = jQuery("#txtTitle").val();
},
get_controlData: function () {
return this.get_propertyEditor().get_control();
},
get_propertyEditor: function () {
return this._propertyEditor;
}
}
-
Register the client class and specify its base class.
This is done by calling the registerClass method. You must pass the Telerik.Sitefinity.Web.UI.ControlDesign.ControlDesignerBase as the base class.
NewsRotator.RotatorDesigner.registerClass('NewsRotator.RotatorDesigner', Telerik.Sitefinity.Web.UI.ControlDesign.ControlDesignerBase);
if (typeof (Sys) !== 'undefined') Sys.Application.notifyScriptLoaded();
Referencing the client script
You must reference the client component from the designer class. You do this in the override of the GetScriptReferences method. In it you must create a script reference for your client component and add it to the existing list of references. When creating the reference, you must specify the name of the embedded resource that contains the client component and the assembly it resides in. The name of the resource follows the same naming conventions as the name of the template.
public override IEnumerable<System.Web.UI.ScriptReference> GetScriptReferences()
{
var res = new List<System.Web.UI.ScriptReference>(base.GetScriptReferences());
var assemblyName = this.GetType().Assembly.GetName().ToString();
res.Add(new System.Web.UI.ScriptReference("NewsRotator.Resources.RotatorDesigner.js", assemblyName));
return res.ToArray();
}