Vaadin-on-Kotlin

https://www.vaadinonkotlin.eu
Admin
Vaadin-on-Kotlin (or VoK for short) is a web-application framework that includes everything...
Tokens:48,888
Snippets:531
Trust Score:7.3
Update:3 months ago
Show doc for...
Tokens:
Raw
### Initial Welcome View

Source: https://www.vaadinonkotlin.eu/tutorial

The starting view of the application before adding interactive elements. It sets up the basic layout and a static welcome heading.

```kotlin
package com.example.vok

import com.github.mvysny.karibudsl.v10.*
import com.vaadin.flow.router.Route

@Route("")
class WelcomeView : KComposite() {
    private val root = ui {
        verticalLayout {
            setSizeFull(); content { align(center, middle) }; isMargin = false; isSpacing = true

            h1("Welcome to BoltShop")
        }
    }
}

```

--------------------------------

### Basic Form Layout with Vaadin Components (Java Example)

Source: https://www.vaadinonkotlin.eu/creating_ui

This example demonstrates creating a `FormLayout` and adding standard Vaadin form components like `TextField`, `Checkbox`, and `DatePicker` in plain Java. This serves as a reference for the Kotlin DSL equivalent.

```java
FormLayout layout = new FormLayout();
TextField nameField = new TextField("Name:");
nameField.setValue("Donald Knuth");
layout.add(nameField);
layout.add(new Checkbox("Internal employee"));
layout.add(new DatePicker("Date of birth:"));

```

--------------------------------

### GET /api/products Endpoint

Source: https://www.vaadinonkotlin.eu/tutorial

This snippet defines the GET endpoint for retrieving all products. It uses ktorm-vaadin's findAll and maps entities to DTOs.

```kotlin
get("/api/products") { ctx ->
    ctx.json(Products.findAll().map { it.toDto() })
}
```

--------------------------------

### ButtonBar extending KComposite

Source: https://www.vaadinonkotlin.eu/creating_ui

This example demonstrates the KComposite pattern where the UI structure is explicitly defined within the `ui {}` block. The root layout is clearly visible, making the component's hierarchy easy to understand at a glance.

```kotlin
class ButtonBar : KComposite() {
    val root = ui {
        horizontalLayout {
            button("ok")
        }
    }
}
```

--------------------------------

### Implement Vaadin Service Init Listener for Access Control

Source: https://www.vaadinonkotlin.eu/security

Install a `SimpleNavigationAccessControl` as a Vaadin `BeforeEnterListener` by creating a `VaadinServiceInitListener`. This listener intercepts navigation events and enforces route annotations.

```kotlin
class AppServiceInitListener : VaadinServiceInitListener {
    private val accessControl = SimpleNavigationAccessControl.usingService { Session.loginService }
    init {
        accessControl.setLoginView(LoginRoute::class.java)
    }

    override fun serviceInit(e: ServiceInitEvent) {
        e.source.addUIInitListener { uiInitEvent ->
            uiInitEvent.ui.addBeforeEnterListener(accessControl)
        }
    }
}

```

--------------------------------

### Embedded Jetty Startup Message

Source: https://www.vaadinonkotlin.eu/tutorial

This message indicates that the embedded Jetty server has started successfully and is ready to serve the application. It shows the URL where the application is accessible.

```text
=================================================
Embedded Jetty started successfully on http://localhost:8080
=================================================


```

--------------------------------

### GET /api/products/{sku} Endpoint

Source: https://www.vaadinonkotlin.eu/tutorial

This snippet defines the GET endpoint for retrieving a single product by SKU. It uses path parameters and ktorm's find operation within a db block.

```kotlin
get("/api/products/{sku}") { ctx ->
    val sku = ctx.pathParam("sku")
    val product = db { database.sequenceOf(Products).find { it.sku eq sku } } ?: throw NotFoundResponse("No product with SKU '$sku'")
    ctx.json(product.toDto())
}
```

--------------------------------

### Minimal Vaadin Grid with ktorm-vaadin DataProvider

Source: https://www.vaadinonkotlin.eu/databases

A basic example of a Vaadin Grid displaying Person entities. It utilizes ktorm-vaadin's `dataProvider` for lazy loading and SQL sorting. Includes custom column renderers and actions.

```kotlin
import com.vaadin.flow.component.button.NativeButton
import com.vaadin.flow.component.grid.Grid
import com.vaadin.flow.component.orderedlayout.VerticalLayout
import com.vaadin.flow.router.Route
import org.ktorm.entity.delete
import org.ktorm.entity.forEach
import org.ktorm.entity.sequence

@Route("")
class PersonListView : VerticalLayout() {
    init {
        setSizeFull()
        grid<Person>(Persons.dataProvider) {
            setSizeFull()
            columnFor(Person::id)
            columnFor(Person::name)
            columnFor(Person::age)
            columnFor(Person::dateOfBirth, converter = { it?.toString() })
            columnFor(Person::maritalStatus)
            columnFor(Person::alive)
            columnFor(Person::created, converter = { it?.toString() })
            addColumn(NativeButtonRenderer<Person>("Delete") { person ->
                person.delete()
                this@grid.refresh()
            })
        }
    }
}
```

--------------------------------

### Japanese Localization Bundle

Source: https://www.vaadinonkotlin.eu/i18n

Create language-specific resource bundles, like `VokMessages_ja.properties`, to provide translations for particular locales. This example shows Japanese translations.

```properties
newuser.name=名
newuser.surname=姓
```

--------------------------------

### Get or Create JVM Singleton Service

Source: https://www.vaadinonkotlin.eu/services

Use this code to access or create a single instance of a service throughout the application's runtime. This approach allows for providing different implementations, especially for testing.

```kotlin
val Services.yourService: YourService
    get() = singletons.getOrCreate(YourService::class) { YourService() }
```

--------------------------------

### Get Product by SKU

Source: https://www.vaadinonkotlin.eu/tutorial

Retrieves a single product by its Stock Keeping Unit (SKU).

