Exclude a URL from Being Served by Hippo CMS
In a Hippo CMS site, all URLs are under its control. Using the sitemap configuration, you can to some extent influence how URLs will map to content but there's no obvious or well-documented way to make Hippo CMS ignore the URL and let it be processed by a different servlet.
I had to achieve this when I was integrating the OWASP CSRFGuard library with Hippo CMS in order to prevent CSRF (Cross-Site Request Forgery) attacks in the forms served by Hippo CMS. The CSRFGuard library can serve a JavaScript file tailored to your configuration which will dynamically inject CSRF tokens into the forms on your pages.
This is done by a servlet which you need to configure in your web.xml file. No matter where in the file you place the required <servlet> and <servlet-mapping> elements, Hippo CMS will still handle all the requests including those configured in the CSRFGuard <servlet-mapping> element, i.e. /JavaScriptServlet by default:
<servlet-mapping>
<servlet-name>JavaScriptServlet</servlet-name>
<url-pattern>/JavaScriptServlet</url-pattern>
</servlet-mapping>
If this URL won't map to any CMS content (which should usually be the case), then Hippo will serve its 404 (Page Not Found) error page.
Fortunately, there is a way to prevent that. In the fixed default channel configuration you can add entries for which the requests will be delegated to the configured container servlet. You can base this configuration on the default matchers for the static files. The following entry will instruct Hippo to forward the request for the CSRFGuard JavaScript file from the <servlet-mapping> configuration above to JavaScriptServlet:
/hst:hst/hst:configurations/hst:default/hst:sitemap/JavaScriptServlet:
jcr:primaryType: hst:sitemapitem
hst:containerresource: true
The key part of the sitemap configuration is the hst:containerresource property being set to true. This property can only be used in the default channel configuration and will apply to all channels in your Hippo CMS instance. If you try to use the same property in any other channel, then the sitemap entry will be ignored and the following error will be emitted:
[HstSiteMapService.<init>:87] Skipping sitemap item '/hst:hst/hst:configurations/mychannel/hst:sitemap/JavaScriptServlet' : 'Invalid sitemap item configuration for '/hst:hst/hst:configurations/mychannel/hst:sitemap/JavaScriptServlet'. A sitemap item is only allowed to be marked with 'hst:containerresource = true' if the sitemap item is located in '/hst:default/hst:sitemap/'.'
I don't find this too restrictive. At least in my scenario, there's no harm if the JavaScript file will be served at this URL even if a particular channel doesn't use it.
