Enable Freemarker template support

Bloomreach Experience Manager projects created from the Maven archetype have Freemarker support built-in by default, but there are cases where you may want to enable or disable this feature manually. This page walks you through the procedure of enabling the Freemarker support. It is assumed that you are starting a new empty project and have successfully checked out and built HST from our source repository. If you started with the archetype (Get Started Trail) then note that Freemarker support is already enabled.

Enabling Freemarker Templates Support

Add the following servlet declaration and mapping to the web.xml of the site/webapp submodule ( site/webapp/src/main/webapp/WEB-INF/web.xml)

<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> 

and

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

Modify the root pom.xml and add the Freemarker Maven dependency to the dependencyManagement section.

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

Note that the Hippo hippo-cms7-project parent pom already defines the ${freemarker.version} property. 

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

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

That's it! Freemarker support is enabled.

Handling Freemarker Template Exception

HstFreemarkerServlet is by default configured to only log errors and to continue rendering after an error. It is possible to control these behaviours when there are errors in the freemarker template sources through configuring this in the web.xml for the HstFreemarkerServlet. To configure the HstFreemarkerServlet to log a stack trace and re-throw an exception (which will stop rendering!), you can 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>

The possible values for template_exception_handler are:

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

Note: when no template_exception_handler is configured, an extended "ignore" type template exception handler will be configured which provides additional detail logging (beyond what Freemarker itself logs) but like the "ignore" handler will continue rendering. 

Also see http://freemarker.sourceforge.net/docs/api/freemarker/core/Configurable.html.