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:
|
xtype |
Built-in rendering template |
Default rendering orientation |
|
hst.vbox |
Renders a <div> element with all the child components wrapped in a <div> element. |
vertical |
|
hst.unorderedlist |
Renders a <ul> element with all the child components wrapped in an <li> element. |
vertical |
|
hst.orderedlist |
Renders a <ol> element with all the child components wrapped in an <li> element. |
vertical |
|
hst.span |
Renders a <div> element with all the child components wrapped in a <span> element. |
horizontal |
|
hst.nomarkup |
Renders no markup elements, but requires the surrounding templates (i.e. the parent template of the container and all container items) to fulfill certain conditions (described below) |
vertical |
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. The Components tab is only available in the Channel Editor's Edit mode. 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:
- 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.
- 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 Channel 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 Channel 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>