This article covers a Bloomreach Experience Manager version 11. There's an updated version available that covers our most recent release.

Customize Link Processing



Customize how internal links are processed in Hippo's delivery tier.


Hippo is a content-oriented system and therefore its delivery tier must map documents to pages in a sitemap. Internal links within a site are created and resolved using this mapping. This process of creating and resolving links provides an extension point through the HstLinkProcessor interface. By implementing this interface developers can pre-process and/or post-process internal links.


The org.hippoecm.hst.core.linking.HstLinkProcessor interface defines two methods:

  • HstLink postProcess(HstLink link)
    Called after the delivery tier creates a link through org.hippoecm.hst.core.linking.HstLinkCreator.

  • HstLink preProcess(HstLink link)
    Called before the delivery tier matches a link through org.hippoecm.hst.core.request.HstSiteMapMatcher.

The delivery tier uses a chain of link processors. Any number of custom link processors can be added to the chain through Spring configuration (see example below).

HstLinkProcessor implementations must be thread-safe. In other words, they must not maintain state in member variables or otherwise.‚Äč


Use Case

Consider a project created from Hippo's Maven archetype with the Simple Content feature added.

Documents of type myhippoproject:contentdocument are stored in the repository folder /content/documents/myhippoproject/content.

These documents are mapped to a URL and page template through the following sitemap items:

  + content [hst:sitemapitem]
    - hst:componentconfigurationid = hst:pages/contentlist
    - hst:relativecontentpath = content
    + _any_.html [hst:sitemapitem]
      - hst:componentconfigurationid = hst:pages/contentpage
      - hst:relativecontentpath = ${parent}/${1}

As a result, a document /content/documents/myhippoproject/content/sample-document would be available at the URL http://localhost:8080/site/content/sample-document.html.

Now suppose you organize your simple content documents using subfolders with names corresponding to the first character of the names of documents inside them. For example:

  + content [hippostd:folder]
    + a [hippostd:folder]
      + about-hippo [hippo:handle]
      + archetype [hippo:handle]
    + b [hippostd:folder]
      + best-practices [hippo:handle]
      + big-hippo [hippo:handle]
    + c [hippostd:folder]
      + code-formatting [hippo:handle]
      + create-project [hippo:handle]

This means that these documents will be available at URLs like http://localhost:8080/site/content/a/about-hippo.html, http://localhost:8080/site/content/b/best-practices.html etc.

However your requirements state that the URLs should not contain the subfolder name and look like http://localhost:8080/site/content/about-hippo.html, http://localhost:8080/site/content/best-practices.html etc.

This is a typical use case for a custom link processor.


The solution is to implement org.hippoecm.hst.core.linking.HstLinkProcessor as follows:

  • For any link created with a relative path starting with content/,  e.g. content/a/about-hippo, remove the subfolder path element (a/) so it becomes e.g. content/about-hippo and meets your URL requirements.
  • For any link matched in the sitemap with a relative path starting with content/, e.g. content/about-hippo, add the subfolder path element based on the first character of the path element following content/, so it becomes e.g. content/a/about-hippo and matches the relative content path of the document.


HstLinkProcessor Implementation


package org.example;

import java.util.regex.Matcher;
import java.util.regex.Pattern;

import org.hippoecm.hst.core.linking.HstLink;
import org.hippoecm.hst.linking.HstLinkProcessorTemplate;

public class ExampleHstLinkProcessor extends HstLinkProcessorTemplate {

    protected HstLink doPostProcess(HstLink link) {
        String path = link.getPath();
        if (path.startsWith("content/")) {
            String pattern = "(content/)./(.+)";
            Pattern r = Pattern.compile(pattern);
            Matcher m = r.matcher(path);
            if (m.find()) {
                path = m.replaceAll("$1$2");
        return link;

    protected HstLink doPreProcess(HstLink link) {
        String path = link.getPath();
        if (path.startsWith("content/")) {
            String pattern = "(content)(/.)(.?)";
            Pattern r = Pattern.compile(pattern);
            Matcher m = r.matcher(path);
            if (m.find()) {
                path = m.replaceAll("$1$2$2$3");
        return link;


Spring Configuration


<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns=""

  <bean id="org.hippoecm.hst.core.linking.HstLinkProcessor" class="org.hippoecm.hst.core.linking.HstLinkProcessorChain">
    <property name="processorsInChain">
        <bean class="org.example.ExampleHstLinkProcessor" />

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?