For developers: Components of a widget

The primary component of the widget is the control itself. It represents the frontend functionality that the end-user interacts with on the website.

It is defined either as a standard user control (.ascx) and its associated code-behind file (.cs) or a custom control (.dll) and its associated template file (.ascx).

Widgets are generally made up of different HTML elements and ASP.NET controls, such as textboxes and buttons, and can use more complex controls, such as Telerik RadControls. 

All the backend functionality that the user uses to set the widget properties is called control (widget) designer. The default Sitefinity CMS widget designer displays all public properties of the widget as input fields.

A control designer has the following elements:

Control designer class

This is the class file that defines the control designer and is used to wire-up all of the designer elements. It must inherit from the ControlDesignerBase class.

Control designer template

The template is an .ascx file that represents the actual editor that is displayed to the user. It is made up of standard HTML elements that are mapped to the properties of the widget.

Control designer JavaScript file

Control designers use JavaScript to pass information from the widget to the editor template and to persist the changes from the editor template back to the widget. 

For the script file to function properly, perform the following:

1. Register the namespace of your widget
   This way, it can be referenced using JavaScript
2. Initialize a client-side instance of the designer.
3. Define the events that need to be handled by the designer and the actions to be taken at each event.
   This way, you define the relevant client-side events that load and persist the widget properties between the designer template and the widget itself.
   The most important events to define are the following:
   • initialize: default initializer; 
     You use this event when you need to setup variables or other controls on page load, such as loading external libraries or setting up global variables.
   • dispose: default destructor;
     You use this event when you need to dispose items or call a function on close.
   • refreshUI
     You use this event when you load the properties from the widget and map them to the HTML template, so they can be edited.
   • applyChanges
     You use this event when to save the changes in the template, mapping the values back to the widget.
4. Register the client-side class, so it can be used by the designer template.