+1-888-365-2779
Try Now
More in this section
Categories
Bloggers
Blogs RSS feed

HOW TO : create a control designer for user controls

by Ivan Osmak

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

User Controls - Control Designer Diagram

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:

User Controls - BulletedList Control Designer Mockup

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.

Installation

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)

Explanation

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

Conclusion

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.

4 comments

Leave a comment
  1. Romi Apr 28, 2008
    Many thanks for this contribution. We need more helps like this to increase Sitefinity users. Perhaps the others SF dev team could contribute lilte more to this Forum?. Thanks Ivan.
  2. Seth May 14, 2008
    Hi Ivan, there does seem to be a problem with the project... It doesn't seem to work as describe eg. There is no designer showing wheb you drop it into a Sitefinity page. Did to miss something in your project? It would be real helpful if you could check it. Thanks
  3. Monika May 30, 2008
    Hi Lvan, I am also facing the same problem as Seth is facing. Plese let us know the reason or there might be some setting missing in web.config, if so, please let me know them.
  4. Ivan Oct 09, 2008
    Hi Seth & Monika, I am not at the office at the moment and can't update the blog, however, I've transferred this and some additional samples to developers manual so you can go and download the code from there: http://www.sitefinity.com/help/developer-manual/control-adding-controls-designers.html . It is a series of articles and the one I've provided you with a link is the last in the series. The complete project with all samples and needed code can be downloaded from here: http://www.sitefinity.com/sf3/sampleprojects/UserControls_LinksList_project.zip .That link together with explanations is on the introductory page: http://www.sitefinity.com/help/developer-manual/controls-adding-controls-overview.html . Sorry for buch of links, we've made some mistakes with download links in dev manual and are working on fixing that. Hope this helps.

    Leave a comment