- 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.
Demo: https://ui.atk4.org/demos/interactive/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::$buttonPrevious
- 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 “Previous” 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.