Context Aware, Canonical, Preferred and navigationStateful URLs

Context Aware URLs

Out-of-the-box, and by default, the HST creates context aware urls for your Content Beans. What does this mean?

It means, that if one and the same content bean can be translated to two equally well suited URLs, then, the URL that matches the current context best, is taken.

So, assume, the content node at /documents/content/news/2009/mynewsitem can have a url as:

/news/2009/mynewsitem

but also

/eu/climate/news/2009/mynewsitem

where the myitem is linked to eu climate subject, hence is also to be found at this part of the website.

If we assume the following sitemap items parts:

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

Now, you can see, that

/eu/*/news/*/**

is equally well suited to be a url for a newsitem as

/news/*/**

So, what does the HST do for you? By default, the link being created, when equally suited for multiple sitemap items we return the one 'closest' to the current context! For the exact implementation of closest you can take a look at the javadocs of LocationMapResolver.

So, when I would browse to /eu/climate/news and I would have some news archive over there, then the url for 'mynewsitem' would be

/eu/climate/news/2009/mynewsitem

On the other hand, if I would browse to /news/2009, and would look at the link for 'mynewsitem', it would be

/news/2009/mynewsitem

Canonical URLs

Search engines do not like to index the almost same html page at different URLs. Most engines (for example Yahoo, Google, Bing) support for this the concept of canonical links, see for example http://googlewebmastercentral.blogspot.com/2009/02/specify-your-canonical.html. So, suppose in our example of /eu/climate/news/2009/mynewsitem and /news/2009/mynewsitem, then, the html of /eu/climate/news/2009/mynewsitem could contain:

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

It means, that you indicate that search engines can find the canonical page, the page they should index, for this page at /news/2009/mynewsitem.

So, how do we achieve this in the HST? Really simple: If you use:

JSP

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

Freemarker

<@hst.link hippobean=document/>

you by default get the Context Aware link. If you want the canonical version, just tell the hst:link to do so as follows:

JSP

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

Freemarker

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

By default, when there are multiple URLs possible, we return the shortest possible one to be the canonical. If two URLs are equally well, and equally short, we pick one, and make sure the canonical is always this one.

Preferred URLs

You can prefer some sitemap subtree to first be used to create a URL for a Content Bean, and then, if not succeeded do or do not have a fallback to the original linkrewriting for the entire sitemap tree. You can also use the canonical="true" version for subtree URL creation. An example:

Suppose you prefer a link being created below the sitemap item at path ' /themes/sometheme'

Then, you can create a hst:link as follows:

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 you do not specify fallback att, the default is true)

Now, we first try to create a URL below /themes/sometheme. If this is not possible, we fallback to original linkrewriting. If fallback would be false, then a notfound will be returned. If you also specift canonical=true on the hst:link, we search for the canonical url in the subtree.

Furthermore, next to the attr preferPath, you could also use preferItemId (the id of the sitemap item) or preferItem (a HstSiteMapItem object). This can be found in the hst-core.tld

NavigationStateful URLs

NavigationStateful URLs are URLs which are created from the current URL and from the contextual location of the repository jcr node: Normal links are created by first taking the canonical location of a document. Note, that the canonical location of a document still possibly results in different URLs because of Context Aware URLs, see above.

NavigationStateful URLs are very useful for faceted navigation, where you might want to create a link for a document in the resultset in the context of the current faceted navigation. NavigationStateful links can also be used when you'd like to link to some mirrored document in the context of the current document, thus in context of the current URL.

You create a context relative URL as follows:

JSP

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

Freemarker

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

NavigationStateful URLs also repeat the queryString if it exists in the current URL.