Introduction to the HST Configuration Model

Understanding the HST (Hippo Site Toolkit) configuration model is essential when developing websites using the delivery tier of Bloomreach Content. If you are new to the model and want to get started without in-depth knowledge, follow the Build a Website tutorial.

Website development with the HST involves four main areas:

Content stored in the Hippo Repository and accessed via HST Content Beans (Model)
Java classes that implement HST Components (Controller)
Rendering templates, such as JSP or Freemarker files (View)
The HST configuration model: configuration stored in the Hippo Repository that connects the model, controller, and view, and defines request matching for the HST framework

By default, HST processes web page requests using the Hierarchical-Model-View-Controller (HMVC) pattern. Request matching in HST works similarly to HTTPD virtual host matching, combined with path matching as described in HST SiteMapItem Matching. Unlike many frameworks, HST uses the inverse of the matching configuration for link rewriting, such as document links stored in the repository. Link rewriting is handled automatically; developers do not need to implement this themselves.

To understand request matching and request processing, you need to be familiar with the HST configuration model. This page explains the structure and components of the model.

Location of the HST Configuration

The Platform web application loads HST configuration models from the content repository. These models are stored as node trees with names that start with the /hst: prefix. In a typical single-site project, you will find two main configuration trees:

/hst:platform
/hst:myproject

When a request reaches the CMS or platform web application and the HstFilter is triggered, HST uses the configuration under /hst:platform to handle the request. The /hst:myproject node contains the configuration for the HST site application, which serves one or more channels or REST services. In this documentation, myproject is used as an example site application name. If your project includes multiple site web applications, each will have its own HST configuration root node.

The /hst:myproject path refers to the configuration root node in the content repository. The corresponding YAML definition typically uses /hst:hst as the name. When the definition is bootstrapped, the Configuration Management logic replaces /hst:hst with the value specified in site/webapp/src/main/webapp/META-INF/hcm-site.yaml under the hstRoot property. In the hst-config.properties file packaged with the site web application, the hst.configuration.rootPath property must match the hstRoot value from hcm-site.yaml.

If you are running in Single Webapp Mode rather than Multi Webapp Mode, you will not have an hcm-site.yaml file. In this case, only set the hst.configuration.rootPath property in hst-config.properties.

Model Loading Process

When a request reaches an HST web application, HST matches the request against its configuration model. The model is provided by the platform (CMS) web application, which loads the HST configuration from the repository and builds an in-memory representation. When the repository configuration changes, the platform reloads the affected part of the HST model. Because the model can be large (over 100,000 configuration nodes, potentially covering hundreds of sites), loading is performed lazily and previously loaded, unchanged parts are reused. Each model instance is append-only; loaded data is immutable.

Main HST Configuration Nodes

After you start the Bloomreach Content application for the first time (see the Get Started Trail), the repository is initialized with default HST configuration nodes. Assuming your project is named myproject, you can log in at http://localhost:8080/cms/console and view the following main configuration nodes under /hst:myproject:

/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

The main nodes are:

hst:blueprints: Contains blueprint HST configurations for creating new channels.
- myproject-subsite: A blueprint configuration for adding a new subsite.
hst:configurations: Contains all channel and site configuration nodes, including sitemap matching and HMVC configuration.
- hst:sitemap: Defines a tree of sitemap items used to match the request path (after mount matching). A sitemap item typically points to an hst:component node, usually a child of hst:pages. Sitemap items also reference the content (document) mapped to the current request.
- hst:pages, hst:components, hst:abstractpages, hst:templates: These nodes define the HMVC configuration used to render pages.
- hst:workspace: Stores configuration nodes for the myproject site that can be modified at runtime by webmasters through the Experience manager. Changes made via the Experience manager are stored under /hst:myproject/hst:configuration/myproject/hst:workspace, not directly under /hst:myproject/hst:configuration/myproject/hst:sitemap. This separation ensures that webmaster changes are isolated from developer changes, which typically reside outside the workspace node.
- hst:channel: Contains the channel name as displayed in the CMS Experience manager, along with channel configuration parameters. The hst:channel node can also be a sibling of /hst:projects/hst:configurations/myproject; in that case, channel settings are read-only in the Experience manager.
- hst:catalog: Contains all components that can be added to a page container via the Channel Editor in the Experience manager. See Channel Editor Catalog and Channel Editor Component Parameters for details.
- hst:prototypepages: Contains prototype pages that webmasters can use to create new pages through the Experience manager.
- hst:sitemapitemhandlers: Stores post-processors for matched sitemap items using SitemapItem Handlers.
hst:hosts: Defines host and mount (sub-channel) matching configuration.
- dev-localhost: The host group for local development.
hst:sites: Contains all hst:site nodes, which reference the root content (documents) for a site and specify which sitemap and HMVC configuration to use.
- myproject: The site configuration for myproject.

For more details about the hosts configuration, see the hosts configuration documentation.