class Atk4\Ui\Wizard

Wizard

Wizard is a high-level component, which makes use of callback to track step progression through the stages. It has an incredibly simple syntax for building UI and display a lovely UI for you.

_images/wizard.png

Demo: https://ui.agiletoolkit.org/demos/wizard.php

Introduced in UI v1.4

Basic Usage

Atk4\Ui\Wizard::addStep($title, $callback)
Atk4\Ui\Wizard::addFinish($callback)

Start by creating Wizard inside your render tree:

$wizard = Wizard::addTo($app);

Next add as many steps as you need specifying title and a PHP callback code for each:

$wizard->addStep('Welcome', function (Wizard $wizard) {
    Message::addTo($wizard, ['Welcome to wizard demonstration'])->text
        ->addParagraph('Use button "Next" to advance')
        ->addParagraph('You can specify your existing database connection string which will be used
        to create a table for model of your choice');
});

Your callback will also receive $wizard as the first argument. Method addStep returns WizardStep, which is described below. You can also provide first argument to addStep as a seed or an object:

$wizard->addStep([
    'Set DSN',
    'icon' => 'configure',
    'description' => 'Database Connection String',
], function (Wizard $p) {
    // some code here
});

You may also specify a single Finish callback, which will be used when wizard is complete:

$wizard->addFinish(function (Wizard $wizard) {
    Header::addTo($wizard, ['You are DONE', 'class.huge centered' => true]);
});

Properties

When you create wizard you may specify some of the following options:

property Atk4\Ui\Wizard::$defaultIcon

Other properties are used during the execution of the wizard.

Step Tracking

property Atk4\Ui\Wizard::$stepCallback

Wizard employs Callback to maintain which step you currently are on. All steps are numbered started with 0.

Important

Wizard currently does not enforce step completion. Changing step number in the URL manually can take you to any step. You can also go backwards and re-do steps. Section below explains how to make wizard enforce some restrictions.

property Atk4\Ui\Wizard::$currentStep

When Wizard is initialized, it will set currentStep to a number (0, 1, 2, ..) corresponding to your steps and finish callback, if you have specified it.

property Atk4\Ui\Wizard::$buttonPrev
property Atk4\Ui\Wizard::$buttonNext
property Atk4\Ui\Wizard::$buttonFinish

Those properties will be initialized with the buttons, but some of them may be destroyed by the render step, if the button is not applicable. For example, first step should not have “prev” button. You can change label or icon on existing button.

Code Placement

As you build up your wizard, you can place code inside callback or outside. It will have a different effect on your wizard:

$wizard->buttonNext->icon = 'person';

$wizard->addStep('Step 3', function (Wizard $wizard) {
    $wizard->buttonNext->icon = 'book';
});

Step defines the callback and will execute it instantly if the step is active. If step 3 is active, the code is executed to change icon to the book. Otherwise icon will remain ‘person’. Another handy technique is disabling the button by adding “disabled” class.

WizardStep

class Atk4\Ui\WizardStep
property Atk4\Ui\WizardStep::$title
property Atk4\Ui\WizardStep::$description
property Atk4\Ui\WizardStep::$icon
property Atk4\Ui\WizardStep::$wizard

Each step of your wizard serves two roles. First is to render title and icon above the wizard and second is to contain a callback code.