Site Menus - BloomReach Experience - Open Source CMS
07-01-2019

Site Menus

Site menus define navigational structures for a site. They are configured inside the HST Workspace under the hst:sitemenus node. There can be multiple site menus and each one is defined as a child node of hst:sitemenus, of node type hst:sitemenu. The actual menu items are defined as descendants of such an hst:sitemenu node using the node type hst:sitemenuitem.

The example below shows a simple site menu main with two menu items  home and news:

/hst:hst/hst:configurations/myproject/hst:workspace:
  /hst:sitemenus:
    jcr:primaryType: hst:sitemenus
    /main:
      jcr:primaryType: hst:sitemenu
      /home:
        jcr:primaryType: hst:sitemenuitem
      /news:
        jcr:primaryType: hst:sitemenuitem

Menu items can contain child menu items, so a menu can be hierarchical, for example:

/hst:hst/hst:configurations/myproject/hst:workspace:
  /hst:sitemenus:
    jcr:primaryType: hst:sitemenus
    /main:
      jcr:primaryType: hst:sitemenu
      /home:
        jcr:primaryType: hst:sitemenuitem
      /news:
        jcr:primaryType: hst:sitemenuitem
        /archive:
          jcr:primaryType: hst:sitemenuitem
          /2014:
            jcr:primaryType: hst:sitemenuitem
          /2013:
            jcr:primaryType: hst:sitemenuitem

A site menu item is linked to a sitemap item (i.e. a URL mapping) through its property hst:referencesitemapitem, which refers to either the name of a sitemap item or the hst:refId of a sitemap item.

For example, given the following sitemap item configuration:

/hst:hst/hst:configurations/myproject/hst:sitemap:
  /news:
    jcr:primaryType: hst:sitemapitem
    hst:componentconfigurationid: hst:pages/newslist
    hst:relativecontentpath: news
    hst:refId: newslist

Either of the following site menu items links to the same  news sitemap item above:

/hst:hst/hst:configurations/myproject/hst:workspace/hst:sitemenus/main:
  /news:
    jcr:primaryType: hst:sitemenuitem
    hst:referencesitemapitem: news
/hst:hst/hst:configurations/myproject/hst:workspace/hst:sitemenus/main:
  /news:
    jcr:primaryType: hst:sitemenuitem
    hst:referencesitemapitem: newslist

The first site menu item above refers to the sitemap item's name ( news), the second one refers to the sitemap item's hst:refid ( newslist).

Alternatively a site menu item can link to an external URL through the property hst:externallink:

/hst:hst/hst:configurations/myproject/hst:workspace/hst:sitemenus/main:
  /news:
    jcr:primaryType: hst:sitemenuitem
    hst:externallink: https://www.onehippo.com/

If both the hst:referencesitemapitem and hst:externallink properties are defined, the hst:referencesitemapitem property is ignored (i.e. the site menu item will link to the external URL).

As of Bloomreach Experience Manager 12.0.4 and 12.1.1, javascript: and data: protocol usages are automatically removed from the hst:externallink property by default. This security features can be disabled in your project's hst-config.properties as follows:

sitemenu.externallink.omitJavascriptProtocol = false
Site menus can be modified by webmasters using the Menu Editor in the Channel Manager.
The delivery tier provides a standard Menu Component which makes an  org.hippoecm.hst.core.sitemenu.HstSiteMenu object available to the rendering engine.

Configuration Parameters

Optionally configuration parameters can be specified on an hst:sitemenuitem node through the multi-valued hst:parameternames and hst:parametersvalues properties.

Both properties must be of the same size, and the order defines which parameter name has which parameter value.

For example, the following parameters:

  • subtitle = 'breaking news'
  • color = 'blue'

are configured as follows:

/news:
  jcr:primaryType: hst:sitemenuitem
  hst:referencesitemapitem: news
  hst:parameternames: [subtitle, color]
  hst:parametervalues: [breaking news, blue]

Exposing Configuration Parameters through the UI

Supported from CMS 10.2.0 and onwards

