HST Configuration Model Introduction

When developing websites with Bloomreach Experience Manager's delivery tier (a.k.a. "Hippo Site Toolkit" or "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 it.

Where is the HST configuration stored?

The Platform webapp reads the HST configuration models from the content repository. The models are stored in node trees that all start with '/hst:' as prefix of the top nodes name. A standard single site project will have two configuration trees:

• /hst:platform
• /hst:myproject

When a request hits the CMS/platform web application and the HstFilter is invoked, HST uses the configuration rooted at /hst:platform for handling the request. /hst:myproject provides the configuration for the HST site application that serves one or more channels and/or REST services. We use the name myproject here as the example name of the site application. If your project spans multiple site web applications, each site web application has its own HST configuration root node.

How and when is the model loaded?

When a request hits an HST webapp, the HST will try to match that request against its model. The model will be provided by the platform (CMS) webapp which loads the HST configuration from the repository and builds an in-memory model of that configuration. Whenever the configuration in the repository changes, the platform will reload the corresponding HST model. Since the model can be very large (100.000+ configuration nodes), covering configuration of hundreds of sites, the model loading is lazy and reuses previously loaded configuration parts that did not change.  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 for the first time as described in the Getting Started Trail, the repository gets bootstrapped with some initial HST configuration nodes. Assuming as project name myproject, then logging in at http://localhost:8080/cms/console, you can see below the node /hst:myproject in the repository the following main configuration nodes:

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

1. hst:blueprints : The blueprint HST configuration for new channels
   • myproject-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 myproject 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:myproject/hst:configuration/example/hst:sitemap but always below /hst:myproject/hst:configuration/myproject/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:myproject/hst:configuration/myproject/hst:sitemap instead.
   • hst:channel : Contains 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:projects/hst:configurations/myproject 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 added to 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
   • myproject : The myproject site

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