# Multistep Form Multistep form is a new generation of the [Form](/web-pages/components/legacy-components/form.md) 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`

Paragraph element allows to insert HTML and to use the Templating engine

If the element has a description ` 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"}]`).

A dropdown for changing the state property — options are set manually here

* Apply [Action button](#using-action-buttons) for changing the state; * Apply [Sync request processing](#processing-requests-synchronically). #### 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](#configuring-conditional-visibility-of-elements)) and Form State:

Here is how debug mode looks like:

{% hint style="info" %} Don't forget to turn off the debug when you go public with your app! {% endhint %} ### 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! {% hint style="warning" %} First and foremost — the dynamic input is one for `link` or `arrayLink` fields. The options are defined by the request to the additional endpoint. {% endhint %} 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](/data/data-structures.md#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](#applying-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](#configuring-conditional-visibility-of-elements). One can hide or disable the button conditionally. Actions support [sync API response processing](#processing-requests-synchronically). ### 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](#processing-requests-synchronically). ### Editing Existing Objects Turn on switch "Edit the 1-st object in API-response"

{% hint style="warning" %} 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](/web-pages/setting-up-pages-layout/subpages-and-url-parameters.md) {% endhint %} If you want to proceed editing object after submitting, turn on "Keep the model" on [Submit element](#submitting-the-model). ### 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](#steps-sections-visibility) you can set up `popup` specifying which section should be displayed in the popup (for example, [using Action button](#using-actions)):

If you like you can even configure a chain of popups! ### Processing Requests Synchronically {% hint style="warning" %} This feature turns Multistep-form into a super-powerful component! {% endhint %} [Submit](#submitting-the-model) and [Action](#using-actions) can send a POST-request. As we know, the [POST-request can be synchronous](/api-integrations/api-endpoints-security-layer/advanced-techniques-for-get-requesting/synchronic-scenarios-for-post-requests.md). That means the API response may contain the result of the object processing within the scenario. Use [API-response step](/scenarios/editing-scenarios/integration-steps/api-response.md) in the scenario and compose a response in the following format: ```json //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](#steps-sections-visibility) (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](/web-pages/components/link-button.md), 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](#processing-requests-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](#editing-existing-objects) using the Multiform, you can update it using [plugin Socket.io](/plugins/using-plugins/websockets-socket.io.md). #### 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)

Object on the platform (left) and the form (right)

#### 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`)

{% hint style="info" %} Don't forget to publish and run the scenario! {% endhint %} Next — add a refresher component to the page where the form is located (use the same event name. In our case — `refresh`)

Web-page with the form and socket refresher

That it is! Result:

### Using data-actions You can now make any HTML element inside a Multistep Form interactive using data-action-type attributes. This allows buttons, links, or spans to trigger actions, navigate, or open modals — directly from HTML content (e.g. inside **Paragraph** element). #### Supported types | Type | Description | Example | | ------ | ------------------------------------------ | ----------------------------------------------------------------------------------- | | action | Run an action defined in the form settings | `` | | route | Navigate to a page (supports templating) | `View Profile` | | modal | Open a modal window | `✏️ Edit` | #### Key points * Templating support – use {{field}} in data-action-data. * Action integration – call existing actions by name or ID. * Event delegation – works seamlessly with other click handlers. * Compatible with ElementText and any HTML-enabled content. #### Example ```html View Profile ✏️ Edit ``` This feature lets you build rich, interactive forms without extra JavaScript — just simple HTML attributes. ### Using Custom API Multistep Form provides a public API for programmatic form control from external JavaScript code. This allows you to integrate the form with custom logic and dynamically modify form data and state. [Explore custom API](/web-pages/components/multistep-form/multiform-custom-api.md) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://readme.directual.com/web-pages/components/multistep-form.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.