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.

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)

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)
    }
}

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

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

Type-safe templates

There’s an alternate way to declare your templates in your Java code, which relies on the following convention:

• Organise your template files in the /src/main/resources/templates directory, by grouping them into one directory per resource class. So, if your ItemResource class references two templates hello and goodbye, place them at /src/main/resources/templates/ItemResource/hello.txt and /src/main/resources/templates/ItemResource/goodbye.txt. Grouping templates per resource class makes it easier to navigate to them.

• In each of your resource class, declare a @CheckedTemplate static class Template {} class within your resource class.

• Declare one public static native TemplateInstance method(); per template file for your resource.

• Use those static methods to build your template instances.

Here’s the previous example, rewritten using this style:

We’ll start with a very simple template:

HelloResource/hello.txt

Hello {name}! (1)

Now let’s declare and use those templates 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.api.CheckedTemplate;
@Path("hello")
public class HelloResource {
    @CheckedTemplate
    public static class Templates {
        public static native TemplateInstance hello(); (1)
    }
    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public TemplateInstance get(@QueryParam("name") String name) {
        return Templates.hello().data("name", name); (2) (3)
    }
}

Keep in mind this style of declaration allows you to reference templates declared in other resources too:

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;
@Path("goodbye")
public class GoodbyeResource {
    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public TemplateInstance get(@QueryParam("name") String name) {
        return HelloResource.Templates.hello().data("name", name);
    }
}

Toplevel type-safe templates

Naturally, if you want to declare templates at the toplevel, directly in /src/main/resources/templates/hello.txt, for example, you can declare them in a toplevel (non-nested) Templates class:

HelloResource.java

package org.acme.quarkus.sample;
import io.quarkus.qute.TemplateInstance;
import io.quarkus.qute.Template;
import io.quarkus.qute.api.CheckedTemplate;
@CheckedTemplate
public class Templates {
    public static native TemplateInstance hello(); (1)
}

Template Parameter Declarations

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.

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 and price.

Let’s start again with the template:

ItemResource/item.html

<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>{item.name}</title> (1)
</head>
<body>
    <h1>{item.name}</h1>
    <div>Price: {item.price}</div> (2)
</body>
</html>

Finally, let’s create a resource class with type-safe templates:

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;
import io.quarkus.qute.api.CheckedTemplate;
@Path("item")
public class ItemResource {
    @CheckedTemplate
    public static class Templates {
        public static native TemplateInstance item(Item item); (1)
    }
    @GET
    @Path("{id}")
    @Produces(MediaType.TEXT_HTML)
    public TemplateInstance get(@PathParam("id") Integer id) {
        return Templates.item(service.findItem(id)); (2)
    }
}

Template parameter declaration inside the template itself

Alternatively, you can declare your template parameters in the template file itself.

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>
</body>
</html>

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)
    }
}

Template Extension Methods

Template extension methods are used to extend the set of accessible properties of data objects.

Sometimes, you’re not in control of the classes that you want to use in your template, and you cannot add methods to them. Template extension methods allows you to declare new method for those classes that will be available from your templates just as if they belonged to the target class.

Let’s keep extending on our simple HTML page that contains the item name, price and add 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 update our template:

HelloResource/item.html

<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>{item.name}</title>
</head>
<body>
    <h1>{item.name}</h1>
    <div>Price: {item.price}</div>
    {#if item.price > 100} (1)
    <div>Discounted Price: {item.discountedPrice}</div> (2)
    {/if}
</body>
</html>

Finally, let’s create a class where we put all our extension methods:

TemplateExtensions.java

package org.acme.quarkus.sample;
import io.quarkus.qute.TemplateExtension;
@TemplateExtension
public class TemplateExtensions {
    public static BigDecimal discountedPrice(Item item) { (1)
        return item.price.multiply(new BigDecimal("0.9"));
    }
}

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>

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...
    }
}

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.