Introduction

This modules provides means to use the  FreeMarker template engine (www.freemarker.org) from within OpenCms. The module includes glue logic that allows FreeMarker to read templates from OpenCms' virtual file system as well as wrappers for the core OpenCms objects so these can be accessed from within FreeMarker templates.

The markup syntax used the FreeMarker is easier to edit with a plain HTML editor than when writing the markup with JSP. This makes it possible for content editors to edit the templates. Also, since it is focused on presentation, the user is "sandboxed" and does not have access to the full functionality that is provided by JSP.

A good example of its usage would be templates for confirmation emails and the like. FreeMarker is actually very capable and can do more than just these simple tasks, but this module is not intended to provide an alternative to the OpenCms' default JSP templating mechanism, even if FreeMarker itself could be used as such.

Integration

The most basic integration provided by this module, is the VFSTemplateLoader class which enables FreeMarker to load its template files from OpenCms' virtual filesystem.

Simply instantiate it with the CmsObject and the "root"-directory (this is the directory from which FreeMarker loads templates):

TemplateLoader loader = new VFSTemplateLoader(cmsObject, "/a/VFS/folder/with/templates/");

The other important part of the integration is the CmsHash class which provides access to some basic OpenCms information from within the FreeMarker template:

CmsHash root = new CmsHash(cmsObject);
Configuration cfg = new Configuration();
cfg.setTemplateLoader(new VFSTemplateLoader(cmsObject, "/a/VFS/folder/with/templates/));
cfg.setLocalizedLookup(false);
Template template = cfg.getTemplate("template.html", "ISO-8859-1");
template.process(root, out);

Assuming that the "template.html" contains the following:

<html>
  <body>
    <p>
      The title of this
      <a href=" ${cms.link(cms.info('opencms.request.uri'))}">
        resource
      </a>
      is: <b> ${localProperties.Title}</b>
    </p>
  </body>
</html>

This will write out the title of the VFS file and insert a link to itself.

The above uses  FreeMarker from scriplet code. It is also possible to use the FreeMarker tag-lib. Please refer to the examples provided in the modules doc-folder.

Documentation

The module includes a readme file as well as a couple of example on how to use the OpenCms-specific features. The document for FreeMarker itself is available from www.freemarker.org.

License

This module and source code is licensed under the GNU Lesser General Public License, see http://www.gnu.org/licenses/lgpl.html for more information.

This module is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Download

OpenCms 6:  com.codedroids.oc.freemarker_1.0.1.zip (appr. 30 KBytes)

Source code:  com.codedroids.oc.freemarker_1.0.1-src.zip (appr.  34 KBytes)

OpenCms 5: please contact us for further info.

If you have comments or suggestions you are welcome to email them to us (support@codedroids.com) but we cannot guarantee that we will act upon them or even respond to them.
If you need to get some issue solved or a new feature added we do provide consulting and support at reasonable rates, you can contact us here.

If you want to be informed when a new version of this or other of our modules are released, you can sign up to receive our Tech newsletter.

Dependencies

This module requires the freemarker.jar which is not a part of the OpenCms 6 distribution:

freemarker.jar - download it from the FreeMarker web site. You may also want to download the fmtag.tld file.

The module has been tested with FreeMarker version 2.3.8.

Installation

Makes sure that the freemarker.jar is placed in ... opencms/WEB-INF/lib/-folder (replace "opencms" with whatever appropriate if you have installed OpenCms under a different name).

If you plan to use the FreeMarker taglib place the fmtag.tld in the ...opencms/WEB-INF/-folder.

Then install this module via the Module Management in the Administrative view in OpenCms.

Restart the instance or you servlet container and you should be ready to go. You can test the installation with the examples provided in the modules docs-folder (note that example 3 uses the FreeMarker taglib).