FreeMarker OpenCms integration

This module provides the glue needed to work with FreeMarker (www.freemarker.org) inside OpenCms.

Why use FreeMarker, why not use JSP or taglibs? Well, the most important thing is that the MS WYSIWYG-editor mostly leaves the ${...} intact, which cannot be said for scriplets nor taglib-markup.

The usage of ${...} markup also seems to go well with non-programmers for the simpler tasks. We're using FreeMarker for email-templates and the like which the user can edit themselves.

FreeMarker is fairly complex and can do a lot more than just mangling email-templates, but that is left as an exercise for the reader :-)

Most important bit is the VFSTemplateLoader which provides a FreeMarker template loader that works with OpenCms virtual filesystem.

Simply instantiate it with the current CmsObject and the "root"-directory (this is the directory from which FreeMarker loads templates, note that FreeMarker only accepts relative paths when loading templates - see examples):

CmsJspActionElement cms = new CmsJspActionElement(pageContext, request, response);
CmsObject cmso = cms.getCmsObject();
TemplateLoader loader = new VFSTemplateLoader(cmso, "/system/modules/com.codedroids.oc.freemarker/docs/");

The CmsHash class extends FMs SimpleHash to provide convenient access to various information from the request and resource in question. The 'root' of the information contains:

cms
utils
resource
request
parameters
properties
localProperties

They are all hash'es, except for the resource which is a CmsResource object wrapped by the bean wrapper. For that you access methods accordingly.

The cms-hash holds a number of methods allowing access to basic information from the CmsJspActionElement:

link
property
user
info

The utils-hash holds convenience methods:

dateFromLong - creates a date object from e.g. the dateLastModified value from the resource.
absLink - creates an absolute link from a server relative url (e.g. /opencms/opencms/index.html -> http://www.bogus.com/opencms/opencms/index.html)
removeSiteRoot and setSiteRoot help handling site root issue, the first adjusts the VFS path such that it does no include the site root, whereas the latter allow you to set a different site root for the request context (in case you need to be able to read from a different site).

The request- and parameter-hashes uses FMs HttpRequestHashModel and HttpRequestParametersHashModel respectively.

The properties- and localProperties-hashes provides access to the properties of the resource. They are mostly a convenience as you could do the same by means of cms.property(). The localProperties-hash only looks at the properties set directly on the resource while the properties-hash will search upward hierarchy. E.g. properties.Title returns the same value as cms.property("Title", "search").

Installation

Upload the module like any other OpenCms module.

Install the freemarker.jar in .../WEB-INF/lib/. The module has been tested with FreeMarker version 2.3.8.

If you plan to use the FM taglib you should install the fmtag.tld in .../WEB-INF/.

Then restart the instance or the servlet container. Test the installation with the examples provided in /system/modules/com.codedroids.oc.freemarker/docs/ folder (note: example 3 requires the fmtag.tld to be installed).