Quarkus QuteServerPages

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

The index.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/index.html will be served from the paths /qsp/index, /qsp/index.html and /qsp/ by default.

Installation

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

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

<dependency>
    <groupId>io.quarkiverse.quteserverpages</groupId>
    <artifactId>quarkus-qute-server-pages</artifactId>
    <version>2.0.1.Final</version>
</dependency>

Accessing Data

In a template you can access:

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 /qsp/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/foo.html and src/main/resource/templates/foo.xml and the client sends the Accept: text/html, application/xml;q=0.9 header then foo.html is rendeder and the Content-type: text/html header is set.

qsp: Namespace

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

Name Description Example

qsp:request

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

{qsp:request.path}

qsp:param

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

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

qsp:header

Return the first HTTP request header value with the specified name

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

qsp:headers

Makes it possible to access HTTP header values like properties

{qsp:headers.Accept-Encoding} or {qsp: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 {qsp: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.qsp.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 /qsp/foo and /qsp/foo.html by default.

Environment variable: QUARKUS_QSP_ROOT_PATH

string

/qsp

quarkus.qsp.hidden-templates

This regular expression is used to hide template files from the src/main/resource/templates directory. 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 templates directory and the / is used as a path separator. For example, a template located in src/main/resource/templates/foo.html will be matched for foo.tml and foo.

By default, the user tags from the src/main/resource/templates/tags directory are hidden.

Environment variable: QUARKUS_QSP_HIDDEN_TEMPLATES

Pattern

tags/.*

quarkus.qsp.route-order

The order of the qsp route which handles the templates.

Environment variable: QUARKUS_QSP_ROUTE_ORDER

int

quarkus.qsp.use-blocking-handler

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

Environment variable: QUARKUS_QSP_USE_BLOCKING_HANDLER

boolean

true