Annotate Channel or Component Configuration Parameters with UI Directives

Overview

This page explains how to annotate channel or component configuration parameters with UI directives. These annotations control how configuration dialogs are rendered in the Experience manager and Channel Editor.

Purpose

Use UI annotation directives to specify how channel and component configuration parameters appear and behave in the Experience manager or Channel Editor.

Context

End users configure channels and page components using dialogs in the Experience manager and Channel Editor. These dialogs are generated from parameters defined in a ChannelInfo or ParametersInfo interface. You can annotate these interfaces and their methods to control the UI rendering.

Annotation Usage Matrix

Annotation	Component Class	ParametersInfo Interface	ParametersInfo Method	ChannelInfo Interface	ChannelInfo Method
@ParametersInfo	✓
@FieldGroupList		✓		✓
@FieldGroup		✓		✓
@Parameter			✓		✓
@DropDownList			✓		✓
@JcrPath			✓		✓

Component Class Annotations

You can use the following annotation on a delivery tier component class:

@ParametersInfo

Use @ParametersInfo to specify the interface that defines the parameters for the component.

Example:
MyComponent.java

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

Parameters Interface Annotations

Apply these annotations to a ParametersInfo interface or a ChannelInfo interface:

@FieldGroupList

Defines a list of @FieldGroup annotations. Each field group contains related configuration parameters. The order of field groups determines their order in the configuration dialog.

@FieldGroup

Specifies a group of configuration parameters for the dialog. Reference each parameter by name. The order in the list determines the display order.

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();
}

You can localize field group titles using a resource bundle. See Localization.

Parameters Interface Method Annotations

You can annotate getter methods in a ParametersInfo interface or ChannelInfo interface with the following:

@Parameter

Defines a parameter's name, optional default value, and required status.

name: The parameter name, stored in the hst:parameternames property. Must be unique per component.
required: Marks the parameter as required. The Channel Editor only saves parameters when all required fields are filled. Default: false.
displayName: The label shown in the UI for the parameter. Defaults to the name value. You can localize this label with a resource bundle.

If no additional annotation is present, the CMS UI widget type is determined by the method's return type:

Return Type	CMS UI Widget
`java.lang.String`	Text field for alphanumeric input
`short`, `int`, `long`, `java.lang.Short`, `java.lang.Integer`, `java.lang.Long`	Numeric-only text field
`boolean`, `java.lang.Boolean`	Checkbox for true/false
`java.util.Date`	Date picker

@DropDownList

Provides dropdown selection for a parameter. You can configure dropdown values in several ways:

Static value list:
Annotate a getter returning a String with a fixed set of values.

@Parameter(name = "cssDisplay", displayName = "CSS Display")
@DropDownList(value = {"inline", "block", "flex"})
String getCssDisplay();

You can localize value display names with a resource bundle.

Dynamic value list:
Use a ValueListProvider implementation to supply dropdown values.

@Parameter(name = "cssDisplay2", displayName = "CSS Display 2")
@DropDownList(valueListProvider = CssDisplayValueListProvider.class)
String getCssDisplay2();

