Context Aware, Canonical, Preferred, and NavigationStateful URLs

This page explains the different types of URLs generated by Bloomreach Content: context aware, canonical, preferred, and navigationStateful URLs. Each type serves a specific purpose in content delivery, SEO, and navigation.

Context Aware URLs

By default, the HST (Hippo Site Toolkit) generates context aware URLs for content beans. A context aware URL reflects the current navigation context when multiple valid URLs exist for the same content.

For example, consider a content node at /documents/content/news/2009/mynewsitem. This node can be accessed through multiple URLs:

  • /news/2009/mynewsitem
  • /eu/climate/news/2009/mynewsitem

The second URL is available because the item is linked to the "eu climate" subject, making it accessible in that section of the site.

Suppose your sitemap configuration includes the following structure:

/news:
  /*:
    /**:
      relativecontentpath: news/${1}/${2}
/eu:
  /*:
    /news:
      /*:
        /**:
          relativecontentpath: news/${2}/${3}

Both /eu/*/news/*/** and /news/*/** are valid URL patterns for a news item.

When generating a link, the HST selects the URL pattern that is closest to the current context. The definition of "closest" is implemented in the LocationMapResolver.

For example:

  • If you are browsing /eu/climate/news, the link to 'mynewsitem' will be: 
    /eu/climate/news/2009/mynewsitem
  • If you are browsing /news/2009, the link will be: 
    /news/2009/mynewsitem

Canonical URLs

Search engines prefer to index a single canonical version of a page, even if the same content is available at multiple URLs. To support this, you can specify a canonical link in your HTML. For example, if both /eu/climate/news/2009/mynewsitem and /news/2009/mynewsitem resolve to the same content, you can declare the canonical URL as follows:

<link rel="canonical" href="news/2009/mynewsitem"/>

This tells search engines to index /news/2009/mynewsitem as the authoritative version.

By default, using the hst:link tag in JSP or Freemarker returns the context aware link.

JSP

<hst:link hippobean="${requestScope.document}"/>

Freemarker

<@hst.link hippobean=document/>

To generate the canonical URL, set the canonical attribute to true:

JSP

<hst:link hippobean="${requestScope.document}" canonical="true"/>

Freemarker

<@hst.link hippobean=document canonical=true/>

When multiple URLs are possible, the canonical URL is the shortest valid URL. If two URLs are equally short and valid, one is selected and consistently used as the canonical URL.

Preferred URLs

You can instruct the HST to prefer generating URLs under a specific sitemap subtree. If the preferred path cannot be used, you can configure whether to fall back to the default link rewriting behavior.

For example, to prefer URLs under /themes/sometheme:

JSP

<hst:link hippobean="${requestScope.doc}">
 <hst:sitemapitem preferPath="/themes/sometheme" fallback="true"/>
</hst:link>

Freemarker

<@hst.link hippobean=doc>
 <@hst.sitemapitem preferPath="/themes/sometheme" fallback=true/>
</@hst.link>

If fallback is not specified, it defaults to true. When fallback is true, the system attempts to generate a URL under /themes/sometheme. If this is not possible, it falls back to the default sitemap. If fallback is false and no URL can be created under the preferred path, the link will not be generated.

You can also specify canonical=true to generate the canonical URL within the preferred subtree.

In addition to preferPath, you can use preferItemId (the sitemap item's ID) or preferItem (an HstSiteMapItem object). Refer to the hst-core.tld for details.

NavigationStateful URLs are generated relative to the current URL and the contextual location of the JCR node. Unlike canonical URLs, which are based on the primary location of a document, navigationStateful URLs reflect the current navigation context. This is useful for scenarios such as faceted navigation, where you want links to maintain the user's current filter or navigation state.

To generate a navigationStateful URL:

JSP

<hst:link var="link" hippobean="${requestScope.result}" navigationStateful="true" />

Freemarker

<@hst.link var="link" hippobean=result navigationStateful=true />

NavigationStateful URLs also include the current query string, if present.

For more information on link generation and sitemap configuration, refer to the related documentation.

Share Feedback
Page: /frontend/urls-routing/context-aware-canonical-preferred-and-navigationstateful-urls
Section: Frontend
Category *