Define a Channel’s Configuration Parameters

Overview

This page describes how to define configuration parameters for a delivery channel. These parameters allow the Experience manager UI to display a configuration dialog for the channel.

When to Use

Use channel configuration parameters to expose small, configurable aspects of a channel—such as a logo or color—to end users through the Experience manager UI.

Prerequisites

• Access to the project’s source code and repository configuration.
• Familiarity with Java interfaces and annotations.
• Understanding of the channel configuration node structure.

Implementation Steps

1. Define a ChannelInfo Interface

Create a Java interface that extends org.hippoecm.hst.configuration.channel.ChannelInfo. For each configuration parameter, define a getter method.

Annotate each getter with @org.hippoecm.hst.core.parameters.Parameter, specifying at least the name attribute. You can add further annotations to control the Experience manager UI, such as widget type or grouping.

For details on available annotations and localization, see Annotate Channel or Component Configuration Parameters with UI Directives.

Place the interface in the site/components module.

Example:

site/components/src/main/java/org/example/channels/WebsiteInfo.java

package org.example.channels;

import org.hippoecm.hst.configuration.channel.ChannelInfo;
import org.hippoecm.hst.core.parameters.DropDownList;
import org.hippoecm.hst.core.parameters.FieldGroup;
import org.hippoecm.hst.core.parameters.FieldGroupList;
import org.hippoecm.hst.core.parameters.JcrPath;
import org.hippoecm.hst.core.parameters.Parameter;

@FieldGroupList({
  @FieldGroup(
    titleKey = "fields.channel",
    value = {"logo", "pageTitlePrefix", "themeCss", "color"}
  )
})
public interface WebsiteInfo extends ChannelInfo {
  @Parameter(name = "logo")
  @JcrPath(
    pickerSelectableNodeTypes = {"hippogallery:imageset"},
    pickerInitialPath = "/content/gallery/logos"
  )
  String getLogoPath();

  @Parameter(name = "pageTitlePrefix", defaultValue = "My Hippo Project")
  String getPageTitlePrefix();

  @Parameter(name = "themeCss",
             defaultValue = "/content/assets/themes/css/green.css")
  @JcrPath(
    pickerConfiguration = "cms-pickers/assets",
    pickerSelectableNodeTypes = {"hippogallery:exampleAssetSet"},
    pickerInitialPath = "/content/assets/themes/css"
  )
  String getThemeCss();

  @Parameter(name = "color", defaultValue = "blue")
  @DropDownList({"red", "green", "blue"})
  String getColor();
}
copy

2. Link the Interface to the Channel

Set the hst:channelinfoclass property on the channel’s configuration node to the fully qualified name of your interface.

Example:

/hst:myproject/hst:configurations/myproject/hst:workspace/hst:channel:
  hst:channelinfoclass: org.example.channels.WebsiteInfo
copy

After this configuration, end users can edit channel parameters in the Experience manager. The parameter values are stored as properties of an hst:channelinfo child node under the channel’s configuration node:

/hst:myproject/hst:configurations/myproject/hst:workspace/hst:channel:
  /hst:channelinfo:
    logo: /content/gallery/logos/hippologo.png
    pageTitlePrefix: My Hippo Project
    themeCss: /content/assets/themes/css/green.css
    color: blue
copy

Note:
The hst:channel node can be a sibling of the hst:workspace node instead of a child. If configured as a sibling, channel configuration parameters are read-only.

3. Access Channel Parameters in a Component Class

The delivery tier provides a proxy implementation of your ChannelInfo interface, allowing you to access configuration parameters with type safety. Retrieve the proxy from a component class using org.hippoecm.hst.configuration.hosting.Mount.getChannelInfo().

Example:

site/components/src/main/java/org/example/components/MyComponent.java

public class MyComponent extends BaseHstComponent { 