```APIDOC
## GET /api/products/{sku}

### Description
Retrieves one product by its natural key (SKU).

### Method
GET

### Endpoint
/api/products/{sku}

### Parameters
#### Path Parameters
- **sku** (string) - Required - The SKU of the product to retrieve.

### Response
#### Success Response (200)
- product (object) - The product object matching the provided SKU.
```

--------------------------------

### Define an Empty Services Object

Source: https://www.vaadinonkotlin.eu/services

This is a simple singleton object that acts as a container for service extensions. It requires no setup beyond its declaration.

```kotlin
object Services
```

--------------------------------

### Referencing TextFields in a View

Source: https://www.vaadinonkotlin.eu/creating_ui

Capture component references to access their values, for example, within a button click handler. This example demonstrates creating a simple view with text fields for name and age.

```kotlin
package com.example.vok

import com.github.mvysny.karibudsl.v10.*
import com.vaadin.flow.component.notification.Notification
import com.vaadin.flow.component.orderedlayout.VerticalLayout
import com.vaadin.flow.component.textfield.TextField
import com.vaadin.flow.router.Route

@Route("")
class WelcomeView : VerticalLayout() {
    private lateinit var nameField: TextField
    private lateinit var ageField: TextField
    init {
        formLayout {
            nameField = textField("Name:")
            ageField = textField("Age:")
        }
        button("Click me") {
            onClick {
                Notification.show("Hello, ${nameField.value} of age ${ageField.value}")
            }
        }
    }
}

```

--------------------------------

### Get All Products

Source: https://www.vaadinonkotlin.eu/tutorial

Retrieves a list of all products. It fetches all records from the Product table and returns them as a JSON array of ProductDto objects.

```APIDOC
## GET /api/products

### Description
Retrieves a list of all products. It fetches all records from the Product table and returns them as a JSON array of ProductDto objects.

### Method
GET

### Endpoint
/api/products

### Response
#### Success Response (200)
- **Array** - A JSON array of product objects.

#### Response Example
```json
[
  {
    "sku": "string",
    "name": "string",
    "price": 0.0
  }
]
```
```

--------------------------------

### Using Session Login Service in UI Event Listener

Source: https://www.vaadinonkotlin.eu/services

An example of how to use the `Session.loginService` extension property within a Vaadin `LoginForm`'s login listener to authenticate a user and log them in.

```kotlin
loginForm.addLoginListener { e ->
    val user = User.findByUsername(e.username)
    if (user == null || !user.passwordMatches(e.password)) {
        loginForm.setErrorMessage("Login failed", "Invalid username or password")
    } else {
        Session.loginService.login(user)
    }
}

```

--------------------------------

### ButtonBar extending HorizontalLayout

Source: https://www.vaadinonkotlin.eu/creating_ui

This example shows a component directly extending a layout class. The UI structure is less explicit, requiring inspection of the constructor or init block to understand the component's layout hierarchy.

```kotlin
class ButtonBar : HorizontalLayout() {
    init {
        button("ok")
    }
}
```

--------------------------------

### Get Product by SKU

Source: https://www.vaadinonkotlin.eu/tutorial

Retrieves a single product by its Stock Keeping Unit (SKU). It queries the database for a product matching the provided SKU and returns its DTO. If no product is found, it returns a 404 error.

```APIDOC
## GET /api/products/{sku}

### Description
Retrieves a single product by its Stock Keeping Unit (SKU). It queries the database for a product matching the provided SKU and returns its DTO. If no product is found, it returns a 404 error.

### Method
GET

### Endpoint
/api/products/{sku}

### Parameters
#### Path Parameters
- **sku** (string) - Required - The Stock Keeping Unit of the product to retrieve.

### Response
#### Success Response (200)
- **object** - A JSON object representing the product.

#### Response Example
```json
{
  "sku": "string",
  "name": "string",
  "price": 0.0
}
```

#### Error Response (404)
- **message** (string) - Description of the error (e.g., "No product with SKU '...'")
```

--------------------------------

### Creating a Reusable Form Component

Source: https://www.vaadinonkotlin.eu/creating_ui

Define a class extending a layout to create a reusable component. This example shows a `NameAgeForm` class with text fields and a greeting property.

```kotlin
class NameAgeForm : FormLayout() {
    private val nameField = textField("Name:")
    private val ageField = textField("Age:")
    val greeting: String get() = "Hello, ${nameField.value} of age ${ageField.value}"
}

```

--------------------------------

### Annotating Product Entity Properties

Source: https://www.vaadinonkotlin.eu/tutorial

This snippet shows the Product interface with various Jakarta Bean Validation annotations applied to its properties. Ensure you use the `@get:` site target for these annotations to be recognized by the validation framework.

```kotlin
package com.example.vok

import com.github.mvysny.ktormvaadin.ActiveEntity
import jakarta.validation.constraints.NotNull
import jakarta.validation.constraints.Pattern
import jakarta.validation.constraints.Positive
import jakarta.validation.constraints.PositiveOrZero
import jakarta.validation.constraints.Size
import org.ktorm.entity.Entity
import org.ktorm.schema.Column
import org.ktorm.schema.Table
import org.ktorm.schema.decimal
import org.ktorm.schema.enum
import org.ktorm.schema.int
import org.ktorm.schema.long
import org.ktorm.schema.varchar
import java.math.BigDecimal

enum class Category { Tools, Fasteners, Plumbing, Electrical, Paint, Garden }

enum class UnitOfMeasure { Each, Box, Meter, Kilogram }

interface Product : ActiveEntity<Product> {
    var id: Long?

    @get:NotNull
    @get:Size(min = 1, max = 40)
    @get:Pattern(
        regexp = "[A-Z0-9-]+",
        message = "SKU may only contain uppercase letters, digits and hyphens"
    )
    var sku: String?

    @get:NotNull
    @get:Size(min = 1, max = 200)
    var name: String?

    @get:NotNull
    var category: Category?

    @get:NotNull
    @get:Positive(message = "Price must be greater than zero")
    var price: BigDecimal?

    @get:NotNull
    @get:PositiveOrZero(message = "Stock cannot be negative")
    var stock: Int?

    @get:NotNull
    var unit: UnitOfMeasure?

    override val table: Table<Product> get() = Products

    companion object : Entity.Factory<Product>()
}

// Products table object unchanged from Chapter 3

```

