HST Freemarker Support

Overview

The Hippo Site Toolkit (HST) provides support for Freemarker templates as a templating engine. You can load Freemarker templates from several locations:

Repository web files (available since CMS 10.0)
The web application (webapp)
The classpath
Repository JCR nodes

If your application does not yet support Freemarker templates, see Enabling Freemarker Template Support.

This page assumes that Freemarker support is enabled for files with the .ftl extension. The recommended location for storing and loading Freemarker templates is the repository web files. For more information, see Web Files Introduction.

Loading Freemarker Templates from Repository Web Files

Store Freemarker templates as files in your project's repository bootstrap configuration. For example:

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

Reference the layout.ftl template in your HST configuration as follows:

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

Loading Freemarker Templates from the Web Application

You can store Freemarker templates in your web application, similar to JSP files. For a single web application or page, you can render some parts with Freemarker templates and others with JSPs. For example, your web application might include the following structure:

/webapp:
  /WEB-INF:
    /ftl:
      /layout.ftl:
      /home.ftl:
    /jsp:
      /detail.jsp:
      /footer.jsp:

To use a Freemarker template from a repository-stored hst:template, reference it as you would a JSP file:

/hst:hst:
  /hst:configurations:
    /myproject:
      /hst:templates:
        /layout:
          hst:renderpath: ftl/layout.ftl

Loading Freemarker Templates from the Classpath

If the layout.ftl Freemarker template is packaged in a JAR located in the web application's lib directory, and the template is at:

org/example/builtin/ftl/layout.ftl

Reference this template in your hst:template by prefixing the path with classpath:/:

/hst:hst:
  /hst:configurations:
    /myproject:
      /hst:templates:
        /layout:
          hst:renderpath: classpath:/org/example/builtin/ftl/layout.ftl

You can also load the template relative to the HstComponent class that dispatches to the renderer. In this case, use classpath: (without a trailing slash). For example, if your HstComponent class is located at /org/example/builtin/MyComponent.class, set the render path as follows:

hst:renderpath = classpath:ftl/layout.ftl

Loading Freemarker Templates from the Repository HST Configuration

To enable runtime changes to your templates, HST supports loading Freemarker templates directly from the repository. Templates are loaded once and cached. When a template changes in the repository, it is automatically reloaded.

Store the template content in the hst:script property of the hst:template node. The node name must end with .ftl. For example:

/hst:hst:
  /hst:configurations:
    /myproject:
      /hst:templates:
        /layout.ftl
          jcr:primaryType: hst:template
          hst:script:
               <#assign hst=JspTaglibs[
                    "http://www.hippoecm.org/jsp/hst/core"]>
                 <html>
                    <head>
                      <@hst.headContributions categoryExcludes="scripts" />
                    </head>
                    <body>
                      <div id="custom-doc" class="yui-t6">
                        <@hst.include ref="body"/>
                        <@hst.include ref="footer"/>
                       </div>
                    </body>
                 </html>

Note: The hst:template node must have a name ending with .ftl when using the hst:script property for Freemarker scripts.

Alternative: Loading Freemarker Templates from a JCR Property

As an alternative to using the hst:script property, you can use the hst:renderpath property with a value that starts with jcr: followed by the absolute repository path to the property containing the Freemarker template. The property name must end with .ftl. For example:

/hst:hst:
  /hst:configurations:
    /myproject:
      /hst:templates:
        /layout:
         hst:renderpath: jcr:/templates/freemarker/layout/script.ftl