Ktor 3.0.0-beta-1 Help

Thymeleaf

Ktor allows you to use Thymeleaf templates as views within your application by installing the Thymeleaf plugin.

Add dependencies

To use Thymeleaf, you need to include the ktor-server-thymeleaf artifact in the build script:

implementation("io.ktor:ktor-server-thymeleaf:$ktor_version")
implementation "io.ktor:ktor-server-thymeleaf:$ktor_version"
<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-server-thymeleaf-jvm</artifactId> <version>${ktor_version}</version> </dependency>

Install Thymeleaf

To install the Thymeleaf plugin to the application, pass it to the install function in the specified module. The code snippets below show how to install Thymeleaf...

  • ... inside the embeddedServer function call.

  • ... inside the explicitly defined module, which is an extension function of the Application class.

import io.ktor.server.engine.* import io.ktor.server.netty.* import io.ktor.server.application.* import io.ktor.server.thymeleaf.* fun main() { embeddedServer(Netty, port = 8080) { install(Thymeleaf) // ... }.start(wait = true) }
import io.ktor.server.application.* import io.ktor.server.thymeleaf.* // ... fun Application.module() { install(Thymeleaf) // ... }

Configure Thymeleaf

Configure template loading

Inside the install block, you can configure the ClassLoaderTemplateResolver. For example, the code snippet below enables Ktor to look up *.html templates in the templates package relative to the current classpath:

import io.ktor.server.application.* import io.ktor.server.thymeleaf.* import org.thymeleaf.templateresolver.ClassLoaderTemplateResolver fun Application.module() { install(Thymeleaf) { setTemplateResolver(ClassLoaderTemplateResolver().apply { prefix = "templates/" suffix = ".html" characterEncoding = "utf-8" }) } }

Send a template in response

Imagine you have the index.html template in resources/templates:

<html xmlns:th="http://www.thymeleaf.org"> <body> <h1 th:text="'Hello, ' + ${user.name}"></h1> </body> </html>

A data model for a user looks as follows:

data class User(val id: Int, val name: String)

To use the template for the specified route, pass ThymeleafContent to the call.respond method in the following way:

get("/index") { val sampleUser = User(1, "John") call.respond(ThymeleafContent("index", mapOf("user" to sampleUser))) }

Example: Auto reload Thymeleaf templates

The example below shows how to reload Thymeleaf templates automatically when development mode is used.

package com.example import io.ktor.server.application.* import io.ktor.server.response.* import io.ktor.server.routing.* import io.ktor.server.thymeleaf.* import org.thymeleaf.templateresolver.* fun main(args: Array<String>): Unit = io.ktor.server.netty.EngineMain.main(args) fun Application.module() { install(Thymeleaf) { setTemplateResolver((if (developmentMode) { FileTemplateResolver().apply { cacheManager = null prefix = "src/main/resources/templates/" } } else { ClassLoaderTemplateResolver().apply { prefix = "templates/" } }).apply { suffix = ".html" characterEncoding = "utf-8" }) } routing { get("/index") { val sampleUser = User(1, "John") call.respond(ThymeleafContent("index", mapOf("user" to sampleUser))) } } } data class User(val id: Int, val name: String)

You can find the complete example here: thymeleaf-auto-reload.

Last modified: 02 April 2024