JavaScript Interop

Introduction

Kweb's DOM interaction functionality is build on top of two functions that allow you to interact directly with the browser's JavaScript interpreter:

Note that this is unrelated to Kotlin's ability to compile to JavaScript.

Calling a JavaScript function

doc.body {
    browser.callJsFunction("""alert("Hello World!")""")
}

Calling with parameters

You can pass parameters to a JavaScript function by passing them as arguments to the callJsFunction() function, using {} for substitution:

doc.body {
    val greeting = "Hello".json
    val name = "World".json
    browser.callJsFunction("""alert({} + " " + {} + "!")""", greeting, name)
}

Parameters must be converted to a JsonElement, for example by using the json extension property. Within the JavaScript code the {} should be treated like a variable, so alert({}) is ok but alert("{}") will not work.

Function caching and preloading

Kotlin automatically caches JavaScript functions in the browser for efficiency. If the function is first called during initial page render, it will be parsed and cached as part of the initial page load.

Calling a JavaScript function with a result

You can also retrieve a result from a function call using callJsFunctionWithResult(). Note that the last line of the jsBody parameter must be a return statement:

doc.body {
    elementScope().launch {
        val result : JsonElement = browser.callJsFunctionWithResult("return Date.now()")
        println("Result: ${result.jsonPrimitive.intOrNull}")
    }
}

callJsFunctionWithResult() is a suspend function so it must be called inside a CoroutineScope. You can create one within Kweb's DSL using elementScope(). This scope will be cancelled automatically when this part of the DOM is no-longer needed.

Including static JavaScript files

The JavascriptPlugin can be used to conveniently add multiple static JavaScript files to your website, just add it to your resources folder as follows:

├── src
│  └─── main
│      └─── resources
│          └─── script
│              └── test.js

Next add the plugin via the plugins constructor parameter.

Kweb(port = 16097, plugins = listOf(JavascriptPlugin("script", "test.js"))) {
    // ...
}

Specify the relative path to the folder inside src/main/resources and the files to include (either a single file name or a list of file names).

The files will be served under /kweb_static/js and linked from the websites HTML head tag, for example:

<script type="text/javascript" src="/kweb_static/js/test.js"></script>