More in this section
Blogs RSS feed

Building a module for Sitefinity (part 6) : Anatomy of a web control

by Ivan Osmak

Anatomy of web controlGenerally, we can say that all web controls you are going to build for Sitefinity modules have several things in common. In this post I will explain how I’ve approached building a ControlPanel control for Contacts module. Once that is explained everything else should come pretty easy to you. At the end of this post you’ll find a link to the project so you can download it and examine (I’ve commented the project rather extensively).

There are two cornerstone ideas we have when we build any kind of control :

  1. Appearance of control is defined through a template. To control it should make no difference how the template is created
  2. Working with data is done through a manager class. It should make no difference to control how is data being stored, that’s up to provider.

Take a look at following diagram to get a high overview of how Web controls are built in Sitefinity.

Web control diagram

Working with controls

On the left we have Web Control (blue) which represents ControlPanel in this example. This control acts as a wrapper control for the actual controls of ControlPanel. The child controls being (if you forgot how control panel should look like, take a look at this mockup Contacts module > View mode) :

  1. Add new contact - when clicked Control panel should switch from list mode to insert mode
  2. Contacts grid - Rad Grid that lists all the contacts
  3. Contact Editor - this control serves a purpose of adding new contacts or editing existing contacts (if you forgot, this is how this control looks like Contacts module > Insert / edit mode)

In order to allow designer / user experience expert to modify the look and feel of the controls without messing with the code and recompiling we load controls from template. This is where the GenericContainer kicks in. We are always going to instantiate the template inside a class that inherits from GenericContainer. Generic Container class allows us to define controls that are absolutely necessary for ControlPanel to be working (required controls), but also allows us to define the controls that can be there, but are not necessary (optional controls). So if a template creator forgets to add a Button control with the id of “addNewContact” an exception we’ll be thrown saying that template is missing a required “addNewContact” button. By using GenericContainer class we have an easy way to make a contract between a programmer and designer.

Template creator has two options when it comes to creating a template without coding. One is to create an user control and set it’s path in the web.config provider or he can declaratively create template. Note that it is only possible to create declarative template if the ControlPanel is added to the page or user control declaratively as well (it’s obvious that if we add ControlPanel dynamically we can’t create template declaratively).

Third option for creating a template is default template, class that inherits from ITemplate. You should always implement default template because it is possible that Page object will not be accessible at one time or another (Design) and you don’t want the control to crash at that moment.

If all this sounds messy, take a look at the diagram once again, download the project and examine the code, and then reread it again. This whole idea is actually much simpler than it sounds.

Working with data

In order to keep our control as flexible as possible, all the work with data will be done through manager (ContactsManager) in this example. Depending on how you initialize manager (without the provider name it will use ‘DefaultProvider’ or with the actual name of the provider) manager will decide which provider to use to work with data.

This, for example, allows you to move your data from Sql Server to XML without ever modifying the Web controls. All you need to do is create a new Data provider and initialize manager with the name of new provider.

Few last words

I’ve just explained the logic behind creating the controls. Understanding this logic should ease your decisions regarding where to create controls, how to bind controls to data and such. The detailed explanation you can get by examining the project, since I’ve commented all the crucial parts. Once again, if you have any questions, don’t hesitate to ask. Nothing would make me more happier that a request from you to write a blog post on a topic that has not be understood clearly :)

Next steps

Since we’ve covered most of the topics so far, I won’t be explaining the project step-by-step anymore, but will point out important aspects. So from now on, I’ll be working more on the code and comments… while in posting I’ll let you know what has been added so you can see how to whole thing is rolling out.


One more thing, once the module is completed I’ll make the entire solution (with Sitefinity Community Edition) available for download.


Leave a comment
  1. chris Jul 04, 2007
    Hello, can you provide a link to download this project? It appears the link to isn't working. Thanks so much!
  2. Paul Jul 26, 2007
    Seems to me it was some temporary glitch with the download link. It works for me now. 10x for the project
  3. Roman Aug 07, 2007
    Sample.Contacts\WebControls\Admin\ContactEditor.cs To avoid error I've commented lines from 135 to 140 Now I don't see any controls when I press "Add new contact" I think it's because not implemented "DefaultContactEditorTemplate.InstantiateIn" in line 271. How to solve this problem?
  4. amjad Aug 10, 2007
    hi i m amjad khan warsi
  5. CorkNBeans Sep 05, 2007
    Guide To Building Houses Part 1 - 5: Here is a general overview of what a house is. Part 6: Here is a completed house; I hope that helps! I feel like I might be missing a few steps in there...
  6. Darchele Webb Oct 01, 2007
    Help... this post discusses the need for a template, but the project does not include the template as an example. Can you post the template as well??
  7. May 21, 2008
  8. May 23, 2008
  9. May 24, 2008
  10. Brian Boatright Jul 22, 2008
    Sorry to be a noob but how do you actually use this? With some modifications I can use this almost exactly but with so many files in the project source I'm confused on how to actually get it to work with Sitefinity. Ideally I would like a single DLL to give to the customer to upload.
  11. Ivan Jul 28, 2008
    Hi Brian, when developing a module you will generally end up with one or two .dll files (see why there could be one or two assemblies here: The external files (templates) are purposely put outside of an assembly, so that User Interface can be modified without the need for recompiling the project. Obviously, you can use only default templates inside of assembly and not provide a way for external templating, but that would be quite inflexible.
  12. Nugs Oct 08, 2008
    Ivan, I am a little confused too... First of all... Where is part 4 of this blog?? We went right from setting up the project in VS to the "nitty-gritty" of data access?? I have a fairly major project here... We are currently working with the community addition of SiteFinity and will be purchasing the commercial version. We are completely moving in the direction SiteFinity requires us to... This mean completely converting everythign we have into modules and control that can work hand-in-hand with the CMS... After reading throught he blog and downloading the sample projects and setting these up in VS, i am wondering if modules is really the way to go for what we need done... To explain we have a MULTI-PAGE engine (search, select, review, checkout, confirmation) that i wanted to build into a module. I am not so concerned with the admin aspect of the module but more so with what the module displays on the website. We already have systems in place that handle the data displayed to the user... It is important that i can manipulate the display of the module on the website as i would a normal aspx page... (styles, html, images, controls, etc...) Is a module the way to go for this or what would you suggest? Nugs

    Leave a comment