--------------------------------

### Application Startup Log

Source: https://www.vaadinonkotlin.eu/tutorial

Observe the application startup log to confirm initialization, database migrations, and server status.

```text
Hikari ... Start completed.
Vaadin On Kotlin initialized
Running DB migrations
Flyway ... Migrating schema "PUBLIC" to version "1 - create product"
Flyway ... Successfully applied 1 migration to schema "PUBLIC", now at version v1
Initialization complete
Embedded Jetty started successfully on http://localhost:8080

```

--------------------------------

### Create a Welcome View with a Button

Source: https://www.vaadinonkotlin.eu/creating_ui

This snippet demonstrates creating a basic view with a single button that shows a notification when clicked. It uses the `VerticalLayout` as the root and a DSL builder for the button.

```kotlin
package com.example.vok

import com.github.mvysny.karibudsl.v10.*
import com.vaadin.flow.component.notification.Notification
import com.vaadin.flow.component.orderedlayout.VerticalLayout
import com.vaadin.flow.router.Route

@Route("")
class WelcomeView : VerticalLayout() {
    init {
        button("Click me") {
            onClick {
                Notification.show("Clicked")
            }
        }
    }
}

```

--------------------------------

### Run Gradle Application

Source: https://www.vaadinonkotlin.eu/tutorial

Execute the Gradle wrapper to run the application. Ensure the server is stopped before restarting.

```bash
$ ./gradlew run

```

--------------------------------

### Clone Vaadin on Kotlin Starter Project

Source: https://www.vaadinonkotlin.eu/tutorial

Clone the official starter repository to begin your Vaadin on Kotlin project. This command fetches the project files and sets up the basic structure.

```bash
$ git clone https://github.com/mvysny/vok-helloworld-app
$ cd vok-helloworld-app

```

--------------------------------

### Retrieve a product by SKU via API

Source: https://www.vaadinonkotlin.eu/tutorial

Fetch a specific product using its SKU. A `404 Not Found` response is returned if the SKU does not exist.

```bash
$ curl -s http://localhost:8080/api/products/HX-M6-40
{"id":1,"sku":"HX-M6-40","name":"Hex bolt M6×40mm, zinc-plated","category":"Fasteners","price":0.35,"stock":120,"unit":"Each"}

$ curl -i http://localhost:8080/api/products/NOPE
HTTP/1.1 404 Not Found
Content-Type: application/json
...

No product with SKU 'NOPE'

```

--------------------------------

### List all products via API

Source: https://www.vaadinonkotlin.eu/tutorial

Use `curl` to fetch a list of all products from the API. The output is pretty-printed using `python3 -m json.tool` for readability.

```bash
$ curl -s http://localhost:8080/api/products | python3 -m json.tool
[
    {
        "id": 1,
        "sku": "HX-M6-40",
        "name": "Hex bolt M6×40mm, zinc-plated",
        "category": "Fasteners",
        "price": 0.35,
        "stock": 120,
        "unit": "Each"
    },
    {
        "id": 2,
        "sku": "HX-M8-50",
        ...
    },
    ...
]

```

--------------------------------

### Creating RouterLinks with Different Overloads

Source: https://www.vaadinonkotlin.eu/navigating

Demonstrates the various ways to create `RouterLink` instances using the `routerLink` DSL extension. Use these for declarative in-app links that avoid full page reloads.

```kotlin
import com.github.mvysny.karibudsl.v10.routerLink
import com.vaadin.flow.component.icon.VaadinIcon
import com.vaadin.flow.router.HighlightConditions

// no parameter
routerLink(VaadinIcon.LIST, "Reviews", ReviewsList::class) {
    addClassName("main-layout__nav-item")
    highlightCondition = HighlightConditions.sameLocation()
}

// single typed URL parameter (HasUrlParameter<T>)
routerLink(text = "Edit", viewType = PersonView::class, parameter = person.id!!)

// named RouteParameters
routerLink(text = "Open", viewType = AdminView::class, parameters = mapOf("id" to "25"))

// no target — useful when the destination is set later, e.g. in HasUrlParameter.setParameter()
routerLink(text = "Loading…") { /* set route later via setRoute(...) */ }

```

--------------------------------

### Bean Validation Annotations on Entity Getters

Source: https://www.vaadinonkotlin.eu/forms

Annotate entity getters with Jakarta Bean Validation annotations. The `@get:` site target is crucial for interfaces.

```kotlin
import com.github.mvysny.ktormvaadin.ActiveEntity
import jakarta.validation.constraints.Max
import jakarta.validation.constraints.Min
import jakarta.validation.constraints.NotNull
import jakarta.validation.constraints.Size
import org.ktorm.entity.Entity
import org.ktorm.schema.Table

interface Person : ActiveEntity<Person> {
    var id: Long?

    @get:NotNull
    @get:Size(min = 1, max = 200)
    var name: String?

    @get:NotNull
    @get:Min(15)
    @get:Max(100)
    var age: Int?

    // ...

    override val table: Table<Person> get() = Persons
    companion object : Entity.Factory<Person>()
}
```

--------------------------------

### Vaadin on Kotlin Project Structure Overview

Source: https://www.vaadinonkotlin.eu/tutorial

This file structure outlines the core components of a minimal Vaadin on Kotlin application, including startup scripts, main application file, utilities, and the initial view.

```text
src/main/kotlin/com/example/vok/
├── Bootstrap.kt    — startup: datasource, VoK init, Flyway, REST scaffold
├── Main.kt         — the main() that boots Vaadin Boot
├── Utils.kt        — small helpers
└── WelcomeView.kt  — the @Route("") landing page


```

--------------------------------

