Wizard

A multi-step form wizard with a visual step-progress strip, per-step validation, skippable steps, remote data binding, and structured AJAX submission. All field values are collected across steps and submitted as a single payload that includes a _wizard metadata block.

Registration Wizard (validation & skip)

Three-step registration flow. The Account step requires a username and e-mail before you can continue. The Profile step is optional and can be skipped. The Confirmation step shows a review panel and triggers AJAX submission.

Account

Profile

Confirm

These fields are optional — you can skip this step.

Review your details below, then click Create Account to complete registration.

Your details will appear here when you reach this step.

Wizard output will appear here after submission…

// Build step content using Manhattan Form + Validator
// The Form component handles layout; Validator handles inline field errors.

$step1Form = $m->form('reg-step1-form')
    ->noCsrf()           // Wizard handles CSRF via X-CSRF-Token header
    ->noValidation()     // Validator is attached manually below
    ->formAttr('onsubmit', 'return false')  // Prevent Enter-key submission
    ->field($m->textbox('reg-username')->name('username'), 'Username')
    ->field($m->textbox('reg-email'   )->name('email'),    'Email Address')
    ->field($m->textbox('reg-password')->name('password')->attr('type', 'password'), 'Password');

$step1Validator = $m->validator('reg-step1-form')
    ->field('reg-username', 'Username is required.',                    ['required'])
    ->field('reg-email',    'Please enter a valid email address.',      ['required', 'email'])
    ->field('reg-password', 'Password must be at least 8 characters.',  ['required', ['minLength' => 8]]);

$step1 = (string)$step1Form . (string)$step1Validator;

echo $m->wizard('regWizard')
    ->step('account', 'Account')
        ->icon('fa-user')
        ->content($step1)
        ->useValidator('reg-step1-form')   // delegate validation to Validator
        ->validationMessage('Please fill in all required fields.')
    ->step('profile', 'Profile')
        ->icon('fa-id-card')
        ->content($profileContent)
        ->skippable()
    ->step('confirm', 'Confirm')
        ->icon('fa-check-circle')
        ->content($confirmContent)
    ->submitUrl('/orders/create')
    ->submitText('Create Account')
    ->onComplete('handleComplete')
    ->onStepChange('handleStepChange');

function regWizardComplete(response) {
    m.toaster('appToaster').show(response.message || 'Done!', 'success');
}

function regWizardStepChange(event) {
    // event = { from, to, direction, wizard }
    // return false to cancel navigation
    return true;
}

// Programmatic control
var wiz = m.wizard('regWizard');
wiz.next();              // validate then advance
wiz.prev();              // go back
wiz.skip();              // skip current step (if skippable)
wiz.goTo(2);             // jump to step index 2 (click completed step circle to go back)
wiz.submit();            // trigger final submission
wiz.reset();             // back to step 0, clear data + reset all validators
wiz.getCurrentStep();    // → { index, key, title, skippable, validateFields, validatorFormId, … }
wiz.getData();           // → full payload including _wizard meta-block

Order Wizard (remote data source)

Demonstrates ->dataUrl(): on initialisation the wizard fetches data from the server and pre-populates fields. The submit payload mirrors the structured _wizard metadata so the server knows exactly which steps were completed, skipped, and what data was entered at each step.

Customer

Items

Delivery

Review

Review your order — then click Place Order.

Order summary will appear here.

Order wizard output will appear here…

// Order wizard with 4 steps and remote data source
echo $m->wizard('orderWizard')
    ->step('customer', 'Customer')
        ->icon('fa-user-tie')
        ->content($customerContent)
        ->validateFields(['ord-customer', 'ord-customer-email'])
    ->step('items', 'Items')
        ->icon('fa-box')
        ->content($itemsContent)
        ->validateFields(['ord-product'])
    ->step('delivery', 'Delivery')
        ->icon('fa-truck')
        ->content($deliveryContent)
        ->validateFields(['ord-delivery-date'])
    ->step('review', 'Review')
        ->icon('fa-clipboard-check')
        ->content($reviewContent)
    ->submitUrl('/orders/create')
    ->dataUrl('/orders/formData')   // GET – pre-populate fields
    ->submitText('Place Order')
    ->onComplete('orderWizardComplete');

// Server response from dataUrl:
// { "success": true, "data": { "ord-customer": "Acme Corp", ... } }
// Fields are populated by matching keys to element IDs / name attributes.

