Adding widgets (controls) to the toolbox
In order to use custom widgets (controls) that you develop on a Sitefinity page, you have to register them in the toolbox. Once you do this, the widgets will be available for drag and drop in the page editor user interface.
User controls vs. Custom controls
There are several ways you can register a widget. All of them require a ControlType parameter. The value of this parameter depends on the type of widget used.
- When registering a custom widget built into an assembly, the parameter is the fully qualified type name of the widget.
- When registering a user control, the parameter is the virtual URL of the user control
Register through the advanced settings
This is the easiest and most common way to register a widget.
- In the backend, navigate to Administration -> Settings -> Advanced
- In the navigation tree on the left, open Toolboxes -> Toolboxes -> PageControls -> Sections
- Choose the section where the widget will be registered. Sections are the collapsible groups that appear in the toolbox UI. You can create a new one, or use an existing section.
- To create a new section, make sure that the “Sections” node is selected in the tree. Then click the “Create New” button. Give the section a Name, Title and Description, and save it. Then select the newly created section in the tree.
- To use an existing section, flick on it in the tree, and then click the “Tools” child node.
- Once you’ve selected a section, click the Create New button to register a new widget in it.
- For the value of “Control CLR type or virtual path”, enter the full type name (in case of custom controls) or a virtual path (in case of user controls). See the beginning of this article for the differences between the two.
- For Name, enter a developer name for the widget. This can be used to access it using the API later.
- For Title, supply the title which will appear in the toolbox user interface.
- The rest of the values are optional. Description appears as a tooltip in the user interface.
Register manually through the configuration file
When you use the advanced settings backend user interface, the values are persisted in configuration. By default, these are stored as physical files in the ~/App_Data/Sitefinity/Configuration folder of your web project. Instead of using the UI, you can manually edit the files there to register widgets. The toolbox configurations have their own separate file, called ToolboxesConfig.config.
- To register a new widget, open the ToolboxesConfig.config file.
- Find the section you want to use, or create a new section under the <sections> element.
- If you are working with a custom widget, register it with the following snippet:
<add enabled="True" type="~/MyControls/MyUserControl.ascx" title="My User Control" visibilityMode="None" name="MyUserControl" />
- If you are working with a user control, register it with the following snippet:
<add enabled="True" type="MyAssembly.MyNamespace.MyCustomWidget, MyAssembly" title="My custom widget" description="A sample custom control" name="MyCustomControl" visibilityMode="None" />
- Save the file and restart the application.
Register using Sitefinity Thunder
If you are using Sitefinity Thunder with your project, you can register widgets from there. For more information please read the following article: http://www.sitefinity.com/documentation/documentationarticles/registering-a-widget
Register through code using the Configuration API
Sometimes, people want to register their custom widgets in the toolbox through the API. A case where this is needed is when the widget is part of a custom module and should be registered when the module is installed. You can use the Sitefinity configuration API to register a widget. This is done with the following code:
var configManager = ConfigManager.GetManager();
var config = configManager.GetSection<ToolboxesConfig>();
var controls = config.Toolboxes["PageControls"];
var sectionName = "MySection";
var section = controls.Sections.Where<ToolboxSection>(e => e.Name == sectionName).FirstOrDefault();
if (section == null)
{
section = new ToolboxSection(controls.Sections)
{
Name = sectionName,
Title = sectionName,
Description = sectionName,
ResourceClassId = typeof(PageResources).Name
};
controls.Sections.Add(section);
}
var controlName = "MyControl";
var controlType = typeof(MyControl);
if (!section.Tools.Any<ToolboxItem>(e => e.Name == controlName))
{
var tool = new ToolboxItem(section.Tools)
{
Name = controlName,
Title = controlName,
Description = controlName,
ControlType = controlType.AssemblyQualifiedName
};
section.Tools.Add(tool);
}
configManager.SaveSection(config);
In the above snippet, you should change the name of the section, the name of the control and the type of the control to reflect your custom control values.