Define a Channel’s Configuration Parameters

Introduction

Goal

Define a delivery channel’s configuration parameters in order to enable the Channel Manager UI to render the channel’s configuration dialog.

Background

A delivery channel can be configured through parameters stored in the channel's configuration node in the repository. A typical application of these parameters is to enable end users to configure small visual aspects of a channel, such as a logo or a color.

As a developer, you can define these parameters in an interface to enable the Channel Manager UI to render the channel’s configuration dialog. In addition, the interface provides strongly typed access to the configured parameters from within component classes, which increases the robustness and readability of component code.

Instructions

Define a ChannelInfo Interface

Define an interface which extends org.hippoecm.hst.configuration.channel.ChannelInfo.

Within the interface, define a getter method for each configuration parameter.

Annotate each getter method with @org.hippoecm.hst.core.parameters.Parameter and specify at least the name attribute.

Optionally, annotate the parameter getter methods with directives to control which widgets are rendered by the Channel Manager UI to edit the parameters.

Optionally, annotate the interface with grouping directives to control the order in which the Channel Manager UI renders the widgets.

Package the interface with 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();
}

Couple the Interface to the Channel

Couple the interface to the channel by setting the value of the hst:channelinfoclass property of the channel's configuration node to the fully qualified name of the interface.

Example:

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

The channel configuration parameters can now be modified by end users in the Channel Manager. The values are stored as properties of an hst:channelinfo child node of 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

Access a Channel's Configuration Parameters from within a Component Class

The delivery tier will implement the ChannelInfo interface using a proxy, transparently providing strongly typed access to the configuration parameters. The proxied instance can be accessed from within a component class through 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);
  }
}

Multiple ChannelInfo Mixins Support

In Bloomreach Experience Manager 12.5 and newer, you can configure other ChannelInfo interface(s) as mixin(s) for the same channel. In the previous sections, you could set WebsiteInfo interface name to the hst:channelinfoclass property and use it in Java code to read channel parameters. Now suppose you want to separate some channel configuration group(s) into a different ChannelInfo interface(s), without having to mix everything into single big ChannelInfo interface. In that case, you can set the hst:channelinfomixins property (type of String and multiple) to mixin ChannelInfo interface names, and use any of those in Java code to read different groups of channel parameters.

Example ChannelInfo Mixin Interface

Package the interface with the site/components module.

Example:

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

}

Channel Configuration with Mixins

Configure the hst:channelinfomixins property next to the hst:channelinfoclass property with the new ChannelInfo mixin interface name.

Example:

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

Channel Parameters

Now the channel configuration may include two more parameters for the mixin:

/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: ''

Example Java Code

The delivery tier will implement all the ChannelInfo interfaces including new mixin type(s) through a proxy instance. The proxy instance can be accessed from within a component class by any of the ChannelInfo interfaces.

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

    // Or you can do first: AnalyticsChannelInfo info = mount.getChannelInfo();
    // The returned proxy implement every ChannelInfo interface anyway.
    WebsiteInfo info = mount.getChannelInfo();

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

    // You can cast the proxy instance to another mixin ChannelInfo interface.
    AnalyticsChannelInfo analyticsInfo = (AnalyticsChannelInfo) info;
    Boolean analyticsEnabled = analyticsInfo.isAnalyticsEnabled();
    String analyticsScriptlet = analyticsInfo.getAnalyticsScriptlet();

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

Constraints of ChannelInfo Mixin

• If a ChannelInfo Mixin defines the same method as that of the preloaded ChannelInfo interface which is either configured by the hst:channelinfoclass property or another ChannelInfo mixin configured in the hst:channelinfomixins property, then the operation is never used. In other words, the same operation by a ChannelInfo mixin interface cannot override the same method of preloaded ChannelInfo interfaces. The loading order is from the hst:channelinfoclass property to each ordered item in the hst:channelinfomixins property.
• If a ChannelInfo Mixin defines the same method but with a different return type, a java.lang.IllegalArgumentException will be thrown when accessing a ChannelInfo instance. Java does not allow dynamic proxy creation with multiple interfaces that do not share the same method signatures.