Guia de Referência do Qute

When evaluating expressions a list of registered value resolvers is used. The first part of the expression is always resolved against the current context object. If no result is found for the first part, it’s resolved against the parent context object (if available). For an expression that starts with a namespace the current context object is found using all the available NamespaceResolvers. For an expression that does not start with a namespace the current context object is derived from the position of the tag. All other parts of an expression are resolved using all ValueResolvers against the result of the previous resolution.

For example, expression {name} has no namespace and single part - name. The "name" will be resolved using all available value resolvers against the current context object. However, the expression {global:colors} has the namespace global and single part - colors. First, all available NamespaceResolvers will be used to find the current context object. And afterwards value resolvers will be used to resolve "colors" against the context object found.

If an expression does not specify a namespace, the current context object is derived from the position of the tag. By default, the current context object represents the data passed to the template instance. However, sections may change the current context object. A typical example is the let section that can be used to define named local variables:

You can iterate over elements of an array with Loop Section. Moreover, it’s also possible to get the length of the specified array and access the elements directly via an index value. Additionally, you can access the first/last n elements via the take(n)/takeLast(n) methods.

For HTML and XML templates the ', ", <, >, & characters are escaped by default if a template variant is set.

If you need to render the unescaped value:

A virtual method is a part of an expression that looks like a regular Java method invocation. It’s called "virtual" because it does not have to match the actual method of a Java class. In fact, like normal properties a virtual method is also handled by a value resolver. The only difference is that for virtual methods a value resolver consumes parameters that are also expressions.

A virtual method with single parameter can be called using the infix notation:

Virtual method parameters can be "nested" virtual method invocations.

Objects that implement java.util.concurrent.CompletionStage and io.smallrye.mutiny.Uni are evaluated in a special way. If a part of an expression resolves to a CompletionStage, the resolution continues once this stage is completed and the next part of the expression (if any) is evaluated against the result of the completed stage. For example, if there is an expression {foo.size} and foo resolves to CompletionStage<List<String>> then size is resolved against the completed result, i.e. List<String>. If a part of an expression resolves to a Uni, a CompletionStage is first created from Uni using Uni#subscribeAsCompletionStage() and then evaluated as described above.

