Rocker Templates by Fizzed

Automated Testing

The following Java versions and platforms are tested using GitHub workflows:

The following platforms are tested using the Fizzed, Inc. build system:

Overview

Rocker is a Java 8+ optimized, near zero-copy rendering, speedy template engine that produces statically typed, plain java object templates that are compiled along with the rest of your project. No more "warm-up" time in production, slow reflection-based logic, or nasty surprises that should have been caught during development.

Write your templates using an intuitive, tagless syntax with standard Java expressions for logic, iteration, and values. Use Rocker's special ? presence operator for null-safe evaluation. All the heavy lifting is done by the Rocker parser during development -- which keeps the runtime dependencies down to just a handful of classes. Rocker will parse your templates and generate well-documented Java source files (so you can easily inspect and understand how it works).

Includes the following features:

Templates are runtime compatible with Java 8+ -- using Lambdas and type inference under-the-hood
Near zero-copy rendering
Hot reload support in two flavors
Elegant, intuitive, tagless syntax that infers when your logic ends for control / dynamic content. All dynamic / control code uses standard Java syntax.
A special ? presence operator extends syntax for simplified handling of null values.
Parsed templates become normal POJOs with defined arguments -- allowing you to tap into your IDEs code completion, syntax highlighting, etc.
Support for injecting intermediate application-specific super classes during parsing & generating phase -- thereby creating your own app-specific template engine where you can make implicit variables/methods available to all templates.
Since templates are just Java classes -- your logic / dynamic content can call out to any other Java code. Your templates can be as advanced or as simple as you need. No reflection used.
No runtime configuration/engine required -- there isn't any sort of RockerEngine class required to execute templates. Each compiled template is ready-to-go and knows how to render itself.
Templates retain enough information about the original template to throw exceptions at runtime (during render()) that let you track down the problematic line in the original template source file.
GraalVM compatability if you leverage the new PlainText strategy of STATIC_BYTE_ARRAYS

Sponsorship & Support

Project by Fizzed, Inc. (Follow on Twitter: @fizzed_inc)

Developing and maintaining opensource projects requires significant time. If you find this project useful or need commercial support, we'd love to chat. Drop us an email at ping@fizzed.com

Project sponsors may include the following benefits:

Priority support (outside of Github)
Feature development & roadmap
Priority bug fixes
Privately hosted continuous integration tests for their unique edge or use cases

Performance

Based on the following template benchmark, Rocker is the clear winner. ~250% faster than Freemarker while also requiring orders-of-magnitude less memory.

Template Comparison

Quick Start

Most templates are used for websites, so here is a quick sample showing how Rocker templates work and can call each other during the rendering process. Create a template containing a common header and footer as well as a placeholder for body content. Create template src/main/java/views/main.rocker.html

@args (String title, RockerBody content)

<html>
    <head>
        <title>@title</title>
    </head>
    <body>
    @content
    </body>
</html>

The template we actually plan on showing to a user will render its content within the context of the common/header footer. In Java terms, it's passing a block of rendering code to be executed within another template. Create template src/main/java/views/index.rocker.html

@args (String message)

@views.main.template("Home") -> {
    <h1>Hello @message!</h1>
}

Hey, what about the RockerBody content argument? We cover it in more detail in the syntax readme, but for now just understand that its the only special type of argument and instructs Rocker that a template expects a "body" to be passed to it.

The Rocker parser will generate a Java source file for each template. They will be target/generated-sources/rocker/views/main.java and target/generated-sources/rocker/views/index.java. In your application, you can render the index template like so.

static public void main(String[] args) {

    String output = views.index.template("World")
        .render()
        .toString();

}

The output will equal:

<html>
    <head>
        <title>Home</title>
    </head>
    <body>
        <h1>Hello World!</h1>
    </body>
</html>

Once you generate the Java sources and peek inside the code, it's simple to see how this works. The views.index class creates a views.main template instance and hands off rendering to it -- while also passing a block of itself that it will render when views.main calls the @content variable. The syntax is identical to how a lambda is defined in Java 8 (implemented with lambdas for Java 8 and anonymous inner classes for Java 6/7). Rocker does a number of things behind the scenes to make sure templates that create other templates share the same rendering context (output buffer, application-specific context/implicit state).

Syntax

Checkout the SYNTAX.md file for a comprehensive deep dive on the rocker syntax.

Framework integrations

Rocker has a growing list of frameworks that it has been seamlessly integrated with. If you want to link to a new framework added, please file an issue or submit a PR:

Ninja Framework: https://github.com/fizzed/ninja-rocker
Jooby: http://jooby.org/doc/rocker
Spark Framework: https://github.com/perwendel/spark-template-engines
Micronaut Framework: https://github.com/micronaut-projects/micronaut-views

Near zero-copy rendering

Static (plain text) for each Rocker template is (by default) stored internally as static byte arrays already converted into your target charset (e.g. UTF-8). When a template is rendered -- the static byte arrays are reused across all requests. Rocker render

Rocker

Install / Use

README