## Installation
To install this library you need to add a new dependency to your app's build.gradle file.
### Gradle
```groovy
repositories {
maven { url "https://repo.itemtest.no/releases" }
maven { url "https://repo.itemtest.no/snapshots" }
}
dependencies {
include "no.item:lib-xp-freemarker:3.0.0-SNAPSHOT"
}
```
### TypeScript
To update the version of *enonic-types* in *package.json* using npm, run the following command:
```bash
npm i -D @item-enonic-types/lib-freemarker
```
You can add the following changes to your *tsconfig.json* to get TypeScript-support.
```diff
{
"compilerOptions": {
+ "baseUrl": "./",
+ "paths": {
+ "/lib/xp/*": ["./node_modules/@enonic-types/lib-*"],
+ "/lib/*": [ "./node_modules/@item-enonic-types/lib-*" ,"./src/main/resources/lib/*"],
+ }
}
}
```
### Add types for IntelliJ
If you are using IDEs from IntelliJ, you can get the correct type for the `portal` object by adding a file
_src/main/resources/freemarker_implicit.ftl_ with this content:
```ftl
[#ftl]
[#-- @implicitly included --]
[#-- @ftlvariable name="portal" type="no.item.freemarker.FreemarkerPortalObject" --]
```
### Configuration file
You can configure the [FreeMarker settings](https://freemarker.apache.org/docs/pgui_config_settings.html) by adding an
_XP_HOME/config/freemarker.properties_ file.
To preserve backwards compatibility in an existing project you can set the `incompatible_improvements` version like this:
```properties
incompatible_improvements=2.3.25
```
Developers should use the [HTML Debug Exception Handler](https://freemarker.apache.org/docs/pgui_config_errorhandling.html#autoid_44)
in their local development environments.
```properties
template_exception_handler=html_debug
```
> [!CAUTION]
> **Do not** use the `html_debug` exception handler in production!
> It should only be used for development as it shows technical information about your system.
## Usage
### Render from template files
You can use `resolve` to get the `ResourceKey` of a template file in your application. Then you can pass in a data model
to render that template.
```TypeScript
import { render } from "/lib/freemarker";
import { getContent } from "/lib/xp/portal";
import type { Response } from "@enonic-types/core";
type FreeMarkerParams = {
title: string;
text: string | undefined;
}
const view = resolve("article.ftl");
export function get(): Response {
const content = getContent()!;
const model: FreeMarkerParams = {
title: content.data.title,
text: content.data.text,
};
return {
body: render\${text}
[/#if] [@Footer.render year=year /] `; export function get(): Response { const content = getContent()!; const virtualTemplateName = "my-inline-template.ftl"; const model: FreeMarkerParams = { title: content.data.title, text: content.data.text, year: "2025" }; return { body: render${portal.localize("article.text")}
``` If you need another `locale` to be used (han that of the current content), you can set it with the [#setting directive](https://freemarker.apache.org/docs/ref_directive_setting.html). ```ftl [#-- Changes the `locale` to Norwegian for the remainder of the template. --] [#-- This will affect the `portal.localize()` and date formatting. --] [#setting locale="no"] [#-- Setting the `time_zone` to get the correct time when formatting dates --] [#setting time_zone="Europe/Oslo"] ``` ## Deploying ### Building To build the project, run the following command ```bash enonic project build ``` You will find the jar-file at _./build/libs/lib-xp-freemarker-[version].jar_ ### Deploying locally Deploy locally for testing purposes: ```bash ./gradlew publishToMavenLocal ``` ## Releasing Releases are driven by [Changesets](https://github.com/changesets/changesets) and run in GitHub Actions. 1. Describe your change in a changeset and commit it with the change itself: ```bash npx changeset ``` 2. When that lands on `main`, the *Publish* workflow opens (or updates) a **Version Packages** pull request. It bumps the version in *package.json*, *package-lock.json* and *gradle.properties*, and folds the changesets into *CHANGELOG.md*. 3. Merging that pull request makes the same workflow do the release: - publish the type definitions to npm as `@item-enonic-types/lib-freemarker`, with [build provenance](https://docs.npmjs.com/generating-provenance-statements) attached automatically - tag the commit `v[version]` and create the matching GitHub release - publish the jar to