Additional Channel Information - BloomReach Experience - Open Source CMS

This article covers a Hippo CMS version 10. There's an updated version available that covers our most recent release.

12-05-2015

Additional Channel Information

Additional Channel Information

It is possible to manage additional channel information by providing a 'ChannelInfo' interface. Such an interface should be packaged with the HST application that is used to render the channel (a channel can only be associated with one application). There is no implementation class of the interface needed, because the HST will return a proxy instance of it, providing strong typed access to the properties that are stored under the node

/hst:hst/hst:channels/<channel-id>/hst:channelinfo

The fully qualified name of the interface to use for a channel is configured at

/hst:hst/hst:channels/<channel-id>
- hst:channelinfoclass (string)

An example ChannelInfo interface is:

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

  @Parameter(name = "pageTitlePrefix", defaultValue = "Hippo Go Green")
  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();
}

Each ChannelInfo interface must extend the org.hippoecm.hst.configuration.channel.ChannelInfo interface. The example interface above defines four channel properties: logo, pageTitlePrefix, themeCss, and color. It should be accompanied by a resource bundle in the same package that contains the translations to use in the CMS UI. For example, the English translations would be located in a file WebsiteInfo.properties:

fields.channel=Channel properties
logo=Logo
logo.help=The logo of the site
pageTitlePrefix=Page Title Prefix
pageTitlePrefix.help=The prefix of the HTML title of each page
themeCss=Theme
themeCss.help=The CSS file with the theme to use on each page
color=Color
color.help=The color of the top navigation bar
color/red=Red
color/green=Green
color/blue=Blue

To help users understand the purpose of a parameter, include a property <parameter>.help in the resource bundle. When such a property is present, a little 'information' icon will be rendered after the parameter in the Channel Settings window in the template composer. Hovering over the icon will show the help text. In the example above, the  themeCss parameter will show a tooltip specified in   themeCss.help.

Limitations

Only channel properties of type String and boolean are supported.

Annotations

Each getter in the ChannelInfo interface of a channel specifies a 'channel property'. All getters must have an @Parameter annotation that defines the name of the parameter and (possibly) its default value. Other annotations define the CMS UI to edit parameters. The parameters can split into 'field groups' that each have their own title in the CMS UI. Each field group lists its parameters vertically. The return type of a getter defines the widget used to edit a channel property. Boolean properties will get a checkbox; other types will get a text field. Additional annotations can be used to specify more complex widgets.

@org.hippoecm.hst.core.parameters.Parameter

The name of the parameter must be unique within the interface. It is used in several places:

  • in the @FieldGroup annotations of the ChannelInfo interface (see below)

  • in the .properties file of the ChannelInfo interface that provides translations for the CMS UI

  • for persistance (as a JCR property name)

  • in the CMS channel list configuration

The defaultValue specifies the initial value of the property when it has not yet been set in the CMS.

The 'required' keyword of the  @Parameter annotation does not have any effect in the channel properties window in the template composer. It is only effective for component parameters.

@org.hippoecm.hst.core.parameters.FieldGroupList

Specifies a list of @FieldGroup annotations that together contain all the channel properties.

@org.hippoecm.hst.core.parameters.FieldGroup

Specifies a list of channel properties to render in the 'Channel Settings' box. Each group may have a title.

@org.hippoecm.hst.core.parameters.JcrPath

Used for a channel property of type String that contain an absolute JCR path. The CMS will render a picker to select a JCR node. The absolute path of the picked node is stored in the channel property. It is possible to specifiy the picker to use, the node types to be able to select, the initial path to use in the picker, and whether the picker should remembers to last visited node. See the javadocs for more details.

@org.hippoecm.hst.core.parameters.DropDownList

Used for a channel property of type String that contains one of the values in a hardcoded list of strings. The CMS will render a dropdown box with the translated value of each option. The key of a translated dropdown value is <name of the parameter> / <value>.

Add information to the channel overview

The channel overview in the CMS can show custom channel properties in additional columns. The names of the properties that are shown initially are stored in the repository at

+ hippo:configuration
  + hippo:frontend
    + cms
      + hippo-channel-manager
        + channel-manager-perspective
          + channel-list
            - columns (string) multiple

The default columns shown are the 'name', 'url', and 'locale' of a channel, which all map to getters of the class ' org.hippoecm.hst.configuration.channel.Channel'.

To also show custom channel properties (for example ' pageTitlePrefix' and ' themeCss'), use an XML import like:

<sv:node sv:name="channel-list" xmlns:sv="http://www.jcp.org/jcr/sv/1.0"
    xmlns:h="http://www.onehippo.org/jcr/xmlimport" h:merge="combine">
  <sv:property sv:name="columns" sv:type="String"
               sv:multiple="true" h:merge="append">
    <sv:value>pageTitlePrefix</sv:value>
    <sv:value>themeCss</sv:value>
  </sv:property>
</sv:node>

configured in the hippoecm-extension.xml as

<sv:node sv:name="gogreen-channelmanager-channel-list">
  <sv:property sv:name="jcr:primaryType" sv:type="Name">
    <sv:value>hippo:initializeitem</sv:value>
  </sv:property>
  <sv:property sv:name="hippo:contentresource" sv:type="String">
    <sv:value>hippo-configuration/channelmanager-channel-list.xml</sv:value>
  </sv:property>
  <sv:property sv:name="hippo:contentroot" sv:type="String">
    <sv:value>
          /hippo:configuration/hippo:frontend/cms/hippo-channel-manager
               /channel-manager-perspective</sv:value>
  </sv:property>
  <sv:property sv:name="hippo:sequence" sv:type="Double">
    <sv:value>31000.0</sv:value>
  </sv:property>
</sv:node>

Access channel information in an HST component

The Hippo Site Toolkit will implement the ChannelInfo interface of a channel using a proxy, transparently making the properties available. The properties can then be accessed in the HST component as:

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);
}
Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?