Default Inherited Configuration - BloomReach Experience - Open Source CMS

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

02-06-2016

Default Inherited Configuration

The Introduction of this chapter explained that the channel configuration for a channel example can be found at

+ hst:hst
   + hst:configurations
      + example           [hst:configuration]

Configuration inheritance explained how the  example configuration can inherit from (and merge with) another configuration.

+ hst:hst
   + hst:configurations
      + example             [hst:configuration]
      |   - hst:inheritsfrom = ../common
      + common              [hst:configuration]

In addition there is one default configuration from which every hst:configuration inherits implicitly, namely :

+ hst:hst
   + hst:configurations
       + hst:default

The hst:default is the implicitly inherited configuration and does not need to be included through the hst:inheritsfrom property.

Why is there a hst:default?

The hst:default node is the only fixed non-project-dependant name below hst:hst/hst:configuration. It is the configuration node to which the HST and  plugins can bootstrap their configuration. For example when using the  Sitemap Plugin, a sitemap.xml sitemap item gets bootstrapped into  hst:default/hst:sitemap resulting in having the url /sitemap.xml directly available for every channel.

The most common use case is that a plugin or library feature bootstraps ready to use component catalog items into the  hst:default configuration. By default, the HST bootstraps the following default sitemap items:

+ hst:hst
  + hst:configurations
    + hst:default
      + hst:sitemap
        + _any_.css
        + _any_.CSS
        + _any_.gif
        + _any_.GIF
        + _any_.ico
        + _any_.ICO
        + _any_.jpeg
        + _any_.JPEG
        + _any_.jpg
        + _any_.JPG
        + _any_.js
        + _any_.JS
        + _any_.pdf
        + _any_.PDF
        + _any_.png
        + _any_.PNG
        + _any_.svg
        + _any_.SVG
        + _any_.jsp
        + _any_.JSP
        + webfiles
        | + _default_
        |   + _any_
        login
        | + _any_
        + binaries
          + _any_

Note _any_ stands for ** matcher and _default_ for *.  Let's dissect the default sitemap items a bit further. 

The static webapp files matchers

The static webapp files matchers are the _any_.css, _any_.CSS, _any_.gif  ...... _any_.JSP. They all have hst:containerresource = true, thus

+ hst:sitemap
  + _any_.css
    - hst:containerresource = true

Opposed to CMS 7.9 where we did not have these default static webapp matchers, every HTTP request since CMS 10.0, also for static webapp resources, is matched in the HST model against a HstSiteMapItem. A request, e.g.  /css/style.css, matches _any_.css, after which the HST pipeline for container resources is executed, namely the  ContainerResourcePipeline. This pipeline has as the last valve the  containerResourceDispatchingValve which just forwards the request. For static webapp files, it will finally be handled by the default container available servlet for serving webapp files. What is nice though is that you can plugin extra behavior in the  ContainerResourcePipeline, for example some authentication check, or you can add a nested sitemap structure for css files, where some css files are only served over https. Perhaps a contrived example, but it is now all pluggable and not only for html pages like it used to be before CMS 10.0. 

A container resource sitemap item (item that has hst:containerresource = true) is only allowed to be configured in the hst:default sitemap, and not in other sitemaps. When a URL is created for an hst link that matches a container resource sitemap item, the resulting link is relative to the  webapp  (e.g. relative to /site) and not to the possibly current channel (e.g. relative to /site/fr/). A container resource sitemap item is by default also scheme agnostic, implying that it does not matter whether it is accessed over http or https. If a matcher is only suited for a specific scheme, the property hst:schemeagnostic needs to be set to false.

The webfiles matcher

The webfiles matcher has been introduced to support Web Files. Including its properties, it is (should be) as follows:

+ webfiles
   - hst:containerresource = true
   - hst:namedpipeline = WebFilePipeline
   - hst:refId = WEB-FILES-ID 
   + _default_
      + _any_
         - hst:parameternames = version
         - hst:parametervalues = ${1}
         - hst:relativecontentpath = ${2}

All URLs for webfiles are considered to be container resources as well. Their URLs are thus relative to the webapp and not relative to the currently matched channel. The webfiles sitemap item must contain  hst:refId = WEB-FILES-ID for web files to work. The _default_ matcher is to match the timestamp in the URL for web files: This because web files are cached on the client for a year, but when changed in the repository, should be directly reloaded. The _any_ matcher matches the web file location in the repository.

The login matcher

The login matcher catches all the authentication requests that are done for  HST authentication and authorization support. By default it looks as follows:

+ login
   - hst:containerresource = true
   - hst:namedpipeline = PlainFilterChainInvokingPipeline
   - hst:scheme = https 
      + _any_

By default, all HST login requests are over https, hence hst:scheme = https (note that for pre CMS 10.0 versions the default login requests were over http and you had to change this yourself).  For local development, in case you don't want create locally a self-signed certificate and don't want to configure your container for SSL support, see for example Tomcat SSL howto, or have to have httpd configured for ssl support with mod_ssl enabled, you can easily set it to work over http. If you want to configure login over http, you have to change hst:scheme to be

hst:scheme = http

If you want to automatically bootstrap hst:scheme for the login to go over http instead of https, you can add to your hippoecm-extension.xml the following instruction:

<sv:node sv:name="set-login-over-http">
  <sv:property sv:name="jcr:primaryType" sv:type="Name">
    <sv:value>hippo:initializeitem</sv:value>
  </sv:property>
  <sv:property sv:name="hippo:sequence" sv:type="Double">
    <sv:value>30000.0</sv:value>
  </sv:property>
  <sv:property sv:name="hippo:contentpropset" sv:type="String">
    <sv:value>http</sv:value>
  </sv:property>
  <sv:property sv:name="hippo:contentroot" sv:type="String">
    <sv:value>/hst:hst/hst:configurations/hst:default/hst:sitemap/login/hst:scheme</sv:value>
  </sv:property>
</sv:node>

The binaries matcher

The binaries matcher is used to serve binaries from the repository. These include binaries from assets, gallery and document embedded binaries. The binaries matcher is by default bootstrapped by the HST as follows:

+ binaries
   - hst:containerresource = true
   - hst:refId = BINARIES-PIPELINE-ID
      + _any_

The binaries matcher is a container resource, implying that one and the same binary used in two different channels on the same host (for example http://www.example.org and http://www.example.org/fr) will use one and the same URL to access the binary. The binaries matcher will delegate via the containerResourceDispatchingValve the request to the binaries servlet, which will serve the binary. In the CMS channel manager when viewing the preview of a channel, the preview of a binary will be served. 

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?