If you need a control that is not provided in the default controls you can create a custom control. Recommended practice is to find an existing control that is a close match to what you need and then to extend it.

• Extending a default control
• Creating a new control
• Registering the control
• Adding the control to a dialog
• Examples of custom controls

Extending a default control

Extending a control means using an existing control as a basis for the new control. The AdminInterface and Standard Templating Kit modules provide several controls that you can extend. These default controls are registered in Configuration > /modules/<module name>/controls.

Each control is implemented by a Java class. The classes are subclasses of DialogControlImpl which implements the DialogControl interface. You can customize a control by extending such a subclass. Once the extended class has been created, register it.

To extend a control:

1. Find the most similar existing control and class name in the Controls reference.
2. Create a class that extends the existing control's class.
3. Overwrite (implement) the methods that need to be customized. (The init method is often the only method that needs to be implemented.)

Creating a new control

Alternatively, you can create a completely new control without using an existing control. Create a class that extends the DialogControlImpl class or that implements the DialogControl interface.

Registering the control

Registering the control means adding it to Magnolia CMS configuration. This gives the control a name that you can use to refer to the control later. It saves you from needing to remember the control's fully-qualified class name each time you need to use it in a dialog.

To register the control:

1. Go to Configuration > /modules/<module name>/controls.
2. Add a content node for the new control and set its value to the control name. Make the name easy to remember; you will need to refer to it later.
3. Under the control content node, add a class data node and set the value to the fully-qualified class name of the control.

Best practice is to register custom controls in your own module. However, you can register them in any existing module. See /modules/adminInterface/controls for examples. Name the control so you can remember it later, such as spreadsheet.

Adding the control to a dialog

Adding the control to a dialog makes it available to users.

To add the new control to a dialog:

1. Navigate to the dialog configuration.
2. Under a tab, create a new content node and name it after the custom control. Any data that users enter in the control is saved in a property of the same name.
3. Add a child data node controlType and set its value to the control name. This is the name the control is registered with. If you did not register the control, set the value to the fully-qualified class name.

Here is an example from the Forum module. The first control on tabThread is called title. Its type is edit which is a basic text box control registered in /modules/adminInterface/controls/edit.

Examples of custom controls

• Query Select is a select (dropdown) control whose options come from configuration nodes anywhere in the system, for example from the Data module.
• DialogInclude renders a JSP page in the dialog. The JSP can in turn provide a completely custom control, in this example a color picker.
• Openmind Controls module provides a grid with common spreadsheet functionality and a multilanguage dialog tab with a language selector on top.
• Blossom TabBuilder allows you to add custom controls to the Blossom module.
• Custom DAM control shows how to modify the default dam control to pick images from Flickr. DAM stands for Digital asset management. It provides the functionality to browse to images and videos and use them on the website.

To customize a DAM control:

1. Create an implementation of Asset (found in Standard Templating Kit module).
2. Create a handler extending AbstractHandler.
3. Add the handler to Configuration > /modules/standard-templating-kit/config/damSupport/handlers.