Karibu-DSL Example App / Archetype

Template for a simple Kotlin-DSL application that only requires a Servlet 3.0 container to run. Just clone this repo and start experimenting!

Uses Karibu-DSL Kotlin bindings for the Vaadin framework. For more information on Vaadin please see the Vaadin 8 Documentation. Also uses the Vaadin Gradle plugin.

Deprecated

Vaadin 8 is no longer maintained and has reached the end-of-life. This example will not be maintained anymore. Please visit karibu-helloworld-application for the up-to-date example.

Getting Started

To quickly start the app, make sure that you have Java 8 (or higher) JDK installed. Then, just type this into your terminal:

git clone https://github.com/mvysny/karibu-helloworld-application
cd karibu-helloworld-application
./gradlew build appRun

The app will be running on http://localhost:8080/

Since the build system is a Gradle file written in Kotlin, we suggest you use Intellij IDEA to edit the project files. The Community edition is enough to run the server via Gretty's ./gradlew appRun. The Ultimate edition will allow you to run the project in Tomcat - this is the recommended option for a real development.

Workflow

To compile the entire project, run ./gradlew.

To run the application, run ./gradlew appRun and open http://localhost:8080/ .

To produce a deployable production mode WAR:

change productionMode to true in the servlet class configuration (located in the MyUI.kt file)
run ./gradlew
You will find the WAR file in build/libs/karibu-helloworld-application.war

This will allow you to quickly start the example app and allow you to do some basic modifications.

Client-Side compilation

The project is using a pre-compiled widgetset by default, present in the vaadin-client-compiled.jar file.

When you add a dependency that needs client-side compilation, the Vaadin Gradle plugin will automatically generate it for you (the AppWidgetset.gwt.xml file; Vaadin UI will automatically use the @Widgetset("AppWidgetset") if such file exists). Your own client-side customisations can be added into the folder src/main/java/client.

Enabling Widgetset compilation

In order to trigger the client-side compilation, do this:

Create an empty folder src/main/java/client.
Remove the compile("com.vaadin:vaadin-client-compiled:${vaadin.version}") dependency from build.gradle.kts
Run ./gradlew. Vaadin Gradle plugin will now detect that there is the client folder and will reconfigure the project to use vaadin-client-compiler to GWT-compile the widgetset. It will also generate src/main/resources/AppWidgetset.gwt.xml which is a configuration file for the GWT compiler.
Running ./gradlew again will now compile the widgetset to src/main/webapp/VAADIN/widgetsets/AppWidgetset and will package it into the WAR archive. The AppWidgetset is somewhat special: if src/main/resources/AppWidgetset.gwt.xml is present, Vaadin will auto-activate this widgetset as if the UI was annotated by @Widgetset("AppWidgetset").
You can now place Java-based client-code to src/main/java/client and shared code to src/main/java/shared. Remember - you have to use Java since GWT can't compile Kotlin.

Debugging client-side

Debugging client side code with Vaadin Gradle Plugin's superdevmode:

run "./gradlew vaadinSuperDevMode" on a separate console while the application is running
browse to http://localhost:8080/?superdevmode to activate the superdevmode
Read more on the superdevmode here: Debugging Your Widgetset Components With SuperDevMode For Dummies

Developing a theme using the runtime compiler

When developing the theme, Vaadin can be configured to compile the SASS based theme at runtime in the server. This way you can just modify the scss files in your IDE and reload the browser to see changes.

To use the runtime compilation, run ./gradlew clean appRun. Gretty will automatically pick up changes in theme files and Vaadin will automatically compile the theme on browser refresh. You will just have to give Gretty some time (one second) to register the change.

When using the runtime compiler, running the application in the "run" mode (rather than in "debug" mode) can speed up consecutive theme compilations significantly.

It is highly recommended to disable runtime compilation for production WAR files.

Development with Intellij IDEA Ultimate

The easiest way (and the recommended way) to develop Karibu-DSL-based web applications is to use Intellij IDEA Ultimate. It includes support for launching your project in any servlet container (Tomcat is recommended) and allows you to debug the code, modify the code and hot-redeploy the code into the running Tomcat instance, without having to restart Tomcat.

First, download Tomcat and register it into your Intellij IDEA properly: https://www.jetbrains.com/help/idea/2017.1/defining-application-servers-in-intellij-idea.html
Then just open this project in Intellij, simply by selecting File / Open... and click on the build.gradle file. When asked, select "Open as Project".
You can then create a launch configuration which will launch this example app in Tomcat with Intellij: just scroll to the end of this tutorial: https://kotlinlang.org/docs/tutorials/httpservlets.html
Start your newly created launch configuration in Debug mode. This way, you can modify the code and press Ctrl+F9 to hot-redeploy the code. This only redeploys java code though, to redeploy resources just press Ctrl+F10 and select "Update classes and resources"

Or watch the Debugging Vaadin Apps With Intellij video.

Dissection of project files

Let's look at all files that this project is composed of, and what are the points where you'll add functionality:

Files	Meaning
build.gradle.kts	Gradle build tool configuration files. Gradle is used to compile your app, download all dependency jars and build a war file
gradlew, gradlew.bat, gradle/	Gradle runtime files, so that you can build your app from command-line simply by running `./gradlew`, without having to download and install Gradle distribution yourself.
.github	Configuration file for the Github Actions. Github will watch any changes to this repo and will automatically build your app and runs all the tests after every commit.
.gitignore	Tells Git to ignore files that can be produced from your app's sources - be it files produced by Gradle, Intellij project files etc.
src/main/resources/	A bunch of static files not compiled by Kotlin in any way; see below for explanation.
simplelogger.properties	We're using Slf4j for logging and this is the configuration file for Slf4j Simple Logger.
webapp/	static files provided as-is to the browser. See below for explanation
mytheme/	Vaadin Theme which is generally a bunch of SCSS files compiled to one large CSS. Read more at Creating and Using Themes
src/main/kotlin/	The main Kotlin sources of your web app. You'll be mostly editing files located in this folder.
MyUI.kt	When Servlet Container (such as Tomcat) starts your app, it will show the components attached to the main `UI` class, or in this case, the `MyUI` class. The `MyUIServlet` defines which UI to use and where to map the application to.
MyUITest.kt	Automatically run by Gradle to test your UI; see Karibu Testing for more information.

More Resources

The DSL technique is used to allow you to nest your components in a structured code. This is provided by the Karibu-DSL library; please visit the Karibu-DSL home page for more information.
The browserless testing is demonstrated in the MyUITest.kt file. Please read Browserless Web Testing for more information.
For more complex example which includes multiple pages, please see the Karibu-DSL example-v8 app.
For information on how to connect the UI to the database backend please visit Vaadin-on-Kotlin You can find a complete CRUD example at Vaadin-on-Kotlin vok-example-crud-sql2o.

mvysny / karibu8-helloworld-application