// Submission payload sent to submitUrl (JSON):
// {
//   "customer_name": "Acme Corp",
//   "customer_email": "acme@example.com",
//   "product": "widget-a",
//   "quantity": "2",
//   "delivery_date": "2026-04-01",
//   "_wizard": {
//     "id": "orderWizard",
//     "currentStep": "review",
//     "currentStepIndex": 3,
//     "completedSteps": ["customer", "items", "delivery", "review"],
//     "skippedSteps": [],
//     "totalSteps": 4,
//     "stepData": {
//       "customer": { "customer_name": "Acme Corp", ... },
//       "items":    { "product": "widget-a", ... },
//       "delivery": { ... },
//       "review":   {}
//     }
//   }
// }

function orderWizardComplete(response) {
    document.getElementById('order-wizard-output').innerHTML =
        '<strong>Order placed!</strong> Reference: ' + (response.ref || 'N/A');
}

PHP PHP Methods (Fluent)

Method / Property	Parameters	Description
`$m->wizard($id)`	`string`	Create a wizard instance.
`->step($key, $title)`	`string, string`	Add a new step. All following step-scoped calls apply to this step until the next `->step()`.
`->icon($icon)`	`string`	Font Awesome icon for the step circle, e.g. `fa-user` or `fas fa-user`. When omitted the step number is shown.
`->content($html)`	`string`	HTML content rendered inside this step's panel. Place Manhattan form components here.
`->skippable()`	`bool?`	Mark the step as skippable. A "Skip" link appears in the footer. Default: `false`.
`->noReturn()`	`bool?`	Mark the step as non-returnable. Once the wizard advances past this step the user cannot navigate back to it — the Back button and step indicator click are blocked. Default: `false`.
`->validateFields($ids)`	`string[]`	Bespoke validation: array of element IDs or `name` attributes that must be non-empty before advancing. Used when not using a Form + Validator.
`->useValidator($formId)`	`string`	Delegate this step's validation to a Manhattan Validator attached to the `<form>` with the given ID. Takes precedence over `->validateFields()`. The Form component's inline field errors are used; the wizard banner shows the summary message.
`->validationMessage($msg)`	`string`	Override the inline error message shown when required fields are empty.
`->submitUrl($url)`	`string`	URL to POST the wizard payload to on final submission.
`->dataUrl($url)`	`string`	URL to GET initial field values from. Response: `{"success":true,"data":{…}}`.
`->submitMethod($method)`	`string`	HTTP method for submission. Default: `POST`.
`->ajaxSubmit()`	`bool?`	Submit via fetch() AJAX (default: `true`). Pass `false` for a standard form POST.
`->onComplete($fn)`	`string`	Name of a JS function invoked on successful submission. Receives the parsed server response.
`->onStepChange($fn)`	`string`	Name of a JS function called before each step change. Return `false` to cancel navigation.
`->nextText($text)`	`string`	Label for the Next button. Default: `Next`.
`->prevText($text)`	`string`	Label for the Back button. Default: `Back`.
`->skipText($text)`	`string`	Label for the Skip link. Default: `Skip`.
`->submitText($text)`	`string`	Label for the Submit button. Default: `Submit`.
`->showStepCounter()`	`bool?`	Show/hide the "Step X of Y" counter. Default: `true`.

JS JS Methods

Method / Property	Parameters	Description
`m.wizard(id, options?)`	`string, object?`	Get (or init) the wizard instance for the given element ID.
`next()`		Validate the current step then advance to the next. Returns `false` if validation fails.
`prev()`		Go to the previous step (no validation).
`skip()`		Skip the current step (only if it is marked skippable). Returns `false` otherwise.
`goTo(index)`	`number`	Jump to a specific step by zero-based index. Does NOT validate. Completed-step circles are also clickable to navigate back.
`submit()`		Validate the current step then submit the collected payload.
`reset()`		Return to step 0 and clear all collected data.
`getCurrentStep()`		Returns the config object for the active step: `{index, key, title, skippable, noReturn, validateFields}`.
`getData()`		Returns the full payload that would be sent on submission, including the `_wizard` meta-block.
`setFieldValue(fieldId, value)`	`string, any`	Programmatically set a field value (supports Manhattan component wrappers).

EVENT Events

Event Name	Detail	Description
`m:wizard:stepchange`	`{ from, to, direction, wizard }`	Fired on the wizard element before navigation. Call `event.preventDefault()` or return `false` from the `onStepChange` callback to cancel.
`m:wizard:stepchanged`	`{ from, to, direction, wizard }`	Fired after a successful step transition.
`m:wizard:validate`	`{ step, fields }`	Fired when step validation fails. `fields` is an array of invalid input elements.
`m:wizard:submit`	`{ data }`	Fired immediately before the AJAX/form submission. `data` is the full payload.
`m:wizard:complete`	`{ response }`	Fired on a successful submission response.
`m:wizard:error`	`{ error, response }`	Fired when the submission fails (network error or server error).