jkuatdsc/form-builder

Jetpack Compose FormBuilder

A customisable android library used to provide an abstraction layer over form elements as well as provide a DRY code implementation of a form.

The library is used to help in the state management of a Form in Jetpack compose. Currently, we don't have an official support for a form state so the library is used to provide a custom implementation of the same.

Installation

In the root build.gradle file add the following:

repositories {
    maven { url "https://jitpack.io" }
}

Then add the following to your module's build.gradle

dependencies {
    implementation 'com.github.jkuatdsc:form-builder:${version}'
}

Basic Usage

The library provides a FormState class that represents the state of your Form. It receives a list of field classes that inherit the basic properties from the BaseState class.

val formState = FormState(
    fields = listOf(
        TextFieldState(
            name = "email",
            transform = { it.trim().lowercase() },
            validators = listOf(Validators.Email()),
        ),
        ChoiceState(
            name = "gender",
            validators = listOf(Validators.Required())
        ),
        SelectState(
            name = "hobbies",
            validators = listOf(Validators.Required())
        )
    )
)

You can pass a list of Validators to the field states. These validators are used to check the validity of the input in the specific field. The validators are executed in the order they are passed.

The transform function allows you to change the text field value to whatever class you desire, e.g, TextFieldState<String> to TextFieldState<Int>.

In your UI:

val formState = remember { viewmodel.formState }

val emailState: TextFieldState = formState.getState("email")

OutlinedTextField(
    value = emailState.text,
    isError = emailState.hasError,
    label = { Text("Email address") },
    onValueChange = { emailState.change(it) }
)
if (emailState.hasError) Text(emailState.errorMessage, color = MaterialTheme.colors.error)

We can get individual states for the fields using the getState function in the FormState class. We can then access various properties of the state like text, hasError, errorMessage etc.

Don't forget to update your state using the setter functions in each field state.

To validate your form and get form data:

if (formState.validate()) {
    val data = formState.getData(Credentials::class)
    Log.d("Data", "submit: data from the form $data")
}

Here is what the Credentials data class looks like. Take note of how the property names correspond to the field values passed when instantiating the form state.

data class Credentials(
    val email: String,
    val gender: String,
    val hobbies: List<String>
)

The validate function returns true if all the fields are valid. You can then access data from the form using the getData function. Pass in your data class and using reflection, we convert the map (Map<String, Any>) to your data class.

You can also pass in custom error messages to the validators.

TextFieldState(
    name = "age",
    transform = { it.toInt() },
    validators = listOf(Validators.MinValue(limit = 18, message = "too young"))
)

Demos

Demo 1 : In this demo, the validations are executed before the next screen is presented.

Demo 2 : In this demo, the validations are run at the end of the survey when submitting data.

You can find the sample apk here

For more details about the library, check out the references.

Further Reading

The links below provide a reinforced understanding to the library.

• Introduction to Form Builder basics
• Advanced Form Builder operations guide

MIT Licence