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 aSiteMapItem. So if the URLhttp://localhost:8080/site/fr/homematches to the Mountfr, the remaining part of the URL to be matched in the sitemap ishome.

TheSiteMap is configured by default at/hst:hst/hst:configurations/{myproject}/hst:sitemap.

The basic idea behindSiteMap matching is to provide flexible rules for matching specific URLs or complete URL spaces and map URLs on component configurations. TheSiteMap (more precise, the inverse of it) is also used to generate page URLs for links to documents. TheSiteMap is a composite structure containing a hierarchy ofSiteMapItems. It can containSiteMapItems with explicit names, or with wildcards matching to any name. A SiteMapItem with name_index_ has a special meaning. See the usage of_index_ SiteMapItems below.

From now on we talk about apath segment when we refer to some part of the URL between two slashes. As wildcards theSiteMap supports:

1 _default_          this is equivalent to a *, matching any single path segment2 _any_              this is equivalent to a **, matching any ending of a URL3 _default_.ext      where 'ext' can be some extension, for example *.html4 _any_.ext          where 'ext' can be some extension, for example **.xml

DuringSiteMapItem matching phase, the remainder of the URL after the Mount is attempted to be matched to thebestSiteMapItem. ThebestSiteMapItem is the one that matchesearliest path segments more specifically.

1 An exact (explicit) match is considered more specific than a wildcard match2 * 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

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

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

 /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 thatagenda/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 theSiteMap is typically the catch-all matcher that creates a 404 page.

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

1. hst:componentconfigurationid: The relative path to thehst:component (tree) below/hst:hst/hst:configurations/{myproject}. For example, for theSiteMapItem home it might behst:pages/home and fornews/any_ for example_hst:pages/newsoverview. REST pipelines using a sitemap do not use thehst:componentconfigurationid : Thecomponentconfigurationid 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 becommon/homepage. Note that therelativecontentpath property can contain references towildcardsfrom theSiteMap. References are indicated by propertyplaceholders which have the syntax${integer} or${parent}, where${parent} means : use the relativecontentpath of the parent SiteMapItem. Thus, for example therelativecontentpath for the followingSiteMapItem could be as follows:
   • news/_any_ :news/${1}
   • 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 tonull.

SiteMapItem _index_ 

There is a special SiteMapItem name that is _index_. It is a bit comparable toApache DirectoryIndex Directive though we do not require the pathInfo to end with a '/'. The_index_ SiteMapItem works as follows:

1. In case a URL is requested that matches SiteMapItem called foo that contains a child SiteMapItem called_index_, and if the hst:relativecontentpath of that_index_ item points to anexisting document or folder, 
   then the final matched SiteMapItem will be the_index_ SiteMapItem. 

2. If there exists an_index_ SiteMapItem below the SiteMapItem matched by thePathInfo, but if that_index_ item does not have an hst:relativecontentpath that points to an existing document or folder, then the SiteMapItem matched by thePathInfo will be returned. 

3. Linkrewriting for documents that do match an_index_ SiteMapItem do get a link that matches the parent of the_index_ SiteMapItem : During the matching phase, the_index_ SiteMapItem will be used any way. 

4. The_index_ SiteMapItem is supported below bothexplicit SiteMapItems and* SiteMapItems. The_index_ SiteMapItem isnot supported directly below the hst:sitemap though. It is not supported below**,**.html or*.html SiteMapItems, either.

5. Thehst:relativecontentpath of_index_ SiteMapItems can use propertyplaceholders like${1},${2} and${parent}.

Additional properties of aSiteMapItem