Bloomreach

Bloomreach Documentation version

HST Freemarker support

Introduction

The Hippo Site Toolkit supports freemarker templates as a templating engine. Freemarker templates can be loaded from

  1. Repository web files (as of CMS 10.0)
  2. The webapp
  3. The classpath
  4. Repository JCR Nodes

If you do not yet have freemarker support in your application, see Enabling freemarker template support.

The rest of this page assumes you have freemarker support enabled for the *.ftl extension. The preferred location to store and load freemarker templates from are the Repository web files, also see Web Files Introduction.

Load freemarker templates from repository web files

In this scenario, you store the freemarker templates as files in your projects repository bootstrap configuration, for example at 

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

and from the HST configuration, you refer to the above  layout.ftl as follows:

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

Load freemarker templates from webapp

You can store freemarker templates in your webapp just like JSPs . For a single webapp and even for a single page, you can have parts of the page rendered by freemarker templates and parts rendered by JSPs'. Assume you have the following freemarker templates in your webapp.

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

To use such a freemarker template from a repository-stored hst:template, you can refer to it just like you would refer to a JSP. For example:

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

Load freemarker templates from the classpath

Assume the freemarker template layout.ftl is not located below webapp/WEB-INF but is part of a jar that is located in the webapp lib directory. Assume the template in the jar is located at

org/example/builtin/ftl/layout.ftl

Using this template from a hst:template can be done by prefixing the location with classpath:/. Thus the above example for layout.ftl would become:

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

Note that you can also load the template relative to the HstComponent class that dispatches to the renderer by not using classpath:/ but classpath: without trailing /. Thus in the example above, if your HstComponent class is located at /org/example/builtin/MyComponent.class, then the renderpath can be hst:renderpath = classpath:ftl/layout.ftl

Load freemarker templates from the repository hst configuration

When you want to be able to make changes to your templates at runtime: HST supports loading freemarker templates from the repository. The templates are loaded only once, and are then cached until the template changes in the repository, at which time they are automatically reloaded.

Loading a freemarker template from the repository is very simple if you store the template in the hst:template node itself as hst:script. Using the property hst:script however requires that the template node name ends with .ftl.

hst:template nodes that have a hst:script property containing a freemarker script must have name that ends with .ftl

For example, loading the layout freemarker template from the repository would result in the following repository configuration:

/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>
Don't forget to include the JspTagLibs above

Alternative loading freemarker template from repository

Note that an alternative to having a template ending with .ftl and a hst:script property is to still use the hst:renderpath but have it start with jcr: followed by the absolute repository path to the property that contains the freemarker template. This property name however must end with .ftl. Thus for example:

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

 

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?