It can happen that a CompletionStage never completes or a Uni emits no item/failure. In this case, the rendering methods (such as TemplateInstance#render() and TemplateInstance#createUni()) fail after a specific timeout. The timeout can be specified as a template instance timeout attribute. If no timeout attribute is set the global rendering timeout is used.

It can happen that an expression may not be evaluated at runtime. For example, if there is an expression {person.age} and there is no property age declared on the Person class. The behavior differs based on whether the Strict Rendering is enabled or not.

If enabled then a missing property will always result in a TemplateException and the rendering is aborted. You can use default values and safe expressions in order to suppress the error.

If disabled then the special constant NOT_FOUND is written to the output by default.

A start tag can define parameters with optional names, e.g. {#if item.isActive} and {#let foo=1 bar=false}. Parameters are separated by one or more spaces. Names are separated from the values by the equals sign. Names and values can be prefixed and suffixed with any number of spaces, e.g. {#let id='Foo'} and {#let id = 'Foo'} are equivalents where the name of the parameter is id and the value is Foo. Values can be grouped using parentheses, e.g. {#let id=(item.id ?: 42)} where the name is id and the value is item.id ?: 42. Sections can interpret parameter values in any way, e.g. take the value as is. However, in most cases, the parameter value is registered as an expression and evaluated before use.

A section may contain several content blocks. The "main" block is always present. Additional/nested blocks also start with # and can have parameters too - {#else if item.isActive}. A section helper that defines the logic of a section can "execute" any of the blocks and evaluate the parameters.

The loop section makes it possible to iterate over an instance of Iterable, Iterator, array, Map (element is a Map.Entry), Stream, Integer, Long, int and long (primitive value). A null parameter value results in a no-op.

This section has two flavors. The first one is using the name each and it is an implicit alias for the iteration element.

The other form is using the name for and specifies the alias used to reference the iteration element:

It’s also possible to access the iteration metadata inside the loop via the following keys:

However, the keys cannot be used directly. Instead, a prefix is used to avoid possible collisions with variables from the outer scope. By default, the alias of an iterated element suffixed with an underscore is used as a prefix. For example, the hasNext key must be prefixed with it_ inside an {#each} section: {it_hasNext}.

And must be used in a form of {item_hasNext} inside a {#for} section with the item element alias.

The for statement also works with integers, starting from 1. In the example below, considering that total = 3:

And the output will be:

A loop section may also define the {#else} block that is executed when there are no items to iterate:

The if section represents a basic control flow section. The simplest possible version accepts a single parameter and renders the content if the condition is evaluated to true. A condition without an operator evaluates to true if the value is not considered falsy, i.e. if the value is not null, false, an empty collection, an empty map, an empty array, an empty string/char sequence or a number equal to zero.

You can also use the following operators in a condition:

Multiple conditions are also supported.

Precedence rules can be overridden by parentheses.

You can also add any number of else blocks:

This section is similar to Java’s switch or Kotlin’s when constructs. It matches a tested value against all blocks sequentially until a condition is satisfied. The first matching block is executed. All other blocks are ignored (this behavior differs to the Java switch where a break statement is necessary).

A tested value that resolves to an enum is handled specifically. The parameters of an is/case block are not evaluated as expressions but compared with the result of toString() invocation upon the tested value.

The following operators are supported in is/case block conditions:

This section allows you to define named local variables:

If a key of a section parameter, such as the name of the local variable, ends with a ?, then the local variable is only set if the key without the ? suffix resolves to null or "not found":

This section tag is also registered under the set alias:

This section can be used to set the current context object. This could be useful to simplify the template structure:

This section might also come in handy when we’d like to avoid multiple expensive invocations:

This section can be used to include another template and possibly override some parts of the template (see the template inheritance below).

Template inheritance makes it possible to reuse template layouts.

User-defined tags can be used to include a tag template, optionally pass some arguments and possibly override some parts of the template. Let’s suppose we have a tag template called itemDetail.html:

In Quarkus, all files from the src/main/resources/templates/tags are registered and monitored automatically. For Qute standalone, you need to put the parsed template under the name itemDetail.html and register a relevant UserTagSectionHelper to the engine:

Then, we can call the tag like this:

By default, a tag template cannot reference the data from the parent context. Qute executes the tag as an isolated template, i.e. without access to the context of the template that calls the tag. However, sometimes it might be useful to change the default behavior and disable the isolation. In this case, just add _isolated=false or _unisolated argument to the call site, for example {#itemDetail item showImage=true _isolated=false /} or {#itemDetail item showImage=true _unisolated /}.

A fragment represents a part of the template that can be treated as a separate template, i.e. rendered separately. One of the main motivations to introduce this feature was to support use cases like htmx fragments.

Fragments can be defined with the {#fragment} section. Each fragment has an identifier that can only consist of alphanumeric characters and underscores.

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

The snippet above should render something like:

You can also include a fragment with an {#include} section inside another template or the template that defines the fragment.

This section can be used to parse and evaluate a template dynamically. The behavior is very similar to Include Section but:

Sometimes it’s practical to cache parts of the template that rarely change. In order to use the caching capability, register and configure the built-in io.quarkus.qute.CacheSectionHelper.Factory:

Then, the {#cached} section can be used in a template:

Value resolvers are used when evaluating expressions. First the resolvers that apply to the given EvalContext are filtered. Then the resolver with highest priority is used to resolve the data. If a io.quarkus.qute.Results.NotFound object is returned then the next available resolver is used instead. However, null return value is considered a valid result.

A custom io.quarkus.qute.ValueResolver can be registered programmatically via EngineBuilder.addValueResolver().

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.

Content filters can be used to modify the template contents before parsing.

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.

Strict rendering is enabled by default. However, you can disable this functionality via io.quarkus.qute.EngineBuilder.strictRendering(boolean).

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

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.

If using templates in Jakarta REST resources, you can rely on the following convention:

You can also declare a top-level Java class annotated with @CheckedTemplate:

Then declare one public static native TemplateInstance method(); per template file. Use those static methods to build your template instances:

A Java record that implements io.quarkus.qute.TemplateInstance denotes a type-safe template. The record components represent the template parameters and @io.quarkus.qute.CheckedTemplate can be optionally used to configure the template.

The path of a type-safe template (@CheckedTemplate method or record) consists of a base path and a defaulted name. The base path is supplied by the @CheckedTemplate#basePath(). By default, the simple name of the enclosing 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/record is used as is.

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.

The method name is used to match the property name by default.

This template extension method makes it possible to render the following template:

However, it is possible to specify the matching name with matchName().

A special constant - TemplateExtension#ANY/* - can be used to specify that the extension method matches any name.

It’s also possible to match the name against a regular expression specified in matchRegex().

Finally, matchNames() can be used to specify a collection of matching names. An additional string method parameter is mandatory as well.

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.

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.

These extension methods can be used as follows.

Quarkus provides a set of built-in extension 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)}.

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.

If not accessed via the global: namespace the 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:

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:

For other templates an explicit parameter declaration is needed:

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.

The message bundles can be used at runtime:

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:

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:

The default locale specified via the quarkus.default-locale config property is used for the @MessageBundle interface by default. However, the io.quarkus.qute.i18n.MessageBundle#locale() can be used to specify a custom locale. Additionally, there are two ways to define a localized bundle:

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.

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.

The @Localized qualifier can be used to inject a localized message bundle interface.

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.

Message templates are validated during the build. If a missing message template is detected, an exception is thrown and build fails.