lib-freemarker
Freemarker library for Enonic XP
Installation
The most straight forward way to get it going is probably jitpack, which builds and makes a public github repo available as a gradle dependency on-the-fly:
Step 1: Add it in your root build.gradle at the end of repositories:
allprojects {
repositories {
...
maven { url 'https://jitpack.io' }
}
}
Step 2. Add the dependency If you are on an Enonic XP 6.15 add the dependency like this:
dependencies {
include 'com.github.tineikt:xp-lib-freemarker:1.1.1'
}
If you are on an Enonic XP 7 add the dependency like this:
dependencies {
include 'no.tine.xp:xp-lib-freemarker:2.0.2'
}
Hopefully this should allow jitpack to build the project, and present it as a standard gradle package for Enonic XP :)
Usage
Just as you are used to with Thymeleaf in your controller
var freemarker = require('/lib/tineikt/freemarker');
exports.get = function(req) {
var model = {
}
var view = resolve('template.ftl');
var html = freemarker.render(view, model);
return {
body: html
}
};
View Functions
Enonic View Functions documentation
Example usage in Thymeleaf:
<a data-th-href="${portal.assetUrl({'_path=css/main.css'})}">Link</a>
<img data-th-src="${portal.imageUrl({'_id=869b29a0-dccc-4d5e-afc5-81e5050a628d', '_scale=block(50,50)'})}"/>
<p data-th-text="${portal.localize({'_key=mystring','_locale=en'})}">Not translated</p>
Example usage in Freemarker
<a href="[@assetUrl path='css/main.css'/]">Link</a>
<img src="[@imageUrl scale='block(50,50)' id='869b29a0-dccc-4d5e-afc5-81e5050a628d'/]">
<p>[@localize locale='en' key='mystring'/]</p>
Formatting Dates
You can format Java 8 dates (e.g. java.time.LocalDateTime
or java.time.ZonedDateTime
) inside your Freemarker template.
The lib-xp-time XP-library provides access to the Java-types so that
you can parse strings
into java.time.*
objects.
[#-- @ftlvariable name="locale" type="java.lang.String" --]
[#-- @ftlvariable name="date" type="java.time.ZonedDateTime" --]
[#setting locale=locale]
<time datetime="${date.format("ISO_OFFSET_DATE_TIME")}">
${date.format("SHORT_DATE")}
</time>
Fixing unresolved references in IntelliJ
If you are using one of the IDEs from Jetbrains, a special comment syntax exists that will fix unresolved references to Enonic View Functions in your project.
You can simply add a file "./src/main/resources/freemarker_implicit.ftl" with the following contents to your project.
[#ftl]
[#-- @implicitly included --]
[#macro pageUrl id="" path="" type="server"][/#macro]
[#macro assetUrl path application="" type="server"][/#macro]
[#macro imageUrl scale id="" path="" format="" quality=85 background="" filter="" type="server"][/#macro]
[#macro attachmentUrl id="" path="" name="" label="source" download=false type="server"][/#macro]
[#macro componentUrl id="" path="" component="" type="server"][/#macro]
[#macro serviceUrl service application="" type="server"][/#macro]
[#macro localize key locale=""][/#macro]
[#macro processHtml value type="server"][/#macro]
[#macro imagePlaceholder width height][/#macro]
Note
Protip: You can provide type checking to your Freemarker-templates by creating @ftlvariable
comments on the top of your ftl-files.
[#-- @ftlvariable name="displayName" type="java.lang.String" --]
<h1>${displayName}</h1>
Freemarker documentation
Component reference
Enonic XP does some post-processing to retrieve and render components.
You are probably used to Thymeleaf and how some magic happens when you use the data-portal-component
.
<div data-th-each="component : ${regions.components}" data-th-remove="tag">
<div data-portal-component="${component.path}" data-th-remove="tag" />
</div>
This magic is implemented using a Freemarker directive, <@component path=component.path />
The same template, in Freemarker would then be.
[#list regions.components as comp]
[@component path=comp.path /]
[/#list]