You can extend Sitefinity control toolbox with both User Controls (.ascx files) and Custom Controls (compiled .dll
files). This topic explains how to add a control to a Sitefinity project.
 |
All the samples in this topic use User Controls, but essentially there is no difference between the implementation
regardless if you are using User Controls or Custom Controls. |
There are no special requirements for controls to become Sitefinity controls, which means that you can use the controls you have already developed for some other .NET system
directly in Sitefinity with no modifications.
To add a control to Sitefinity toolbox one has two choices: controls can be added through GUI in the page editor or you can add them manually through the web.config file. To
manage controls in the Sitefinity toolbox (rename them, regroup them or remove them) you can simply open web.config file and modify the toolboxControls collection.
Adding New Controls Through Page Editor
In order to upload a control through Sitefinity you need to open a page for editing. Once you have done that, you will see the "Upload a control" button on the right side in
the toolbox.
Figure 1: Uploading control through page editor
When you click on the “Upload a control” button a dialog for adding control will appear.
Figure 2: Upload control dialog
The dialog gives you two options: to upload a User Control (.ascx file) or Custom Control (compiled .dll file). If you decide to upload a user
control you will need to provide some information about control such as the name of control, to which toolbox group should the control belong (for example, if you type
“Blogs” the control will be in the same group as Blog Posts control, or you can type the name of a group that doesn’t exist and Sitefinity will create a new group for your
control). Once you have filled in that information, Sitefinity asks you to choose the files of the controls - both .ascx and code-behind (if it exists).
Finally, you should click on the "Upload" button and your control is ready for use. If there are no other controls that you wish to upload you can click on the "I’m done"
button.
For Custom Controls you do not need to provide Sitefinity with as many information, but rather only select the control’s .dll file you would like to upload.
The reason for this is that Custom Controls can define all these properties through class attributes directly in the code, so you do not need to retype them once again when you
are uploading the control.
Once all the controls are uploaded, as shown in Figure 3 for the seven samples of Links List control, these controls will appear in the toolbox and be ready to be used on the
pages.
Figure 3: New controls in the toolbox
Since the group name of all the controls was set to be Links List, they are all grouped under the same group.
Managing Controls Through web.config
Sitefinity also offers the way for you to manage controls through the configuration file. To do so you need to open the web.config file of Sitefinity web site and locate the
cms/toolboxControls section.
Figure 4: toolboxControls collection in the web.config file
To add a new control we can simply add the new element to the toolboxControls collection. We provide the name, the section (in GUI it is called group) and URL of the
control if it is a User Control, while you will need to specify the type of the control if it is a Custom Control.
In web.config you can simply change the name of the control, by modifying the value of the name attribute or change the group/section of the control by modifying the value of the
section attribute. Finally, if you wish to remove the control from the toolbox all you have to do is to delete the item from the toolboxControls collection.