You can obtain a fragment programmatically via the io.quarkus.qute.Template.getFragment(String) method.

@Inject
Template item;
String useTheFragment() {
   return item.getFragment("item_aliases") (1)
            .data("aliases", List.of("Foo","Bar")) (2)
            .render();
You can also include a fragment with an {#include} section inside another template or the template that defines the fragment.
Including a Fragment in user.html
<h1>User - {user.name}</h1>
<p>This document contains a detailed info about a user.</p>
{#include item$item_aliases aliases=user.aliases /} (1)(2)

A template identifier that contains a dollar sign $ denotes a fragment. The item$item_aliases value is translated as: Use the fragment item_aliases from the template item.
The aliases parameter is used to pass the relevant data. We need to make sure that the data are set correctly. In this particular case the fragment will use the expression user.aliases as the value of aliases in the {#for alias in aliases} section.
3.5.9.1. Hidden Fragments

By default, a fragment is normally rendered as a part of the original template. However, sometimes it might be useful to mark a fragment as hidden with rendered=false. An interesting use case would be a fragment that can be used multiple-times inside the template that defines it.




    

Fragment Definition in item.html
{#fragment id=strong rendered=false} (1)
<strong>{val}</strong>
{/fragment}
<h1>My page</h1>
<p>This document
{#include $strong val='contains' /} (2)
a lot of
{#include $strong val='information' /} (3)
Defines a hidden fragment with identifier strong. In this particular case, we use the false boolean literal as the value of the rendered parameter. However, it’s possible to use any expression there.
Include the fragment strong and pass the value. Note the syntax $strong which is translated to include the fragment strong from the current template.
Include the fragment strong and pass the value.
The template content is passed directly, i.e. not obtained via an io.quarkus.qute.TemplateLocator,
It’s not possible to override parts of the evaluated template.
The result of myData.template will be used as the template. The template is executed with the Current Context, i.e. can reference data from the template it’s included into.
It’s also possible to define optional parameters that can be used in the evaluated template.
The content of the section is always ignored.
// A simple map-based cache
ConcurrentMap<String, CompletionStage<ResultNode>> map = new ConcurrentHashMap<>();
engineBuilder
    .addSectionHelper(new CacheSectionHelper.Factory(new Cache() {
        @Override
        public CompletionStage<ResultNode> getValue(String key,
           Function<String, CompletionStage<ResultNode>> loader) {
              return map.computeIfAbsent(key, k -> loader.apply(k));
     })).build();
If the key param is not used then all clients of the template share the same cached value.
This part of the template will be cached and the {service.findResult} expression is only evaluated when a cache entry is missing/invalidated.
{#cached key=currentUser.username} (1)
 User-specific result: {service.findResult(currentUser)}
{/cached}

When using cache it’s very often important to have the option to invalidate a cache entry by the specific key. In Qute the key of a cache entry is a String that consist of the template name, line and column of the starting {#cached} tag and the optional key parameter: {TEMPLATE}:{LINE}:{COLUMN}_{KEY}. For example, foo.html:10:1_alpha is a key for the cached section in a template foo.html, the {#cached} tag is placed on the line 10, column 1. And the optional key parameter resolves to alpha.
3.6. Rendering Output

TemplateInstance provides several ways to trigger the rendering and consume the result. The most straightforward approach is represented by TemplateInstance.render(). This method triggers a synchronous rendering, i.e. the current thread is blocked until the rendering is finished, and returns the output. By contrast, TemplateInstance.renderAsync() returns a CompletionStage<String> which is completed when the rendering is finished.
TemplateInstance.renderAsync() Example
template.data(foo).renderAsync().whenComplete((result, failure) -> { (1)
   if (failure == null) {
      // consume the output...
   } else {
      // process failure...
There are also two methods that return Mutiny types. TemplateInstance.createUni() returns a new Uni<String> object. If you call createUni() the template is not rendered right away. Instead, every time Uni.subscribe() is called a new rendering of the template is triggered.
TemplateInstance.createUni() Example
template.data(foo).createUni().subscribe().with(System.out::println);
TemplateInstance.createMulti() returns a new Multi<String> object. Each item represents a part/chunk of the rendered template. Again, createMulti() does not trigger rendering. Instead, every time a computation is triggered by a subscriber the template is rendered again.
TemplateInstance.createMulti() Example
template.data(foo).createMulti().subscribe().with(buffer:append,buffer::flush);
The template rendering is divided in two phases. During the first phase, which is asynchronous, all expressions in the template are resolved and a result tree is built. In the second phase, which is synchronous, the result tree is materialized, i.e. one by one the result nodes emit chunks that are consumed/buffered by the specific consumer.
3.7.1. Value Resolvers

Value resolvers are used when evaluating expressions. A custom io.quarkus.qute.ValueResolver can be registered programmatically via EngineBuilder.addValueResolver().
ValueResolver Builder Example
engineBuilder.addValueResolver(ValueResolver.builder()
    .appliesTo(ctx -> ctx.getBase() instanceof Long && ctx.getName().equals("tenTimes"))
    .resolveSync(ctx -> (Long) ctx.getBase() * 10)
    .build());
3.7.2. Template Locator

A template can be either registered manually or automatically via a template locator. The locators are used whenever the Engine.getTemplate() method is called, and the engine has no template for a given id stored in the cache. The locator is responsible for using the correct character encoding when reading the contents of a template.
3.7.3. Content Filters

Content filters can be used to modify the template contents before parsing.
Content Filter Example
engineBuilder.addParserHook(new ParserHook() {
    @Override
    public void beforeParsing(ParserHelper parserHelper) {
        parserHelper.addContentFilter(contents -> contents.replace("${", "$\\{")); (1)
3.7.4. Strict Rendering

The strict rendering enables the developers to catch insidious errors caused by typos and invalid expressions. If enabled then any expression that cannot be resolved, i.e. is evaluated to an instance of io.quarkus.qute.Results.NotFound, will always result in a TemplateException and the rendering is aborted. A NotFound value is considered an error because it basically means that no value resolver was able to resolve the expression correctly.
If you really need to use an expression which can potentially lead to a "not found" error, you can use default values and safe expressions in order to suppress the error. A default value is used if the previous part of an expression cannot be resolved or resolves to null. You can use the elvis operator to output the default value: {foo.bar ?: 'baz'}, which is effectively the same as the following virtual method: {foo.bar.or('baz')}. A safe expression ends with the ?? suffix and results in null if the expression cannot be resolved. It can be very useful e.g. in {#if} sections: {#if valueNotFound??}Only rendered if valueNotFound is truthy!{/if}. In fact, ?? is just a shorthand notation for .or(null), i.e. {#if valueNotFound??} becomes {#if valueNotFound.or(null)}.
In Quarkus, a preconfigured engine instance is provided and available for injection - a bean with scope @ApplicationScoped, bean type io.quarkus.qute.Engine and qualifier @Default is registered automatically. Moreover, all templates located in the src/main/resources/templates directory are validated and can be easily injected.
import io.quarkus.qute.Engine;
import io.quarkus.qute.Template;
import io.quarkus.qute.Location;
class MyBean {
    @Inject
    Template items; (1)
    @Location("detail/items2_v1.html") (2)
    Template items2;
    @Inject
    Engine engine; (3)
If there is no Location qualifier provided, the field name is used to locate the template. In this particular case, the container will attempt to locate a template with path src/main/resources/templates/items.html.
The Location qualifier instructs the container to inject a template from a path relative from src/main/resources/templates. In this case, the full path is src/main/resources/templates/detail/items2_v1.html.
Inject the configured Engine instance.
    void configureEngine(@Observes EngineBuilder builder) {
       // Add a custom section helper
       builder.addSectionHelper(new CustomSectionFactory());
       // Add a custom value resolver
       builder.addValueResolver(ValueResolver.builder()
                .appliesTo(ctx -> ctx.getBase() instanceof Long && ctx.getName().equals("tenTimes"))
                .resolveSync(ctx -> (Long) ec.getBase() * 10)
                .build());
However, in this particular case the section helper factory is ignored during validation at build time. If you want to register a section that participates in validation of templates at build time then use the convenient @EngineConfiguration annotation:
import io.quarkus.qute.EngineConfiguration;
import io.quarkus.qute.SectionHelper;
import io.quarkus.qute.SectionHelperFactory;
@EngineConfiguration (1)
public class CustomSectionFactory implements SectionHelperFactory<CustomSectionFactory.CustomSectionHelper> {
    @Inject
    Service service; (2)
    @Override
    public List<String> getDefaultAliases() {
        return List.of("custom");
    @Override
    public ParametersInfo getParameters() {
        // Param "foo" is required
        return ParametersInfo.builder().addParameter("foo").build(); (3)
    @Override
    public Scope initializeBlock(Scope outerScope, BlockInfo block) {
        block.addExpression("foo", block.getParameter("foo"));
        return outerScope;
    @Override
    public CustomSectionHelper initialize(SectionInitContext context) {
        return new CustomSectionHelper();
    class CustomSectionHelper implements SectionHelper {
        private final Expression foo;
        public CustomSectionHelper(Expression foo) {
            this.foo = foo;
        @Override
        public CompletionStage<ResultNode> resolve(SectionResolutionContext context) {
            return context.evaluate(foo).thenApply(fooVal -> new SingleResultNode(service.getValueForFoo(fooVal))); (4)
A SectionHelperFactory annotated with @EngineConfiguration is used during validation of templates at build time and automatically registered at runtime (a) as a section factory and (b) as a CDI bean.
A CDI bean instance is used at runtime - this means that the factory can define injection points
Validate that foo parameter is always present; e.g. {#custom foo='bar' /} is ok but {#custom /} results in a build failure.
Use the injected Service during rendering.
The @EngineConfiguration annotation can be also used to register ValueResolvers and NamespaceResolvers.
4.1.1. Template Locator Registration

The easiest way to register template locators is to make them CDI beans. As the custom locator is not available during the build time when a template validation is done, you need to disable the validation via the @Locate annotation.
Custom Locator Example
@Locate("bar.html") (1)
@Locate("foo.*") (2)
public class CustomLocator implements TemplateLocator {
    @Inject (3)
    MyLocationService myLocationService;
    @Override
    public Optional<TemplateLocation> locate(String templateId) {
        return myLocationService.getTemplateLocation(templateId);
A regular expression foo.* disables validation for templates whose name is starting with foo.
Injection fields are resolved as template locators annotated with @Locate are registered as singleton session beans.
    String renderItems() {
       return items.data("items",manager.findItems()).setAttribute(TemplateInstance.SELECTED_VARIANT, new Variant(Locale.getDefault(),"text/html","UTF-8")).render();
For the expression cdi:personService.findPerson(10).name, the implementation class of the injected bean must either declare the findPerson method or a matching template extension method must exist.
For the expression inject:foo.price, the implementation class of the injected bean must either have the price property (e.g. a getPrice() method) or a matching template extension method must exist.
4.4. Type-safe Expressions

Template expressions can be optionally type-safe. Which means that an expression is validated against the existing Java types and template extension methods. If an invalid/incorrect expression is found then the build fails.
For example, if there is an expression item.name where item maps to org.acme.Item then Item must have a property name or a matching template extension method must exist.
An optional parameter declaration is used to bind a Java type to expressions whose first part matches the parameter name. Parameter declarations are specified directly in a template.
A Java type should be always identified with a fully qualified name unless it’s a JDK type from the java.lang package - in this case, the package name is optional. Parameterized types are supported, however wildcards are always ignored - only the upper/lower bound is taken into account. For example, the parameter declaration {@java.util.List<? extends org.acme.Foo> list} is recognized as {@java.util.List<org.acme.Foo> list}. Type variables are not handled in a special way and should never be used.
Parameter Declaration Example
{@org.acme.Foo foo} (1)
<!DOCTYPE html>
<meta charset="UTF-8">
<title>Qute Hello</title>
</head>
  <h1>{title}</h1> (2)
  Hello {foo.message.toLowerCase}! (3) (4)
</body>
</html>

This expression is validated. org.acme.Foo must have a property message or a matching template extension method must exist.
Likewise, the Java type of the object resolved from foo.message must have a property toLowerCase or a matching template extension method must exist.
A parameter declaration may specify the default value after the key. The key and the default value are separated by an equals sign: {@int age=10}. The default value is used in the template if the parameter key resolves to null or is not found.




    

For example, if there’s a parameter declaration {@String foo="Ping"} and foo is not found then you can use {foo} and the output will be Ping. On the other hand, if the value is set (e.g. via TemplateInstance.data("foo", "Pong")) then the output of {foo} will be Pong.
The type of a default value must be assignable to the type of the parameter declaration. For example, see the incorrect parameter declaration that results in a build failure: {@org.acme.Foo foo=1}.
The default value is actually an expression. So the default value does not have to be a literal (such as 42 or true). For example, you can leverage the @TemplateEnum and specify an enum constant as a default value of a parameter declaration: {@org.acme.MyEnum myEnum=MyEnum:FOO}. However, the infix notation is not supported in default values unless the parentheses are used for grouping, e.g. {@org.acme.Foo foo=(foo1 ?: foo2)}.
{@int pages} (1)
{@java.util.List<String> strings} (2)
{@java.util.Map<String,? extends Number> numbers} (3)
{@java.util.Optional<?> param} (4)
{@String name="Quarkus"} (5)

The wildcard is ignored and the upper bound is used instead: {@java.util.Map<String,Number>}
The wildcard is ignored and the java.lang.Object is used instead: {@java.util.Optional<java.lang.Object>}
The type is java.lang.String, the key is name and the default value is Quarkus.
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.
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
import io.quarkus.qute.TemplateInstance;
import io.quarkus.qute.Template;
import io.quarkus.qute.CheckedTemplate;
@Path("item")
public class ItemResource {
    @CheckedTemplate
    public static class Templates {
        public static native TemplateInstance item(Item item); (1) (2)
    @Path("{id}")
    @Produces(MediaType.TEXT_HTML)
    public TemplateInstance get(Integer id) {
        return Templates.item(service.findItem(id)); (3)
Declare a method that gives us a TemplateInstance for templates/ItemResource/item.html and declare its Item item parameter so we can validate the template.
The item parameter is automatically turned into a parameter declaration and so all expressions that reference this name will be validated.
Make the Item object accessible in the template.
4.5.1. Top-level Type-safe Templates

You can also declare a top-level Java class annotated with @CheckedTemplate:
Top-level checked templates
package org.acme.quarkus.sample;
import io.quarkus.qute.TemplateInstance;
import io.quarkus.qute.Template;
import io.quarkus.qute.CheckedTemplate;
@CheckedTemplate
public class Templates {
    public static native TemplateInstance hello(String name); (1)
Then declare one public static native TemplateInstance method(); per template file. Use those static methods to build your template instances:
HelloResource.java
package org.acme.quarkus.sample;
import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.QueryParam;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
import io.quarkus.qute.TemplateInstance;
@Path("hello")
public class HelloResource {
    @Produces(MediaType.TEXT_PLAIN)
    public TemplateInstance get(@QueryParam("name") String name) {
        return Templates.hello(name);
4.5.2. Customized Template Path

The template path of a @CheckedTemplate method consists of the base path and a defaulted name. The base path is supplied by the @CheckedTemplate#basePath(). By default, the simple name of the declaring class for a nested static class or an empty string for a top level class is used. The defaulted name is derived by the strategy specified in @CheckedTemplate#defaultName(). By default, the name of the @CheckedTemplate method is used as is.
Customized Template Path Example
package org.acme.quarkus.sample;
import jakarta.ws.rs.Path;
import io.quarkus.qute.TemplateInstance;
import io.quarkus.qute.CheckedTemplate;
@Path("item")
public class ItemResource {
    @CheckedTemplate(basePath = "items", defaultName = CheckedTemplate.HYPHENATED_ELEMENT_NAME)
    static class Templates {
        static native TemplateInstance itemAndOrder(Item item); (1)
4.5.3. Type-safe Fragments

You can also define a type-safe fragment in your Java code. A native static method with the name that contains a dollar sign $ denotes a method that represents a fragment of a type-safe template. The name of the fragment is derived from the annotated method name. The part before the last occurence of a dollar sign $ is the method name of the related type-safe template. The part after the last occurence of a dollar sign is the fragment identifier. The strategy defined by the relevant CheckedTemplate#defaultName() is honored when constructing the defaulted names.
Type-safe Fragment Example
import io.quarkus.qute.CheckedTemplate;
import org.acme.Item;
@CheckedTemplate
class Templates {
  // defines a type-safe template
  static native TemplateInstance items(List<Item> items);
  // defines a fragment of Templates#items() with identifier "item"
  static native TemplateInstance items$item(Item item); (1)
Quarkus validates at build time that each template that corresponds to the Templates#items() contains a fragment with identifier item. Moreover, the parameters of the fragment method are validated too. In general, all type-safe expressions that are found in the fragment and that reference some data from the original/outer template require a specific parameter to be present.
  String renderItem(Item item) {
     // this would return something like "<li>Foo</li>"
     return Templates.items$item(item).render();
4.6. Template Extension Methods

Extension methods can be used to extend the data classes with new functionality (to extend the set of accessible properties and methods) or to resolve expressions for a specific namespace. For example, it is possible to add computed properties and virtual methods.
A value resolver is automatically generated for a method annotated with @TemplateExtension. If a class is annotated with @TemplateExtension then a value resolver is generated for every non-private static method declared on the class. Method-level annotations override the behavior defined on the class. Methods that do not meet the following requirements are ignored.
A template extension method:
If there is no namespace defined the class of the first parameter that is not annotated with @TemplateAttribute is used to match the base object. Otherwise, the namespace is used to match an expression.
4.6.1. Matching by Name

The method name is used to match the property name by default.
Extension Method Example
package org.acme;
class Item {
    public final BigDecimal price;
    public Item(BigDecimal price) {
        this.price = price;
@TemplateExtension
class MyExtensions {
    static BigDecimal discountedPrice(Item item) { (1)
        return item.getPrice().multiply(new BigDecimal("0.9"));
@TemplateExtension(matchName = "discounted")
static BigDecimal discountedPrice(Item item) {
   // this method matches {item.discounted} if "item" resolves to an object assignable to "Item"
   return item.getPrice().multiply(new BigDecimal("0.9"));
A special constant - TemplateExtension#ANY/* - can be used to specify that the extension method matches any name.
TemplateExtension#ANY Example
@TemplateExtension(matchName = "*")
static String itemProperty(Item item, String name) { (1)
   // this method matches {item.foo} if "item" resolves to an object assignable to "Item"
   // the value of the "name" argument is "foo"
It’s also possible to match the name against a regular expression specified in matchRegex().
TemplateExtension#matchRegex() Example
@TemplateExtension(matchRegex = "foo|bar")
static String itemProperty(Item item, String name) { (1)
   // this method matches {item.foo} and {item.bar} if "item" resolves to an object assignable to "Item"
   // the value of the "name" argument is "foo" or "bar"
Finally, matchNames() can be used to specify a collection of matching names. An additional string method parameter is mandatory as well.
TemplateExtension#matchNames() Example
@TemplateExtension(matchNames = {"foo", "bar"})
static String itemProperty(Item item, String name) {
   // this method matches {item.foo} and {item.bar} if "item" resolves to an object assignable to "Item"
   // the value of the "name" argument is "foo" or "bar"
4.6.2. Method Parameters

An extension method may declare parameters. If no namespace is specified then the first parameter that is not annotated with @TemplateAttribute is used to pass the base object, i.e. org.acme.Item in the first example. If matching any name or using a regular expression, then a string method parameter needs to be used to pass the property name. Parameters annotated with @TemplateAttribute are obtained via TemplateInstance#getAttribute(). All other parameters are resolved when rendering the template and passed to the extension method.
Multiple Parameters Example
@TemplateExtension
class BigDecimalExtensions {
    static BigDecimal scale(BigDecimal val, int scale, RoundingMode mode) { (1)
        return val.setScale(scale, mode);
4.6.3. Namespace Extension Methods

If TemplateExtension#namespace() is specified then the extension method is used to resolve expressions with the given namespace. Template extension methods that share the same namespace are grouped in one resolver ordered by TemplateExtension#priority(). The first matching extension method is used to resolve an expression.
Namespace Extension Method Example
@TemplateExtension(namespace = "str")
public class StringExtensions {
   static String format(String fmt, Object... args) {
      return String.format(fmt, args);
   static String reverse(String val) {
      return new StringBuilder(val).reverse().toString();
These extension methods can be used as follows.
{str:format('%s %s!','Hello', 'world')} (1)
{str:reverse('hello')} (2)

4.7.1. Accessing Static Fields and Methods

If @TemplateData#namespace() is set to a non-empty value then a namespace resolver is automatically generated to access the public static fields and methods of the target class. By default, the namespace is the FQCN of the target class where dots and dollar signs are replaced by underscores. For example, the namespace for a class with name org.acme.Foo is org_acme_Foo. The static field Foo.AGE can be accessed via {org_acme_Foo:AGE}. The static method Foo.computeValue(int number) can be accessed via {org_acme_Foo:computeValue(10)}.
public class Statuses {
    public static final String ON = "on";
    public static final String OFF = "off";
4.7.2. Convenient Annotation For Enums

There’s also a convenient annotation to access enum constants: @io.quarkus.qute.TemplateEnum. This annotation is functionally equivalent to @TemplateData(namespace = TemplateData.SIMPLENAME), i.e. a namespace resolver is automatically generated for the target enum and the simple name of the target enum is used as the namespace.




    

Enum Annotated With @TemplateEnum
package model;
@TemplateEnum (1)
public enum Status {
4.8. Global Variables

The io.quarkus.qute.TemplateGlobal annotation can be used to denote static fields and methods that supply global variables which are accessible in any template. Internally, each global variable is added to the data map of any TemplateInstance via the TemplateInstance#data(String, Object) method.
Global Variables Definition
enum Color { RED, GREEN, BLUE }
@TemplateGlobal (1)
public class Globals {
    static int age = 40;
    static Color[] myColors() {
      return new Color[] { Color.RED, Color.BLUE };
    @TemplateGlobal(name = "currentUser") (2)
    static String user() {
       return "Mia";
If a class is annotated with @TemplateGlobal then every non-void non-private static method that declares no parameters and every non-private static field is considered a global variable. The name is defaulted, i.e. the name of the field/method is used.
Method-level annotations override the class-level annotation. In this particular case, the name is not defaulted but selected explicitly.
4.8.1. Resolving Conflicts

Global variables may conflict with regular data objects. Type-safe templates override the global variables automatically. For example, the following definition overrides the global variable supplied by the Globals#user() method:
Type-safe Template Definition
import org.acme.User;
@CheckedTemplate
public class Templates {
    static native TemplateInstance hello(User currentUser); (1)
So the corresponding template does not result in a validation error even though the Globals#user() method returns java.lang.String which does not have the name property:
templates/hello.txt
User name: {currentUser.name} (1)

4.9. Native Executables

In the JVM mode a reflection-based value resolver may be used to access properties and call methods of the model classes. But this does not work for a native executable out of the box. As a result, you may encounter template exceptions like Property "name" not found on the base object "org.acme.Foo" in expression {foo.name} in template hello.html even if the Foo class declares a relevant getter method.
There are several ways to solve this problem:
Annotate the model class with @TemplateData - a specialized value resolver is generated and used at runtime
Annotate the model class with @io.quarkus.runtime.annotations.RegisterForReflection to make the reflection-based value resolver work
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-resteasy-reactive-qute</artifactId>
</dependency>
Both of these extensions register a special ContainerResponseFilter implementation which enables resource methods to return a TemplateInstance, thus freeing users of having to take care of all necessary internal steps.
The end result is that a using Qute within a Jakarta REST resource may look as simple as:
HelloResource.java
package org.acme.quarkus.sample;
import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.QueryParam;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
import io.quarkus.qute.TemplateInstance;
import io.quarkus.qute.Template;
@Path("hello")
public class HelloResource {
    @Inject
    Template hello; (1)
    @Produces(MediaType.TEXT_PLAIN)
    public TemplateInstance get(@QueryParam("name") String name) {
        return hello.data("name", name); (2) (3)
If there is no @Location 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.
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.
Note that we don’t trigger the rendering - this is done automatically by a special ContainerResponseFilter implementation.
    @Produces({ MediaType.TEXT_HTML, MediaType.TEXT_PLAIN })
    public TemplateInstance item() {
        return item.data("myItem", new Item("Alpha", 1000)); (2)
Inject a variant template with base path derived from the injected field - src/main/resources/templates/item.
For text/plain the src/main/resources/templates/item.txt template is used. For text/html the META-INF/resources/templates/item.html template is used.
The RestTemplate util class can be used to obtain a template instance from a body of a Jakarta REST resource method:
RestTemplate Example
@Path("/detail")
class DetailResource {
    @Produces({ MediaType.TEXT_HTML, MediaType.TEXT_PLAIN })
    public TemplateInstance item() {
        return RestTemplate.data("myItem", new Item("Alpha", 1000)); (1)
4.12.1. Basic Concepts

The basic idea is that every message is potentially a very simple template. In order to prevent type errors, a message is defined as an annotated method of a message bundle interface. Quarkus generates the message bundle implementation at build time.
Message Bundle Interface Example
import io.quarkus.qute.i18n.Message;
import io.quarkus.qute.i18n.MessageBundle;
@MessageBundle (1)
public interface AppMessages {
    @Message("Hello {name}!") (2)
    String hello_name(String name); (3)
Denotes a message bundle interface. The bundle name is defaulted to msg and is used as a namespace in templates expressions, e.g. {msg:hello_name}.
Each method must be annotated with @Message. The value is a qute template. If no value is provided, then a corresponding value from a localized file is taken. If no such file exists, an exception is thrown and the build fails.
The method parameters can be used in the template.
Directly in your code via io.quarkus.qute.i18n.MessageBundles#get(); e.g. MessageBundles.get(AppMessages.class).hello_name("Lucie")
Injected in your beans via @Inject; e.g. @Inject AppMessages
Referenced in the templates via the message bundle namespace:
 {msg:hello_name('Lucie')} (1) (2) (3)
 {msg:message(myKey,'Lu')} (4)

4.12.2. Default Bundle Name

The bundle name is defaulted unless it’s specified with @MessageBundle#value(). For a top-level class the msg value is used by default. For a nested class the name consists of the simple names of all enclosing classes in the hierarchy (top-level class goes first), followed by the simple name of the message bundle interface. Names are separated by underscores.
For example, the name of the following message bundle will be defaulted to Controller_index:
class Controller {
    @MessageBundle
    interface index {
        @Message("Hello {name}!")
        String hello(String name); (1)
4.12.3. Bundle Name and Message Keys

Message keys are used directly in templates. The bundle name is used as a namespace in template expressions. The @MessageBundle can be used to define the default strategy used to generate message keys from method names. However, the @Message can override this strategy and even define a custom key. By default, the annotated element’s name is used as-is. Other possibilities are:
All expressions without a namespace must map to a parameter; e.g. Hello {foo} → the method must have a param of name foo
All expressions are validated against the types of the parameters; e.g. Hello {foo.bar} where the parameter foo is of type org.acme.Foo → org.acme.Foo must have a property of name bar
Message bundle files must be encoded in UTF-8. The file name consists of the relevant bundle name (e.g. msg) and underscore followed by a language tag (IETF; e.g. en-US). The language tag may be omitted, in which case the language tag of the default bundle locale is used. For example, if bundle msg has default locale en, then msg.properties is going to be treated as msg_en.properties. If both msg.properties and msg_en.properties are detected, an exception is thrown and build fails. The file format is very simple: each line represents either a key/value pair with the equals sign used as a separator or a comment (line starts with #). Blank lines are ignored. Keys are mapped to method names from the corresponding message bundle interface. Values represent the templates normally defined by io.quarkus.qute.i18n.Message#value(). A value may be spread out across several adjacent normal lines. In such case, the line terminator must be escaped with a backslash character \. The behavior is very similar to the behavior of the java.util.Properties.load(Reader) method.
Localized File Example - msg_de.properties
# This comment is ignored
hello_name=Hallo {name}! (1) (2)

Each line in a localized file represents a key/value pair. The key must correspond to a method declared on the message bundle interface. The value is the message template.
Keys and values are separated by the equals sign.
An example properties file is generated into the target directory for each message bundle interface automatically. For example, by default if no name is specified for @MessageBundle the file target/qute-i18n-examples/msg.properties is generated when the application is build via mvn clean package. You can use this file as a base for a specific locale. Just rename the file - e.g. msg_fr.properties, change the message templates and move it in the src/main/resources/messages directory.
Note that the line terminator is escaped with a backslash character \ and white space at the start of the following line is ignored. I.e. {msg:hello('Edgar')} would be rendered as Hello Edgar and good morning!.
Once we have the localized bundles defined, we need a way to select the correct bundle for a specific template instance, i.e. to specify the locale for all message bundle expressions in the template. By default, the locale specified via the quarkus.default-locale configuration property is used to select the bundle. Alternatively, you can specify the locale attribute of a template instance.
locale Attribute Example
@Singleton
public class MyBean {
    @Inject
    Template hello;
    String render() {
       return hello.instance().setAttribute("locale", Locale.forLanguageTag("cs")).render(); (1)
4.12.6. Message Templates

Every method of a message bundle interface must define a message template. The value is normally defined by io.quarkus.qute.i18n.Message#value(), but for convenience, there is also an option to define the value in a localized file.
Example of the Message Bundle Interface without the value
import io.quarkus.qute.i18n.Message;
import io.quarkus.qute.i18n.MessageBundle;
@MessageBundle
public interface AppMessages {
    @Message (1)
    String hello_name(String name);
    @Message("Goodbye {name}!") (2)
    String goodbye(String name);
The annotation value is not defined. In such a case, the value from supplementary localized file is taken.
The annotation value is defined and preferred to the value defined in the localized file.
By default, engine.getTemplate("foo") would result in several lookups: foo, foo.html, foo.txt, etc.
Environment variable: QUARKUS_QUTE_SUFFIXES

The list of exclude rules used to intentionally ignore some parts of an expression when performing type-safe validation.
An element value must have at least two parts separated by dot. The last part is used to match the property/method name. The prepended parts are used to match the class name. The value * can be used to match any name.
Examples:
This regular expression is used to exclude template files from the templates directory. Excluded templates are neither parsed nor validated during build and are not available at runtime.
The matched input is the file path relative from the templates directory and the / is used as a path separator.
By default, the hidden files are excluded. The name of a hidden file starts with a dot.
Environment variable: QUARKUS_QUTE_TEMPLATE_PATH_EXCLUDE

<alias_> - the alias of an iterated element suffixed with an underscore is used, e.g. item_hasNext and it_count
<alias?> - the alias of an iterated element suffixed with a question mark is used, e.g. item?hasNext and it?count
<none> - no prefix is used, e.g. hasNext and count  By default, the <alias_> constant is set.
The list of content types for which the ', ", <, > and & characters are escaped if a template variant is set.
Environment variable: QUARKUS_QUTE_ESCAPE_CONTENT_TYPES

The strategy used when a standalone expression evaluates to a "not found" value at runtime and the quarkus.qute.strict-rendering config property is set to false
This strategy is never used when evaluating section parameters, e.g. {#if foo.name}. In such case, it’s the responsibility of the section to handle this situation appropriately.
By default, the NOT_FOUND constant is written to the output. However, in the development mode the PropertyNotFoundStrategy#THROW_EXCEPTION is used by default, i.e. when the strategy is not specified.
Environment variable: QUARKUS_QUTE_PROPERTY_NOT_FOUND_STRATEGY

Specify whether the parser should remove standalone lines from the output. A standalone line is a line that contains at least one section tag, parameter declaration, or comment but no expression and no non-whitespace character.
Environment variable: QUARKUS_QUTE_REMOVE_STANDALONE_LINES

If set to true then any expression that is evaluated to a Results.NotFound value will always result in a TemplateException and the rendering is aborted.
Note that the quarkus.qute.property-not-found-strategy config property is completely ignored if strict rendering is enabled.
Environment variable: QUARKUS_QUTE_STRICT_RENDERING

The global rendering timeout in milliseconds. It is used if no timeout template instance attribute is set.
Environment variable: QUARKUS_QUTE_TIMEOUT

If set to true then the timeout should also be used for asynchronous rendering methods, such as TemplateInstance#createUni() and TemplateInstance#renderAsync().
Environment variable: QUARKUS_QUTE_USE_ASYNC_TIMEOUT

The additional map of suffixes to content types. This map is used when working with template variants. By default, the java.net.URLConnection#getFileNameMap() is used to determine the content type of a template file.
Environment variable: QUARKUS_QUTE_CONTENT_TYPES

By default, no template locators are registered, i.e. Engine.getTemplate(String) will not work.
You can register a custom template locator using EngineBuilder.addLocator() or parse a template manually and put the result in the cache via Engine.putTemplate(String, Template).