Scripting languages and renderers

Magnolia provides renderers for Freemarker and JSP out of the box. You can choose the language you prefer. You can even mix languages on the same site, using Freemarker in some templates and JSP in others.

Freemarker

At Magnolia we prefer Freemarker for its flexibility, cleaner syntax and better error reporting, but also because it does not depend on the file system. Templates do not have to be extracted to the file system. This means you can store them in the repository and access like any other resources, apply version control if you wish, and add custom properties and metadata.

Example: Render the page title, or render the name if no title exists.

<h3>${content.title!content.@name}</h3>

Here are some of the benefits that Freemarker offers:

• It is a general templating language and not bound to any Java context.
• Provides basic directives such as [if], [else] and [list].
• Has a large set of built-ins.
• Can call public methods of any Java object and any returned object.
• Does not need to be rendered in the request/response context.
• Provides direct access to node objects (beans).
• Can directly iterate any content collections that extend a Java list.
• Strict  null value handling leads to stable templates.
• Allows the use of JSP taglibs if required.

See: FreeMarker reference

JSP

JSP stands for JavaServer Pages. It is an extension of Java Servlet technology for combining Java server-side programs and HTML.

Example: Render the page title or the name if no title exists.

<h3>
<c:choose>
    <c:when test="${not empty content.title}">${content.title}</c:when>
    <c:otherwise>${content['@name']}</c:otherwise>
</c:choose>
</h3>

See:

• JavaServer Pages Technology at Oracle
• JSP Standard Tag Library

Other languages

You can also use another templating language. Some sites use Apache Velocity, for example. If a renderer for your language is available, you can most likely incorporate it into Magnolia. This allows you to use a templating language that you are already familiar with.

Renderer configuration

FreemarkerRenderer and JspRenderer are configured in the Configuration app /modules/rendering/renderers/freemarker and /jsp.

The STK defines its own renderer STKRenderer configured in the Configuration app > /modules/standard-templating kit/rendering/renderers/stk.

The renderType property in page, area and component definitions defines the template renderer to use. For STK templates the type is stk.

Freemarker exception handling

Freemarker exceptions render differently on the author and public instances. On author, Freemarker exceptions show the stack trace in a yellow block with red text, and on public in preview mode errors are hidden and logged.

This behavior is controlled by ModeDependentTemplateExceptionHandler registered in configuration in /server/rendering/freemarker/templateExceptionHandler. You can extend this class to fine-grain behavior.