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").
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).