Getting Started

What you’ll need

Some familiarity with Kotlin is assumed, as is familiarity with Gradle. You should also have some familiarity with HTML.

Adding Kweb to your project

Kweb is distributed via JitPack, so add this to the repositories {block} in your build.gradle:

repositories {
  maven { url 'https://jitpack.io' }
}

Then add Kweb to the dependencies block:

dependencies {
  compile 'com.github.kwebio:kweb-core:LATEST_VERSION'
}

Replace LATEST_VERSION with the latest version of Kweb, which you can find on https://jitpack.io/#kwebio/kweb-core, along with instructions for other dependency management tools like Maven and Ivy.

Hello world

Create a new Kotlin file and type this:

import io.kweb.*
import io.kweb.dom.element.*
import io.kweb.dom.element.creation.tags.*

fun main() {
  Kweb(port = 16097) {
    doc.body.new {
      h1().text("Hello World!")
    }
 }
}

Run it, and then visit http://localhost:16097/ in your web browser to see the traditional greeting, translating to the following HTML body:

<body>
  <h1>Hello World!</h1>
</body>

This simple example already illustrates some important features of Kweb:

  • Getting a kwebsite up and running is a breeze, no messing around with servlets, or third party webservers
  • Your Kweb code will loosely mirror the structure of the HTML it generates

Hello world²

One way to think of Kweb is as a domain-specific language (DSL) for building and manipulating a DOM in a remote web browser.

But this DSL can also do anything Kotlin can do, including control flow features such as for loops:

Here is a simple example using a for loop:

import io.kweb.*
import io.kweb.dom.element.*
import io.kweb.dom.element.creation.tags.*

fun main() {
  Kweb(port = 16097) {
    doc.body.new {
      ul().new {
          for (x in 1..5) {
             li().text("Hello World $x!")
          }
      }
    }
 }
}

To produce…

<body>
  <ul>
      <li>Hello World 1!</li>
      <li>Hello World 2!</li>
      <li>Hello World 3!</li>
      <li>Hello World 4!</li>
      <li>Hello World 5!</li>
  </ul>
</body>

You can use functions for modularization and reuse:

fun main() {
    Kweb(port = 16097) {
        doc.body.new {
            ul().new {
                for (x in 1..5) {
                    createMessage(x)
                }
            }
        }
    }
}

private fun ElementCreator<ULElement>.createMessage(x: Int) {
    li().text("Hello World $x!")
}

As you can see this is an extension function, which allows you to use the Kweb DSL within the newly created function.

Don’t worry if you’re unsure about this because you can use IntelliJ’s extract function refactoring to create these functions automatically.