Creating a Website with Ktor (Part 2: Using FreeMarker)

Exploring Ktor Projects

4 min readMay 2, 2024

In the previous article, “Creating a Website with Ktor (Part 1: Setting Up),” we focused on setting up a Ktor project and getting it started. In this installment, we’ll delve into creating web pages using a template engine. We’ll specifically use ‘FreeMarker’, a popular template engine that enhances the efficiency of web development. While Ktor supports various template engines, this article will concentrate on integrating and understanding the basics of FreeMarker.

❓ What is ‘FreeMarker’?

FreeMarker is a template engine that allows the creation of static text files using HTML tags on Java or Kotlin platforms. Although it incorporates unique syntax for integrating dynamic data, the static parts are authored just like a regular HTML file. This means that if you already have a basic understanding of HTML, you can quickly adapt to using FreeMarker.

Consider this example of an HTML code, which is also valid as a FreeMarker template file:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My First Ktor</title>
</head>
<body>
    <h1>Hello, Ktor!</h1>
</body>
</html>

It’s important to note that FreeMarker, first released in 1999, is much older than Ktor, which debuted in 2016. Despite its age, FreeMarker should not be dismissed as outdated. It is recommended on the official Ktor tutorial site and continues to be employed in various projects today. This longevity and ongoing usage underscore its stability and consistent improvements over the years.

For those interested in learning more about FreeMarker, please visit its official website: https://freemarker.apache.org/

For now, understanding FreeMarker as a tool that allows for the creation of template files using HTML tags will suffice for our purposes in this article.

🔧 Setting Up FreeMarker

To begin using FreeMarker in your Ktor project, you first need to include the necessary dependencies. Open your build.gradle.kts file and add the following line under dependencies:

implementation("io.ktor:ktor-server-freemarker:$ktor_version")

After setting up the dependency, proceed to configure FreeMarker within your project. Create a new Kotlin file named Templating.kt in the plugins directory and include the following setup:

import freemarker.cache.*
import io.ktor.server.application.*
import io.ktor.server.freemarker.*

fun Application.configureTemplating() {
    install(FreeMarker) {
        templateLoader = ClassTemplateLoader(this::class.java.classLoader, "templates")
    }
}

This code snippet demonstrates how to install FreeMarker into your Ktor application. The templateLoader configuration specifies that FreeMarker should load templates from a directory named templates.

As of now, the templates directory does not exist, so your next step is to create this directory within the resources directory of your project. This is where all your FreeMarker templates will reside.

Next, we’ll look into creating a template file within the templates directory, which will allow us to start defining our web pages using FreeMarker.

✏ Creating a FreeMarker Template File

Now it’s time to create a new template file. Inside the templates directory, create a file named index.ftl and insert the following HTML code:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My First Ktor</title>
    <style>
        body { height: 100vh; display: grid; place-items: center; font-family: sans-serif; }
    </style>
</head>
<body>
    <h1 style="color: red;">Hello, Ktor!</h1>
</body>
</html>

This simple HTML structure includes embedded CSS for simplicity, but it’s generally better to manage styles separately through CSS files. However, for the purpose of this tutorial, styles are included within the HTML to keep things straightforward. The beauty of using FreeMarker is that it allows us to leverage standard HTML techniques seamlessly in our templates.

Next, we’ll configure the routing to serve this template and see how it appears in a web browser.

💡 Setting the Routing and Displaying the Page

To display template files using FreeMarker, you need to pass a FreeMarkerContent() object to the response function. This function requires two arguments: the first is the name of the template file, and the second is a map of the data that will be dynamically passed to the template. Since we don't need to pass any dynamic data in this example, we'll set the second argument to null. Here's how you can set up the routing:

get("/index") {
    call.respond(FreeMarkerContent("index.ftl", null))
}

Run the project and navigate to http://0.0.0.0:8080/index. You should see the text "Hello, Ktor" in red displayed in your web browser:

In this tutorial, we’ve focused on a static introduction to using FreeMarker without diving into dynamic data handling. A more detailed exploration of dynamic content with FreeMarker will be covered in a future article. For now, I recommend that beginners familiarize themselves with the basics of setting up and displaying static content using FreeMarker.

<aside>
  <p>
    Thank you for reading!<br>
    If you enjoyed this post, <br>
    I'd appreciate a clap. 😄
  </p>
</aside>