  public void doBeforeRender(HstRequest request, HstResponse response) {
    super.doBeforeRender(request, response);

    Mount mount = request.getRequestContext().getResolvedMount().getMount();
    WebsiteInfo info = mount.getChannelInfo();
    String logoPath = info.getLogoPath();
    Object logo = getObjectBeanManager(request).getObject(logoPath);

    request.setAttribute("logo", logo);
  }
}
copy

Multiple ChannelInfo Mixins

brXM 12.5+ supports multiple ChannelInfo interfaces (mixins) for a single channel. This allows you to separate configuration groups into different interfaces.

• Set hst:channelinfoclass to the primary interface.
• Set hst:channelinfomixins (multi-valued String) to additional mixin interface names.
• The proxy instance implements all specified interfaces, and you can cast as needed in Java code.

Example: ChannelInfo Mixin Interface

Define and package the mixin interface in the site/components module.

site/components/src/main/java/org/example/channels/AnalyticsChannelInfo.java

@FieldGroupList({
    @FieldGroup(
        titleKey = "analyticsChannel",
        value = { "analyticsEnabled", "analyticsScriptlet" }
    )
})
public interface AnalyticsChannelInfo extends ChannelInfo {

    @Parameter(name = "analyticsEnabled")
    Boolean isAnalyticsEnabled();

    @Parameter(name = "analyticsScriptlet")
    String getAnalyticsScriptlet();

}
copy

Example: Channel Configuration with Mixins

Configure both the main and mixin interfaces in the channel node:

/hst:myproject/hst:configurations/myproject/hst:workspace/hst:channel:
  hst:channelinfoclass: org.example.channels.WebsiteInfo
  hst:channelinfomixins: [org.example.channels.AnalyticsChannelInfo]
copy

Example: Channel Parameters with Mixins

The channel configuration can now include parameters from both interfaces:

/hst:myproject/configurations/myproject/hst:workspace/hst:channel:
  /hst:channelinfo:
    logo: /content/gallery/logos/hippologo.png
    pageTitlePrefix: My Hippo Project
    themeCss: /content/assets/themes/css/green.css
    color: blue
    analyticsEnabled: false
    analyticsScriptlet: ''
copy

Example: Accessing Mixin Parameters in Java

The proxy instance implements all configured ChannelInfo interfaces. Cast the proxy to the appropriate interface as needed.

site/components/src/main/java/org/example/components/MyComponent.java

public class MyComponent extends BaseHstComponent { 

  public void doBeforeRender(HstRequest request, HstResponse response) {
    super.doBeforeRender(request, response);

    Mount mount = request.getRequestContext().getResolvedMount().getMount();

    // The proxy implements all ChannelInfo interfaces.
    WebsiteInfo info = mount.getChannelInfo();

    String logoPath = info.getLogoPath();
    Object logo = getObjectBeanManager(request).getObject(logoPath);
    request.setAttribute("logo", logo); 

    // Cast to the mixin ChannelInfo interface.
    AnalyticsChannelInfo analyticsInfo = (AnalyticsChannelInfo) info;
    Boolean analyticsEnabled = analyticsInfo.isAnalyticsEnabled();
    String analyticsScriptlet = analyticsInfo.getAnalyticsScriptlet();

    if (analyticsEnabled != null && analyticsEnabled.booleanValue()) {
        request.setAttribute("analyticsScriptlet", analyticsScriptlet);
    }
  }
}
copy

Constraints of ChannelInfo Mixins

• If a mixin interface defines a method with the same signature as the primary or another mixin interface, the method from the primary interface (or the first in the mixin list) takes precedence. Mixins cannot override methods of previously loaded interfaces.
• If a mixin defines a method with the same name but a different return type, accessing the proxy will throw a java.lang.IllegalArgumentException. Java dynamic proxies require method signatures to match across interfaces.

Related Topics

• Annotate Channel or Component Configuration Parameters with UI Directives
• Channel Configuration Model
• Component Class Development