### Responsive Form Layout Steps

Source: https://www.vaadinonkotlin.eu/forms

Configures responsive behavior for a FormLayout using karibu-dsl's condensed DSL for responsive steps. Allows defining column counts and label positions based on viewport width.

```kotlin
formLayout {
    responsiveSteps {
        responsiveSteps {"0px"(1, top); "30em"(2, aside)}

        textField("Name")
        textField("Age")
    }
}

```

--------------------------------

### Create a new product via API

Source: https://www.vaadinonkotlin.eu/tutorial

Use a `POST` request with JSON data to create a new product. A `201 Created` status is returned on success.

```bash
$ curl -i -X POST http://localhost:8080/api/products \
    -H 'Content-Type: application/json' \
    -d '{
      "sku": "HX-M10-60",
      "name": "Hex bolt M10x60mm",
      "category": "Fasteners",
      "price": 1.20,
      "stock": 50,
      "unit": "Each"
    }'
HTTP/1.1 201 Created
Content-Type: application/json
...

{"id":11,"sku":"HX-M10-60","name":"Hex bolt M10x60mm","category":"Fasteners","price":1.20,"stock":50,"unit":"Each"}


```

--------------------------------

### Initialize VaadinOnKotlin and Flyway Migration

Source: https://www.vaadinonkotlin.eu/tutorial

This snippet initializes the VaadinOnKotlin framework and its data source, then configures and runs Flyway migrations. Ensure Flyway is configured with the correct data source to apply SQL migration scripts.

```kotlin
VaadinOnKotlin.dataSource = HikariDataSource(cfg)
VaadinOnKotlin.init()

val flyway = Flyway.configure()
    .dataSource(VaadinOnKotlin.dataSource)
    .load()
flyway.migrate()
```

--------------------------------

### Add New Product via Dialog

Source: https://www.vaadinonkotlin.eu/tutorial

Opens a dialog to add a new product, fills in the form fields, and creates the product. Verifies the notification and the increased row count in the grid.

```kotlin
_get<Button> { text = "+ Add product" }._click()
val dialog = _get<Dialog>()

dialog._get<TextField> { label = "SKU" }._value = "NEW-PRODUCT-1"
dialog._get<TextField> { label = "Name" }._value = "New product"
dialog._get<ComboBox<Category>> { label = "Category" }._value = Category.Tools
dialog._get<BigDecimalField> { label = "Price" }._value = "5.50".toBigDecimal()
dialog._get<IntegerField> { label = "Stock" }._value = 100
dialog._get<ComboBox<UnitOfMeasure>> { label = "Unit" }._value = UnitOfMeasure.Each
dialog._get<Button> { text = "Create" }._click()

expectNotifications("Created New product")
_get<Grid<Product>>().expectRows(11)
```

--------------------------------

### PersonForm with Binder

Source: https://www.vaadinonkotlin.eu/forms

A Vaadin FormLayout that uses Binder to bind input fields to properties of the Person entity. Includes examples of text, date, combo box, and check box bindings with converters.

```kotlin
import com.github.mvysny.karibudsl.v10.*
import com.vaadin.flow.component.formlayout.FormLayout
import com.vaadin.flow.data.binder.Binder

class PersonForm : FormLayout() {
    val binder = Binder<Person>(Person::class.java)
    init {
        textField("Name") {
            focus()
            bind(binder).trimmingConverter().bind(Person::name)
        }
        textField("Age") {
            bind(binder).toInt().bind(Person::age)
        }
        datePicker("Date of birth") {
            bind(binder).bind(Person::dateOfBirth)
        }
        comboBox<MaritalStatus>("Marital status") {
            setItems(MaritalStatus.entries)
            bind(binder).bind(Person::maritalStatus)
        }
        checkBox("Alive") {
            bind(binder).bind(Person::alive)
        }
    }
}
```

--------------------------------

### Create Product

Source: https://www.vaadinonkotlin.eu/tutorial

Creates a new product in the catalog.

```APIDOC
## POST /api/products

### Description
Creates a new product.

### Method
POST

### Endpoint
/api/products

### Request Body
- **name** (string) - Required - The name of the product.
- **sku** (string) - Required - The SKU of the product.
- **price** (number) - Required - The price of the product.
- **stock** (integer) - Required - The current stock level of the product.
- **category** (string) - Optional - The category of the product.
- **lowStockThreshold** (integer) - Optional - The threshold for low stock notification.

### Request Example
{
  "name": "Example Product",
  "sku": "EX-001",
  "price": 19.99,
  "stock": 100,
  "category": "Electronics",
  "lowStockThreshold": 10
}

### Response
#### Success Response (200)
- message (string) - Confirmation message that the product was created.
- product (object) - The newly created product object.
```

--------------------------------

### Replace Binder with BeanValidationBinder

Source: https://www.vaadinonkotlin.eu/tutorial

Replace the standard Binder with beanValidationBinder() to enable automatic JSR-303 constraint checks on bindings. This helper function returns a BeanValidationBinder, which is a subclass of Binder that simplifies validation setup.

```kotlin
val binder: Binder<Product> = Binder(Product::class.java)
```

```kotlin
val binder: Binder<Product> = beanValidationBinder()
```

--------------------------------

### Configure a Vaadin Grid with Kotlin DSL

Source: https://www.vaadinonkotlin.eu/tutorial

Use the Karibu-DSL builder to create and configure a Vaadin Grid component. This snippet demonstrates binding the Grid to a data class and setting up columns using property references.

```kotlin
grid<Product>(Product::class) {
    setItems(sampleProducts)
    columnFor(Product::sku) { setHeader("SKU") }
    columnFor(Product::name) { setHeader("Name"); flexGrow = 1 }
    columnFor(Product::price) { setHeader("Price") }
}
```

--------------------------------

### Run Vaadin on Kotlin Application with Gradle

Source: https://www.vaadinonkotlin.eu/tutorial

Execute the Gradle wrapper to build and run the Vaadin on Kotlin application. The first run will download all necessary dependencies.

