Embed a form builder with Kotlin
Tags: kotlin, mobile, coding, android
Published: 2024-05-10 18:46:37

In this guide, we'll show how to embed a form builder with Kotlin using Joyfill’s [Kotlin form builder SDK](https://joyfill.io/developers), and learn how to render your first form in minutes.

You can think of Joyfill as a sort of Stripe or Twilio, but for forms.

We offer four libraries entirely build in kotlin multiplatform

`io.joyfill:joyfill-compose`: The main library for integrating Joyfill into your Compose app. This library includes all the necessary UI components for displaying and interacting with Joyfill documents.

`io.joyfill:joyfill-models`: A library for integrating Joyfill models into your Kotlin app.

`io.joyfill:joyfill-builder`: A library for creating documents programmatically in kotlin

`io.joyfill:joyfill-api`: A library for all the network interactions with the Joyfill API.

### **Setup**

Please see our [Overview](https://docs.joyfill.io/reference/overview-api) and [Getting Started Guide](https://docs.joyfill.io/docs/quick-start)

### Project Requirements

Note: userAccessTokens & identifiers will need to be stored on your end (usually on a user and set of existing form field-based data) in order to interact with our API and UI Components effectively

See our [API Documentation](https://docs.joyfill.io/docs) for more information on how to interact with our API.

### Install Dependency

Add the following maven coordinates to your dependencies in your `build.gradle.kts` file.

```kotlin
implementation("io.joyfill:compose:<version>")
```

Select the SDK version that you want to use.

Note: We recommend using the default (latest) SDK version, but you can choose an older version if needed.

Choose the Joyfill libraries you want to use.

### Getting Started

**Show a Joyfill Document with the `Form` Composable**

```kotlin
import joyfill.Form

Form(
    document = getJoyDoc(),
    mode = JoyMode.readonly, // or JoyMode.fill,
    onChange = { event ->
        // handle your events here
    }
)
```

See our example project for more details.

### `Form` Params

- `mode: 'Mode.fill' | 'Mode.readonly'`
    - Enables and disables certain JoyDoc functionality and features.
    - Default is `Mode.fill`.
    - Options
        - `fill` is the mode where you simply input the field data into the form
        - `readonly` is the mode where everything in the form is set to read-only.
- `document: Document`
    - The JoyDoc JSON object to load into the SDK. Must be in the JoyDoc JSON data structure.
    - The SDK uses object reference equality checks to determine if the `doc` or any of its internal `pages` or `fields` have changed in the JSON. Ensure you’re creating new object instances when updating the document, pages, or fields before passing the updated `doc` JSON back to the SDK. This will ensure your changes are properly detected and reflected in the SDK.
- `pageID: String`
    - Specify the page to display in the form.
    - Utilize the `_id` property of a Page object. For instance, `page._id`.
    - If page is not found within the `doc` it will fallback to displaying the first page in the `pages` array.
    - You can use this property to navigate to a specific page in the form.
- `onChange: (event: ChangeEvent) -> Unit`
    - Used to listen to any field change events.
    - `event.changelogs: List<ChangeLog>`
        - Can contain one or more of the changelog object types supported. [Learn more about changelogs](https://docs.joyfill.io/docs/changelogs)
    - `event.document: Document`
        - Fully updated JoyDoc JSON structure with changes applied.
- `onUpload: suspend (event: FieldEvent) -> List<String>`
    - Used to listen to file upload events.
    - Specifies information about the uploaded file.
- `onFocus: (event: FieldEvent) -> Unit`
    - Used to listen to field focus events.
    - `event` Specifies information about the focused field.
    - `blur: Function`
        - Triggers the field blur event for the focused field.
        - If there are pending changes in the field that have not triggered the `onChange` event yet then the `e.blur()` function will trigger both the change and blur events in the following order: 1) `onChange` 2) `onBlur`.
        - If the focused field utilizes a modal for field modification, ie. signature, image, tables, etc. the `e.blur()` will close the modal.
- `onBlur: (event: FieldEvent) -> Unit`
    - Used to listen to field focus events.
    - `event` Specifies information about the blurred field.
- `onFieldChange: (event: FieldEvent) -> Unit`
    - Used to listen to individual micro field change events.
    - `event` Specifies information about the field change.
    

### ChangeEvent Properties

**Field Events:**

- **Text**, **Textarea**, **Number**
    - `onFocus(params: object, e: object)` is fired when the field is focused.
    - `onChange` is fired when the field value is modified.
    - `onBlur` is fired when the field is blurred.
- **Date**, **Dropdown**
    - `onFocus` is fired when the field is pressed and selection modal is displayed.
    - `onChange` is fired when the field value is modified.
    - `onBlur` is fired when the field is blurred and the selection modal is closed.
- **Multiselect**
    - `onFocus` is fired when an option is selected or unselected for the first time on the field.
    - `onChange` is fired when an option is selected or unselected in the field.
- **Chart**
    - `onFocus` is fired when “view” button is pressed and modal is displayed.
    - `onChange` is fired when the field value is modified.
    - `onBlur` is fired when modal is closed.
- **Image**
    - `onFocus` is fired when “view” button is pressed and modal is displayed.
        - An empty image field that is focused will also trigger the `onUploadAsync` request.
        - A populated image field that is focused will trigger the image modal to open.
    - `onChange` is fired when the field images are uploaded or removed.
    - `onBlur` is fired when modal is closed.
- **Signature**
    - `onFocus` is fired when open modal button is pressed and modal is displayed.
    - `onChange` is fired when the field value is modified.
    - `onBlur` is fired when the modal is closed.
- **Table**
    - `onFocus` is fired when “view” button is pressed and modal is displayed.
    - `onBlur` is fired when modal is closed.
    - **Table Cells**
        - **Text Cell**
            - `onFocus` is fired when the cell is focused.
            - `onChange` is fired when the cell value is modified.
            - `onBlur` is fired when the cell is blurred
        - **Dropdown Cell**
            - `onFocus` is fired when the cell is pressed and selection modal is displayed.
            - `onChange` is fired when the field value is modified.
            - `onBlur` is fired when the cell is blurred and the selection modal is closed.
        - **Image Cell**
            - `onFocus` is fired cell is pressed and modal is displayed.
                - An empty image cell that is focused will also trigger the `onUploadAsync` request.
                - A populated image cell that is focused will trigger the image modal to open.
            - `onChange` is fired when the cell images are uploaded or removed.
            - `onBlur` is fired when modal is closed.

**IMPORTANT NOTE:** JoyDoc SDK `onFocus`, `onChange` and `onBlur` events are not always called in the same order. Two different fields can be triggering events at the same time. For instance, if you have Field A focused and then focus on Field B, the Field B onFocus event could be fired before the Field A onBlur event. Always check the event params object ids to match up the associated field events.

### Kotlin form builder guide summary

Embarking on a Kotlin cross-platform project with Joyfill entails leveraging a suite of robust libraries designed to seamlessly integrate document management into your application. With offerings like joyfill-compose, joyfill-models, joyfill-builder, and joyfill-api, developers gain access to comprehensive tools for UI integration, model incorporation, document creation, and network interaction. By following the outlined project requirements and installing dependencies, developers can swiftly immerse themselves in the Joyfill ecosystem.

The process of getting started is straightforward, with the ability to display Joyfill documents using the Form Composable feature. By specifying parameters such as mode, document, pageID, and implementing event listeners like onChange and onUpload, developers can customize the interaction with Joyfill documents to suit their application's needs.

Moreover, the Joyfill SDK offers a versatile range of event triggers for various field types, ensuring comprehensive control over user interactions. From text fields to charts and images, developers can harness onFocus, onChange, and onBlur events to facilitate seamless user experiences.

With additional resources such as sample applications and the Kotlin Joyfill API, developers have access to further guidance and documentation to aid in the integration and utilization of Joyfill functionalities within their projects.