ValueListProviderService (brXM 14.3+):
Register value list providers in the platform Spring context in the cms webapp. The configuration file must match META-INF/hst-assembly/overrides/addon/org/hippoecm/hst/platform/*.xml.

<bean id="customValueListProviders" class="org.springframework.beans.factory.config.MapFactoryBean">
  <property name="targetMapClass">
    <value>java.util.HashMap</value>
  </property>
  <property name="sourceMap">
    <map>
      <entry key="css-display-3" value="org.example.CssDisplayValueListProvider" />
    </map>
  </property>
</bean>

Reference the provider in the annotation using the map key:

@Parameter(name = "cssDisplay3", displayName = "CSS Display 3")
@DropDownList(valueListProviderKey = "css-display-3")
String getCssDisplay3();

See BannerInfo.java, DemoChannelInfo.java, CssDisplayValueListProvider.java, and testprovider.xml for implementation examples.

@JcrPath

Use @JcrPath for a getter that returns a document path as a String. The UI displays a picker for document selection. Options:

isRelative: If true, the stored path is relative to the channel's canonical content root. Default: false (absolute path).
pickerConfiguration: The root path of the CMS configuration for the picker, relative to /hippo:configuration/hippo:frontend/cms. Default: "cms-pickers/documents".
- To restrict to images, use "cms-pickers/images".
- To restrict to documents, use "cms-pickers/documents-only".
pickerRootPath: Absolute root path for the picker, or empty to use the channel content path. If set, must start with /. Default: "".
pickerInitialPath: Initial path for the picker if no selection exists, relative to pickerRootPath. Use a folder path to open in that folder, or a document handle to preselect a document. Default: "".
pickerRemembersLastVisited: If true, the picker remembers the last visited path. Default: true.
pickerSelectableNodeTypes: List of node types selectable in the picker. Default: empty (picker default behavior).

Localization

You can localize field group titles, parameter names, dropdown values, and hint texts using a resource bundle. Both repository-based and Java-based bundles are supported.

The resource bundle must match the package and name of the parameters interface.
For repository-based bundles, definitions are stored under /hippo:configuration/hippo:translations/hippo:hst/componentparameters or /hippo:configuration/hippo:translations/hippo:hst/channelparameters. Add YAML definitions to the repository-data-application module.
For Java-based bundles, include the .properties file in the CMS web application.

Example repository resource bundle YAML for org.example.components.MyComponentParamsInfo:

definitions:
  config:
    /hippo:configuration/hippo:translations/hippo:hst/componentparameters/org:
      jcr:primaryType: hipposys:resourcebundles
      /example:
        jcr:primaryType: hipposys:resourcebundles
        /components:
          jcr:primaryType: hipposys:resourcebundles
          /MyComponentParamsInfo:
            jcr:primaryType: hipposys:resourcebundles
            /en:
              jcr:primaryType: hipposys:resourcebundle
              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

Note: For dropdown values, repository resource bundles use # as the separator, while Java resource bundles use /.

If both repository and Java resource bundles are present, the repository resource bundle takes precedence.

Hint Texts

To provide additional guidance for a parameter, add a <parameter>.hint property to the resource bundle. The UI displays an information icon next to the parameter. Hovering over the icon shows the hint text.

Example repository-based resource bundle YAML:

size.hint: Select a size

Example Java-based resource bundle:

size.hint=Select a size

Note: If your project includes the Relevance Module, component configuration dialogs use the legacy pop-up style, which does not support hint texts.

Inheritance

Field groups from super interfaces are merged with those in sub-interfaces. Parameters in field groups with the same title key are combined.

You can include parameter names from super interfaces in a sub-interface's field group to reorder or regroup parameters. Each parameter appears only once; including a parameter in a sub-interface field group overrides its position.
Inherited field groups and parameters are processed breadth-first.
Resource bundles from super interfaces are available to sub-interfaces. Sub-interface bundles can override keys from super interfaces. Multiple inheritance and deeper super interfaces are supported. Bundle inheritance scanning uses breadth-first order.

Troubleshooting

These features require specific dependencies and configuration.

Ensure the hippo-plugin-selections-hst-client dependency is present in your implementation project. If missing, add it to cms-dependencies/pom.xml:

<dependency>
  <groupId>org.onehippo.cms7</groupId>
  <artifactId>hippo-plugin-selections-hst-client</artifactId>
</dependency>

Add the Selection content beans to the hst-beans-annotated-classes context parameter in your site webapp's web.xml:

<context-param>
  <param-name>hst-beans-annotated-classes</param-name>
  <param-value>classpath*:org/onehippo/forge/selection/hst/contentbean/*.class</param-value>
</context-param>

Info: For details, see Automatic Scanning for Content-Bean Annotated Classes.