```bash
./gradlew run

```

--------------------------------

### Bootstrap Database Configuration

Source: https://www.vaadinonkotlin.eu/databases

Configure HikariCP for H2 in-memory database and initialize VaadinOnKotlin. Ensure DATABASE_TO_UPPER=FALSE for case-sensitive identifiers with ktorm.

```kotlin
val config = HikariConfig().apply {
    driverClassName = Driver::class.java.name  // org.h2.Driver
    jdbcUrl = "jdbc:h2:mem:test;DB_CLOSE_DELAY=-1;DATABASE_TO_UPPER=FALSE"
    username = "sa"
    password = ""
}
VaadinOnKotlin.dataSource = HikariDataSource(config)  // also wires ActiveKtorm.database
VaadinOnKotlin.init()

Flyway.configure().dataSource(VaadinOnKotlin.dataSource).load().migrate()
```

--------------------------------

### Initial Javalin Servlet Mapping

Source: https://www.vaadinonkotlin.eu/tutorial

This snippet shows the initial placeholder mapping for the Javalin servlet in Bootstrap.kt.

```kotlin
@WebServlet(urlPatterns = ["/rest/*"], name = "JavalinRestServlet", ...) class JavalinRestServlet : HttpServlet() { ... }
```

--------------------------------

### Set Custom JVM Singleton Service Implementation

Source: https://www.vaadinonkotlin.eu/services

This snippet demonstrates how to set a specific (e.g., fake) implementation for a service before application initialization, which is crucial for testing purposes.

```kotlin
Services.singletons.set(YourService::class, YourFakeService())
```

--------------------------------

### CatalogView.kt: Full Vaadin on Kotlin UI Implementation

Source: https://www.vaadinonkotlin.eu/tutorial

This snippet shows the complete implementation of a catalog view using Vaadin on Kotlin. It includes setting up the UI layout, data providers, filtering, data binding, and event handling for saving and deleting products.

```kotlin
package com.example.vok

import com.github.mvysny.karibudsl.v10.*
import com.github.mvysny.kaributools.setPrimary
import com.github.mvysny.ktormvaadin.dataProvider
import com.vaadin.flow.component.button.Button
import com.vaadin.flow.component.notification.Notification
import com.vaadin.flow.data.binder.Binder
import com.vaadin.flow.data.value.ValueChangeMode
import com.vaadin.flow.router.Route
import org.ktorm.dsl.and
import org.ktorm.dsl.eq
import org.ktorm.dsl.or
import org.ktorm.schema.ColumnDeclaring
import org.ktorm.support.postgresql.ilike

@Route("")
class CatalogView : KComposite() {

    private val dp = Products.dataProvider
    private val binder = Binder<Product>(Product::class.java)
    private var selected: Product? = null
    private lateinit var saveButton: Button
    private lateinit var deleteButton: Button

    private val root = ui {
        verticalLayout {
            setSizeFull(); isPadding = true; isSpacing = true

            h2("BoltShop catalog")

            horizontalLayout {
                val searchField = textField {
                    placeholder = "Search by name or SKU"
                    valueChangeMode = ValueChangeMode.LAZY
                    setWidth("20em")
                }
                val categoryField = comboBox<Category> {
                    placeholder = "Category"
                    setItems(Category.entries)
                    setWidth("12em")
                    isClearButtonVisible = true
                }

                fun applyFilters() {
                    dp.setFilter(productFilter(searchField.value, categoryField.value))
                }
                searchField.addValueChangeListener { applyFilters() }
                categoryField.addValueChangeListener { applyFilters() }
            }

            horizontalLayout {
                setSizeFull(); isSpacing = true

                grid<Product>(Product::class, dp) {
                    flexGrow = 1.0
                    setSizeFull()
                    columnFor(Product::sku) { setHeader("SKU") }
                    columnFor(Product::name) { setHeader("Name"); flexGrow = 1 }
                    columnFor(Product::category) { setHeader("Category") }
                    columnFor(Product::price) { setHeader("Price") }
                    columnFor(Product::stock) { setHeader("Stock") }
                    columnFor(Product::unit) { setHeader("Unit") }

                    asSingleSelect().addValueChangeListener { e -> showSelection(e.value) }
                }

                verticalLayout {
                    setWidth("28em"); isPadding = true; isSpacing = true

                    h3("Product details")

                    textField("SKU") { bind(binder).bind(Product::sku) }
                    textField("Name") { bind(binder).bind(Product::name) }
                    comboBox<Category>("Category") {
                        setItems(Category.entries)
                        bind(binder).bind(Product::category)
                    }
                    bigDecimalField("Price") { bind(binder).bind(Product::price) }
                    integerField("Stock") { bind(binder).bind(Product::stock) }
                    comboBox<UnitOfMeasure>("Unit") {
                        setItems(UnitOfMeasure.entries)
                        bind(binder).bind(Product::unit)
                    }

                    horizontalLayout {
                        saveButton = button("Save") {
                            setPrimary()
                            onClick { onSave() }
                        }
                        deleteButton = button("Delete") {
                            onClick { onDelete() }
                        }
                    }
                }
            }
        }
    }

    init {
        showSelection(null)
    }

    private fun showSelection(product: Product?) {
        selected = product
        binder.readBean(product)
        saveButton.isEnabled = product != null
        deleteButton.isEnabled = product != null
    }

    private fun onSave() {
        val product = selected ?: return
        if (!binder.writeBeanIfValid(product)) return
        product.save()
        dp.refreshAll()
        Notification.show("Saved ${product.name}")
    }

    private fun onDelete() {
        val product = selected ?: return
        product.delete()
        dp.refreshAll()
        showSelection(null)
        Notification.show("Deleted ${product.name}")
    }
}

private fun productFilter(search: String, category: Category?): ColumnDeclaring<Boolean>? {
    val s = search.trim()
    val parts = listOfNotNull(
        if (s.isEmpty()) null else {
            val pattern = "%$s%"
            Products.name.ilike(pattern) or Products.sku.ilike(pattern)
        },
        category?.let { Products.category eq it },
    )
    return parts.reduceOrNull { a, b -> a and b }
}

```

