Fork me on GitHub

Javalin rendering

The javalin-rendering artifact is an optional module for the Javalin web framework that provides a simple way to render HTML using popular template engines. The javalin-rendering artifact includes default implementations for several template engines, including JTE, Mustache, Velocity, Pebble, Handlebars, and Thymeleaf, but you also have to add the dependency for the template engine you want to use.

Adding dependencies

<dependency>
    <groupId>io.javalin</groupId>
    <artifactId>javalin-rendering</artifactId>
    <version>6.1.0</version>
</dependency>
<dependency>
    <groupId><!-- template engine group --></groupId>
    <artifactId><!-- template engine artifact --></artifactId>
    <version><!-- template engine version --></version>
</dependency>
implementation("io.javalin:javalin-rendering:6.1.0")
// template engine dependency

Included template engines

The javalin-rendering artifact includes default implementations for several template engines:

Freemarker  ➜  https://freemarker.apache.org
JTE  ➜  https://jte.gg/
Mustache  ➜  https://github.com/spullara/mustache.java
Pebble  ➜  https://pebbletemplates.io/
Thymeleaf  ➜  https://www.thymeleaf.org/
Velocity  ➜  https://velocity.apache.org/
Commonmark  ➜  https://github.com/commonmark/commonmark-java

Using the plugin

All the template engines look for templates/markdown files in src/resources/templates. To enable a template engine, you have to register it on the Javalin config:

Javalin.create(config -> {
    config.fileRenderer(new JavalinMustache());
});
Javalin.create { config ->
    config.fileRenderer(JavalinMustache())
}

You can also register your own rendering engine.

Rendering a template

Once you have added the dependencies for the template engine you want to use, all you have to do is call ctx.render() with the path to your template file (and optionally a model):

ctx.render("/templateFile.ext", model("firstName", "John", "lastName", "Doe"));
ctx.render("/templateFile.ext", mapOf("firstName" to "John", "lastName" to "Doe"))

Configuring a template engine

If you wish to configure a template engine (for example, to set a root directory for your template files), all constructors have optional parameters with their template engine configurations:

Javalin.create(config -> {
    config.fileRenderer(new JavalinVelocity(myVelocityEngine));
});
Javalin.create { config ->
    config.fileRenderer((JavalinVelocity(myVelocityEngine)
}

The configuration classes are not from Javalin, but from the template engine you are using, so please consult the documentation for that particular template engine to learn how to use them.

Recreating the old JavalinRenderer

Older versions of Javalin had a JavalinRenderer class that was used to render templates. This class was able to render templates based on the file extension.

You can recreate this class like this:

class JavalinRenderer implements FileRenderer {
    private Map<String, FileRenderer> renderers = new HashMap<>();
    public JavalinRenderer register(String extension, FileRenderer renderer) {
        renderers.put(extension, renderer);
        return this;
    }

    @Override
    public String render(String filePath, Map<String, ? extends Object> model, Context context) {
        String extension = filePath.substring(filePath.lastIndexOf(".") + 1);
        return renderers.get(extension).render(filePath, model, context);
    }
}
class JavalinRenderer : FileRenderer {
    private val renderers = HashMap<String, FileRenderer>()
    fun register(extension: String, renderer: FileRenderer): JavalinRenderer {
        renderers[extension] = renderer
        return this
    }


    override fun render(filePath: String, model: Map<String, Any?>, context: Context): String {
        val extension = filePath.substring(filePath.lastIndexOf(".") + 1)
        return renderers[extension]!!.render(filePath, model, context)
    }
}

You can then register it like any other renderer:

Javalin.create(config -> {
    config.fileRenderer(
        new JavalinRenderer()
            .register("mustache", new JavalinMustache())
            .register("jte", new JavalinJte())
    );
});
Javalin.create { config ->
    config.fileRenderer(
        JavalinRenderer()
            .register("mustache", JavalinMustache())
            .register("jte", JavalinJte())
    )
}

Like Javalin?
Star us 😊

×