Adds form fields abstraction for implementing input forms with validations using reactive approaches, supporting both LiveData and Flow for validation logic. Includes chain and DSL validation formats.
This is a Kotlin MultiPlatform library that add form fields abstraction to implement any input forms with validations.
LiveData from moko-mvvm or Flow from kotlinx.coroutines).root build.gradle
allprojects {
repositories {
mavenCentral()
}
}
project build.gradle
dependencies {
commonMainApi("dev.icerock.moko:fields-core:0.12.0")
// integration with reactive flows
commonMainApi("dev.icerock.moko:fields-livedata:0.12.0")
commonMainApi("dev.icerock.moko:fields-flow:0.12.0")
androidMainApi("dev.icerock.moko:fields-material:0.12.0")
}
to work correctly on the iOS side, you need to export the
mvvm-flow and mvvm-core dependencies to the iOS framework.
Create FormField to text input with empty validation:
val textField = FormField<String, StringDesc>("", { inputLiveData ->
inputLiveData.map { text ->
if (text.isBlank()) "should be not blank!".desc()
else null
}
})
Use liveBlock to simplify validation create.
val textField = FormField<String, StringDesc>("", liveBlock { text ->
if (text.isBlank()) "should be not blank!".desc()
else null
})
Use LiveData in validation lambda to merge with other fields.
val passwordField = FormField<String, StringDesc>("", { inputLiveData ->
inputLiveData.map { text ->
if (text.isBlank()) "should be not blank!".desc()
else null
}
})
val passwordConfirmField = FormField<String, StringDesc>("", { inputLiveData ->
passwordField.data.mergeWith(inputLiveData) { password, passwordConfirm ->
if (passwordConfirm.isBlank()) .desc()
(passwordConfirm != password) .desc()
}
})
Call validate to perform validations and show error to user by field.error LiveData.
Bind FormField to UI by data and error LiveDatas.
<com.google.android.material.textfield.TextInputLayout
app:error="@{viewModel.emailField.error.ld}">
<EditText
android:text="@={viewModel.emailField.data.ld}" />
</com.google.android.material.textfield.TextInputLayout>
emailField.bindTextTwoWay(liveData: viewModel.emailField.data)
emailField.bindError(liveData: viewModel.emailField.error)
Create FormField to text input with empty validation:
val emailField: FormField<String, StringDesc> = FormField(
scope = viewModelScope,
initialValue = "",
validationTransform = { email ->
ValidationResult.of(email) {
notBlank(MR.strings.cant_be_blank.desc())
matchRegex(MR.strings.wrong_format.desc(), EMAIL_REGEX)
}
}
)
FormField to work with coroutines, CoroutineScope is required.
Call validate to perform validations and show error to user by field.error StateFlow.
Bind FormField to UI by data and error StateFlows:
val email: String by viewModel.emailField.data.collectAsState()
TextField(
placeholder = @Composable {
Text("Email")
},
value = email,
onValueChange = { viewModel.emailField.data.value = it }
)
For ease of use in working with SwiftUI, you can use this CocoaPods dependency.
There is a useful ValidationResult class for building validation monads for a form fields.
Two formats for creating validation are implemented:
ValidationResult.of(emailFieldValue)
.notBlank(blankErrorStringDesc)
.matchRegex(wrongEmailErrorStringDesc, EMAIL_REGEX)
.validate()
For this variant, do not forget to call function validate at the end!
ValidationResult.of(emailFieldValue) {
notBlank(blankErrorStringDesc)
matchRegex(wrongEmailErrorStringDesc, EMAIL_REGEX)
}
To create a new function for validation monad, you need to create an extension function of class
ValidationResult using builder nextValidation. For example, this is how the ready-made function
for checking String values for blankness looks like:
fun ValidationResult<String>.notBlank(errorText: StringDesc) = nextValidation { value ->
if (value.isNotBlank()) {
ValidationResult.success(value)
} else {
ValidationResult.failure(errorText)
}
}
All the ready-made validation functions of the library can be found in the source codes in the files
AnyValidations.kt for Any class and StringValidations.kt for String class.
To simplify of adding validation to the FormField object (without mapping of a LiveData
objects) you can use the builder-function fieldValidation:
val passwordField = FormField<String, StringDesc>(
initialValue = "",
validation = fieldValidation {
notBlank(MR.strings.cant_be_blank.desc())
minLength(MR.strings.must_contain_more_char.desc(), 4)
}
)
More examples can be found in the sample directory or sample-declarative-ui directory.
All development (both new features and bug fixes) is performed in develop branch. This way master sources always contain sources of the most recently released version. Please send PRs with bug fixes to develop branch. Fixes to documentation in markdown files are an exception to this rule. They are updated directly in master.
The develop branch is pushed to master during release.
More detailed guide for contributers see in contributing guide.
Copyright 2019 IceRock MAG Inc
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance the License.
You may obtain a copy of the License at
http:
Unless applicable law agreed to writing, software
distributed under the License distributed an BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express implied.
See the License the specific language governing permissions
limitations under the License.
class LoginViewModel(
override val eventsDispatcher: EventsDispatcher<EventsListener>
) : ViewModel(), EventsDispatcherOwner<LoginViewModel.EventsListener> {
val emailField = FormField<String, StringDesc>("", liveBlock { email ->
if (email.isBlank()) MR.strings.cant_be_blank.desc()
else null
})
val passwordField = FormField<String, StringDesc>("", liveBlock { password ->
if (password.isBlank()) MR.strings.cant_be_blank.desc()
else null
})
private val fields = listOf(emailField, passwordField)
fun onLoginPressed() {
if (!fields.validate()) return
val email = emailField.value()
val password = passwordField.value()
val message = "$email:$password"
eventsDispatcher.dispatchEvent { showMessage(message.desc()) }
}
interface EventsListener {
fun showMessage(message: StringDesc)
}
}
class LoginViewModel : ViewModel() {
private val _actions: Channel<Action> = Channel(Channel.BUFFERED)
val actions: CFlow<Action> get() = _actions.receiveAsFlow().cFlow()
val emailField: FormField<String, StringDesc> = FormField(
scope = viewModelScope,
initialValue = "",
validation = flowBlock { email ->
ValidationResult.of(email) {
notBlank(MR.strings.cant_be_blank.desc())
matchRegex(MR.strings.wrong_format.desc(), EMAIL_REGEX)
}
}
)
val passwordField: FormField<String, StringDesc> = FormField(
scope = viewModelScope,
initialValue = "",
validation = fieldValidation {
notBlank(MR.strings.cant_be_blank.desc())
minLength(MR.strings.must_contain_more_char.desc(), 4)
}
)
private val fields = listOf(emailField, passwordField)
fun onLoginPressed() {
if (!fields.validate()) return
val email = emailField.value()
val password = passwordField.value()
val message = "$email:$password"
_actions.trySend(Action.ShowMessage(message.desc()))
}
sealed interface Action {
data class ShowMessage(val message: StringDesc) : Action
}
companion object {
private val EMAIL_REGEX =
Regex("[a-zA-Z0-9\\+\\.\\_\\%\\-\\+]{1,256}\\@[a-zA-Z0-9][a-zA-Z0-9\\-]{0,64}(\\.[a-zA-Z0-9][a-zA-Z0-9\\-]{0,25})+")
}
}
struct LoginScreen: View {
var viewModel: LoginViewModel = LoginViewModel()
var body: some View {
LoginScreenBody(
email: viewModel.binding(\.emailField.data),
emailError: viewModel.state(\.emailField.error)
)
}
}
struct LoginScreenBody: View {
var email: String
let emailError: StringDesc?
var body: some View {
VStack {
TextField("email", text: viewModel.binding(\.passwordField.data))
if let emailError = emailError {
Text(emailError.localized())
}
}
}
}
kotlinx.coroutines;moko-mvvm LiveDatasfields-livedata on Android, iOS & mpp-library connected to appsfields-flow on Android with Compose,on iOS with SwiftUI and shared module connected to appsSurfaced from shared tags and platforms — no rankings paid for.