Channel Editor Containers

When creating web pages, a developer can configure certain regions in the web page to be editable by webmasters. These regions are called containers.

Layout defined by xtype

A container groups a number of components. The layout of these components - horizontal (row) vs. vertical (column) - depends on the 'xtype' of the container. The Channel Editor supports the following xtypes:

The default rendering orientation indicates how a container of this xtype renders its components by default. This orientation can be changed through custom CSS, but this is discouraged because the Channel Editor's UI uses the rendering orientation to control the positioning of the components.

HST configuration 

A container is defined in the HST configuration by a node of type hst:containercomponent. For example, if you want to add a vertical box of components to a page, you need to define a container component as shown below:

/main:
  jcr:primaryType: hst:containercomponent
  hst:xtype: hst.vbox

Note that all child nodes of an hst:containercomponent node must be of type hst:containeritemcomponent. HST will add such child nodes when a CMS user adds a component to the container. To add containers to a page, a developer must configure the containers of a page in the HST workspace.

Component toolbar

A developer can also configure a list of items that can be added to a container. These items will be shown in the Components tab of the Channel Editor's side-nav. Users can click on a component on that tab to select it and and then click inside any container to add the selected component to it. Each item in the tab represents an HST component. To add a component to the Components tab, add its configuration to the HST catalog.

Built-in rendering templates

When the hst:containercomponent configuration node does not specify a template explicitly (by means of the hst:template property), the built-in rendering template, derived from the container's xtype, is used to render the container. The table above describes what the built-in rendering template renders per xtype. For more detailed information, consult the actual implementation of your container xtype's built-in rendering template. For any xtype, you can override the built-in rendering template by specifying the hst:containercomponent's hst:template property, referring to your custom rendering template. In order to make your custom rendering template interact nicely with the Channel Editor's UI to add, remove, and move components, the two conditions described in the next section must be met. The built-in rendering templates ensure that these conditions are met.

For example, the HST configuration snippet below uses the built-in rendering template for xtype hst.vbox to render the contents of container main:

/hst:workspace:
  /hst:containers:
    /homepage:
      /main:
        jcr:primaryType: hst:containercomponent
        hst:xtype: hst.vbox
        /list1:
          jcr:primaryType: hst:containercomponentitem
          hst:xtype: hst.item
        /list2:
          jcr:primaryType: hst:containercomponentitem
          hst:xtype: hst.item

Using the NoMarkup xtype

The xtype hst.nomarkup is available since Hippo CMS 11.0 and comes with a built-in rendering template which inserts no HTML elements at all. It imposes some restrictions on the HTML element hierarchy rendered by your project's component templates, which may require some additional elements in your HTML. However, the advantage of hst.nomarkup over the other xtypes is that you maintain full control over the type (e.g. div, span, etc.) and attributes (e.g. class) of the elements. 

In order to make the Channel Editor's UI to add, move, and remove components work nicely with containers of this type, the following two conditions must be met:

1. The content of the HST container is rendered as the only child HTML element of the enclosing HTML element, living in the parent component's rendering template.
2. All HST container components (catalog components) that are expected to be used inside containers of this type must render their content inside a single root HTML element.

Here are a few examples visualizing above constraints. The following Freemarker snippet would be a valid rendering template for the parent component of an HST container of xtype hst.nomarkup:

[...]
<div>
  <!-- optional comment -->
  <@hst.include ref="nomarkup-container"/>
</div>
[...]

The following snippet will not work well in the Experience manager, because it doesn't fulfill condition 1:

[...]
<div>
  <@hst.include ref="nomarkup-container"/>
  <div class="additional-sibling-element-breaking-channel-manager-ui">
    [arbitrary content]
  </div>
</div>
[...]

The following snippet would be a valid rendering template for a container item component (catalog component) used inside an HST container of xtype hst.nomarkup:

[optional Freemarker tags such as #assign, #include etc]
<!-- optional comment -->
<div class="nomarkup-container-item-root">
  [arbitrary content]
</div>

The following snippet will not work well in the Experience manager, because if doesn't fulfill condition 2:

[optional Freemarker tags such as #assign, #include etc]
<div class="nomarkup-container-item-root">
  [arbitrary content]
</div>
<div class="additional-root-level-element-breaking-channel-manager-ui>
  [more arbitraty content]
</div>