Skip to main content

Wizards

When you have a large or complex form, the best user experience is to turn it into a multi step wizard so they can fill out bits of information at a time. Follow these best practices to streamline wizards.

Component structure​

There should be one parent component, and a child component for each step/nested view. The job of the parent is to handle the routing between steps, and the children can focus on their individual step's form logic.

In the above file structure, step 1 has nested views. These views will still be managed by the parent however, so we keep them at the same level as the main steps even though they will appear nested in step 1's breadcrumbs.

One Form per Step​

Rather than trying to connect all the steps together under 1 BwForm, give each step it's own form and emit the final object on form submission. This avoids complications with trying to validate steps when they are not visible in the dom.

State Management​

Utilize BwSession's for keeping track of the user's progress through the wizard. The parent component will open a session, and will wait to close it until the user completes the final step. Some benefits to this approach is:

  1. Avoids spaghetti code from trying to keep all the values in memory.
  2. Users progress will not be lost if they refresh the page or leave and come back later. You have to explicitly close the session for the progress to be lost.
  3. BwSession's are not permanent, they are tied to sessionStorage. You get a little bit of persistence without needing to mantain storage.

Full Example​

This is a rough example showcasing wizards and sessions

Note: For brevity, each step is directly inside the ng-template, but in production you should put them in their own components to keep the parent clean.

import { CurrencyPipe, NgTemplateOutlet } from '@angular/common';
import { Component, CUSTOM_ELEMENTS_SCHEMA, ElementRef, signal, viewChild, ViewEncapsulation } from '@angular/core';
import { toSignal } from '@angular/core/rxjs-interop';
import { closeSession, createDialog, openSession } from 'bluewater'
import { OverlayDirective } from "bluewater-angular";
import { combineLatest } from 'rxjs';

@Component({
    selector: 'app-root',
    imports: [NgTemplateOutlet, OverlayDirective, CurrencyPipe],
    templateUrl: './app.html',
    styleUrl: './app.css',
    schemas: [CUSTOM_ELEMENTS_SCHEMA],
    encapsulation: ViewEncapsulation.None
})
export class App {
    step = signal(0)
    session = openSession('WizardExample')
    wizardComp = viewChild<ElementRef<HTMLBwWizardElement>>('wiz')
    products = toSignal(this.session.get<{name: string,price:number}[]>('products'))

    addProduct(data: any) {
        const products = this.products() ?? []
        this.session.set('products', [...products, data]).subscribe(() => {
            this.step.set(1)
        })
    }

    async done() {
        const res = await firstValueFrom(combineLatest({
            step1: this.session.get('step1'),
            step2: this.session.get('step2'),
            step3: this.session.get('step3')
        }))
        createDialog({
            header: 'Wizard complete!',
            message: JSON.stringify(res)
        }).present()
        closeSession(this.session).subscribe()
    }
}