Forms

Form component is one of the most used feature in the KASKO framework. Constructing forms with existing components should be a breeze. Though, when building custom form components, it is beneficial to understand the form building mechanism in-depth. This guide covers both - a basic usage example and some additional information for power users.

Basic form

A basic form consists of the form wrapper component and some fields assigned to this form. Without the wrapping form component, the form-input component will not work.

Example form with one text field:

{
  "type": "form",
  "config": {
    "components": [
      {
        "type": "form-input",
        "config": {
          "field_name": "first_name"
        }
      }
    ]
  }
}

Note: for a full list of form components, view the component storybook.

The three states

Each application screen with a form has three states.

The three states

Component state

This is the lowest level state which is fully contained to the component level. Sometimes a component has multiple input fields. In such cases this state level is very useful.

For example, the dob (date-of-birth) component has three fields - date, month and year. Only when all three have been selected the value is sent to the screen state to be validated.

Some components do not utilize this state level. This is fine if there is only one customer input field.

Screen state

The next level is the screen state. Before the screen is visually shown, a FormInstance element is constructed with all the available fields that are on the given screen. The fields are retrieved by aggregating all field_name and fields component configurations. They are combined with defined field definitions and existing values in global input state to produce the resulting object.

The resulting object consists of (for each field):

1. unique field name (key)

2. validation rules

3. value (if not pre-filled or defaulted - this will be empty)

The screen state is refreshed each time a new screen is opened.

When the screen state is updated with new values, the validator is ran and errors are shown (though most times the errors will only appear after clicking "next" as not to confuse the customer with premature error messages).

Once the "next" button (form-next) is clicked or if the form has config.watch_changes=true set, then the screen state is forwarded to the global state.

Global state

The final and highest level state is the global state. Only the customer inputs stored in the global state are forwarded to the API requests (quote, policy, leads etc.).

There are several ways how values can be inserted into global state

1. through submitting the FormInstance (screen state)

2. through default values in the manifest
3. through pre-fills via integration snippet or kdata