Emit HTML with a DSL

This feature integrates with kotlinx.htmlto directly emit HTML using Chunked transfer encoding without having to keepmemory for the whole HTML.

This feature is defined in the class io.ktor.html.HtmlContent in the artifact io.ktor:ktor-html-builder:$ktor_version.

dependencies { implementation "io.ktor:ktor-html-builder:$ktor_version"}

dependencies { implementation("io.ktor:ktor-html-builder:$ktor_version")}

<project> … <dependencies> <dependency> <groupId>io.ktor</groupId> <artifactId>ktor-html-builder</artifactId> <version>${ktor.version}</version> <scope>compile</scope> </dependency> </dependencies></project>

Installing

This feature doesn’t require installation.

Basic Usage

When generating the response, instead of calling the respond/respondText methods, you have to call ApplicationCall.respondHtml:

  1. call.respondHtml {
  2.     head {
  3.         title { +"Async World" }
  4.     }
  5.     body {
  6.         h1(id = "title") {
  7.             +"Title"
  8.         }
  9.     }
  10. }

For documentation about generating HTML using kotlinx.html, please check its wiki.

Templates & Layouts

In addition to plain HTML generation with the DSL, ktor exposes a simple typed templating engine.You can use it to generate complex layouts in a typed way. It is pretty simple, yet powerful:

  1. call.respondHtmlTemplate(MulticolumnTemplate()) {
  2.     column1 {
  3.         +"Hello, $name"
  4.     }
  5.     column2 {
  6.         +"col2"
  7.     }
  8. }
  10. class MulticolumnTemplate(val main: MainTemplate = MainTemplate()) : Template<HTML> {
  11.     val column1 = Placeholder<FlowContent>()
  12.     val column2 = Placeholder<FlowContent>()
  13.     override fun HTML.apply() {
  14.         insert(main) {
  15.             menu {
  16.                 item { +"One" }
  17.                 item { +"Two" }
  18.             }
  19.             content {
  20.                 div("column") {
  21.                     insert(column1)
  22.                 }
  23.                 div("column") {
  24.                     insert(column2)
  25.                 }
  26.             }
  27.         }
  28.     }
  29. }
  31. class MainTemplate : Template<HTML> {
  32.     val content = Placeholder<HtmlBlockTag>()
  33.     val menu = TemplatePlaceholder<MenuTemplate>()
  34.     override fun HTML.apply() {
  35.         head {
  36.             title { +"Template" }
  37.         }
  38.         body {
  39.             h1 {
  40.                 insert(content)
  41.             }
  42.             insert(MenuTemplate(), menu)
  43.         }
  44.     }
  45. }
  47. class MenuTemplate : Template<FlowContent> {
  48.     val item = PlaceholderList<UL, FlowContent>()
  49.     override fun FlowContent.apply() {
  50.         if (!item.isEmpty()) {
  51.             ul {
  52.                 each(item) {
  53.                     li {
  54.                         if (it.first) b {
  55.                             insert(it)
  56.                         } else {
  57.                             insert(it)
  58.                         }
  59.                     }
  60.                 }
  61.             }
  62.         }
  63.     }
  64. }

You have to define classes implementing Template<TFlowContent>,overriding the TFlowContent.apply method and optionally definePlaceholder or TemplatePlaceholder properties just likein the example.

When generating the template with call.respondHtmlTemplate(MulticolumnTemplate()) { },you will get the template as receiver, and will be able to access the placeholdersdefined as properties in a typed way.