Quarkus Qute Web

The goal of this extension is to expose Qute templates located in the src/main/resource/templates/pub directory via HTTP. Automatically, no controllers needed. For example, the template src/main/resource/templates/pub/foo.html will be served from the paths /foo and /foo.html by default.

The index.html and index.qute.html pages are handled specifically, i.e. they are also served as a "default page" of the containing directory. For example, the template src/main/resource/templates/pub/index.html will be served from the paths /index, /index.html and / by default.

Installation

If you want to use this extension, you need to add the io.quarkiverse.qute.web:quarkus-qute-web extension first to your build file.

For instance, with Maven, add the following dependency to your POM file:

<dependency>
    <groupId>io.quarkiverse.qute.web</groupId>
    <artifactId>quarkus-qute-web</artifactId>
    <version>3.4.4</version>
</dependency>

Accessing Data

In a template you can access:

Data initializers

It is also possible to define a data initializer; a CDI bean that implements io.quarkiverse.qute.web.DataInitializer. It can be used to initialize template data for specific pages, i.e. to set the data and attributes of a template instance for a given path. The scope of an implementation must be @Singleton or @ApplicationScoped.

@Singleton
public class SimpleInitializer implements DataInitializer {

    @Override
    public void initialize(InitContext ctx) {
        if (ctx.path().endsWith("hello")) {
            ctx.templateInstance().data("name", "world");
        }
    }
}

Compression Support

If the HTTP compression support is enabled by means of quarkus.http.enable-compression=true then the response body is compressed if the Content-Type header derived from the template file name is a compressed media type as configured via quarkus.http.compress-media-types.

Template Fragments

It is possible to specify the template fragment via the frag query param. For example, if there is a template foo.html that defines a fragment with id bar then the fragment is served from the path /foo?frag=bar.

Content Negotiation

This extension attempts to serve the appropriate template and set the HTTP Content-type header based on the selected template variant and the value of Accept header. For example, if there are templates src/main/resource/templates/pub/foo.html and src/main/resource/templates/pub/foo.txt and the client sends the Accept: text/html, text/plain;q=0.9 header then foo.html is rendeder and the Content-type: text/html header is set.

http: Namespace

Some useful template extension methods that handle the http namespace are registered automatically.

Name Description Example

http:request

Returns the current io.vertx.core.http.HttpServerRequest

{http:request.path}

http:param

Returns the first HTTP request query param value with the specified name

{http:param('page')} or {http:param('name', 'default value')}

http:header

Return the first HTTP request header value with the specified name

{http:header('HX-Request')}

http:headers

Makes it possible to access HTTP header values like properties

{http:headers.Accept-Encoding} or {http:headers.accept-encoding}
HTTP header names are case-insensitive.
If you need to obtain all values of a specific HTTP header then you can use something similar to {http:request.headers.getAll('My-Header')}.

Extension Configuration Reference

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

Configuration property

Type

Default

quarkus.qute.web.root-path

The root path. All templates will be served relative to this path which is relative to the HTTP root path.

If the template name ends with a suffix listed in the quarkus.qute.suffixes config property then the suffix may be omitted.

For example, a template located in src/main/resource/templates/foo.html will be served from the paths /foo and /foo.html by default.

Environment variable: QUARKUS_QUTE_WEB_ROOT_PATH

string

/

quarkus.qute.web.public-dir

The directory from which the templates are served. The path is relative to a template root directroy, i.e. relative to src/main/resource/templates by default. For example, the value ping could be translated to src/main/resource/templates/ping.

By default, the templates located in the src/main/resource/templates/pub directory are served.

Environment variable: QUARKUS_QUTE_WEB_PUBLIC_DIR

string

pub

quarkus.qute.web.hidden-templates

This regular expression is used to hide template files from the web templates path. Hidden templates are not exposed.

All template file paths are matched, including the versions without suffixes. The matched input is the file path relative from the web templates path (for example templates/web) and the / is used as a path separator. For example, a template located in src/main/resource/templates/web/foo.html will be matched for foo.tml and foo.

By default, no templates are hidden.

Environment variable: QUARKUS_QUTE_WEB_HIDDEN_TEMPLATES

Pattern

quarkus.qute.web.route-order

The order of the route which handles the templates.

By default, the route is executed before the default routes (static resources, etc.).

Environment variable: QUARKUS_QUTE_WEB_ROUTE_ORDER

int

1000

quarkus.qute.web.use-blocking-handler

If set to true then the route should use a blocking handler.

Environment variable: QUARKUS_QUTE_WEB_USE_BLOCKING_HANDLER

boolean

true