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

Channel Manager

Introduction

The channel manager allows a webmaster to manage multiple channels inside the CMS. A ‘channel’ can be any HST site, like a website, mobile site, REST API, etc. Each channel is tied to one mount inside an HST host group. A mount references the channel it belongs to. Mounts without a channel are not shown in the channel manager.

//onehippo-prod.global.ssl.fastly.net/binaries/ninecolumn/content/gallery/connect/library/channel-manager/10.0/channel-manager-overview.png

The CMS shows an overview of all available channels. Each channel can be previewed inside the CMS. When the hst:cmseditlink tag is used, the preview shows a button next to each rendered document that opens the CMS editor for that document. Similarly, when the hst:cmseditmenu tag is used for a menu, a button will be shown that allows the webmaster to edit the menu. The Channel Editor can be used inside the same preview, allowing a webmaster to add components to containers inside the page.

//onehippo-prod.global.ssl.fastly.net/binaries/ninecolumn/content/gallery/connect/library/channel-manager/11.0/template-composer.png

Developers can define a channel's configuration parameters in a Java interface. These Settings can be edited in the Channel Manager. HST components can access these properties via Java interfaces.

//onehippo-prod.global.ssl.fastly.net/binaries/ninecolumn/content/gallery/connect/library/channel-manager/11.0/channel-settings.png

Besides managing existing sites, the channel manager can also create new sites from blueprints defined by developers. A webmaster only needs to click 'Add channel', select the blueprint to use, and provide a name and URL for the new channel.

Define available channels

To show an HST mount as a channel in the channel manager, you must create an hst:channel node for it that contains the name of the channel and (optionally) the channel properties and the interface name to access them.

For example, we have a channel called 'example' with the URL ' http://www.example.com'. The HST host configuration would contain the mount

/hst:hst/hst:hosts/dev-localhost/com/example/www/hst:root

To show this channel in the channel manager:

  1. Create the container node hst:channels if it does not exist yet:

    + hst:hst
        + hst:channels [hst:channels]
  2. Create the new channel node:

    + hst:hst
        + hst:channels
            + example [hst:channel]
                - hst:name = Example
  3. In the mount node, refer to the created channel node by setting the property hst:channelpath:

    + hst:hst
        + hst:hosts
            + dev-localhost
                + com
                    + example
                        + www
                            +hst:root
                                - hst:channelpath = /hst:hst/hst:channels/example
  4. Save changes

The channel manager overview will now show the channel with the name ‘Example’ with the URL ‘ http://www.example.com'.

Channel manager host group

HST allows multiple host groups (e.g. to distinguish different DTAP environments). Depending on the HST version, different mechanisms are used to determine which host group is used by the channel manager.

Channel manager CMS location

HST needs to know the URL of the CMS in order to create the right preview mounts automatically. This is specified in the property hst:cmslocation of the host group node. For example:

+ hst:hst
    + hst:hosts
        + dev-localhost
            - hst:cmslocation = http://localhost:8080/cms

Multiple CMS locations

The property hst:cmslocation can contain a comma separated list of cms locations, for example

+ hst:hst
    + hst:hosts
        + dev-localhost
            - hst:cmslocation = https://cms.example.org, https://cms.example.com

Authorization

By default, all users have read-only access to the channel manager. They can see the channel overview and preview existing channel. All users in the group 'webmaster' can also create new channels and edit existing ones. Admin users can always do everything.

For example, the following delta-XML in your hippoecm-extension.xml file adds the user 'editor' to the group 'webmaster':

<sv:node sv:name="hippogogreen-group-webmaster-includes-editor">
  <sv:property sv:name="jcr:primaryType" sv:type="Name">
    <sv:value>hippo:initializeitem</sv:value>
  </sv:property>
  <sv:property sv:name="hippo:contentroot" sv:type="String">
    <sv:value>/hippo:configuration/hippo:groups/webmaster/hipposys:members
    </sv:value>
  </sv:property>
  <sv:property sv:name="hippo:sequence" sv:type="Double">
    <sv:value>11204</sv:value>
  </sv:property>
  <sv:property sv:name="hippo:contentpropadd" sv:multiple="true"
               sv:type="String">
    <sv:value>editor</sv:value>
  </sv:property>
