Troubleshoot Static Webapp Resources

Introduction

Goal

Solve common problems related to serving static webapp resources in a Hippo project.

Background

This document describes common problems related to serving static webapp resources in a Hippo project, and their solutions. Static webapp resources are files that are located at, in case you website webapp is called site :

{project}/site/src/main/webapp

For example:

{project}/site/src/main/webapp/css/style.css

New file with new extension does not get rendered by browser

To make the (HST) site also able to render newly added extensions, make sure you add a hst:default sitemap matcher for the extension at the Default Inherited Configuration. By default, the delivery tier (HST) renders the following extensions:

+ hst:hst
  + hst:configurations
    + hst:default
      + hst:sitemap
        + _any_.css
        + _any_.CSS
        + _any_.gif
        + _any_.GIF
        + _any_.ico
        + _any_.ICO
        + _any_.jpeg
        + _any_.JPEG
        + _any_.jpg
        + _any_.JPG
        + _any_.js
        + _any_.JS
        + _any_.pdf
        + _any_.PDF
        + _any_.png
        + _any_.PNG
        + _any_.svg
        + _any_.SVG
        + _any_.jsp
        + _any_.JSP

where _any_ stands for a catch all ** matcher.

Solution

You need to bootstrap an extra sitemap item. For example, _any_.swf  that contains the same properties as _any_.css if you also want to have the site serve SWF files. 

Static webapp files below some folder do not get rendered correctly

This is a known rare condition which happens only in sitemap setups (explicit item followed by _any_ catch-all matcher) combined with static webapp folders that are equal to the explicit sitemap item. Assume the following sitemap configuration for the project  example.

+ hst:hst
  + hst:configurations
    + example
      + hst:sitemap
        + news
          + _any_

Thus, an explicit sitemap matcher news, followed by a catch-all. Now, also assume a static webapp folder containing  example.png as follows:

{project}/site/src/main/webapp/news/example.png

A URL for this image created by <hst:link path="/news/example.png"/> looks something like :

http://localhost:8080/site/news/example.png

When matching the above URL in the HST to a sitemap item, instead of matching the _any_.png matcher in the hst:default/hst:sitemap it matches news/_any_ in the example/hst:sitemap, and most likely, this matcher does not render the image correctly. The reason why it matches the wrong sitemap item is that  explicit matchers have precedence over wildcard matchers, see SiteMapItem Matching. 

Solution

Do not use static webapp folders with names that are equal to  explicit sitemap items that are followed by a _any_ or _default_ matcher. It is not considered to be a bug in the HST, but an unsupported setup.