Use Web Files

Overview

This page describes how to reference web files in templates and how to store Freemarker templates as web files in Bloomreach Content.

Web Files Overview

Web Files are static resources such as CSS, JavaScript, and Freemarker templates stored in the content repository. This page covers:

• Web files storage location
• Referencing web files in templates
• Storing Freemarker templates as web files

Project Setup for Web Files

Projects created with the Maven archetype are preconfigured to use web files.

If you are working with an older project, upgrade to web files as part of the upgrade to Hippo 10. (Upgrade instructions: link not available.)

The default configuration is sufficient for most use cases. For advanced scenarios, see:

• Configure Web Files
• Secure Web Files
• Web Files Best Practices
• Web Files Troubleshooting

Web Files Storage Location

Each web application uses its own web file bundle. The bundle name matches the web application context (for example, "site" for the site.war application). A web file bundle contains files and directories, which you can organize hierarchically. Web files are referenced by their path relative to the bundle root, such as /css/style.css.

In a standard project, the site's web file bundle is located at:

repository-data/webfiles/src/main/resources/site

Organize web files by type in subfolders under site, such as css, js, fonts, and freemarker.

When you start the application, web files are bootstrapped into the content repository at /webfiles/site.

During local development, modifying web files on the file system triggers automatic synchronization with the repository and reloads affected pages in open browsers.

Note: Keep the repository-data-webfiles module and its web files under version control along with other project source files.

Reference Web Files in Templates

Ensure the HST tag library is available in your template. Typically, you include a generic "imports" template.

Freemarker

<#include "../include/imports.ftl">
copy

JSP

<%@ include file="/WEB-INF/jsp/include/imports.jsp" %>
copy

Use the hst:webfile tag to reference resources in the web file bundle.

Freemarker

<@hst.webfile var="link" path="/js/script.js" />
<script src="${link}" />
copy

JSP

<hst:webfile var="link" path="/js/script.js" />
<script src="${link}" />
copy

This produces markup similar to:

<script src="/webfiles/<anti-cache>/js/script.js" />
copy

The <anti-cache> segment is generated automatically when the bundle changes. This mechanism prevents browsers from using outdated cached web files while still allowing long-term caching. All web files receive an 'Expires' header set to one year.

To enable stable web file URLs (for example, for server-side applications needing persistent URLs), see Web Files Stable URLs.

Store Freemarker Templates as Web Files

You can store Freemarker templates as web files. Template filenames must end with .ftl. For example, to render the main layout of your web pages using the template /ftl/layout/webpage.ftl, store it at:

/repository-data:
  /webfiles:
    /src:
      /main:
        /resources:
          /site:
            /ftl:
              /layout:
                /webpage.ftl:

To reference a Freemarker web file in a template configuration node, set the hst:renderpath property to a value starting with webfile:, followed by the web file path:

/hst:hst:
  /hst:configurations:
    /myproject:
      /hst:templates:
        /layout.webpage:
          hst:renderpath: webfile:/ftl/layout/webpage.ftl
copy

The value webfile:/ftl/layout/webpage.ftl is a shorthand for jcr:/webfiles/site/ftl/layout/webpage.ftl. Use the webfile: notation to let the system resolve the storage location and application context automatically.

Live Reload: Automatically Reload Browsers When Web Files Change

During local development, updating a web file automatically reloads all browser pages rendering a Bloomreach Content site.

Enable or disable auto-reload with the following configuration property:

/hippo:configuration/hippo:modules/autoreload/hippo:moduleconfig:
  enabled: true
copy

Changes to this property take effect immediately.

Verify Auto-Reload Status

Auto-reload status is logged when Tomcat starts and whenever you enable or disable it. Example log output:

[INFO] [talledLocalContainer] 09:44:53 Automatic reload of browsers is enabled

Auto-reload also writes debug messages to the browser's JavaScript console:

Warning: Auto-reload is not supported when using a reverse proxy, such as when configuring Apache HTTP Server as a reverse proxy.

Warning: Do Not Use Auto-Reload in Production
Auto-reload is only available when the file hippo-service-autoreload-<version>.jar is present in Tomcat's shared/lib directory. During local development, the Cargo plugin configuration in the Bloomreach Content release pom manages this automatically. In production, do not include the auto-reload JAR in any Tomcat or web application library folders. If present, each visitor will attempt to establish a WebSocket connection to the server.

Technical Details

Auto-reload requires browsers that support WebSockets. Each browser connects to a WebSocket server running in Tomcat and reloads the current page when notified by the server.

If Tomcat is stopped, auto-reloading browsers attempt to reconnect for 10 minutes. If Tomcat restarts within that period, browsers reconnect and resume auto-reloading. After 10 minutes, the script stops trying. To resume, manually refresh the browser.

Note: The delivery tier automatically adds the auto-reload script to the head contributions of the site. To enable auto-reload, ensure the <hst:headContributions> tag is present in the template of the top-level page component.