Welcome to Vaadin-On-Kotlin
Vaadin-on-Kotlin is a web-application framework that includes everything needed to create database-backed web applications. Please see the official documentation at www.vaadinonkotlin.eu.
Vaadin-on-Kotlin does not enforce you to use Model-View-Controller (MVC), Dependency Injection (DI) nor Service-Oriented Architecture (SOA). It by default does not use Spring nor JavaEE. Instead, Vaadin-on-Kotlin focuses on simplicity.
The View layer leverages component-oriented programming as offered by the Vaadin framework. Vaadin offers powerful components which are built on AJAX; programming in Vaadin resembles programming in a traditional client-side framework such as JavaFX or Swing.
The database access layer is covered by the vok-orm library. vok-orm allows you to present the data from database rows as objects and embellish these data objects with business logic methods. Using vok-orm is the recommended approach to access SQL databases. Of course, you may decide not to use vok-orm and integrate with NoSQL instead, or use JPA and/or Hibernate.
Everything is combined with the conciseness of the Kotlin programming language, which makes Vaadin-on-Kotlin a perfect starting point for beginner programmers. And Kotlin is statically-typed, so you can always Ctrl+Click on a code and learn how it works under the hood!
For a Getting Started guide please see the official documentation at www.vaadinonkotlin.eu/.
Getting Started
-
Please install Java 8 JDK and git client if you haven't yet.
-
Then, at the command prompt, just type in:
git clone https://github.com/mvysny/vok-helloworld-app cd vok-helloworld-app ./gradlew clean build web:appRun -
Using a browser, go to http://localhost:8080 and you'll see: "Yay! You're on Vaadin-on-Kotlin!"
-
Follow the guidelines to start developing your application. You may find the following resources handy:
-
For easy development, we encourage you to edit the project sources in Intellij IDEA; the Community Edition is enough.
Example project
A more polished example application which you can inspire from. Just type this into your terminal:
git clone https://github.com/mvysny/vaadin-on-kotlin
cd vaadin-on-kotlin
./gradlew vok-example-crud-vokdb:appRun
The web app will be running at http://localhost:8080.
You can find the VoK-CRUD Live Demo running on Heroku.
For more information check out the vok-example-crud-vokdb module.
Vaadin 14 Flow Example project
Head to Beverage Buddy VoK for the standalone example project.
Run the example application from Intellij IDEA Community
- In Intellij IDEA, open the project simply by opening the
build.gradlefile, and then selecting "Open as Project". - To run the application from IDEA, just open Gradle tab, select
vok-example-crud-vokdb / Tasks / gretty / appRun, right-click and select Debug. The web app will be running at http://localhost:8080.
If you have the Intellij IDEA Ultimate version, we recommend you to use Tomcat for development, since it offers better code hot-redeployment:
- Open the project in IDEA
- Launch the
vok-example-crud-vokdbWAR in Tomcat as described here: https://kotlinlang.org/docs/tutorials/httpservlets.html
Contributing
We encourage you to contribute to Vaadin-on-Kotlin! Join us and discuss at Vaadin Forums: Miscellaneous.
Trying to report a possible security vulnerability in Vaadin-on-Kotlin? Please use Vaadin Bug Tracker.
For general Vaadin-on-Kotlin bugs, please use the Vaadin-on-Kotlin Github Issue Tracker.
Modules
Vaadin-on-Kotlin consists of several modules which provides you with handy functionality. To include the modules into your project, you simply add appropriate Gradle jar dependencies to your build.gradle.
Every module contains a description of what exactly the module does, when you should use it and when it might be better to use something else.
The list of modules:
- vok-framework - the very core of Vaadin-on-Kotlin which contains machinery for developing VoK plugins, and also the means to bootstrap/teardown the VoK runtime. Always included in your project when you build your app with VoK.
- vok-util-vaadin - when you want to have additional support for Vaadin 14. You typically include this module when you build your Vaadin10-based app with VoK.
- vok-framework-vokdb - when you want to have additional support for Vaadin 14 and the support for the database using the recommended approach. Includes vok-util-vaadin and vok-db.
- vok-rest - when you want to expose data from your VoK app to other REST-consuming clients.
- vok-rest-client - when you want to consume data in your VoK app from other REST servers.
- vok-db - Provides access to the database; uses VoK-ORM
- vok-security - provides basic security support. The documentation there explains the basics and provides links to sample projects.
Code Examples
Easy database transactions:
vok-orm:
button("Save", { db { person.save() } })
See vok-orm for an explanation on how this works.
Prepare your database
Simply use Flyway: write Flyway scripts, add a Gradle dependency:
compile 'org.flywaydb:flyway-core:7.1.1'
and introduce a context listener, to auto-update your database to the newest version before your app starts:
@WebListener
class Bootstrap: ServletContextListener {
override fun contextInitialized(sce: ServletContextEvent?) {
VaadinOnKotlin.init()
val flyway = Flyway()
flyway.dataSource = VaadinOnKotlin.getDataSource()
flyway.migrate()
}
}
Please scroll below for more details.
Defining UI DSL-style
verticalLayout {
formLayout {
isSpacing = true
textField("Name:") {
focus()
}
textField("Age:")
}
horizontalLayout {
w = 100.perc
isSpacing = true
button("Save") {
onLeftClick { okPressed() }
setPrimary()
}
}
}
Simple popups
popupView("Details") {
verticalLayout {
formLayout { ... }
button("Close", { isPopupVisible = false })
}
}
vok-orm-based grid is a breeze
Support for sorting and filtering out-of-the-box:
grid<User>(dataProvider = Person.dataProvider) {
isExpand = true
val filterBar = appendHeaderRow().asFilterBar(this)
columnFor(User::id) {
filterBar.forField(NumberRangePopup(), this).inRange()
}
columnFor(User::username) {
filterBar.forField(TextField(), this).ilike()
}
columnFor(User::roles) {
filterBar.forField(TextField(), this).ilike()
}
columnFor(User::hashedPassword)
addButtonColumn(VaadinIcon.EDIT, "edit", { createOrEditUser(it) }) {}
addButtonColumn(VaadinIcon.TRASH, "delete", { it.delete(); refresh() }) {}
}
Advanced syntax
Keyboard shortcuts via operator overloading
import com.github.mvysny.karibudsl.v8.ModifierKey.Alt
import com.github.mvysny.karibudsl.v8.ModifierKey.Ctrl
import com.vaadin.event.ShortcutAction.KeyCode.C
button("Create New Person (Ctrl+Alt+C)") {
onLeftClick { ... }
clickShortcut = Ctrl + Alt + C
}
Width/height
button {
icon = ...
w = 48.px
h = 50.perc
}
if (button.w.isFillParent) { ... }
Further Links
- Visit Vaadin Forums to discuss any issues or questions regarding Vaadin-on-Kotlin
- Please file bug reports at the VoK Bug Tracker
- Chat freely at VoK Gitter
- For troubleshooting, please check the Vaadin Troubleshooting article.
License
Licensed under the MIT License.
Copyright (c) 2017-2018 Martin Vysny
All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
1.9k Jan 6, 2023
22 Oct 3, 2022
85 Nov 17, 2022
9 Dec 14, 2022
2.7k Jan 2, 2023
2 Apr 9, 2022
899 Jan 2, 2023
1.9k Dec 29, 2022
40 Dec 11, 2022
1 Dec 5, 2021
13 Sep 30, 2022
643 Nov 28, 2022
439 Nov 29, 2022
23 Apr 7, 2022
0 Oct 26, 2021
0 Jan 3, 2022
3 Jan 8, 2022
36 Oct 3, 2022
615 Dec 27, 2022
619 Dec 27, 2022