Troubleshoot Static Webapp Resources

Overview

This page addresses common issues when serving static webapp resources in a Bloomreach Content (formerly Hippo) project.

Static webapp resources are files located in the following directory, assuming your web application module is named site:

{project}/site/webapp/src/main/webapp

For example, a CSS file would be located at:

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

New File with Unrecognized Extension Not Rendered

When you add a static file with a new extension, the site may not serve it unless you update the sitemap configuration. By default, the delivery tier (HST) only serves files with certain extensions. The default configuration includes:

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

In this configuration, _any_ acts as a catch-all (**) matcher for the specified file extensions.

Resolution

To serve files with a new extension (for example, .swf), add an additional sitemap item such as _any_.swf to your configuration. Use the same properties as an existing static file matcher like _any_.css. For more information, see Default Inherited Configuration.

Static Webapp Files in Certain Folders Not Rendered Correctly

This issue occurs when a static webapp folder shares its name with an explicit sitemap item that is followed by a catch-all matcher (such as _any_). For example, consider the following sitemap configuration for a project named example:

/hst:hst:
  /hst:configurations:
    /example:
      /hst:sitemap:
        /news:
          /_any_:
copy

Here, news is an explicit sitemap matcher, followed by a catch-all.

If you place a static file at:

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

and generate a link using <hst:link path="/news/example.png"/>, the resulting URL is:

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

When the HST processes this URL, it matches the explicit news/_any_ sitemap item in the example/hst:sitemap configuration, instead of the _any_.png matcher in the hst:default/hst:sitemap. As a result, the image may not be rendered correctly. Explicit sitemap matchers always take precedence over wildcard matchers. For details, see SiteMapItem Matching.

Resolution

Avoid creating static webapp folders with names that match explicit sitemap items followed by a _any_ or _default_ matcher. This setup is not supported and may cause static resources to be served incorrectly. This behavior is by design and not considered a bug in the HST.