Delivery Tier URLs

Introduction

Bloomreach Experience Manager's delivery tier (HST) provides URL creation out-of-the-box. It takes care of including or excluding the context path, hence, should be used for every URL, also for static resources like CSS. This way the HST application can be deployed as for example site.war, but does not show the /site context path in the URL. Combined with Apache HTTP Server configured as reverse proxy the HST can serve any scheme ( http/https), domain and port and can be deployed with any context path:

The HST creates out-of-the-box URLs for a page, a repository binary resource or a container resource (like CSS or image). The HST supports link rewriting to URLs for internal links between Hippo Documents stored in Hippo Repository. The HST does this automatically, based on the configuration of the SiteMap: It is the Request Matching reversed. For link rewriting the HST supports by default:

1. Cross Domain / Multi Site URLs : URLs between subsites, even with different domains
2. Cross Scheme : URLs from http to https and vice versa. Even cross domain and cross scheme links combined are supported.
3. Channel Aware URLs : mobile URLs stay within the mobile channels, while the URLs same content for the normal website stays within the website
4. Context Aware URLs : URLs for one and the same document can be different according the context of the current URL
5. Canonical URLs : A URL that is independent of the context of the current URL (highly appreciated by search engines like Google, Yahoo, see canonical links)
6. Preferred URLs : URLs for a specific part of the SiteMap only
7. NavigationStateful URLs : URLs taking the current navigation state into account, for example to get a URL in the context of the current faceted navigation location.

In a HstComponent that extends from the org.hippoecm.hst.component.support.bean.BaseHstComponent, you can access the HstLinkCreator as follows:

public abstract class AbstractSearchComponent extends BaseHstComponent {
    @Override
    public void doBeforeRender(HstRequest request, HstResponse response)
                                             throws HstComponentException {
       // getting hold of the HippoBean for the current request (the
       // resolved sitemap item's its relative content path)
       HippoBean myBean = request.getRequestContext().getContentBean();
       // getting hold of the link creator
       HstLinkCreator linkCreator = request.getRequestContext()
                                                  .getHstLinkCreator();
       // create HstLink
       HstLink link = linkCreator.create(myBean,
                                          request.getRequestContext());
       // create the url String
       String Url = link.toUrlForm(request.getRequestContext(), false);
    }

Most of the time however, you won't need to create a URL in a HstComponent Java class, but rather create one in during the rendering of the template (jsp/freemarker). Therefore, the HST provides a custom tag, the <hst:link> tag. See at the end of this page for all the possible attributes. The <hst:link> tag is a tag that can create URLs for HippoBeans, for JCR nodes, for repository binaries, repository webfiles and for static resources. It automatically includes the context path in the URL when this is needed.

The <hst:link> tag takes an optional attribute var in which the String output is stored. If the attribute is missing, the value is directly written to the rendered output of the template.

Examples of the <hst:link> Tag

Note that out-of-the-box, the examples below for HippoBean are cross-domain, multi-site, context and channel aware!

Create a URL for a HippoBean

Assume you stored some  HippoBean objects in the documents variable below, then the JSP for creating URLs for these documents is:

<ul>
  <c:forEach var="document" items="${requestScope.documents}">
    <li>
        <hst:link var="link" hippobean="${document}"/>
        <a href="${link}">${document.title}</a>
    </li>
  </c:forEach>
</ul>

The same as above in a Freemarker template is as follows:

<ul>
  <#list documents as document>
    <li>
        <@hst.link var="link" hippobean=document/>
        <a href="${link}">${document.title}</a>
    </li>
  </#list>
</ul>

1. If you want a canonical URL, add canonical=true to the link tag.
2. If you want a navigationalStateful URL, add navigationalStateful=true to the link tag.
3. If you want a preferred URL, add a <hst:sitemapitem> child to the <hst:link> tag

Create a URL for a Container Resource (For Example a CSS)

Creating a link to a CSS file:

JSP

<hst:link var="css" path="/css/style.css"/>
<link href="${css}" type="text/css"/>

Freemarker

<@hst.link var="css" path="/css/style.css"/>
<link href="${css}" type="text/css"/>

Create a URL for a Repository Resource when you know the Exact Location

Normally, you access a repository binary resource just like any other JCR node through a HippoBean wrapper. The HST linkrewriting makes sure for the beans correct binary URLs are created. If you want to create a binary URL by pointing to a repository location, this can be done by using the attr path and prefix the absolute repository location by /binaries. Suppose the binary is at /content/assets/mypdfs/test.pdf. Then this will create a repository binary link:

JSP

<hst:link var="link" path="/binaries/content/assets/mypdfs/test.pdf"/>
<a href="${link}">my pdf</a>

Freemarker

<@hst.link var="link" path="/binaries/content/assets/mypdfs/test.pdf"/>
<a href="${link}">my pdf</a>

Create a URL for a siteMapItemRefId

When you have multiple sites in multiple languages, you want to use the same JSP to say, create a hard-coded link to the contact page. However, the URL for the contact page is different for every language because every language has its own HST sitemap. For this purpose, a siteMapItemRefId can be used. Every sitemap should then have the contact sitemap item set to the same hst:refId. So, suppose every sitemap item for the contact page in every language has hst:refId = 'contactId'. Then the following code snippet creates the correct URL for each language:

JSP

<hst:link var="link" siteMapItemRefId="contactId"/>
<a href="${link}"><fmt:message key="key.contact"/></a>

Freemarker

<@hst.link var="link" siteMapItemRefId="contactId"/>
<a href="${link}"><fmt:message key="key.contact"/></a>

Create a URL for a Specific Site

By default, the HST will always try to create a URL within the current site. If instead you want to explicitly specify the site to create the URL for, you can use the mount parameter in the hst:link tag.

First, make sure the mount for the site you want to link to has an alias defined. For example:

/hst:hst/hst:hosts/dev-localhost/localhost:
  /hst:root:
    jcr:primaryType: hst:mount
    hst:alias: english-website

Then taking the previous example and changing it to always, within every site, link to the contact page on the English website, the code snippet becomes:

JSP

<hst:link var="link" mount="english-website" siteMapItemRefId="contactId"/>
<a href="${link}"><fmt:message key="key.contact"/></a>

Freemarker

<@hst.link var="link" mount="english-website" siteMapItemRefId="contactId"/>
<a href="${link}"><fmt:message key="key.contact"/></a>

Create a URL for the Current Page or Current Matched Sitemap Item

Frequently, you just need to create a URL for the current page you are at, only without request parameters. For example, if you are on a search result URL http://localhost:8080/site/search?query=foo_ and you want to go clear the search, thus go back to http://localhost:8080/site/search. You can achieve this by using the hst:link tag without path, subPath, hippobean, or siteMapItemRefId attribute. The simplest way is:

JSP

<hst:link var="link"/>
<a href="${link}">Link for currently matched sitemap item</a>

Freemarker

<@hst.link var="link"/>
<a href="${link}">Link for currently matched sitemap item</a>

Create a fullyQualified URL

When your URL needs to include the scheme, host and possibly portnumber, you can use the fullyQualified attribute.

JSP

<hst:link var="link" hippobean="${requestScope.myBean}" fullyQualified="true"/>
<a href="${link}">fully qualified link</a>

Freemarker

<@hst.link var="link" hippobean=myBean fullyQualified=true />
<a href="${link}">fully qualified link</a>

Create a Canonical URL

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 HST2? 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 />