--------------------------------

### Read Query Parameters within a View

Source: https://www.vaadinonkotlin.eu/navigating

Access query parameters within a Vaadin view using the `QueryParameters` object. The `get(name)` operator retrieves a single value, while `getValues(name)` retrieves all values for a given parameter.

```kotlin
val params: QueryParameters = event.location.queryParameters
val lang: String? = params["lang"]                    // single value or null
val tags: List<String> = params.getValues("tag")      // multi-valued
```

--------------------------------

### Update CatalogView to use Database Finder

Source: https://www.vaadinonkotlin.eu/tutorial

This snippet shows how to modify the `CatalogView.kt` file to fetch product data from the database using `Products.findAll()`. It replaces the hardcoded list with a dynamic data source for the Vaadin Grid.

```kotlin
package com.example.vok

import com.github.mvysny.karibudsl.v10.*
import com.github.mvysny.ktormvaadin.findAll
import com.vaadin.flow.router.Route

@Route("")
class CatalogView : KComposite() {
    private val root = ui {
        verticalLayout {
            setSizeFull(); isPadding = true; isSpacing = true

            h2("BoltShop catalog")
            grid<Product>(Product::class) {
                setSizeFull()
                setItems(Products.findAll())
                columnFor(Product::sku) { setHeader("SKU") }
                columnFor(Product::name) { setHeader("Name"); flexGrow = 1 }
                columnFor(Product::category) { setHeader("Category") }
                columnFor(Product::price) { setHeader("Price") }
                columnFor(Product::stock) { setHeader("Stock") }
                columnFor(Product::unit) { setHeader("Unit") }
            }
        }
    }
}

```

--------------------------------

### Saving Changes from the Form to a Product Bean

Source: https://www.vaadinonkotlin.eu/tutorial

Use writeBeanIfValid to validate and write form field values back to the bean. This method returns false if validation fails. The example assumes no validators are present, making it always succeed.

```kotlin
private fun onSave() {
    val product = selected ?: return
    if (!binder.writeBeanIfValid(product)) return
    product.save()
    dp.refreshAll()
    Notification.show("Saved ${product.name}")
}
```

--------------------------------

### Create and Initialize FormLayout using DSL

Source: https://www.vaadinonkotlin.eu/dsl_explained

Constructs a FormLayout and uses the DSL to define its content, including a text field and a checkbox. This is useful when you need to create a component without immediately adding it to the parent layout.

```kotlin
val form = FormLayout().apply {
  textField("Name:")
  checkBox("Employed")
}

```

--------------------------------

### Calling a Class-based Service Function

Source: https://www.vaadinonkotlin.eu/services

Demonstrates how to instantiate a service class and then invoke its method.

```kotlin
BookingService().book()
```

--------------------------------

### Create a View with a Form Layout and Button

Source: https://www.vaadinonkotlin.eu/creating_ui

This snippet shows how to create a view containing a `FormLayout` with two text fields, followed by a button. It demonstrates nesting components within layouts using the DSL.

```kotlin
package com.example.vok

import com.github.mvysny.karibudsl.v10.*
import com.vaadin.flow.component.notification.Notification
import com.vaadin.flow.component.orderedlayout.VerticalLayout
import com.vaadin.flow.router.Route

@Route("")
class WelcomeView : VerticalLayout() {
    init {
        formLayout {
            textField("Name:")
            textField("Age:")
        }
        button("Click me") {
            onClick {
                Notification.show("Clicked")
            }
        }
    }
}

```

--------------------------------

### Vaadin Dialog with Product Form and Binder

Source: https://www.vaadinonkotlin.eu/tutorial

Instantiates a ProductForm and a draft Product entity, then binds the form to the draft bean. The form is then added to the dialog.

```kotlin
val form = ProductForm()
val draft = Product()
form.binder.readBean(draft)
dialog.add(form)
```

--------------------------------

### Add Karibu-Testing Dependencies

Source: https://www.vaadinonkotlin.eu/tutorial

Wire JUnit Jupiter and Karibu-Testing into your build.gradle.kts file. Ensure the JUnit Platform Launcher is included for Gradle 9 compatibility.

```gradle
dependencies {
    // ... existing implementation deps unchanged ...

    // tests
    testImplementation(libs.junit)
    testImplementation(libs.kaributesting)
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}

```

--------------------------------

### Configuring a Grid with an EntityDataProvider

Source: https://www.vaadinonkotlin.eu/tutorial

This Karibu-DSL overload configures a Vaadin Grid with a provided data provider. The Grid automatically wires itself to the provider, enabling lazy loading of rows without explicit `setItems` calls.

```kotlin
grid<Product>(Product::class, dp) { ... }
```

--------------------------------

### Creating an EntityDataProvider for Products

Source: https://www.vaadinonkotlin.eu/tutorial

This extension property provides an `EntityDataProvider` for the `Product` entity, which implements Vaadin's `DataProvider` interface using ktorm. It fetches data by executing SQL queries.

```kotlin
val dp = Products.dataProvider
```

--------------------------------

### Catalog View with Product Grid

Source: https://www.vaadinonkotlin.eu/tutorial

This snippet defines the `CatalogView` which replaces the default welcome view. It uses a `KComposite` to build a UI with a `verticalLayout` containing a `h2` title and a `grid` to display `Product` data. The grid is configured with specific columns and populated with sample products. Use this to create a catalog or list view in your Vaadin application.

