HST Configuration Inheritance - BloomReach Experience - Open Source CMS

This article covers a Hippo CMS version 11. There's an updated version available that covers our most recent release.

25-08-2016

HST Configuration Inheritance

Note that hst:workspace nodes are only inherited when explicitly inherited, see below! 

HST provides multi-site, multi-channel and multi-language support out-of-the-box. This is achieved by being able to configure as many hosts, mounts and different hst:configurations as needed. Because for many (sub)sites, the hst configuration has many overlapping parts, hst configuration can be inherited between sites. For example, an English and French version of my website can most likely share a lot of their hst:abstractpages, hst:components and hst:templates. What they might not share is for example their hst:sitemenu and hst:sitemap (because for example the French website shows French URLs). The hst:configuration nodes in this case without inheritance could look something like:

+ hst:hst
  + hst:configurations
    + hst:default
    + myproject
    |   + hst:abstractpage
    |   + hst:catalog
    |   + hst:components
    |   + hst:pages
    |   + hst:prototypepages
    |   + hst:sitemap
    |   + hst:templates
    |   + hst:workspace
    |      + hst:pages
    |      + hst:sitemap
    |      + hst:sitemenus
    |      + hst:containers
    + monproject
       + hst:abstractpage
       + hst:catalog
       + hst:components
       + hst:pages
       + hst:prototypepages
       + hst:sitemap
       + hst:templates
       + hst:workspace
          + hst:pages
          + hst:sitemap
          + hst:sitemenus
          + hst:container 

Now, suppose the abstractpages, catalog items,  components, prototypepages and  templates would be the same for both English and French site. Then, the following configuration shows a setup with inheritance:

+ hst:hst
  + hst:configurations
    + hst:default
    + common
    |   + hst:abstractpage
    |   + hst:catalog
    |   + hst:components
    |   + hst:prototypepages
    |   + hst:templates
    + myproject
    |   - hst:inheritsfrom = {../common}
    |   + hst:pages
    |   + hst:sitemap
    |   + hst:workspace
    |      + hst:pages
    |      + hst:sitemap
    |      + hst:sitemenus
    |      + hst:containers
    + monproject
        - hst:inheritsfrom = {../common}
        + hst:pages
        + hst:sitemap
        + hst:workspace
           + hst:pages
           + hst:sitemap
           + hst:sitemenus
           + hst:container
note we write ../common between {} because the hst:inheritsfrom property is multi-valued. It is multivalued because multiple configurations can be inherited

Now, all common parts have moved to common, and the specific parts are below myproject and monproject. The inheritance is done by adding a  multi-valued property hst:inheritsfrom on myproject and monproject. If multiple values are configured for the hst:inheritsfrom property, the inheritance is in order of the top one first. The inheritance is a coarse-grained merge: If myproject has the same child node below hst:pages as common has (assuming common configuration also had hst:pages configured) than the inherited one is ignored. The exact inheritance rules are as follows. If we have the (sub)site myproject:

+ hst:configurations [hst:configurations]
   + common 
   |   + hst:pages
   |      + aaa
   |      |   + child_of_aaa
   |      + bbb
   + myproject 
      - hst:inheritsfrom = ../common
      + hst:pages
          + aaa
   

Then

  • myproject/hst:pages does not hide common/hst:pages

  • myproject/hst:pages/aaa does hide common/hst:pages/aaa (thus the child child_of_aaa is not inherited). The above results in a effective (resolved) configuration for myproject to be:

// with inheritance resolved
+ myproject
   + hst:pages
       + aaa
       + bbb

Default inheritance

This is the implicitly inherited configuration, and is configured below hst:default.  It is always inherited by all configurations. It is typically the location where dependencies outside the scope of the current project (e.g. plugins) can bootstrap their configuration to. The page default inherited configuration explains the exact details of the default inheritance. 

An example with a hst:default (which has lowest precedence but is inherited implicitly), we will have the following total behavior:
if our configuration is:

