Annotate Channel or Component Configuration Parameters with UI Directives

Introduction

Goal

Annotate channel or component configuration parameters with UI directives for the Channel Manager or Channel Editor.

Background

End users can configure channels and page components through configuration dialogs in the Channel Manager and Channel Editor, respectively. These configuration dialogs are rendered based on the parameters defined in a ChannelInfo or ParametersInfo interface. These interfaces and their methods can be annotated with specific UI directives to enable the Channel Manager or Channel Editor to render the configuration dialog as intended.

Component Class Annotations

The following annotations can be used on a delivery tier component class. 

@ParametersInfo

Specifies the interface that defines the parameters of the annotated component. For example:

MyComponent.java 

@ParametersInfo(type = MyComponentParamsInfo.class)
public class MyComponent extends BaseHstComponent {
   ...
}

Parameters Interface Annotations

The following annotations can be used on a ParametersInfo interface that defines the parameters of a component as well as on a ChannelInfo interface that defines the configuration parameters of a channel.

@FieldGroupList

Specifies a list of @FieldGroup annotations that together contain all configuration parameters. The order of the field groups determines the order in which they are rendered in the configuration dialog.

@FieldGroup

Specifies a list of configuration parameters to render in the configuration dialog. Each parameter is referenced by its name. The order of the names determines the order in which the parameters are rendered in the configuration dialog. For example:

MyComponentParamsInfo.java 

@FieldGroupList({
    @FieldGroup(titleKey = "address", value = { "street", "city" }),
    @FieldGroup(titleKey = "layout", value = { "size" })
})
public interface MyComponentParamsInfo {

    @Parameter(name = "street")
    String getStreet();

    @Parameter(name = "city")
    String getCity();

    @Parameter(name = "size", defaultValue="medium")
    @DropDownList({"small", "medium", "large"})
    String getSize();
}

The title of a field group can be localized using a resource bundle.

Parameters Interface Method Annotations

Component Parameters and Channel Parameters

The following annotations can be used for getter methods of a ParametersInfo interface that defines the parameters of a component or a ChannelInfo interface that defines the configuration parameters of a channel.

@Parameter

Specifies the name of the parameter, an optional default value, and whether it's required or not. Options:

• name

  The name of the parameter that will be stored in the hst:parameternames property. Must be unique per component.

• required

  Whether this parameter is required or not. The Channel Editor only saves a component's parameters when all required parameters have been filled in. Default: false.

• displayName

  The string displayed to the user as the label for the parameter field in the component's properties panel in the Channel Editor. Default: the same value as name. Alternatively, resource bundles can be used to localize the label.

If no other annotations are used, the widget in the CMS UI to edit the parameter depends on the return type of the annotated method:

Method Return Type	CMS UI Widget
java.lang.String	Text field that accepts an alpha-numeric value for the parameter
short, int, long, java.lang.Short, java.lang.Integer, java.lang.Long	Text field that accepts only numeric values
boolean, java.lang.Boolean	Checkbox that sets 'true' or 'false' in the parameter value
java.util.Date	Date picker widget

@DropDownList

Used for a getter that returns a String value from a fixed set of values. The display name of each value can be localized using a resource bundle.

@JcrPath

Used for a getter that returns a path to a document as String value. The path can be set by picking a document. The path can be either absolute or relative, depending on the isRelative option. The CMS UI will display the name or the last path element of the document, and a button that opens a document picker. Options:

• isRelative

  Whether the stored path is relative to the canonical content root path of the channel in which this annotation is used. The default is 'false', i.e. the stored path is absolute.

• pickerConfiguration

  The root path of the CMS configuration to use for the picker, relative to /hippo:configuration/hippo:frontend/cms. Default value: "cms-pickers/documents".

  To pick only images, use the value "cms-pickers/images".
  To pick only documents, use the value "cms-pickers/documents-only".