```kotlin
package com.example.vok

import com.github.mvysny.karibudsl.v10.*
import com.vaadin.flow.router.Route

@Route("")
class CatalogView : KComposite() {
    private val root = ui {
        verticalLayout {
            setSizeFull(); isPadding = true; isSpacing = true

            h2("BoltShop catalog")
            grid<Product>(Product::class) {
                setSizeFull()
                setItems(sampleProducts)
                columnFor(Product::sku) { setHeader("SKU") }
                columnFor(Product::name) { setHeader("Name"); flexGrow = 1 }
                columnFor(Product::category) { setHeader("Category") }
                columnFor(Product::price) { setHeader("Price") }
                columnFor(Product::stock) { setHeader("Stock") }
                columnFor(Product::unit) { setHeader("Unit") }
            }
        }
    }
}

private val sampleProducts: List<Product> = listOf(
    Product("HX-M6-40",      "Hex bolt M6×40mm, zinc-plated",    Category.Fasteners,  "0.35".toBigDecimal(), 120, UnitOfMeasure.Each),
    Product("HX-M8-50",      "Hex bolt M8×50mm, stainless",      Category.Fasteners,  "0.85".toBigDecimal(),   0, UnitOfMeasure.Each),
    Product("NT-M6-BOX100",  "Hex nut M6, zinc-plated, 100/box", Category.Fasteners,  "4.50".toBigDecimal(),  18, UnitOfMeasure.Box),
    Product("WD40-400",      "WD-40 lubricant spray 400ml",      Category.Tools,      "7.90".toBigDecimal(),  32, UnitOfMeasure.Each),
    Product("SD-FLAT-6",     "Screwdriver, flat blade 6mm",      Category.Tools,      "6.50".toBigDecimal(),  12, UnitOfMeasure.Each),
    Product("PIPE-CU-22",    "Copper pipe Ø22mm",                Category.Plumbing,  "12.40".toBigDecimal(),  45, UnitOfMeasure.Meter),
    Product("CABLE-3G15",    "Power cable 3G1.5mm²",             Category.Electrical, "1.80".toBigDecimal(), 200, UnitOfMeasure.Meter),
    Product("PAINT-WHT-1L",  "Interior paint, white matte 1L",   Category.Paint,     "14.90".toBigDecimal(),   8, UnitOfMeasure.Each),
    Product("PAINT-WHT-10L", "Interior paint, white matte 10L",  Category.Paint,     "89.00".toBigDecimal(),   3, UnitOfMeasure.Each),
    Product("SAND-CONCRETE", "Concrete sand",                    Category.Garden,     "0.45".toBigDecimal(), 800, UnitOfMeasure.Kilogram),
)

```

--------------------------------

### Application Frame Layout with RootLayout

Source: https://www.vaadinonkotlin.eu/creating_ui

Sets up an application frame with a left-aligned menu and a right-aligned content area using HorizontalLayout and VerticalLayout. The content area expands to fill remaining space.

```kotlin
import com.github.mvysny.karibudsl.v10.*
import com.vaadin.flow.component.HasElement
import com.vaadin.flow.component.button.ButtonVariant
import com.vaadin.flow.component.icon.Icon
import com.vaadin.flow.component.icon.VaadinIcon
import com.vaadin.flow.component.orderedlayout.HorizontalLayout
import com.vaadin.flow.component.html.Div
import com.vaadin.flow.router.RouterLayout

class RootLayout : HorizontalLayout(), RouterLayout {
    private val viewContainer: Div
    init {
        setSizeFull()
        verticalLayout {
            width = null; height = "100%"; isSpacing = false; isPadding = false
            button("About", icon = Icon(VaadinIcon.QUESTION)) {
                addThemeVariants(ButtonVariant.LUMO_TERTIARY)
            }
            button("Users", icon = Icon(VaadinIcon.USERS)) {
                addThemeVariants(ButtonVariant.LUMO_TERTIARY)
            }
            button("Log Out", icon = Icon(VaadinIcon.SIGN_OUT)) {
                addThemeVariants(ButtonVariant.LUMO_TERTIARY)
            }
        }
        viewContainer = div {
            isExpand = true
        }
    }

    override fun showRouterLayoutContent(content: HasElement) {
        viewContainer.removeAll()
        viewContainer.element.appendChild(content.element)
    }
}

@Route("", layout = RootLayout::class)
class WelcomeView : VerticalLayout() {
    init {
        div {
            text("Hello world!")
        }
    }
}

```

--------------------------------

### Exporting All Data with Ktorm Sequence DSL

Source: https://www.vaadinonkotlin.eu/databases

For straightforward 'export everything' scenarios without filters, use Ktorm's sequence DSL to write your SELECT statement or call a find all method.

```kotlin
Persons.findAll()
```

--------------------------------

### Calling a Singleton Service Function

Source: https://www.vaadinonkotlin.eu/services

Demonstrates how to invoke a method on a singleton service object.

```kotlin
BookingService.book()
```

--------------------------------

### Test product creation validation via API

Source: https://www.vaadinonkotlin.eu/tutorial

Attempt to create a product with invalid data to test API validation constraints. A `400 Bad Request` response details the validation errors.

```bash
$ curl -i -X POST http://localhost:8080/api/products \
    -H 'Content-Type: application/json' \
    -d '{
      "sku": "bad-sku",
      "name": "",
      "category": "Tools",
      "price": 0,
      "stock": -5,
      "unit": "Each"
    }'
HTTP/1.1 400 Bad Request
Content-Type: application/json
...

{"errors":["Price must be greater than zero","must not be empty","Stock cannot be negative","SKU may only contain uppercase letters, digits and hyphens"]}


```

--------------------------------

### Create Product Table and Seed Data

Source: https://www.vaadinonkotlin.eu/tutorial

This SQL script defines the 'Product' table schema and inserts initial seed data. It is intended for use with Flyway for database migrations.