+ hst:configurations 
    + hst:default
    |   + hst:pages
    |     + bbb
    |     |   + child_of_bbb
    |     + ccc
    |       + child_of_ccc
    + common 
    |   + hst:pages
    |       + aaa
    |       |   + child_of_aaa
    |       + bbb
    + myproject
       - hst:inheritsfrom = ../common
       + hst:pages
           + aaa

Then, the myproject configuration with its inheritance resolved will become

// with inheritance resolved
+ myproject
    + hst:pages
        + aaa // from now-en self: it does not inherit config below 'aaa' from common!
        + bbb // from common: it does not inherit config below 'bbb' from hstdefault!
        + ccc // from hstdefault
            + child_of_ccc

Multiple Inheritance

An HST configuration can inherit from multiple other configurations; hst:inheritsfrom is a multi-valued property:

+ hst:configurations
    + common
    + common-en
    + myproject
       - hst:inheritsfrom = {../common-en,../common}

The order of the values of hst:inheritsfrom is important: in the example above common-en is specified before common and therefore takes precedence over it.

In case of circular reference, the inheritance stops at already inherited configuration nodes

Cascading inheritance

Supported since CMS 10.2.0 and onwards

Instead of the configuration above where myproject contains

- hst:inheritsfrom = {../common,../common-en}

you can also make use of cascading inheritance :

+ hst:configurations
    + common
    + common-en
    |  - hst:inheritsfrom = {../common}
    + myproject
       - hst:inheritsfrom = {../common-en}

With the above configuration, myproject inherits everything from common-en and through common-en, it inherits also everything from common

Note that projects that are on an older version than CMS 10.2.0 can use multiple inheritance instead of cascading inheritance if a configuration needs to inherit from two other configurations

Workspace inheritance

Supported since CMS 10.1.0 and onwards

As warned in the top of this page, by default workspaces are not inherited. If we have the following setup:

+ hst:hst
  + hst:configurations
    + hst:default
    + common
    |   + hst:abstractpage
    |   + hst:catalog
    |   + hst:components
    |   + hst:prototypepages
    |   + hst:templates
    + corporate
    |   - hst:inheritsfrom = {../common}
    |   + hst:pages
    |   + hst:sitemap
    |   + hst:workspace
    |      + hst:pages
    |      + hst:sitemap
    |      + hst:sitemenus
    |      + hst:containers
    + subsite
        - hst:inheritsfrom = {../corporate}
        + hst:pages
        + hst:sitemap
        + hst:workspace
           + hst:pages
           + hst:sitemap
           + hst:sitemenus
           + hst:container

then subsite does inherit pages and sitemap from the corporate site and from common. However, subsite does not inherit the hst:workspace from corporate. By default, the hst:workspace configuration is not inherited. Unless, you explicitly configure the workspace to be inherited! Changing above the subsite configuration into:

+ subsite
  - hst:inheritsfrom = {../corporate, 
  |                     ../corporate/hst:workspace}
  + hst:pages
  + hst:sitemap
  + hst:workspace
    + hst:pages
    + hst:sitemap
    + hst:sitemenus
    + hst:container

ensures that also the corporate workspace gets inherited. This is particularly useful for a setup where subsites need to mimic the corporate site completely, but need to add or override some specific pages only (or only have custom content for some pages).

Next to inheriting the entire workspace, you can also inherit just some main child config node in the configuration. Assuming the setup above, that the workspace from corporate site needs to be inherited, except for the sitemenus. This can be achieved as follows:

+ subsite
  - hst:inheritsfrom = {../corporate, 
  |                     ../corporate/hst:workspace/hst:pages, 
  |                     ../corporate/hst:workspace/hst:sitemap, 
  |                     ../corporate/hst:workspace/hst:container}
  + hst:pages
  + hst:sitemap
  + hst:workspace
    + hst:pages
    + hst:sitemap
    + hst:sitemenus
    + hst:container
It is not possible to reference in the hst:inheritsfrom property children below the children of hst:workspace. 

 

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?