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

SiteMapItem Matching 

After the URL has been matched to a Mount, the remaining part of the URL after the Mount is attempted to be matched to a SiteMapItem. So the URL if the URL http://localhost:8080/site/fr/home matches to the Mount _fr_, the remaining part of the URL to be matched in the sitemap is home. The SiteMap is by default configured at /hst:hst/hst:configurations/{myproject}/hst:sitemap. The basic idea behind SiteMap matching is to provide flexible rules for matching specific URLs or complete URL spaces and map URLs on component configurations. The SiteMap is also used for linkrewriting which we will show later on. The SiteMap is a composite structure containing a hierarchy of SiteMapItems. It can contain SiteMapItems with explicit names, or with wildcards matching to any name.

From now on we talk about a pathstep we refer to some part of the URL between two slashes (i.e. a path segment). As wildcards the SiteMap supports:

1 _default_          this is equivalent to a * , matching any single pathstep
2 _any_              this is equivalet to a \*\* , matching any ending of a URL
3 _default_.ext      where 'ext' can be some extension, for example \*.html
4 _any_.ext          where 'ext' can be some extension, for example \**.xml

** and *.xxx* matchers are only allowed as leaf SiteMapItem in the composite structure.

During SiteMapItem matching phase, the remainder of the URL after the Mount is attempted to be matched to the best SiteMapItem. The best SiteMapItem is the one that matches earliest path segments more specifically.

1 An exact (explicit) match is considered more specific than a wildcard match
2 * is more specific than a **
3 *.html is more specific than a *
4 **.html is more specific than **
5 * is more specific than **.html

Up to rule 4 it is very straightforward. Rule 5 is debatable, but we chose for * to be more explicit than **.html.
For example suppose the following (contrived) SiteMap

TODO-IMAGE images/download/attachments/33554836/sitemap.png

The following URLs (after the Mount part) match to the following SiteMapItems:

 /home -->home
 /news -->news
 /news/2011 -->news/_any_
 /news/2011/myNewsItem.html --> news/_any_.html
 /agenda/2010 --> agenda/_any_
 /agenda/2011/foo --> agenda/2011/_default_
 /agenda/2011/foo/bar --> agenda/2011/_default_/_default_
 /agenda/2011/foo/myAgendaItem.html --> agenda/2011/_default_/_default_
 /agenda/2011/foo/bar/lux --> agenda/_any_
 /agenda/2011/foo/bar/myAgendaItem.html --> agenda/_any_.html
 /home/foo/bar --> _any_

Give some special attention to /agenda/2011/foo/bar/lux and /agenda/2011/foo/bar/myAgendaItem.html. Understand that agenda/2011/_default/default_ does not fit, and why the fallback to the _any_ and _any_.html is done. The matcher _any_ at the root of the SiteMap is typically the catch-all matcher that creates a 404 page.

After a SiteMapItem is matched the HST request processing is invoked with a flyweight runtime instance of this SiteMapItem. The 2 most important properties of a SiteMapItem are:

  1. hst:componentconfigurationid : The relative path to the hst:component (tree) below /hst:hst/hst:configurations/{myproject}. For example, for the SiteMapItem home it might be hst:pages/home and for news/any_ for example _hst:pages/newsoverview. REST pipelines using a sitemap do not use the hst:componentconfigurationid : The componentconfigurationid is only used for website development that is based on aggregating content based on HST Components

  2. hst:relativecontentpath : The content path relative to /hst:hst/hst:sites/{myproject}/hst:content. For example for the SiteMapItem home it might be common/homepage. Note that the relativecontentpath property can contain references to wildcardsfrom the SiteMap. References are indicated by propertyplaceholders which have the syntax ${integer} . Thus, for example the relativecontentpath for the following SiteMapItem could be as follows:

  3. news/_any_ : news/${1}

  4. news/default/default/_any_ : news/${1}/${2}/${3}

* Note that the ${1} always refers to the top matched ancestor containing a _default_, ${2} to the second, etc.
* Also note that if one of the property placeholders cannot be resolved for a request, the entire value is resolved to null.

Also, here are some additional properties of a SiteMapItem to note:

Property name

Example

Description

hst:namedpipeline

JaxrsRestContentPipeline

The pipeline to use for the further HST request processing. If not present, the parent namedpipeline is used and if there is no parent, the Mount namedpipeline is used. If also not configured on the Mount, the default value used by the HST is DefaultSitePipeline which is a pipeline that invokes the HstComponent based request processing

hst:refId

homeId

Optional property. It must be unique within a single sitemap item tree. With this property value, you can create a link to the SiteMapItem with this refId value instead of a path value of SiteMapItem.
For example, instead of using path values to SiteMapItems, you can configure a refId values in 'hst:referencesitemapitem' of a SiteMenuItem, 'hst:homepage', or 'hst:pagenotfound' of a Mount configuration.
This can be very useful if you have different SiteMapItem nodes for each language, but each SiteMapItem has the same 'hst:refId' value such as 'home' because those are just multi-lingual variants of the same
sitemap item like 'home'.
HST Link Creating components will look up a SiteMapItem configuration by refId first and then it will look up a SiteMapItem configuration by the path if not found by refId

hst:excludedforlinkrewriting

true

Do not use this sitemapitem for linkrewriting if set to true. This is an important property if you want to support REST sitemap items next to normal website sitemap items

hst:locale

en_US

The locale for the sitemapitem and descendants. If not configured, the value is inherited from the Mount

hst:parameternames

pageSize

keys which can be retrieved during HST request processing. The multi-valued property parameternames ans parametervalues must have equal number of items, otherwise, they are all skipped

hst:parametervalues

5

values which can be retrieved during HST request processing. Propertyplaceholders like ${1\, ${2} are supported. The multi-valued property parameternames ans parametervalues must have equal number of items, otherwise, they are all skipped

hst:authenticated / hst:roles / hst:users

see HST-2 Authentication and Authorization Support

securing the sitemapitem