```sql
CREATE TABLE Product(
  id BIGINT AUTO_INCREMENT PRIMARY KEY,
  sku VARCHAR(40) NOT NULL UNIQUE,
  name VARCHAR(200) NOT NULL,
  category VARCHAR(20) NOT NULL,
  price DECIMAL(10, 2) NOT NULL,
  stock INTEGER NOT NULL,
  unit VARCHAR(20) NOT NULL
);

INSERT INTO Product (sku, name, category, price, stock, unit) VALUES
  ('HX-M6-40',      'Hex bolt M6×40mm, zinc-plated',    'Fasteners',   0.35, 120, 'Each'),
  ('HX-M8-50',      'Hex bolt M8×50mm, stainless',      'Fasteners',   0.85,   0, 'Each'),
  ('NT-M6-BOX100',  'Hex nut M6, zinc-plated, 100/box', 'Fasteners',   4.50,  18, 'Box'),
  ('WD40-400',      'WD-40 lubricant spray 400ml',      'Tools',       7.90,  32, 'Each'),
  ('SD-FLAT-6',     'Screwdriver, flat blade 6mm',      'Tools',       6.50,  12, 'Each'),
  ('PIPE-CU-22',    'Copper pipe Ø22mm',                'Plumbing',   12.40,  45, 'Meter'),
  ('CABLE-3G15',    'Power cable 3G1.5mm²',             'Electrical',  1.80, 200, 'Meter'),
  ('PAINT-WHT-1L',  'Interior paint, white matte 1L',   'Paint',      14.90,   8, 'Each'),
  ('PAINT-WHT-10L', 'Interior paint, white matte 10L',  'Paint',      89.00,   3, 'Each'),
  ('SAND-CONCRETE', 'Concrete sand',                    'Garden',      0.45, 800, 'Kilogram');

```

--------------------------------

### Interactive Welcome View with Name Field and Button

Source: https://www.vaadinonkotlin.eu/tutorial

Adds a text field for user input and a button to trigger a greeting notification. The onClick handler reads the name field's value and displays a personalized message.

```kotlin
package com.example.vok

import com.github.mvysny.karibudsl.v10.*
import com.vaadin.flow.component.notification.Notification
import com.vaadin.flow.router.Route

@Route("")
class WelcomeView : KComposite() {
    private val root = ui {
        verticalLayout {
            setSizeFull(); content { align(center, middle) }; isMargin = false; isSpacing = true

            h1("Welcome to BoltShop")
            val nameField = textField("Your name") {
                placeholder = "e.g. Alice"
            }
            button("Say hello") {
                onClick {
                    val name = nameField.value.ifBlank { "stranger" }
                    Notification.show("Hello, $name!")
                }
            }
        }
    }
}

```

--------------------------------

### Integrating Reusable Form Component into DSL

Source: https://www.vaadinonkotlin.eu/creating_ui

Add an extension function to use a custom form component in a DSL fashion. The `init` function from `karibu-dsl` is used to instantiate and configure the form.

```kotlin
fun HasComponents.nameAgeForm(block: NameAgeForm.() -> Unit = {}): NameAgeForm = 
    init(NameAgeForm(), block)

```

--------------------------------

### Run Gradle Tests

Source: https://www.vaadinonkotlin.eu/tutorial

Execute the Gradle test task to run the project's test suite. The first run downloads necessary artifacts, while subsequent runs are faster. The HTML report is generated at build/reports/tests/test/index.html.

```bash
$ ./gradlew test

```

--------------------------------

### Grid Filtering with Ktorm-Vaadin

Source: https://www.vaadinonkotlin.eu/databases

Demonstrates setting up a Vaadin Grid with various filter components (TextField, NumberRangePopup, BooleanFilterField, DateRangePopup, EnumFilterField) and integrating them with Ktorm-Vaadin's data provider for dynamic filtering. The `updateFilter` function shows how to collect filter values and apply them using the `.and()` extension.

```kotlin
import com.github.mvysny.ktormvaadin.and
import com.github.mvysny.ktormvaadin.dataProvider
import com.github.mvysny.ktormvaadin.filter.*
import eu.vaadinonkotlin.vaadin.vokdb.enumFilterField
import org.ktorm.dsl.*
import org.ktorm.schema.ColumnDeclaring
import org.ktorm.support.postgresql.ilike   // works on H2 too

class PersonListView : KComposite() {
    private val nameFilter = FilterTextField()
    private val ageFilter = NumberRangePopup()
    private val aliveFilter = BooleanFilterField()
    private val dateOfBirthFilter = DateRangePopup()
    private val maritalStatusFilter = enumFilterField<MaritalStatus>()
    private val dataProvider = Persons.dataProvider

    private val root = ui {
        verticalLayout {
            setSizeFull()
            grid<Person>(dataProvider) {
                setSizeFull()
                val filterBar = appendHeaderRow()

                columnFor(Person::name) {
                    nameFilter.addValueChangeListener { updateFilter() }
                    filterBar.getCell(this).component = nameFilter
                }
                columnFor(Person::age) {
                    ageFilter.addValueChangeListener { updateFilter() }
                    filterBar.getCell(this).component = ageFilter
                }
                columnFor(Person::alive) {
                    aliveFilter.addValueChangeListener { updateFilter() }
                    filterBar.getCell(this).component = aliveFilter
                }
                columnFor(Person::dateOfBirth, converter = { it?.toString() }) {
                    dateOfBirthFilter.addValueChangeListener { updateFilter() }
                    filterBar.getCell(this).component = dateOfBirthFilter
                }
                columnFor(Person::maritalStatus) {
                    maritalStatusFilter.addValueChangeListener { updateFilter() }
                    filterBar.getCell(this).component = maritalStatusFilter
                }
            }
        }
    }

    private fun updateFilter() {
        val conditions = mutableListOf<ColumnDeclaring<Boolean>?>()
        if (nameFilter.value.isNotBlank()) {
            conditions += Persons.name.ilike("${nameFilter.value.trim()}%")
        }
        conditions += Persons.age.between(ageFilter.value.asIntegerInterval())
        aliveFilter.value?.let { conditions += Persons.alive eq it }
        conditions += Persons.dateOfBirth.between(dateOfBirthFilter.value)
        val statuses = maritalStatusFilter.value
        if (statuses.isNotEmpty() && statuses.size < MaritalStatus.entries.size) {
            conditions += Persons.maritalStatus.inList(statuses.toList())
        }
        dataProvider.setFilter(conditions.and())
    }
}
```
Tokens:
Raw