</sv:node>

Filtering channels

If you want channel filtering different from the default enabled filtering based on whether the cms user can read the content of the channel, you can plug in your own filters. See Channel Filtering how to achieve this.

Recommended: Disable HST configuration editor in production

In order to prevent that non-workspace HST configuration is modified by CMS users and causes conflicts with project-driven configuration, we recommend to disable the HST configuration editor on production environments. The HST configuration editor can be disabled by setting the hst.config.editor.disabled property to true:

+ hippo:configuration
  + hippo:frontend
     + cms
       + hippo-channel-manager
          + channel-manager-perspective
             - hst.config.editor.disabled = true

Alternatively, you can choose to hide the Edit Configuration column in the Channel Overview:

+ hippo:configuration
  + hippo:frontend
    + cms
      + hippo-channel-manager
        + channel-manager-perspective
          + channel-list
            - columns [remove value 'hstConfigEditor']

Recommended: Lock inherited hst configuration nodes in hst configuration editor in production

If you choose to keep the HST configuration editor enabled in production, we recommend to lock HST configuration nodes from inherited configurations. We recommend this because inherited configuration does not have a preview / live workflow, only the configuration of your currently edited channel has. This means that a webmaster might think (s)he is changing the preview of the current channel, while she may actually be changing the live configuration of the inherited channel, along with any other channel inheriting from that same channel. Since, in general, this is undesirable, the CMS locks inherited configuration by default. If, for backwards compatibility reasons, you still want inherited configuration to be editable in the HST configuration editor, you need to set hst.config.editor.lock.inherited.nodes to false.

+ hippo:configuration
  + hippo:frontend
     + cms
       + hippo-channel-manager
          + channel-manager-perspective
             - hst.config.editor.lock.inherited.nodes = false

FAQ

How do I get the 'Add Channel' button?

The 'Add Channel' button will only be shown if:

  1. There is at least one blueprint defined

  2. The user is allowed to create new channel (see the previous section on authorization)

How do I remove the ' _cmsinternal' suffix from the preview URLs in the CMS?

When you preview a channel by clicking 'preview' in the channel manager, the URL will by default end with ' _cmsinternal'. The page ' Getting rid of the _cmsinternal in the site preview links from the channel manager' explains when and how this part can be removed.

How do I remove a channel

It is possible to remove a channel from the channel manager using the CMS console. In CMS UI it is only possible to remove a channel if the channel is configured to be deletable, see Delete a Channel. To remove a channel from the channel manager, perform the following steps:

  • Log in to the console
  • In the left-hand tree, navigate to /hst:hst/hst:channels and delete the node corresponding to your channel (possibly also the -preview if present)
  • Deleting just this node only removes the channel from the channel manager; if you also want to delete the underlying site, perform the following additional steps:
    • Delete the configuration of the channel: navigate to /hst:hst/hst:configurations and delete the node corresponding to your channel  (possibly also the -preview if present)
    • Delete the links to the content of the channel: navigate to /hst:hst/hst:sites and delete the node corresponding to your channel
    • Don't forget to check your hosts config under /hst:hst/hst:hosts, a host configuration pointing to a non-existing channel can cause problems.
  • Click Write changes to repository to persist your changes

Removing the channel manager

The channel manager can be removed entirely from your project by removing the following artifacts from the pom.xml in the cms module:

<dependency>
  <groupId>org.onehippo.cms7</groupId>
  <artifactId>hippo-addon-channel-manager-frontend</artifactId>
</dependency>

<dependency>
  <groupId>org.onehippo.cms7</groupId>
  <artifactId>hippo-addon-channel-manager-repository</artifactId>
</dependency>

Since the channel manager relies on HST, it has to be removed when you want to run the CMS without HST.