How do I provide a page template in kotlinx-html?

Question

How do I provide a page template in kotlinx-html?

843 Views Asked by ChrLipp At 16 April 2025 at 17:35

I would like to generate a bunch of HTML files with kotlinx-html and I want to start each file with the same template. I would like to have a function for the base structure and provide a lamda to this function for the specific content like so (non working code):

// provide block as a div for the sub content, does not work!
private fun createHtmlPage(block : () -> DIV.()): String {
    val html = createHTMLDocument().html {
        head {
            meta { charset = "utf-8" }
            meta { name="viewport"; content="width=device-width, initial-scale=1" }
            title { +"Tables" }
            link(href = "https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css", "style")
        }
        body {
            block {}
            script("", "https://cdn.jsdelivr.net/npm/[email protected]/dist/js/bootstrap.bundle.min.js") {}
        }
    }
    return html.serialize(true)
}

and use this function like this (again non working code):

private fun createIndexPage(tables: Tables) {
    val indexFile = File(path, "index.html")

    // call my template function with a lamda - does not work
    val html = createHtmlPage {
        h1 { +"Tables" }
        tables.tableNames.forEach { tableName ->
            a("${tableName}.html") {
                +tableName
            }
            br
        }
    }
    indexFile.writeText(html)
}

Can anyone point me in the direction how to do this?

Additional question

I have found out that project Ktor HTML DSL exists and they have template support on top of kotlinx-html. Am I supposed to use this library instead of kotlinx-html directly? Is it possible to use it without Ktor?

Original Q&A

There are 2 best solutions below

Aleksei Tirman On 29 August 2022 at 09:04

You can use the ktor-server-html-builder library without a server. Here is an example:

import io.ktor.server.html.*
import kotlinx.html.*
import kotlinx.html.stream.appendHTML

fun main() {
    val template = LayoutTemplate().apply {
        header {
            +"Ktor"
        }
        content {
            articleTitle {
                +"Hello from Ktor!"
            }
            articleText {
                +"Kotlin Framework for creating connected systems."
            }
        }
    }

    val builder = StringBuilder()
    builder.appendHTML().html(block = {
        with(template) { apply() }
    })

    println(builder.toString())
}

class LayoutTemplate: Template<HTML> {
    val header = Placeholder<FlowContent>()
    val content = TemplatePlaceholder<ContentTemplate>()
    override fun HTML.apply() {
        body {
            h1 {
                insert(header)
            }
            insert(ContentTemplate(), content)
        }
    }
}

class ContentTemplate: Template<FlowContent> {
    val articleTitle = Placeholder<FlowContent>()
    val articleText = Placeholder<FlowContent>()
    override fun FlowContent.apply() {
        article {
            h2 {
                insert(articleTitle)
            }
            p {
                insert(articleText)
            }
        }
    }
}

I recommend implementing your own layer on top of kotlinx-html for templating because that's not hard to do and it will solve your particular problem better.

**Devabc** · Accepted Answer

You don't need Ktor. It can be done with just kotlinx-html and plain Kotlin.

TLDR

Change block : () -> DIV.() to block : HtmlBlockTag.() -> Unit and change block {} to block(), so that the final code becomes:

private fun createHtmlPage(block: HtmlBlockTag.() -> Unit): String {
    val html = createHTMLDocument().html {
        head {
            meta { charset = "utf-8" }
            meta { name="viewport"; content="width=device-width, initial-scale=1" }
            title { +"Tables" }
            link(href = "https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css", "style")
        }
        body {
            block()
            script("", "https://cdn.jsdelivr.net/npm/[email protected]/dist/js/bootstrap.bundle.min.js") {}
        }
    }
    return html.serialize(true)
}

So that you can use this function with code like this:

val result = createHtmlPage {
    div {
        h1 {
            +"It is working!"
        }
    }
}

println(result)

Then the output will be:

<!DOCTYPE html>
<html>
  <head>
    <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
    <meta charset="utf-8">
    <meta content="width=device-width, initial-scale=1" name="viewport">
    <title>Tables</title>
    <link href="https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css" rel="style">
  </head>
  <body>
    <div>
      <h1>It is working!</h1>
    </div>
    <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/js/bootstrap.bundle.min.js" type=""></script>
  </body>
</html>

What's wrong with the code

Your first block of code has this signature:

private fun createHtmlPage(block : () -> DIV.()): String

This isn't valid Kotlin code, because the type of parameter block isn't valid. Instead of using type () -> DIV.() it should be DIV.() -> Unit. This is a special construct in Kotlin, called a function type with receiver, which allows you to call your createHtmlPage function with a lambda, in which the lambda is scoped to a receiver object of type DIV.

So the function should be changed to:

private fun createHtmlPage(block: DIV.() -> Unit): String

The second part that is not valid is this:

body {
    block {}
}

Because the parameter called block is of type DIV.() -> Unit, it needs to have access to an argument of type DIV. You don't have to pass with argument like in a normal function call, like block(someDiv), but it still needs access to it. But you don't have an object of type DIV available in your code, but you do have an object of type BODY, which is created by the body function. So if you change the parameter type of block from DIV.() -> Unit to BODY.() -> Unit, then you can use the BODY object created by body function.

So you can change the createHtmlPage function to:

private fun createHtmlPage(block: BODY.() -> Unit): String

and then you can provide the object of type BODY like this to block:

body {
   [email protected](this@body)
}

which can be shortened to:

body {
   this.block(this)
}

which can be shortened to:

body {
   block()
}

This last shortening step may be difficult to understand, but it's like this: because body function accepts an function type with receiver of type BODY.() -> Unit, the lambda that you pass to the body function, will be scoped to the BODY class/type, so that lambda has access to members available in the BODY type. The BODY type normally doesn't have access to the block() function, but because block is of type BODY.() -> Unit, instances of BODY also have access to the block function as if block is a member of BODY. Because the call to block() is scoped to an instance of BODY, calling block() behaves like calling aBodyInstance.block(), which is the same as block(aBodyInstance). Because of this, at this location in the code, you can also call is with just block().

Instead of using createHtmlPage(block: BODY.() -> Unit) you could also use createHtmlPage(block: HtmlBlockTag.() -> Unit) so that you can use it in other places.

How do I provide a page template in kotlinx-html?

There are 2 best solutions below

TLDR

What's wrong with the code

Related Questions in KOTLIN

Related Questions in KTOR

Related Questions in KOTLINX

Related Questions in KOTLINX-HTML

Trending Questions

Popular # Hahtags

Popular Questions