ADR-002 — HTML Templating Engine

ADR

ADR-002

Title

HTML Templating Engine

State

Accepted

Author

klenkes74

Decision Body

klenkes74

Valid from

2025-06-07

Expires

./.

1. Context

The {gloss_scs} produces HTML for the web application. The HTML is needed for the controlled pages and for the {gloss_transclude}s.

2. Decision

While there are very good reasons to use Thymeleaf or FreeMarker as templating engines, I decided to use JTE. It is an easy to use, modern templating engine that is specifically designed for Java applications. But more importantly: I want to get used to it, since it is used at my place of work.

3. Consequences

  1. Templates have to be written in JTE syntax.

  2. The templates are not HTML compliant, so they cannot be used as static HTML files.

4. Decision Drivers

Driver Description

DD001

Strong support by spring-boot.

DD002

Strong support for webflux and reactive programming.

DD003

Mature and well-known.

DD004

Easy to use and understand.

DD005

Fulfilling JSR-223 Scripting Integration is not a requirement.

5. Alternatives Considered

5.1. Thymeleaf

Thymeleaf is a modern server-side Java template engine for web and standalone environments with excellent Spring Boot integration.

Pro:

  • Fulfills DD001 through native Spring Boot integration

  • Fulfills DD002 with complete WebFlux support

  • Fulfills DD003 as an established project with a large community

  • Natural templates (function as static HTML) (DD004 fulfilled)

  • Strong security features against XSS

Con:

  • Slower than other engines with complex templates

  • Higher memory consumption

  • Steeper learning curve for advanced features (DD004 only partially fulfilled)

5.2. FreeMarker

FreeMarker is a powerful template engine with a focus on MVC patterns, distinguished by its speed and flexibility.

Pro:

  • Fulfills DD001 with good Spring Boot support

  • Fulfills DD002 through WebFlux compatibility

  • Fulfills DD003 as a long-established engine

  • Excellent performance

  • Powerful macro functions

Con:

  • No natural templates

  • Template syntax not HTML-compliant

  • Less deep Spring integration than Thymeleaf

5.3. Mustache

Mustache is a simple, logic-less template language implemented in many programming languages.

Pro:

  • Fulfills DD004 through extremely simple syntax

  • Minimal learning curve

  • Usable across languages

  • Strictly separates logic and presentation

Con:

  • Only basic Spring Boot integration (DD001 partially fulfilled)

  • Limited WebFlux support (DD002 only partially fulfilled)

  • Limited functionality due to logic-less approach

5.4. Pebble

Pebble is a Java template engine inspired by Twig, with a focus on simplicity and performance.

Pro:

  • Good performance

  • Compact, easily understandable syntax (DD004)

  • Low memory consumption

  • Extensible

Con:

  • Less widespread (DD003 not fully fulfilled)

  • Limited Spring Boot integration (DD001 only partially fulfilled)

  • Limited WebFlux documentation (DD002 uncertain)

5.5. Handlebars

Handlebars extends Mustache with more functionality while maintaining its basic simplicity.

Pro:

  • Simple syntax (DD004)

  • Minimal logic possible in templates

  • Usable across languages

  • Extensible through helper functions

Con:

  • Limited Spring Boot integration (DD001 only partially fulfilled)

  • Limited WebFlux support (DD002 uncertain)

  • Smaller community than Thymeleaf or FreeMarker (DD003 only partially fulfilled)

5.6. Velocity

Apache Velocity is an established Java-based template engine.

Pro:

  • Simple syntax (DD004)

  • Well established (DD003)

  • Powerful

Con:

  • Outdated architecture

  • Limited Spring Boot integration (DD001 partially fulfilled)

  • No modern WebFlux support (DD002 not fulfilled)

  • Less active ongoing development

5.7. Jade4J/PUG

Java implementation of the Jade/Pug template language known from Node.js.

Pro:

  • Compact, indentation-based syntax

  • Fulfills DD004 through clean code

  • Popular in the JavaScript world

Con:

  • Limited Spring Boot integration (DD001 barely fulfilled)

  • No WebFlux support (DD002 not fulfilled)

  • Small Java community (DD003 not fulfilled)

5.8. JTE (Java Template Engine)

JTE is a modern, lightweight template engine specifically for Java, designed for speed and type safety.

Pro:

  • Very high performance through pre-compilation of templates

  • Complete type safety during development

  • Good Spring Boot integration (DD001 fulfilled)

  • Supports WebFlux with reactive rendering (DD002 fulfilled)

  • Simple, intuitive syntax (DD004 fulfilled)

  • Hot-reloading during development

  • Low dependencies and minimal overhead

Con:

  • Still relatively new engine (DD003 only partially fulfilled)

  • Smaller community than Thymeleaf or FreeMarker

  • Less comprehensive documentation and examples (DD004 only partially fulfilled)