HST Configuration Model Introduction

When developing websites with Bloomreach Experience Manager's delivery tier (a.k.a. "HST") it helps a lot to understand the backing configuration model. For a first acquaintance with the model without the need to understand it, you are encouraged to follow the Build a Website tutorial.

Developing a website with the HST in general can be decomposed into four main categories:

1. Content stored in the Hippo Repository / HST Content Beans ( Model)
2. Java classes for HST Components ( Controller)
3. Rendering templates like JSP or Freemarker ( View)
4. HST configuration model: configuration (stored in Hippo Repository) for the  Hierarchical MVC glue of points 1, 2 and 3 above and the configuration for the request matching part of the HST framework.

The default web page request processing of the HST is implemented according to the Hierarchical-Model-View-Controller pattern. The request matching of the framework is implemented similar to HTTPD virtual host matching combined with path matching ( HST SiteMapItem Matching), similar to what many frameworks do. What makes the HST matching unique compared to other frameworks, is that the inverse of the matching configuration is used for link rewriting (for example document links in the content in the repository). Developers do not need to take care of link rewriting themselves.

For a proper understanding of the request matching and request processing concepts, it is important to understand the HST configuration model. This chapter will dissect and zoom in on the different parts of the HST configuration model.

Where is the HST configuration stored?

The HST reads its configuration model from the content repository. The model is (by default) stored below the node  /hst:hst.

How and when is the model loaded?

When a request hits an HST site application, the HST will try to match that request against its model. When there is no model present, the HST will load the HST configuration from the repository and builds an in-memory model of that configuration. Whenever the configuration in the repository changes, the HST will reload its model. Since the model can be very large (100.000+ configuration nodes), covering configuration of thousands of sites, the model loading is lazy and reuses previously loaded configuration parts that did not change. Apart from very efficient loading, requests can be served with stale model support to avoid hiccups. A model instance itself can best be seen as an append-only model: everything that has been loaded is immutable.

HST main configuration nodes 

Right after the Bloomreach Experience Manager application has started as described in the Getting Started Trail, the repository gets bootstrapped with some initial HST configuration nodes. Assuming project name example, then logging in at http://localhost:8080/cms/console, you can see below the node /hst:hst in the repository the following main configuration nodes:

/hst:hst
  /hst:blueprints
    /example-subsite
  /hst:configurations
    /example
      /hst:abstractpages
      /hst:catalog
      /hst:components
      /hst:pages
      /hst:prototypepages
      /hst:sitemap
      /hst:templates
      /hst:sitemapitemhandlers 
      /hst:workspace
      /hst:channel
      /hst:channelinfo
  /hst:hosts
    /dev-localhost
      /localhost
        /hst:root
  /hst:sites
    /example

1. hst:blueprints : The blueprint HST configuration for new channels
   • example-subsite : A blueprint configuration for adding a new subsite
2. hst:configurations : Contains all channel/site configuration nodes that have sitemap matching configuration and optionally HMVC configuration
   • hst:sitemap : Contains a composite tree of sitemap items that are used to match the request path (after the matched mount) against. A sitemap item points in general (unless for example REST or other kind of rendering) to an  hst:component node, which is in most cases a child node of  hst:pages. A sitemap item generally contains a reference to which content (document) is mapped to the current request.
   • hst:pages, hst:components, hst:abstractpages and hst:templates : The hst:pages, hst:components, hst:abstractpages and hst:templates together contain the HMVC configuration to render pages with.
   • hst:workspace : Contains all configuration nodes for the site example that can be modified at runtime by a webmaster through the Channel Manager. For example changes through the channel manager by a webmaster never end up directly below /hst:hst/hst:configuration/example/hst:sitemap but always below /hst:hst/hst:configuration/example/hst:workspace/hst:sitemap. This way we can assure that all changes made by webmasters can be kept apart from changes made by developers (through for example bootstrap configuration) as the changes from developers typically do end up below /hst:hst/hst:configuration/example/hst:sitemap instead.
   • hst:channel : The channel name that is visible in the CMS channel manager plus channel configuration parameters. The hst:channel node can also be a sibling of the hst:workspace node: In this case, the channel settings will be read-only in the Channel Manager.
   • hst:catalog : Below the hst:catalog all components are configured that can be dragged into a container on a page through the Channel Editor in the Channel Manager. More specifically see Channel Editor Catalog and Channel Editor Component Parameters.
   • hst:prototypepages : Below the hst:prototypepages the pages are configured that can be used as a prototype for creating new pages by webmasters through the Channel Manager.
   • hst:sitemapitemhandlers : Post-processors for matched sitemap items with  SitemapItem Handlers.
3. hst:hosts : The host and mount (sub channel) matching configuration
   • dev-localhost : The hostgroup for localhost development
4. hst:sites : Contains all the hst:site nodes that reference the root of the content (documents) for a site and references which sitemap and HMVC configuration to use
   • example : The example site

We will zoom in a bit more into the hosts configuration in the next section.