Sitefinity CMS

Controls Overview Send comments on this topic.
See Also
Sitefinity Building Parts > Controls > Controls Overview

Glossary Item Box

Content and functionality of Sitefinity Pages are defined through Controls. Regardless of what you want your page to do, you will ultimately have to do it with a control. Here are a few examples of how controls define the content and functionality of pages in Sitefinity:

  • Displaying some text on your page – use Generic Content control to display the text
  • Displaying  the blog posts on your page – use Blog Posts control to display the posts
  • Displaying  news on your page – use News View control to display news
  • Showing a link on your page – use HyperLink control to display a link


As explained in Pages Overview, pages in Sitefinity are only containers, while the content and functionality are added through controls.


What Kinds of Controls can be Used with Sitefinity?

Sitefinity supports five types of controls:

  1. Built-in Sitefinity controls (such as Blog Posts, Forums, News View)
  2. Standard ASP.NET controls (such as HyperLink, GridView, XmlDataSource)
  3. User Controls (such as standard ASP.NET user controls - .ascx files – which developers can upload to the Sitefinity toolbox)
  4. Custom Controls (such as compiled controls - .dll files – which developers can upload to the Sitefinity toolbox)
  5. Custom module controls (such as user or custom controls, which are registered in Sitefinity by the module to provide front-end functionality for the module)
When developing controls for Sitefinity (be they User Controls or Custom Controls), there are NO special requirements imposed by Sitefinity. It is possible to use controls created for other systems by simply uploading them to the Sitefinity toolbox.


How Do Controls Achieve Their Intended Functionality?

Controls generally have properties that should be set so that controls could function in the desired manner.

Let’s consider the Blog Posts control which displays blog posts. A user that wishes to display blog posts on a page needs a way to tell the control from which blog the posts should be displayed, how many posts should be displayed at one page, how are they going to be displayed, and so on. Controls are configured through a built-in Sitefinity property grid and/or a control designer. When a control developer builds a control, all properties that the end user should or could modify need to be declared as public properties. Sitefinity will automatically generate property grid editor that will allow the end user to modify these properties directly from the browser. In addition to this, the developer does no need to worry how these properties are going to be persisted (remembered), because Sitefinity will automatically save all the values entered by the user into a database.

Generally, controls have two modes for editing properties. One is the automatically-generated property grid (which is called Advanced mode, because it lists all public properties), and the other one is the control designer (which is called Basic mode, because control creator can create any desired user interface to allow for simple and streamlined setup of the control). Both modes are essentially providing the same funcitonality – configuring properties; still, this is done in a different manner. Let’s take a look at the two modes provided by Blog Posts control to see the difference (Figure 1):

Controls Overview

Figure 1


How to Add New Controls to Sitefinity Toolbox?

Sitefinity toolbox can be extended with additional controls needed by your project. While the theme of this topic is discussed in more details later in the manual (Uploading User Control to Toolbox), here are some basic pointers:

  • To add a new control to Sitefinity, one needs to create a User Control (.ascx) or a Custom Control (.dll) file and upload it to Sitefinity toolbox
  • Sitefinity will automatically generate a Property Grid editor for all the public properties of your controls
  • All public properties of the controls will be automatically persisted for you. For example, if you create a Link control, with public properties "Text" and "Url", whenever user changes the values of these properties, Sitefinity will persist those values to a database. You do not need to implement any persistence mechanisms.
  • Sitefinity offers base classes for control designers (control designers offer alternative way of setting controls properties, which is more user-friendly than Visual Studio-like property grid).
  • Controls added to the Sitefinity toolbox behave just as built-in Sitefinity controls, which means that users can drag-and-drop them to different areas of pages, reorder them, remove them and edit their properties directly from the browser


Controls are added to Sitefinity in Page Editor, by clicking on the Upload Control button, as shown on Figure 2: 

Control Overview - Uploading a Control

Figure 2


For more detailed instructions, see Uploading User Control to Toolbox


Managing Sitefinity Toolbox

Sitefinity toolbox can be managed through the web.config file (<telerik> ... <toolboxControls> section). By modifying that section, one can remove controls from the toolbox, rename them, reorganize them, and so on.


See Also