[UPDATE: problems reported in the comments below this post have been fixed and files for download have been updated]
As you may have noticed on some of our controls, when you edit them in a page editor, there are two modes for editing the control (or setting the properties). There is a simple and advanced way. In this post I am going to explain how to achieve this same functionality for the user controls you create and upload to Sitefinity toolbox.
First of all, let’s see what are the pros and cons of the two editor modes, which will also show you why do we chose to have two editor modes instead of one.
As you can see on the above diagram, both modes have their advantages, so which one should be used really depends on the actual user. When designing your controls, you should keep in mind the knowledge level of the user that is likely to use the control. Based on this assumption, you can decide whether to create a control designer or not.
In this sample we are going to build a simple user control that will wrap standard ASP.NET 2.0 BulletedList control. We are going to let users set the DisplayMode (Text,HyperLink, LinkButton) of a control and in addition to that let them add or remove the items from the list. All in all, it should vaguely resemble to the designer of this control that is available in Visual Studio. Since we are assuming that some pretty unexperienced user will be using this control, we are going to provide them with a Control Designer, or Simple mode for editing the control. To get an idea of how this simple editing mode will look like (more or less :), please take a look at the following image:
At this point, I advise you to download the project so you can keep following the post. The whole project you can download from here.
1.Download the project from here.
2. Unzip the project
3. Copy the ~/App_Code/Designer folder to your ~/App_Code folder (add App_Code folder if it does not exist)
4. Copy the ~/MyTemplates folder to your project
5. Copy the ~/MyControls folder to your project
6. Create a page in Sitefinity and upload a new user control. The control you should upload is ~/MyControls/MyBulletedList.ascx (make sure to upload the code-behind as well)
7. Drag the control onto the page and click on Edit (it’ll appear when you hover over the control if you are in Overlay mode)
Let’s examine the steps that we needed to undertake to make this happen.
First, we created an user control just as any other. We defined the properties of this user control, we make them function, so nothing fancy here.
Second thing we needed to do, was to create a designer class for this control. Since we are doing this for User Control, we have put that class in a App_Code folder. Since I have commented the code I will not get into too many details here, but what we needed to do is to create some kind of a connection between the designer and our user controls. In modules and custom controls, we generally use the type of our control as a reference, but here we are working with the UserControl so that won’t help us a lot. Since C# does not support multiple inheritance, we could not have created a baseclass and let our user control inherit from that class as well (in addition to inheriting UserControl base class). So the solution is to create an interface and implement that interface on our User Control. Then we are going to be able to treat the user control from our designer as a control that implements a specific interface. This approach has some other neat side-effects such as an ability to create one designer and use it by multiple controls.
Finally, you will see that our Custom designer is nothing but a custom control, which creates its user interface through a template (same principle as with creating pluggable modules).
In order to implement a custom designer on a User Control, you are going to need:
1. User control
2. Custom control representing a designer
3. Template for the UI of designer
4. Interface to which you can cast user control
The whole code you can download from here. Drop a comment if you have any additional questions or if there are some problems with the project.