Forms
Forms are one of the most important parts of GUI of many applications, especially the ones which collect and manage data from the users. Traditionally handling HTML forms is a complex process, composed of many small steps like placing HTML form controls on the page, setting and displaying initial data, reading user data from individual HTML elements and finally transforming and validating the data. It gets even worse if you are using custom visual components for complex data types - date, time, rich text, multiple select, uploaded files etc.
KVision lets you work with forms in a very simple, consistent and efficient way. It hides all complex data transformations inside the framework logic and offers you a fully type-safe binding between your data and your forms. It has support for many different, both simple and complex, form controls. And it gives you ready to use data validation.
Form data is modeled with a standard Kotlin data class enhanced with
@Serializable annotation from kotlinx.serialization library. Every field of this model class holds the value of one input item rendered within a form. The model support most basic data types: String, Number(including Intand Double), Boolean, Date and also a special type List<KFile> (a list of uploaded files).@Serializable
data class Form(
val text: String? = null,
val password: String? = null,
val password2: String? = null,
val textarea: String? = null,
val richtext: String? = null,
@Contextual val date: Date? = null,
@Contextual val time: Date? = null,
val checkbox: Boolean = false,
val radio: Boolean = false,
val select: String? = null,
val tomselect: String? = null,
val spinner: Int? = null,
val radiogroup: String? = null,
val upload: List<KFile>? = null
)
Note: You have to add
@Contextual annotations to your Date fields in order to explicitly allow serialization with the KVision context. You can also use @file:UseContextualSerialization(Date::class) file annotation if you want to keep your model classes cleaner. You can find more information about this annotation in the kotlinx.serialization documentation.Form controls are KVision components implementing one of six
FormControl interfaces inside io.kvision.form package: StringFormControl, NumberFormControl, BoolFormControl, TriStateFormControl, DateFormControl and KFilesFormControl. KVision comes with a bunch of build-in or modular form components.Component | Interface | Module | Description |
i.k.f.check.CheckBox | BoolFormControl | built-in | A check-box. |
i.k.f.check.Radio | BoolFormControl | built-in | A radio-button. |
i.k.f.check.RadioGroup | StringFormControl | built-in | A group of radio-buttons. |
i.k.f.check.TriStateCheckBox | TriStateFormControl | built-in | A tri-state check-box. |
i.k.f.text.Text | StringFormControl | built-in | A text field. |
i.k.f.text.Password | StringFormControl | built-in | A text field for password input. |
i.k.f.text.TextArea | StringFormControl | built-in | A text area. |
i.k.f.select.Select | StringFormControl | built-in | A standard select component. |
i.k.f.number.Spinner | NumberFormControl | built-in | Spinner numeric text field. |
i.k.f.number.Range | NumberFormControl | built-in | A range selection field. |
i.k.f.number.Numeric | NumberFormControl | built-in | A numeric form field. |
i.k.f.upload.Upload | KFilesFormControl | build-in | A simple file upload component. |
i.k.f.number.ImaskNumeric | NumberFormControl | kvision-imask | A numeric form field with masking. |
i.k.f.time.DateTime | DateFormControl | kvision-datetime | A date and/or time selection control. |
i.k.f.text.RichText | StringFormControl | kvision-richtext | A rich text editor. |
i.k.f.select.TomSelect | StringFormControl | kvision-tom-select | Advanced select boxwith support for multiple selection and remote data source. |
i.k.f.select.TomSelectRemote | StringFormControl | kvision-tom-select-remote | A select box for fullstack interfaces. |
i.k.f.upload.BootstapUpload | KFilesFormControl | kvision-bootstrap-upload | An upload file control with preview and multi-selection. |
i.k.f.text.TomTypeahead | StringFormControl | kvision-tom-select | A typeahed (autocomplete) text field with support for data source. |
i.k.f.text.TomTypeaheadRemote | StringFormControl | kvision-tom-select-remote | A typeahead (autocomplete) text field for fullstack interfaces. |
Note:
RadioGroup and TomSelect controls always return String values. Multiple selections are comma-separated. There is also
GenericRadioGroup<T> component, which can return value of any type, but it can't be used inside Form/FormPanel containers. KVision provides a dedicated container for working with forms -
FormPanel<K>. To create a FormPanel<K> instance you need to specify a serializer for your model data class.val formPanel = FormPanel(serializer = Form.serializer())
You can also use a DSL builder extension function, which automatically uses default serializer for your data class.
val formPanel = formPanel<Form> {}
Under the hood
FormPanel container uses non-visual form container - Form<K>, which can be used by developers to implement their own form containers.You add form controls to the
FormPanel using add method of the container, and at the same time you bind your controls to your data model by referencing class properties. The binding is type-safe, e.g. you can't bind StringFormControl to Boolean or Date field.formPanel<Form> {
add(
Form::text,
Text(label = "Text field") {
placeholder = "Enter text"
})
add(Form::password, Password(label = "Password field"))
add(Form::textarea, TextArea(label = "Text area field"))
add(Form::richtext, RichText(label = "Rich text field"))
add(Form::date, DateTime(format = "YYYY-MM-DD", label = "Date field"))
add(Form::time, DateTime(format = "HH:mm", label = "Time field"))
add(Form::checkbox, CheckBox(label = "Required checkbox"))
add(Form::radio, Radio(label = "Radio button"))
add(Form::select, TomSelect(options = listOf("first" to "First option", "second" to "Second option"),
label = "Simple select"
)
)
add(Form::spinner, Spinner(label = "Spinner field 10 - 20", min = 10, max = 20))
add(Form::radiogroup, RadioGroup(listOf("option1" to "First option", "option2" to "Second option"),
inline = true, label = "Radio button group"
)
)
add(Form::upload, BootstrapUpload("/", multiple = true, label = "Upload files (images only)") {
explorerTheme = true
dropZoneEnabled = false
allowedFileTypes = setOf("image")
})
}
If you need to manage your form directly you can create your layout using standard KVision DSL builders and bind your form controls manually using
bind extension method.formPanel<Form> {
hPanel(spacing = 5) {
text(label = "text 1").bind(Form::text, required = true)
vPanel(spacing = 5) {
textArea(label = "text 2").bind(Form::text2)
textArea(label = "text 3").bind(Form::text3)
}
}
}
After binding your fields you can treat a
FormPanel<K> instance as a kind of a "black box" - you manage all your data flow with just a few methods - mostly setData() and getData().val formPanel = formPanel<Form> {
// fields binding
}
val formData = Form(text = "Text data", password = "pass",
spinner = 15, select = "second")
formPanel.setData(formData)
val unmodifiedFormData = formPanel.getData()
println(unmodifiedFormData == formData) // true
FormPanel<K> container can layout form elements with three standard Bootstrap layouts: normal, horizontal and inline. The class constructor allows to specify other HTML form parameters as well.val formPanel = formPanel<Form>(
type = FormType.HORIZONTAL,
method = FormMethod.GET,
action = "form",
enctype = FormEnctype.MULTIPART
) {
// ...
}
KVision forms support validation for single fields and for the form as a whole. You can easily mark some fields as required, specify all needed validation functions and specify error messages, which will be displayed by the browser after validation action. Validation functions give you easy access to the values entered in the form.
formPanel<Form> {
add(
Form::password,
Text(label = "Password"),
required = true,
requiredMessage = "This field is required",
validatorMessage = { "Enter more than 8 characters" }
) { (it.getValue()?.length ?: 0) >= 8 }
add(
Form::password2,
Text(label = "Confirm password"),
required = true,
validatorMessage = { "Enter more than 8 characters" }
) { (it.getValue()?.length ?: 0) >= 8 }
validator = {
it[Form::password] == it[Form::password2]
}
validatorMessage = { "The passwords are not the same." }
}
val validationResult = formPanel.validate()
Note:
validatorMessage parameters are functions with the same parameters as validator functions. Note:
requiredMessage and validatorMessage parameters are optional. The default values for them are respectively "Value is required" and "Invalid value". You should use these parameters if you want to give more precise descriptions of the problems or when you want to internationalize your application.You can group several subsequent form fields within a single fieldset container by adding the same
legend parameter to the following add method calls.add(
Form::date,
DateTime(format = "YYYY-MM-DD", label = tr("Date field with a placeholder")).apply {
placeholder = tr("Enter date")
}, legend = tr("Date and time fieldset")
)
add(
Form::time,
DateTime(format = "HH:mm", label = tr("Time field")),
legend = tr("Date and time fieldset")
)
Form data model doesn't support custom types out of the box, but it's possible to add support for your own type as long as you can use such type with a form control based on
StringFormControl interface.Define a custom class for your model. It needs a
toString() method to convert its data to the String value used within a form.class ObjectId(val id: Int) {
override fun toString(): String {
return "$id"
}
}
Next you need to define a custom serializer for this class.
object ObjectIdSerializer : KSerializer<ObjectId> {
override val descriptor: SerialDescriptor = buildClassSerialDescriptor("com.example.ObjectId")
override fun deserialize(decoder: Decoder): ObjectId {
val str = decoder.decodeString()
return ObjectId(str.toInt())
}
override fun serialize(encoder: Encoder, obj: ObjectId) {
encoder.encodeString(obj.id.toString())
}
}
Now you can use this class within your model, by adding
@Contextual annotation.@Serializable
data class Form(
val text: String? = null,
val password: String? = null,
@Contextual val objectId: ObjectId? = null
)
When creating a
FormPanel container, you need to pass a reference to your serializer.formPanel<Form>(customSerializers = mapOf(ObjectId::class to ObjectIdSerializer)) {
// ...
}
Finally you can add your data binding with a special
addCustom method.addCustom(Form::objectId, Text(label = "Object Id"))
Sometimes it's not possible to know the data model of the form because the fields need to be added and/or removed dynamically. For such use cases KVision allows you to model your data with a
Map<String, Any?> type. To work with dynamic forms you need to create a FormPanel container with a simplified form() DSL builder function. Such call will return a FormPanel<Map<String, Any?>> instance. When adding or binding form controls use string identifiers instead of property references.val form: FormPanel<Map<String, Any?>> = form(type = FormType.HORIZONTAL) {
text(label = "First text field").bind("text1")
text(label = "Second text field").bind("text2", required = true)
checkBox(label = "CheckBox").bind("check1")
select(listOfPairs("First option", "Second option"),
label = "Select value", emptyOption = true).bind("select1", required = true)
}
Although all the fields are defined dynamically, you can still treat the form as a whole. You use
getData() and setData() functions using standard Kotlin maps. The identifiers used for bindings will be the keys in the map.val map = form.getData()
val textValue1 = map["text1"].unsafeCast<String?>()
val textValue2 = map["text2"].unsafeCast<String?>()
form.setData(mapOf("check1" to true, "select1" to "First option"))
When using dynamic forms you are intentionally loosing type safety. You need to make sure the values stored in the map are matching the types of form controls.
Last modified 3mo ago