KotlinX HTML
A kotlinx.html library provides DSL to build HTML to Writer/Appendable or DOM at JVM and JavaScript for better Kotlin programming for Web.
Get started
There are three bundles available:
- zip with two JVM jars
- jar with JavaScripts and meta-data (required for Kotlin compiler)
- webjar with JavaScripts (without meta-data)
you can grab them at releases tab and include to your project. Use first for server-side and second for client-side
Maven
To get it work with maven you need to add custom repository
<repository>
<id>bintray-kotlinx</id>
<name>bintray</name>
<url>http://dl.bintray.com/kotlinx/kotlinx</url>
</repository>
For server-side development you can add the following dependency:
<dependency>
<groupId>org.jetbrains.kotlinx</groupId>
<artifactId>kotlinx.html.jvm</artifactId>
<version>${kotlinx.html.version}</version>
</dependency>
For client-side (JavaScript) you need this one:
<dependency>
<groupId>org.jetbrains.kotlinx</groupId>
<artifactId>kotlinx.html.js</artifactId>
<version>${kotlinx.html.version}</version>
</dependency>
If you are building web application with war plugin you can use overlays to pack JavaScripts from webjar like this:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-war-plugin</artifactId>
<version>2.6</version>
<configuration>
<dependentWarExcludes>META-INF/*,META-INF/**/*,*meta.js,**/*class</dependentWarExcludes>
<webXml>src/main/resources/web.xml</webXml>
<webResources>
<resource>
<directory>src/main/webapp</directory>
</resource>
</webResources>
<overlays>
<overlay>
<groupId>org.jetbrains.kotlin</groupId>
<artifactId>kotlin-js-library</artifactId>
<type>jar</type>
<includes>
<include>kotlin.js</include>
</includes>
<targetPath>js/</targetPath>
</overlay>
<overlay>
<groupId>org.jetbrains.kotlinx</groupId>
<artifactId>kotlinx.html.assembly</artifactId>
<classifier>webjar</classifier>
<type>jar</type>
<targetPath>js/</targetPath>
</overlay>
</overlays>
</configuration>
</plugin>
Gradle
You have to add repository and dependencies
repositories {
maven {
url "http://dl.bintray.com/kotlinx/kotlinx"
}
}
dependencies {
// include for server side
compile "org.jetbrains.kotlinx:kotlinx.html.jvm:${kotlinx.html.version}"
// include for client-side
compileClient "org.jetbrains.kotlinx:kotlinx.html.js:${kotlinx.html.version}"
}
DOM
You can build DOM tree at JVM and JS naturally
See example at JavaScript
window.setInterval({
val myDiv = document.create.div("panel") {
p {
+"Here is "
a("http://kotlinlang.org") { +"official Kotlin site" }
}
}
document.getElementById("container")!!.appendChild(myDiv)
document.getElementById("container")!!.append {
div {
+"added it"
}
}
}, 1000L)
Stream
You can build HTML directly to Writer (JVM only) or Appendable (both JVM and JS)
System.out.appendHTML().html {
body {
div {
a("http://kotlinlang.org") {
target = ATarget.blank
+"Main site"
}
}
}
}
Same for StringBuilder
StringBuilder {
appendln("<!DOCTYPE html>")
appendHTML().html {
body {
a("http://kotlinlang.org") { +"link" }
}
}
}
Interceptors
You can define interceptors chain that could transform HTML during building or make some observations. There is default "filter interceptor so you can filter out some elements Here is example that filters HTML that way so all div will be omited but content will remain
println(document {
appendChild(
createTree().filter { if (it.name == "div") SKIP else PASS }.html {
body {
div {
a { +"link1" }
}
a { +"link2" }
}
}
)
}.serialize())
The code above will produce the following output
<!DOCTYPE html>
<html>
<body>
<a>link1</a><a>link2</a>
</body>
</html>
The other interceptor doesn't mutate HTML but measures generation time
System.out.appendHTML().measureTime().html {
head {
title("Welcome page")
}
body {
div {
+"<<<special chars & entities goes here>>>"
}
div {
CDATA("Here is my content")
}
}
}.let {
it.first.println()
it.first.println("Generated in ${it.second} ms")
}
Building and development
Once you open project in IDE you have to select Maven profile (in Maven tab): it should be kotlin-js or kotlin-jvm, you shouldn't enable both otherwise IDEA inspections will not work.
You can build project by Maven only, you can't use IDEA's compile facilities. If you run Maven via IDEA runner please ensure you have -Pkotlin-js,kotlin-jvm in the command line
You have to install shared module before build other dependant submodules. Don't forget to reinstall shared once you have changed something in shared
You can build all by maven by command line
mvn clean package