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 application.

Example:

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

@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 (/hst:hst/hst:channels/<channel-id>) to the fully qualified name of the interface.

Example:

/hst:hst/hst:channels/myhippoproject
  - 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:hst/hst:channels/myhippoproject
  + 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/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);
  }
}