HST Configuration Inheritance

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:channel:
        /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:channel:
        /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:channel:
        /hst:pages:
        /hst:sitemap:
        /hst:sitemenus:
        /hst:containers:
    /monproject:
      hst:inheritsfrom: [../common]
      /hst:pages:
      /hst:sitemap:
      /hst:workspace:
        /hst:channel:
        /hst:pages:
        /hst:sitemap:
        /hst:sitemenus:
        /hst:container:

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:
  jcr:primaryType: 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 implicitly 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 an 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.

Cascading inheritance

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. 

Workspace inheritance

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:channel:
        /hst:pages:
        /hst:sitemap:
        /hst:sitemenus:
        /hst:containers:
    /subsite:
       hst:inheritsfrom: [../corporate]
       /hst:pages:
       /hst:sitemap:
       /hst:workspace:
         /hst:channel:
         /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 does get 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:

Cascading workspace inheritance

As explained, hst:workspace inheritance needs to be explicitly configured. In case of cascading inheritance is it however also inherited if explicitly configured on the inherited configuration. Thus in case of the following configuration

/hst:hst:
  /hst:configurations:
    /corporate:
      /hst:pages:
      /hst:sitemap:
      /hst:workspace:
        /...:
    /subsite:
      hst:inheritsfrom: [../corporate, '../corporate/hst:workspace']
      /hst:pages:
      /hst:sitemap:
      /hst:workspace:
        /...:
    /sub-subsite:
      hst:inheritsfrom: [../subsite]
      /hst:pages:
      /hst:sitemap:
      /hst:workspace:
        /...:

then sub-subsite inherits from subsite and through subsite inherits from corporate and from corporate/hst:workspace. Thus sub-subsite does not inherit from subsite/hst:workspace since not explicitly configured to inherit the workspace, but through cascading inheritance does inherit from corporate/hst:workspace.