logo dile-components dile-components
crud ajax
Doc URL Content

dile-steps-form

The dile-steps-form component builds a multi-step form, also known as a wizard. It loads the data of a resource from the server, distributes it among the forms of every step, and saves each step via Ajax when the user moves forward.

The family has two public components:

Installation

npm i @dile/crud

Usage

Import the components.

import '@dile/crud/components/steps-form/steps-form.js';
import '@dile/crud/components/steps-form/step-form.js';

Place the dile-step-form elements as direct children of dile-steps-form. Every step contains a form component in its form slot.

<dile-steps-form title="New order" endpoint="/api/orders/1">
  <dile-step-form label="Customer" endpoint="/api/orders/1/customer">
    <order-customer-form slot="form"></order-customer-form>
  </dile-step-form>
  <dile-step-form
    label="Shipping"
    endpoint="/api/orders/1/shipping"
    alternativeExit
    alternativeExitLabel="Save as draft"
  >
    <order-shipping-form slot="form"></order-shipping-form>
  </dile-step-form>
  <dile-step-form label="Summary" endpoint="/api/orders/1/summary" endLabel="Place order">
    <order-summary-form slot="form"></order-summary-form>
  </dile-step-form>
</dile-steps-form>

This is how it works:

  1. When endpoint is set, dile-steps-form loads the resource with a GET request and calls setData() on the form of every step.
  2. When the user presses the next button, the step sends the result of the form getData() to its own endpoint (PATCH by default).
  3. If the step is saved, the container moves to the next step. Validation errors are displayed in the form with showErrors().
  4. When the last step is saved, the container dispatches dile-steps-form-complete. The component does not navigate anywhere: listen to this event to decide what to do next.

Form requirements

The form inside every step must implement getData(), setData(data) and showErrors(errors), the same contract used by dile-ajax-form. You can get all of them applying the DileForm mixin of @dile/ui.

Every form receives the whole resource in setData(), so each one picks the fields it needs.

Alternative exit

A step can show a secondary action with the alternativeExit and alternativeExitLabel properties, for example "Save as draft". It saves the step and finishes the wizard, dispatching dile-steps-form-complete with alternativeExit: true, even if it is not the last step.

When the alternative exit is used, the step adds the field alternativeExit: true to the data sent to the server. You can change the name of that field with alternativeExitField, or set it to an empty string to not send it.

Sharing data between steps

By default the forms only receive data when the resource is loaded. If a step needs the data returned by the server when another step is saved, set the refreshOnSave attribute on it.

<dile-step-form label="Lines" endpoint="/api/invoices/1/lines" refreshOnSave>
  <invoice-lines-form slot="form"></invoice-lines-form>
</dile-step-form>

Only use refreshOnSave when the server returns the data that the form needs. Otherwise the form could lose the values it was displaying.

You can also call the reload() and setData() methods of the container.

dile-steps-form

Properties

Methods

Custom Events

dile-step-form

Properties

The container sets active, step, steps and language on every step, so you don't need to set them.

Methods

Custom Events

All these events bubble and are composed, so you can listen to them on dile-steps-form or on any ancestor.

Labels and translations

The labels of the buttons are resolved in this order: the label of the step, the label defined in the container and the translation of the current language ("Previous", "Next" and "Finish" in English). The feedback messages use the message of the server or, if there is none, a translated default text.

CSS Custom Properties

Custom property Description Default
--dile-steps-form-header-font-size Font size of the header 1rem
--dile-steps-form-header-color Color of the header --dile-on-background-color or #303030
--dile-steps-form-title-font-weight Font weight of the title in the header 600
--dile-steps-form-feedback-margin-top Margin top of the inline feedback 1rem
--dile-step-next-prev-margin-top Margin top of the navigation buttons 1.5rem
--dile-step-alternative-exit-color Color of the alternative exit action --dile-link-color

The navigation buttons are placed in a row when the step is wider than 420px, and in a column otherwise (container query).

The steps indicator can be customized with the dile-steps CSS custom properties.

Attributes for Styling

Configuration

dile-steps-form and dile-step-form use dile-ajax to make the requests, so they work with the Axios configuration of the rest of the CRUD components.

dile-steps-form demo

The repository includes a complete demo that uses an in-memory API, with validation errors, the alternative exit and a summary step with refreshOnSave.