Multistep Form

🪜 Build complex dynamic personalised forms in no time!

Last updated 10 months ago

Was this helpful?

Multistep Form

🪜 Build complex dynamic personalised forms in no time!

Multistep form is a new generation of the component (for now we keep them both available). It allows users to create complex multistep dynamic forms which are personalised for app users.

Learning the Basic Component Concepts

Form step (section). A block that includes Form elements.
Form element. Could be one of the following:
- Text paragraph;
- Inputs (up to 12);
- Action buttons (up to 12);
- Submit button;
- Hint;
- Sub-header;
- Redirect.
Object model. JSON-object that includes the current fields' values (default values and filled by the user).
Form state. JSON-object that includes one ore several parameters of the current form state. There are two default properties: step defines which form step is displayed now) and popup shows the popup and the relevant step in it.

Building a Simple Form

Let's start from creating a simple form where all users (both authorised and unauthorised) would be able to add new book, filling it's title. First of all, we are creating a data structure and then follow the steps.

Step 1. Add a Multistep form to your page

Step 2. Configure endpoint

We need to have the endpoint for creating/editing objects. For the beginning we may make it public.

Step 3. Add step elements

By default, we have 2 form steps: default step and submitted. Let's configure them!

Add new element to default step:

Choose Inputs element. Here we can configure inputs for filling fields available for reading (as well as state properties):

The second element will be "Submit". It'll send the POST request to the endpoint creating new object. Also, submit changes Form state step current value → submitted

Step 4. Set up the first form step

The last thing that we need to configure the default value of the state – define the first step in the Form:

Step 5. Test the form!

Push "Save" and – voilà:

Applying the Templating engine

You can use templating engine in the form title, description, in step elements, etc. The available fields include:

Form State properties
Fields from Object model
WebUser's fields like firstName, lastName, role, userpic, id

If the element has a description <HTML /> is allowed here, you can apply HTML and CSS.

You can use the templating engine in different elements like paragraph, sub-header, input descriptions, etc.

Navigating between steps

As we pinpointed, the current step is defined by the form state, FormState.step.

For example, if you want to start from my step, you need to define it as a default value:

Setting default step

Changing state

There are the following ways to change the state (and, the step property in particular):

Add Inputs element and define it as an Input for changing the state. You can configure it as a plain text input, as a dropdown select or a button line. For select and button line you need to add options. Those options can be set manually or pulled from the object's field (type of json, an array of key-value pairs like [{"key" : "option1", "value" : "option one"}, {"key" : "option2", "value" : "option two"}]).

Steps (sections) visibility

By default the step (section) is visible if its name == FormState.step. If you want to make it visible in other cases, use Advanced step settings:

The step may be visible always or when the FormState.step value is in the list (comma separated)

Debugging

Here is how debug mode looks like:

Don't forget to turn off the debug when you go public with your app!

Setting up Dynamic Inputs

One may need an input that dynamically provides user with options. It may be a dropdown select, radio buttons, tags. etc. The options may depend on the other fields' values, on the user's role, and on other parameters. Let's figure out how to set up the dynamic input!

First and foremost — the dynamic input is one for link or arrayLink fields. The options are defined by the request to the additional endpoint.

Example of a dynamic input. first input is a radio button: "guys or girls". The dropdown below provides us with the options according to the first choice:

There are the following options for rendering dynamic input:

Dropdown select (for link)
Dropdown multi-select (for arrayLink)
Radio-buttons (for link)
Checkboxes (for arrayLink)
Tags (both for link and arrayLink)
Images-radio-buttons (for link)
Images-checkboxes (for arrayLink)

Dropdowns support any number of options thanks to dynamic filtering.

Configuring endpoint for Dynamic inputs

Important: if you use dropdown, there have to be system filters for _value and _filer. if you create an endpoint right from the Multiform component, that filter is added automatically. But pay attention, that if you want filtering (quick search in the dropdown) work with more fields, add them in the filter (field like _filter)

Dynamic filtering

If you want to connect filtering on endpoint with the values that user fills, use custom request parameters and pass them those values.

Saving options quantity

If you like, you can save the options quantity to a state field. It works for hidden elements as well.

Configuring Conditional Visibility of Elements

You can set up the conditional visibility for each step element and for each action separately.

equal, not equal
contains/dos not contain (for Directual arrays – comma separated strings)
in/not in (for Directual arrays – comma separated strings)
empty/not empty (no second value)
model is changed/not changed since last submit (no any values at all)

Using Actions

Action is an element that can do the following:

Send POST-request to API-endpoint
Edit object model or state (including resetting the model and discarding changes in it)

Action can be either button or auto-action (performed on a certain step or when a certain field is changed)

One configures an action (tab Actions) first and then add it to the form as an element

There can be a few action buttons within a single form element, in a row.

Submitting the model

To save the whole model to the object you can use Submit element

By default the submit button resets the model and sets the FormState.step to submitted.

You can change those settings: keep the model and choose different step.

Also, you can set up conditional visibility. Common case: hide the submit button if the model is not changed.

On the State tab you can turn on saving state to a certain field on submit.

Editing Existing Objects

Turn on switch "Edit the 1-st object in API-response"

Editing an object pay attention to the following:

Object's fields including ID have to be available both for reading and writing
Form takes the first object from the endpoint. Configure filters or sorting accordingly.

Storing State in the Object

If you edit an object, you can restore the state from it. There are two options.

1. Getting state properties from object fields

2. Getting the whole state from a single field type of JSON

Using Popups

You can place any Step (section) to the popup:

If you like you can even configure a chain of popups!

Processing Requests Synchronically

This feature turns Multistep-form into a super-powerful component!

//if you want to edit model:
{
    "object": {
        "field1" : "value",
        ...
    }
}

//if you want to edit form state:
{
    "state": {
        "step" : "value",
        "popup" : null
        ...
    }
}

//if you want to edit both:
{
    "state": {
        "step" : "value",
        "popup" : null
        ...
    },
    "object": {
        "field1" : "value",
        ...
    }
}

// if you want to redirect user, you can do it as well!
{
    "redirect": {
        "target" : "./{{myField}}", // similar to LINK BUTTON component
        "delay" : 500 // in millisectods. 0 – by default
        ...
    }
}

// if you want all dynamic fields refresh their options
{
    "refresh": true
}

Setting up Progress Bar

You can add a progress bar to the form:

Configure the progress bar, adding steps into it, arranging the order, and filling steps' names, descriptions, etc.

Using Redirect Element

Bear in mind that you can redirect to the page or a subpage using object fields or form state properties in target URL.

Online Refreshing with Socket.io

Step 1. Configure the form

The updated fields have to be available for reading

The form settings includes "Edit object" option

Here is how the form look like (be sure that your endpoint provides you with the required object. If not — use filters and sorting)

Step 2. Install Socket plugin and configure it

Install the plugin from the Marketplace

Create a scenario, that triggers when object is Changed. It calls the Socket plugin for all users (* in the first field), for a certain event (in our example event name = refresh)

Don't forget to publish and run the scenario!

Next — add a refresher component to the page where the form is located (use the same event name. In our case — refresh)

That it is! Result:

PreviousComponents NextCards

Last updated 10 months ago

Was this helpful?