Enable Freemarker Template Support

Bloomreach Content projects created with the Maven archetype include Freemarker support by default. If you need to enable or disable Freemarker manually, follow the steps below. This guide assumes you are starting from an empty project and have checked out and built HST from the source repository. If you used the archetype (Get Started Trail), Freemarker support is already enabled.

Enable Freemarker Template Support

To enable Freemarker support, update your web.xml file in the site/webapp submodule (site/webapp/src/main/webapp/WEB-INF/web.xml) with the following servlet declaration:

<servlet>
    <servlet-name>freemarker</servlet-name>
    <servlet-class>org.hippoecm.hst.servlet.HstFreemarkerServlet</servlet-class>
    <!-- FreemarkerServlet settings: -->
    <init-param>
      <param-name>TemplatePath</param-name>
      <param-value>/</param-value>
    </init-param>
    <init-param>
      <param-name>ContentType</param-name>
      <param-value>text/html; charset=UTF-8</param-value>
      <!-- Forces UTF-8 output encoding! -->
    </init-param>
    <!--
      'template_exception_handler' determines what Freemarker does when it encounters an error:
      - "ignore" lets Freemarker log an exception and then continue rendering.
      - "debug" lets Freemarker log a stack trace, stops rendering and re-throws the exception.
      - "rethrow" does not let Freemarker log a stack trace, stops rendering and re-throws the exception.
      By default, if no template_exception_handler as above is configured, an extended "ignore" type
      template exception handler will be configured which provides additional detail logging but like the
      "ignore" handler will continue rendering.
      <init-param>
        <param-name>template_exception_handler</param-name>
        <param-value>debug</param-value>
      </init-param>
    -->
    <load-on-startup>200</load-on-startup>
</servlet> 
copy

Add the following servlet mapping:

<servlet-mapping>
  <servlet-name>freemarker</servlet-name>
  <url-pattern>*.ftl</url-pattern>
</servlet-mapping>
copy

Next, update the root pom.xml to include the Freemarker Maven dependency in the dependencyManagement section:

<dependency>
  <groupId>org.freemarker</groupId>
  <artifactId>freemarker</artifactId>
  <version>${freemarker.version}</version>
</dependency>
copy

The ${freemarker.version} property is already defined by the Hippo hippo-cms7-project parent POM.

Add the Freemarker dependency to the site-components POM (/site/components/pom.xml):

<dependency>
  <groupId>org.freemarker</groupId>
  <artifactId>freemarker</artifactId>
</dependency>
copy

After completing these steps, Freemarker support is enabled.

Configure Freemarker Template Exception Handling

By default, HstFreemarkerServlet logs errors and continues rendering when a Freemarker template error occurs. You can control this behavior by configuring the servlet in web.xml. To log a stack trace and re-throw exceptions (which stops rendering), configure the servlet as follows:

<servlet>
  <servlet-name>freemarker</servlet-name>
  <init-param>
    <param-name>TemplatePath</param-name>
    <param-value>/</param-value>
  </init-param>
  <init-param>
    <param-name>ContentType</param-name>
    <param-value>text/html; charset=UTF-8</param-value>
  <init-param>
    <param-name>template_exception_handler</param-name>
    <param-value>debug</param-value>
  </init-param>
  <load-on-startup>200</load-on-startup>
</servlet>
copy

Supported values for template_exception_handler:

1. debug
2. html_debug
3. ignore
4. rethrow

If you do not configure template_exception_handler, the servlet uses an extended "ignore" handler by default. This handler provides additional logging and continues rendering.

For more details, refer to the Freemarker Configurable API documentation.