Sitefinity CMS
Contents
Anatomy of a Custom Control Send comments on this topic.
See Also
Developing with Sitefinity > Controls > Adding New Controls to Sitefinity > Custom Controls > Anatomy of a Custom Control

Glossary Item Box

Generally, all Web controls built for Sitefinity modules have several things in common. This topic will provide explanation on how to approach building a ControlPanel control for the Contacts module. 

 

Building a Control 

There are two cornerstone ideas when building any kind of control:

  • Template - defines the appearance of a control. How the template is created and structured should not affect the control in any way.
  • Manager Class - works with data. How the data is stored should make no difference to the control - that is managed by the provider.

Figure 1 gives an overview of how Web controls are built in Sitefinity:

Web Control Anatomy

Figure 1 

 

Working with Controls

In Figure 1, there is a Web Control (in blue) on the left which represents the ControlPanel. This control acts as a wrapper control for the actual controls of ControlPanel. The child controls are:

  • Add New Contact - when clicked ControlPanel should switch from List mode to Insert mode
  • Contacts Grid - the RadGrid that lists all the contacts
  • Contact Editor - this control is used for adding new contacts or editing existing contacts. See the screenshot in Figure 2 for demonstration: 

Contacts - All Departments 

Figure 2

 

In order to allow designer/user-experience expert to modify the look-and-feel of controls without messing with the code and constantly recompiling, controls are loaded from templates. This is where the GenericContainer comes in use - the template should always be instantiated inside a class that inherits from GenericContainer. This class allows us to define controls that are absolutely necessary for the ControlPanel to be working (required controls). It also allows us to define the controls that could be added but are not necessary (optional controls). So if a template creator forgets to add a Button control with the id of "addNewContact" an exception is thrown saying that the template is missing a required “addNewContact” button. By using GenericContainer class there is an easy way to make a contract between a programmer and a designer.

 

A template creator has two options when it comes to creating a template without coding. One is to create a user control and set its path in the web.config provider. Another way is to declaratively create template. Note that it is only possible to create a template declaratively if the ControlPanel is again declaratively added to the page or the user control. If a ControlPanel is added dynamically a template could not be created declaratively.

A third option for creating a template is a default template class which implements the ITemplate interface. Default templates should always be implemented because it is possible that the Page object is not accessible at a specific moment (Design) and this may cause the control to crash at that moment.

 

Working with Data

In order to keep the control as flexible as possible, all the work with data is done using a manager (ContactsManager) in this example. The manager itself decides which provider to use to work with data, depending on how the manager is initialized. If no provider name is passed to the manager, it will use ‘DefaultProvider’; if there is a provider name - it will use what is provided. This, for example, allows to move the data from SQL Server to XML without ever modifying the Web controls. All that must be done is to create a new Data provider and initialize the manager with the name of the new provider.

 

See Also