• pickerInitialPath

  The initial path to use in the picker if nothing has been selected yet. Use the path to a folder to initially open the picker in that folder. Use the path to the handle of a document to preselect that document. Use an empty string to use the default initial path of the picker. Default value: "" (empty string).

• pickerRemembersLastVisited

  Whether the picker remembers the last visited path. Default: true.

• pickerSelectableNodeTypes

  Types of nodes to be able to select in the picker. Default: empty list, resulting in the default behavior of the picker.

Component Parameters Only

The following two annotations can only be used for getter methods of a ParametersInfo interface that defines the parameters of a component. They can not be used in a ChannelInfo interface that defines the configuration parameters of a channel.

@Color

Used for a getter that returns a hexadecimal color value as a String. The CMS UI will display a color picker with a text field that allows you to either pick a color from the color picker or to type in a hex color value.

@DocumentLink

Used for a getter method that returns the path to a document as a String value. The CMS UI will display a dropdown widget with the list of documents of the type specified using the docType parameter. When the allowCreation parameter is set, the user can also create a document of the type specified by docType. Options:

• docType

  The primary node type of the document, used in displaying the dropdown widget with the list of documents.

• allowCreation

  When set to true, the document dropdown widget will also display a link to create a new document from the Channel Editor.

• docLocation

  When allowCreation is set to true, the Channel Editor will use the path specified in this parameter as the location of the document to be created. The path is relative to the channel's content root. For example, if you set docLocation to common/textpages, and the channel's content root is /content/documents/yourchannel, the document will be created under /content/documents/yourchannel/common/textpages. The name of the document will be provided by the user via a prompt window.

Localization

Field group titles, parameter names, parameter values (for parameters annotated with @DropDownList), and help texts can be localized using a resource bundle (either repository-based or Java-based).

The resource bundle must have the same package and name as the parameters interface.

In the case of a repository-based resource bundle, the bundle is loaded from either /hippo:configuration/hippo:translations/hippo:hst/componentparameters or /hippo:configuration/hippo:translations/hippo:hst/channelparameters and a corresponding JSON file should be added to the bootstrap-configuration module, which gets packaged with the cms web application.

In the case of a Java-based resource bundle, the bundle should be packaged with the site web application.

Example repository resource bundle JSON:

{
  "hippo:hst": {
    "componentparameters": {
      "org": {
        "example": {
          "components": {
            "MyComponentParamsInfo": {
              "en": {
                "address": "Address Information",
                "street": "Street",
                "city": "City",
                "layout": "Layout Settings",
                "size": "Size",
                "size#small": "Small",
                "size#medium": "Medium",
                "size#large": "Large"
              }
            }
          }
        }
      }
    }
  }
}

Example Java-based resource bundle (.properties file):

address=Address Information
street=Street
city=City
layout=Layout Settings
size=Size
size/small=Small
size/medium=Medium
size/large=Large

Channel Parameter Help Texts

To help users understand the purpose of a channel configuration parameter, include a property <parameter>.help in the resource bundle. When such a property is present, a small 'information' icon will be rendered next to the parameter in the channel configuration dialog. Hovering over the icon will show the help text.

Example of repository-based resource bundle JSON:

"size.help" : "Select a size"

Example Java-based resource bundle properties:

size.help=Select a size

Inheritance

Field groups of super interfaces are merged with the field groups of the sub interface. Parameters of field groups with the same title key are merged into one group.

A field group can include parameter names from super interfaces, and thereby re-order and re-group these parameters at will. Each parameter is only included once, so including a parameter from a super interface in the field group of a sub-interface will 'override' its position. Inherited field groups and parameters are scanned breadth-first.

If a super interface has resource bundles, they will also work for the sub interface. The resource bundles for the sub interface can override the super interface bundles by redefining the i18n key. Note that multiple inheritance and super interfaces of super interfaces also correctly inherit i18n resource bundles. For the bundle inheritance scanning of super interface, a breadth first super interface bundle scanning is done.