SiteMapItem Matching

After the URL is matched to a Mount, Bloomreach Content attempts to match the remaining part of the URL to a SiteMapItem. For example, if the URL http://localhost:8080/site/fr/home matches the Mount fr, the remaining segment home is matched in the sitemap.

By default, the SiteMap is configured at /hst:hst/hst:configurations/{myproject}/hst:sitemap.

SiteMap matching provides flexible rules for associating specific URLs or URL patterns with component configurations. The SiteMap is also used in reverse to generate URLs for documents. The SiteMap is a hierarchical structure composed of SiteMapItems. These items can have explicit names or use wildcards to match variable segments. The special SiteMapItem name _index_ has unique behavior, described later in this document.

A path segment refers to any part of the URL between two slashes. The SiteMap supports the following wildcards:

1 _default_          Equivalent to *, matches any single path segment
2 _any_              Equivalent to **, matches any trailing part of a URL
3 _default_.ext      Matches a single path segment with a specific extension, e.g., *.html
4 _any_.ext          Matches any trailing part of a URL with a specific extension, e.g., **.xml

The ** and **.xxx matchers are only permitted as leaf SiteMapItems in the hierarchy.

During the SiteMapItem matching phase, the system attempts to match the remainder of the URL after the Mount to the most specific SiteMapItem. Specificity is determined by the following rules:

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

Rules 1–4 are straightforward. Rule 5 prioritizes * over **.html. For example, consider the following (simplified) SiteMap configuration:

/hst:hst:
  /hst:configurations:
    /example:
      /hst:sitemap:
        /home:
        /news:
          /_any_.html:
          /_any_:
        /agenda:
          /_any_.html:
          /_any_:
          /2011:
            /_default_:
              /_default_:
        /_any_:
copy

The following URL paths (after the Mount) match these 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_

Pay attention to /agenda/2011/foo/bar/lux and /agenda/2011/foo/bar/myAgendaItem.html. In these cases, agenda/2011/_default/_default_ does not match, so the system falls back to the _any_ and _any_.html matchers. The _any_ matcher at the root level typically serves as a catch-all, often used for handling 404 pages.

After a SiteMapItem is matched, HST request processing starts using a runtime instance of this SiteMapItem. The most important properties of a SiteMapItem are:

1. hst:componentconfigurationid: Specifies the relative path to the hst:component (tree) under /hst:hst/hst:configurations/{myproject}. For example, the home SiteMapItem might use hst:pages/home, and news/_any_ might use hst:pages/newsoverview. REST pipelines that use a sitemap do not use this property; it is only relevant for website development based on HST Components.
2. hst:relativecontentpath: Specifies the content path relative to /hst:hst/hst:sites/{myproject}/hst:content. For example, the home SiteMapItem might use common/homepage. This property can reference wildcards from the SiteMap using property placeholders in the format ${integer} or ${parent}. ${parent} refers to the parent SiteMapItem's relativecontentpath. For example:
   • news/_any_: news/${1}
   • news/default/default/_any_: news/${1}/${2}/${3}
     • ${1} refers to the topmost matched ancestor with a _default_, ${2} to the second, and so on.
     • If a property placeholder cannot be resolved for a request, the entire value resolves to null.

SiteMapItem _index_

The _index_ SiteMapItem is available in brXM 11.2.0 and later.

The _index_ SiteMapItem functions similarly to the Apache DirectoryIndex Directive, but does not require the path to end with a slash. The _index_ SiteMapItem behaves as follows:

1. If a URL matches a SiteMapItem called foo that has a child _index_ item, and the _index_ item's hst:relativecontentpath points to an existing document or folder, the _index_ SiteMapItem is selected as the final match.
2. If a _index_ SiteMapItem exists under the matched SiteMapItem, but its hst:relativecontentpath does not point to an existing document or folder, the parent SiteMapItem is used instead.
3. When generating links for documents that match a _index_ SiteMapItem, the link points to the parent of the _index_ item. However, during matching, the _index_ item is used.
4. The _index_ SiteMapItem is supported under both explicit and * SiteMapItems. It is not supported directly under the hst:sitemap, nor under **, **.html, or *.html SiteMapItems.
5. The hst:relativecontentpath of _index_ SiteMapItems can use property placeholders such as ${1}, ${2}, and ${parent}.

Additional Properties of a SiteMapItem

Property name	Example	Description
hst:namedpipeline	JaxrsRestContentPipeline	Specifies the pipeline for HST request processing. If not set, the parent pipeline is used. If no parent is set, the Mount pipeline is used. If not configured on the Mount, the default is DefaultSitePipeline, which invokes HstComponent-based processing.
hst:refId	homeId	Optional. Must be unique within a sitemap item tree. Allows you to create links to a SiteMapItem using this refId instead of the path. For example, you can reference SiteMapItems by refId in hst:referencesitemapitem (SiteMenuItem), hst:homepage, or hst:pagenotfound in a Mount configuration. This is useful for multi-language setups where each language variant has the same refId. Link creation components resolve by refId first, then by path if not found.
hst:excludedforlinkrewriting	true	If set to true, excludes this SiteMapItem from link rewriting. Use this property to support REST sitemap items alongside standard website sitemap items.
hst:locale	en_US	Sets the locale for this SiteMapItem and its descendants. If not configured, the value is inherited from the Mount.
hst:parameternames	pageSize	Keys that can be retrieved during HST request processing. The multi-valued properties parameternames and parametervalues must have the same number of items, or they are ignored.
hst:parametervalues	5	Values that can be retrieved during HST request processing. Supports property placeholders like ${1} and ${2}. The multi-valued properties parameternames and parametervalues must have equal length, or they are ignored.
hst:authenticated / hst:roles / hst:users	See Delivery Tier Authorization Configuration	Used to secure the SiteMapItem.
hst:responseheaders	["Access-Control-Allow-Origin: http://localhost:3000", "Access-Control-Allow-Credentials: true"]	Custom HTTP response headers to be set for this SiteMapItem and its descendants, unless overridden. For example, configure CORS headers using this property. Set this property as a string array, each entry formatted as header_name: header_value.
hst:hiddeninchannelmanager	true	If true, hides the SiteMapItem from the Sitemap navigation in Experience manager. Use this to hide items not relevant to end users, such as sitemap items for RSS feeds.