HST Freemarker support
The Hippo Site Toolkit supports freemarker templates as a templating engine. Freemarker templates can be loaded from
- Repository web files (as of CMS 10.0)
- The webapp
- The classpath
- 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
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.
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>
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