Qute Templating Engine

Qute is a templating engine designed specifically to meet the Quarkus needs. The usage of reflection is minimized to reduce the size of native images. The API combines both the imperative and the non-blocking reactive style of coding. In the development mode, all files located in src/main/resources/templates are watched for changes and modifications are immediately visible. Furthermore, we try to detect most of the template problems at build time. In this guide, you will learn how to easily render templates in your application.

This technology is considered experimental.

In experimental mode, early feedback is requested to mature the idea. There is no guarantee of stability nor long term presence in the platform until the solution matures. Feedback is welcome on our mailing list or as issues in our GitHub issue tracker.

For a full list of possible extension statuses, check our FAQ entry.

Hello World with JAX-RS

If you want to use Qute in your JAX-RS application, you need to add the quarkus-qute-resteasy extension first. In your pom.xml file, add:

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-resteasy-qute</artifactId>
</dependency>

We’ll start with a very simple template:

hello.txt
Hello {name}! (1)
1 {name} is a value expression that is evaluated when the template is rendered.
By default, all files located in the src/main/resources/templates directory and its subdirectories are registered as templates. Templates are validated during startup and watched for changes in the development mode.

Now let’s inject the "compiled" template in the resource class.

HelloResource.java
package org.acme.quarkus.sample;

import javax.inject.Inject;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.QueryParam;

import io.quarkus.qute.TemplateInstance;
import io.quarkus.qute.Template;

@Path("hello")
public class HelloResource {

    @Inject
    Template hello; (1)

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public TemplateInstance get(@QueryParam("name") String name) {
        return hello.data("name", name); (2) (3)
    }
}
1 If there is no @ResourcePath qualifier provided, the field name is used to locate the template. In this particular case, we’re injecting a template with path templates/hello.txt.
2 Template.data() returns a new template instance that can be customized before the actual rendering is triggered. In this case, we put the name value under the key name. The data map is accessible during rendering.
3 Note that we don’t trigger the rendering - this is done automatically by a special ContainerResponseFilter implementation.

If your application is running, you can request the endpoint:

$ curl -w "\n" http://localhost:8080/hello?name=Martin
Hello Martin!

Parameter Declarations and Template Extension Methods

Qute has many useful features. In this example, we’ll demonstrate two of them. If you declare a parameter declaration in a template then Qute attempts to validate all expressions that reference this parameter and if an incorrect expression is found the build fails. Template extension methods are used to extend the set of accessible properties of data objects.

Let’s suppose we have a simple class like this:

Item.java
public class Item {
    public String name;
    public BigDecimal price;
}

And we’d like to render a simple HTML page that contains the item name, price and also a discounted price. The discounted price is sometimes called a "computed property". We will implement a template extension method to render this property easily. Let’s start again with the template:

item.html
{@org.acme.Item item} (1)
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>{item.name}</title> (2)
</head>
<body>
    <h1>{item.name}</h1>
    <div>Price: {item.price}</div>
    {#if item.price > 100} (3)
    <div>Discounted Price: {item.discountedPrice}</div> (4)
    {/if}
</body>
</html>
1 Optional parameter declaration. Qute attempts to validate all expressions that reference the parameter item.
2 This expression is validated. Try to change the expression to {item.nonSense} and the build should fail.
3 if is a basic control flow section.
4 This expression is also validated against the Item class and obviously there is no such property declared. However, there is a template extension method declared on the ItemResource class - see below.

Finally, let’s create a resource class.

ItemResource.java
package org.acme.quarkus.sample;

import javax.inject.Inject;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;

import io.quarkus.qute.TemplateInstance;
import io.quarkus.qute.Template;

@Path("item")
public class ItemResource {

    @Inject
    ItemService service;

    @Inject
    Template item; (1)

    @GET
    @Path("{id}")
    @Produces(MediaType.TEXT_HTML)
    public TemplateInstance get(@PathParam("id") Integer id) {
        return item.data("item", service.findItem(id)); (2)
    }

    @TemplateExtension (3)
    static BigDecimal discountedPrice(Item item) {
        return item.price.multiply(new BigDecimal("0.9"));
    }
}
1 Inject the template with path templates/item.html.
2 Make the Item object accessible in the template.
3 A static template extension method can be used to add "computed properties" to a data class. The class of the first parameter is used to match the base object and the method name is used to match the property name.

Rendering Periodic Reports

Templating engine could be also very useful when rendering periodic reports. You’ll need to add the quarkus-scheduler and quarkus-qute extensions first. In your pom.xml file, add:

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-qute</artifactId>
</dependency>
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-scheduler</artifactId>
</dependency>

Let’s suppose the have a SampleService bean whose get() method returns a list of samples.

Sample.java
public class Sample {
    public boolean valid;
    public String name;
    public String data;
}

The template is simple:

report.html
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Report {now}</title>
</head>
<body>
    <h1>Report {now}</h1>
    {#for sample in samples} (1)
      <h2>{sample.name ?: 'Unknown'}</h2> (2)
      <p>
      {#if sample.valid}
        {sample.data}
      {#else}
        <strong>Invalid sample found</strong>.
      {/if}
      </p>
    {/for}
</body>
</html>
1 The loop section makes it possible to iterate over iterables, maps and streams.
2 This value expression is using the elvis operator - if the name is null the default value is used.
ReportGenerator.java
package org.acme.quarkus.sample;

import javax.inject.Inject;

import io.quarkus.qute.Template;
import io.quarkus.qute.api.ResourcePath;
import io.quarkus.scheduler.Scheduled;

public class ReportGenerator {

    @Inject
    SampleService service;

    @ResourcePath("reports/v1/report_01") (1)
    Template report;

    @Scheduled(cron="0 30 * * * ?") (2)
    void generate() {
        String result = report
            .data("samples", service.get())
            .data("now", java.time.LocalDateTime.now())
            .render(); (3)
        // Write the result somewhere...
    }
}
1 In this case, we use the @ResourcePath qualifier to specify the template path: templates/reports/v1/report_01.html.
2 Use the @Scheduled annotation to instruct Quarkus to execute this method on the half hour. For more information see the Scheduler guide.
3 The TemplateInstance.render() method triggers rendering. Note that this method blocks the current thread.

Reactive and Asynchronous APIs

Templates can be rendered as a CompletionStage<String> (completed with the rendered output asynchronously) or as Publisher<String> containing the rendered chunks:

CompletionStage<String> async = template.data("name", "neo").renderAsync();
Publisher<String> publisher = template.data("name", "neo").publisher();

In the case of a Publisher, the template is rendered chunk by chunk following the requests from the subscriber. The rendering is not started until a subscriber requests it. The returned Publisher is an instance of io.smallrye.mutiny.Multi.

It is possible to create an instance of io.smallrye.mutiny.Uni as follows:

Uni<String> uni = Uni.createFrom().completionStage(() -> template.data("name", "neo").renderAsync());

In this case, the rendering only starts once the subscriber requests it.

Qute Reference Guide

To learn more about Qute, please refer to the Qute reference guide.

Qute Configuration Reference

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

Type

Default

The set of suffixes used when attempting to locate a template file.

By default, engine.getTemplate("foo") would result in several lookups: foo, foo.html, foo.txt, etc.

list of string

qute.html,qute.txt,html,txt