As of CMS 10.2, the configuration parameters described above are exposed and you can manage their values through the Additional settings section of the Channel Manager's Menu Editor. You can set up a special, hidden root-level menu item with the name hst:prototypeitem to define which configuration parameters (and their default values) a new item for this menu should have. When you create a new item for a menu which has this special prototype item defined, a copy of it is made, including all hst:parameternames and hst:parametervalues defined on it. You can then manage the values of these parameters through a text input field in the Menu Editor's Additional settings section. There is no validation support for these fields, and it is not possible to add or remove parameters through the UI, nor to change the name of a parameter. 

If the hst:prototypeitem is added to a menu which already has menu items, the pre-existing menu items will not automatically get the prototype item's parameters. You need to add them manually, if so desired.

Here is an example of how the hst:prototypeitem looks in the repository: 

/hst:hst/hst:configurations/myproject/hst:workspace:
  /hst:sitemenus:
    jcr:primaryType: hst:sitemenus
    /main:
      jcr:primaryType: hst:sitemenu
      /hst:prototypeitem:
        jcr:primaryType: hst:sitemuitem
        hst:parameternames: [subtitle, color]
        hst:parametervalues: ['',blue]       
      /home:
        jcr:primaryType: hst:sitemenuitem
      /news:
        jcr:primaryType: hst:sitemenuitem
        /breaking:
          jcr:primaryType: hst:sitemenuitem

Repository-Based Menus

In addition to wiring each site menu item to a sitemap item through configuration as explained above, it is possible to programatically modify a site menu in a delivery tier component and add additional menu items based on folder structures in the content repository. This is commonly referred to as a repository-based menu.

At configuration level it is useful to mark the point at which a site menu should be enriched with repository-based menu items. This can be done by specifying the boolean property hst:repobased with value true on an hst:sitemenuitem node. Optionally, the property hst:depth can be used to configure the depth of the repository folder structure to traverse and recreate as menu items.

/news:
  jcr:primaryType: hst:sitemenuitem
  hst:referencesitemapitem: news
  hst:repobased: true
  hst:depth: 3

At code level the site menu can then be modified using e.g. the following steps:

  1. Use the method  org.hippoecm.hst.core.sitemenu.HstSiteMenu#getEditableMenu() to obtain an  org.hippoecm.hst.core.sitemenu.EditableMenu object.
  2. Get the deepest expanded menu item using  org.hippoecm.hst.core.sitemenu.EditableMenu#getDeepestExpandedItem().
  3. Check if it is a repository-based menu item using  org.hippoecm.hst.core.sitemenu.CommonMenuItem#isRepositoryBased().
  4. Get the depth using  org.hippoecm.hst.core.sitemenu.CommonMenuItem#getDepth().
  5. Get the HippoBean for the folder mapped to the sitemap item linked to the site menu item using  org.hippoecm.hst.core.sitemenu.CommonMenuItem#resolveToSiteMapItem(HstRequest) and  org.hippoecm.hst.component.support.bean.BaseHstComponent#getBeanForResolvedSiteMapItem(HstRequest, ResolvedSiteMapItem).
  6. Iterate through the folder's subfolders using the JCR API.
  7. Programatically add menu items through  org.hippoecm.hst.core.sitemenu.EditableMenuItem#addChildMenuItem(EditableMenuItem).

An example of a repository-based menu implementation can be found in the Hippo testsuite in the following classes:

https://code.onehippo.org/cms-community/hippo-testsuite/blob/hippo-testsuite-4.2.0/components/src/main/java/org/hippoecm/hst/demo/components/LeftMenu.java

https://code.onehippo.org/cms-community/hippo-testsuite/blob/hippo-testsuite-4.2.0/components/src/main/java/org/hippoecm/hst/demo/util/DemoRepoBasedMenuItem.java

When implementing repository-based menus, make sure to take performance implications into account. Recursively expanding repository-based menu items causes degraded performance. The example implementation in the testsuite (see above) is optimized for efficiency and can be used as a reference.
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?