Delivery Tier URLs

Overview

The delivery tier in Bloomreach Content (HST) provides built-in URL generation. HST manages the inclusion or exclusion of the context path, so you should use HST URL creation for all URLs, including static resources such as CSS files. This approach allows you to deploy the HST application with a context path (for example, as site.war), while URLs presented to visitors do not expose the /site context path. When combined with an Apache HTTP Server configured as a reverse proxy, HST can serve any scheme (http or https), domain, and port, and can be deployed with any context path.

HST generates URLs for pages, repository binary resources, and container resources (such as CSS or images). It also supports link rewriting for internal links between documents stored in the repository. HST determines these URLs automatically based on the SiteMap configuration, using a process that is the reverse of Request Matching.

By default, HST link rewriting supports:

1. Cross-domain and multi-site URLs: Generate URLs between subsites, even across different domains.
2. Cross-scheme URLs: Generate URLs that switch between http and https. Cross-domain and cross-scheme combinations are supported.
3. Channel-aware URLs: Ensure URLs for mobile channels remain within the mobile context, while URLs for the main website remain within the website channel.
4. Context-aware URLs: Generate different URLs for the same document, depending on the current context.
5. Canonical URLs: Generate context-independent URLs, which are preferred by search engines. See canonical links.
6. Preferred URLs: Generate URLs for a specific part of the SiteMap.
7. Navigation-stateful URLs: Generate URLs that reflect the current navigation state, such as faceted navigation.

Accessing HstLinkCreator in Java Components

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

public abstract class AbstractSearchComponent extends BaseHstComponent {
    @Override
    public void doBeforeRender(HstRequest request, HstResponse response)
                                             throws HstComponentException {
       // Obtain the HippoBean for the current request (resolved from the sitemap item's relative content path)
       HippoBean myBean = request.getRequestContext().getContentBean();
       // Access the link creator
       HstLinkCreator linkCreator = request.getRequestContext()
                                                  .getHstLinkCreator();
       // Create an HstLink
       HstLink link = linkCreator.create(myBean,
                                          request.getRequestContext());
       // Generate the URL string
       String Url = link.toUrlForm(request.getRequestContext(), false);
    }
copy

However, in most cases, you will generate URLs in templates (JSP or Freemarker) rather than in Java classes. HST provides the <hst:link> tag for this purpose. This tag can generate URLs for HippoBeans, JCR nodes, repository binaries, repository webfiles, and static resources. It automatically includes the context path when required.

The <hst:link> tag supports an optional var attribute. If specified, the generated URL is stored in the variable; otherwise, the URL is written directly to the template output.

Examples of the <hst:link> Tag

The following examples demonstrate how to use the <hst:link> tag. By default, these examples produce URLs that are cross-domain, multi-site, context-aware, and channel-aware.

Generate a URL for a HippoBean

If you have a collection of HippoBean objects in the documents variable, you can generate URLs for each document as follows:

JSP

<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>
copy

Freemarker

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

• To generate a canonical URL, add canonical=true to the link tag.
• To generate a navigation-stateful URL, add navigationalStateful=true to the link tag.
• To generate a preferred URL, add a <hst:sitemapitem> child to the <hst:link> tag.

Generate a URL for a Container Resource (e.g., CSS)

To generate a link to a CSS file:

JSP

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

Freemarker

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

Generate a URL for a Repository Resource by Absolute Path

You can generate a binary URL by specifying the absolute repository location, prefixed with /binaries. For example, to link to /content/assets/mypdfs/test.pdf:

JSP

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

Freemarker

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

Generate a URL Using siteMapItemRefId

When supporting multiple sites and languages, you may want to generate a link to a specific page (such as contact) using the same JSP or Freemarker template. The URL for the contact page will differ per language, as each language has its own HST sitemap. Use the siteMapItemRefId attribute, and ensure each relevant sitemap item has the same hst:refId. For example, if each contact sitemap item uses hst:refId = 'contactId':

JSP

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

Freemarker

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

Generate a URL for a Specific Site

By default, HST generates URLs within the current site. To explicitly generate a URL for another site, use the mount attribute in the hst:link tag. First, ensure the mount for the target site has an alias defined. For example:

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

To always link to the contact page on the English website, use:

JSP

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

Freemarker

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

Generate a URL for the Current Page or Matched Sitemap Item

To generate a URL for the current page (excluding request parameters), use the hst:link tag without specifying path, subPath, hippobean, or siteMapItemRefId.

JSP

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

Freemarker

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

Generate a Fully Qualified URL

To generate a URL that includes the scheme, host, and optionally the port number, use the fullyQualified attribute.

JSP

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

Freemarker

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

Generate a Canonical URL

Search engines prefer canonical links to avoid indexing duplicate content. For example, if /eu/climate/news/2009/mynewsitem and /news/2009/mynewsitem refer to the same content, the canonical link should point to /news/2009/mynewsitem:

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

By default, the hst:link tag generates a context-aware link:

JSP

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

Freemarker

<@hst.link hippobean=document />
copy

To generate the canonical version, set canonical="true":

JSP

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

Freemarker

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

Note: For complete documentation of the hst:link tag, refer to the HST Tag Library documentation.