Creating a custom control
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 >
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:
- Find the most similar existing control and class name in the Controls reference.
- Create a class that extends the existing control's class.
- Overwrite (implement) the methods that need to be customized. (The
initmethod is often the only method that needs to be implemented.)
Creating a new control
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:
- Go to Configuration >
- 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.
- Under the control content node, add a
classdata 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
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:
- Navigate to the dialog configuration.
- 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.
- Add a child data node
controlTypeand 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
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
damcontrol 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.