Customize Link Processing
On this page
Introduction
Goal
Customize how internal links are processed in Hippo's delivery tier.
Background
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.
HstLinkProcessor
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).
Example
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:
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:
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.
Solution
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.
Implementation
HstLinkProcessor Implementation
site/src/main/java/org/example/ExampleHstLinkProcessor.java
Spring Configuration
site/src/main/resources/META-INF/hst-assembly/overrides/customLinkProcessors.xml