yii2-form-wizard ¶

1. Features
2. Installation
3. Usage
4. Contributing

A Yii2 form-wizard widget for bootstrap 5

Features ¶

• Bootstrap 5
• Client side validation, with the option to validate each step separately

Installation ¶The preferred way to install this extension is through composer.
Either run
php composer.phar require --prefer-dist sandritsch91/yii2-form-wizard

or add
"sandritsch91/yii2-form-wizard": "*"

to the require section of your composer.json
Usage ¶use sandritsch91\yii2-form-wizard\FormWizard;

echo FormWizard::widget([
// required
'model' => $model, // The model to be used in the form
'tabOptions' => [ // These are the options for the Bootstrap Tab widget
'items' => [
[
'label' => 'Step 1', // The label of the tab, if omitted, a default-label will be used (Step 1, Step 2, ...)
'content' => $this->render('_step1', ['model' => $model]), // Either the content of the tab
],
[
'label' => 'Step 2',
'view' => '/test/_step2', // or a view to be rendered. $model and $form are passed to the view
'params' => ['a' => 1, 'b' => 2] // Pass additional parameters to the view
]
],
'navType' => 'nav-pills'
],
// optional
'validateSteps' => [ // Optional, pass the fields to be validated for each step.
['name', 'surname'],
[], // Leave array empty if no validation is needed
['email', 'password']
],
'options' => [], // Wizard-container html options
'formOptions' => [], // Form html options
'buttonOptions' => [ // Button html options
'previous' => [
'class' => ['btn', 'btn-secondary'],
'data' => [
'formwizard' => 'previous' // If you change this, make sure the clientOptions match
]
],
'next' => [...],
'finish' => [...]
],
'clientOptions' => [ // Client options for the form wizard, if you need to change them
// 'finishSelector' => '...',
// 'nextSelector' => '...',
// 'previousSelector' => '...',
// 'keepPosition' => true // Keep scroll position on step change.
// Set to false to disable, or pass a selector if you have a custom scroll container.
// Defaults to true.
],
'clientEvents' => [ // Client events for the form wizard
// 'onNext' => 'function () {...}',
// 'onPrevious' => 'function () {...}',
// 'onFinish' => 'function (){...}'
]
]);

Contributing ¶Contributions are welcome.
If you have any questions, ideas, suggestions or bugs, please open an issue.
Testing ¶This package uses codeception for testing. To run the tests, run the following commands:

#### Unit tests

run ```php.exe .\vendor\bin\codecept run Unit``` in the root directory of this repository.

#### Functional tests

run ```php.exe .\vendor\bin\codecept run Functional``` in the root directory of this repository.

#### Accpetance tests

To be able to run acceptance tests, a few requirements are needed:

For Windows:\

- install java runtime environment
- install nodejs
- install selenium-standalone: `npm install -g selenium-standalone`
- start selenium-standalone: `selenium-standalone install && selenium-standalone start`
- host a yii2 application on a server or locally via ```./yii serve```
- add this plugin as a dependency to your ```composer.json``` and update dependencies
- site must be reachable over http://formwizard.com/
- add an action ```actionTest``` to the ```SiteController```, as described below
- this action must return a view file, as described below
- run ```php.exe .\vendor\bin\codecept run Acceptance```

For Linux:
Never did that before, but I think it is similar to the Windows setup.

The action in the SiteController:

```php
public function actionTest(): string
{
include __DIR__ . '/../vendor/sandritsch91/yii2-widget-form-wizard/tests/Support/Data/models/User.php';

$model = new User();

if (Yii::$app->request->post() && $model->load(Yii::$app->request->post()) && $model->validate()) {
return 'success';
}

return $this->render('test', [
'model' => new User()
]);
}
```

The view returned by the action:

```php
/** @var User $model */

use sandritsch91\yii2\formwizard\FormWizard;
use sandritsch91\yii2\formwizard\tests\Support\Data\models\User;

$wizard = FormWizard::widget([
'model' => $model,
'tabOptions' => [
'options' => [
'class' => 'mb-3'
],
'items' => [
[
'label' => 'Step 1',
'view' => '@app/vendor/sandritsch91/yii2-widget-form-wizard/tests/Support/Data/views/site/step1',
'linkOptions' => [
'id' => 'step1-link',,
'params' => [
'test' => 'some test variable'
]
]
],
[
'label' => 'Step 2',
'view' => '@app/vendor/sandritsch91/yii2-widget-form-wizard/tests/Support/Data/views/site/step2',
'linkOptions' => [
'id' => 'step2-link',
]
],
[
'label' => 'Step 3',
'view' => '@app/vendor/sandritsch91/yii2-widget-form-wizard/tests/Support/Data/views/site/step3',
'linkOptions' => [
'id' => 'step3-link',
]
]
],
'navType' => 'nav-pills'
],
'validateSteps' => [
['firstname', 'lastname'],
['username', 'password', 'password_validate'],
['email']
],
'clientOptions' => [
'keepPosition' => true
]
]);

echo \yii\helpers\Html::tag('div', $wizard, [
'class' => 'col-4'
]);
```

After the initial installation, you only have to start the selenium-standalone server ```selenium-standalone start```
and run the tests ```php.exe .\vendor\bin\codecept run Acceptance``` in the root directory of this repository.

If you do not want to setup an application, just run the unit and functional tests by
running ```php.exe .\vendor\bin\codecept run Unit,Functional```, I can modify and run the acceptance tests for you,
after you opened a pull request.