Multistep Form

🪜 Build complex dynamic personalised forms in no time!

Multistep form is a new generation of the Form 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"}]).

Apply Action button for changing the state;
Apply Sync request processing.

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

You can turn on debug for displaying Form Model (and system messages on developer console about Conditions) and Form State:

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

Any dynamic input requires an endpoint. You can configure filters and sorting in this endpoint as you wish. Moreover, don't forget to set up structure visible name and make it available for reading in that endpoint.

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.

The conditions can be combined either with AND or OR operators. You can compare current model fields and state properties with expressions (using the Templating engine). There are the following operators for comparison:

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.

Each action button has its own visibility conditions, similar to element ones. One can hide or disable the button conditionally.

Actions support sync API response processing.

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.

Submit supports sync API response processing.

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.

Tip: usually endpoint filters depend on parameters from URL

If you want to proceed editing object after submitting, turn on "Keep the model" on Submit element.

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:

Similar to step configuration you can set up popup specifying which section should be displayed in the popup (for example, using Action button):

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

Processing Requests Synchronically

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

Submit and Action can send a POST-request. As we know, the POST-request can be synchronous. That means the API response may contain the result of the object processing within the scenario.

Use API-response step in the scenario and compose a response in the following format:

//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:

First—better to put progress bar in a step that is visible everywhere (or at leas on the steps that are included into the progress).

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

Using Redirect Element

Redirect element (surprise!) redirects the user. It works like Link button, but automatically.

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

The common case: the form creates the object, scenario synchronically returns its ID, and the redirect element leads the user to the page where he proceeds editing the object.

Online Refreshing with Socket.io

If you edit an object using the Multiform, you can update it using plugin 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: