Documentation
AcademyCommunitySign In
  • 👋Overview
  • 💙Platform Features
  • Getting started
    • 🚪Signing up & Logging in
      • 👤Profile Settings
    • 🎛️App Management
    • ✴️Templates to Start With
      • Basic Template (Blank app)
      • CRM Template
    • 👨‍🎓Learning Directual
      • 👨‍🏫Webinars
  • Data base
    • Data Structures
      • System Structures
    • Data Types
      • Markdown Cheat Sheet
      • Indexing Fields
      • Formatting Date/Time
    • Directual Query Language (DQL)
    • Import and Export
      • Import API
    • File Storage
      • API for File Storage
  • API and integraions
    • API-Endpoints
      • Advanced techniques for GET and POST requesting
        • Paging for GET-requests
        • Dynamic sorting for GET-requests
        • Custom filtering parameters for GET-requests
        • Advanced filtering for GET-requests
        • Formatting response for GET-request
        • Fields validation for POST-requests
        • Synchronic scenarios for POST-requests
        • Cross-Origin Resource Sharing CORS
      • API testing and debugging
      • Coding mode (raw mode) in filters
      • Swagger specification
    • Webhooks
    • Authentication API
      • Login/password
      • OpenID connect
      • Facebook oAuth
      • Google oAuth
    • Security Features
    • Other Integrations
      • OpenAI
      • Integration Hubs
        • Zapier
      • Telegram
        • Telegram: Advanced Techniques
      • Email
        • SMTP
        • Gmail
      • Twilio SMS
      • Airtable
      • Coupler.io
      • Other No-Code Tools
        • Bubble.io
          • Authorization
          • Displaying Data from Directual on Bubble
        • Adalo
        • UI bakery
        • Tilda
        • AppGyver
  • App interface
    • Web-App Builder basics
    • Web-App Settings
      • General web-app settings
      • Main menu
      • Creating a logotype
      • Web-App color scheme
      • Web-app typography
      • White Labeling
      • Web-App Icon
      • Custom Domain
      • Custom code
    • Setting Up Page Layout
      • Subpages and URL Parameters
    • Components
      • Multistep Form
      • Cards
      • Table
      • Kanban
      • Chart
      • Markdown text
      • HTML code
      • Hint
      • Link Button
      • Video
      • Form (outdated)
    • Embedding Pages
  • Scenarios
    • Understanding Directual Scenarios
      • Directual Event Model
    • Event-Based Triggers
    • Scheduled Triggers
      • Cron Format
    • Synchronous Scenarios
    • Editing Scenarios
      • System Steps
        • Start step
        • Delay step
        • Comment step
        • Catch error step
        • Link scenario step
        • Exit step
      • Action steps
        • Edit object step
        • Create object step
        • Search objects step
        • JSON step
        • Delete object step
        • Run report step
        • Generate document step
        • JS SDK step
      • Condition steps
        • Condition step
        • A/B test step
        • JS SDK condition step
      • Integration steps
        • HTTP-request step
        • Zapier step
        • Telegram step
        • API response
        • Email step
        • SQL-request step
        • Queue step
    • Using Variables
      • Global Variables
      • Context Variables (scenario parameters)
    • Testing and Debugging
    • System Scenarios
    • Advanced Scenario Settings
  • Template system
    • Templating Principles
      • Templating Techniques for Scenarios
      • Templating Techniques for Web-pages
    • Coding Mode (evaluating as a JS-expression)
    • Comparison Component
      • Regular Expressions
    • Tips for Dealing with Data
  • Telegram
    • Telegram
  • Plugins
    • 🔌Using Plugins
      • Scenario Steps Plugins
      • Web Plugins
      • User Authentication Plugins (Not Web3)
        • TMA (Telegram Mini App)
        • Google OAuth Plugin
        • Facebook OAuth Plugin
        • Open ID Auth Plugin
      • Blockchain (Web3)
        • TON (The Open Network)
        • Polygon
        • Ethereum
        • NEAR Protocol
        • NFT and Smart-Contracts
        • MetaMask Wallet
        • WalletConnect
      • WebSockets (Socket.IO)
    • 🪚Developing Plugins
      • Developing Scenario Plugins
      • Developing Web-plugins
        • Example: Using Chart.js in Directual
        • Example: Building Simple Form
        • Example: TON plugin
  • Teams
    • Teams
    • Sandbox Apps
  • JavaScript SDK
    • Directual + JavaScript SDK: The Basics
    • Internal $D Methods
    • Using Google Sheets
    • JS SDK: Examples
  • Reports
    • Reports
  • App life cycle management
    • App Versions
  • Directual 💙 React JS
    • Directual + React JS
  • Pricing and billing
    • 💳How Billing Works
    • 🎁Promo Codes
    • Pricing Plans for Apps
    • Team Pricing Plans
    • How we count requests and operations
    • On-Demand Resource Consumption
    • 🤝Affiliate Program
  • Hire a Directual expert
    • 🏆Certification
    • 🤝Matching with Experts
    • 🏦Escrow service
  • Security and stability
    • 🛡️Public Cloud
    • Platform Architecture
  • Support
    • 📬Contact Directual
  • Directual step-by-step
    • Public Development Roadmap
      • Step 0: Planning App Architecture
      • Step 1: Requesting Features
      • Step 2: Approving Features
      • Step 3. Upvoting Features
      • Step 4. Watching Features
    • Weather Forecast App
    • Web3 Marketplace on Polygon
    • Transferring NFT
Powered by GitBook
On this page
  • Learning the Basic Component Concepts
  • Building a Simple Form
  • Applying the Templating engine
  • Navigating between steps
  • Debugging
  • Setting up Dynamic Inputs
  • Configuring Conditional Visibility of Elements
  • Using Actions
  • Submitting the model
  • Editing Existing Objects
  • Storing State in the Object
  • Using Popups
  • Processing Requests Synchronically
  • Setting up Progress Bar
  • Using Redirect Element
  • Online Refreshing with Socket.io

Was this helpful?

  1. App interface
  2. Components

Multistep Form

🪜 Build complex dynamic personalised forms in no time!

PreviousComponentsNextCards

Last updated 11 months ago

Was this helpful?

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:

Apply for changing the state;

Apply .

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

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 and make it available for reading in that endpoint.

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

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

Actions support .

Submit supports .

Tip: usually endpoint filters depend on

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

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

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

Use in the scenario and compose a response in the following format:

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

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

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

If you using the Multiform, you can update it using .

parameters from URL
API-response step
Link button
Action button
Sync request processing
Conditions
Templating engine
similar to element ones
sync API response processing
sync API response processing
Submit element
configuration
using Action button
POST-request can be synchronous
Submit
Action
visible everywhere
scenario synchronically
plugin Socket.io
edit an object
Form
Creating new public endpoint
Paragraph element allows to insert HTML and to use the Templating engine
A dropdown for changing the state property — options are set manually here
Object on the platform (left) and the form (right)
Start step
The whole scenario
Socket (push) step
Web-page with the form and socket refresher
structure visible name