README

Plugin that allows you to easily implement and configure a wizard system of steps with forms and validations to Winter CMS

Installation

composer require zimudec/wn-wizard-plugin

Usage example

Create a new page and add the "wizard" component. You must configure the url to admit an optional parameter "/:step?", Configure the wizard steps, functions for ajax and the views of each step. Here is a complete example of a page with the implementation and explanatory comments. It can be used as a starting point:

title = "Wizard Example"
url = "/wizard-example/:step?"
layout = "default"
is_hidden = 0

[wizard]
==
<?
function onInit()
{
  // Register and configure list of steps that the wizard component will use
  $this->wizard->steps = [

    // Each of the steps allows you to configure a list of form validations.
    // Once successfully validated, wizard will allow you to go to the next step.
    // The validations will be called from the related ajax request.
    ['step' => 'step1', 'name' => 'Step 1', 'forms' => [
      'onStep1' => [
        'validation' => ['field1' => 'required', 'field2' => 'required'],
        'extra_validation' => function($validator, $fields, $prevValidationsData) {
          // Extra validations
          $errors = $validator->errors();

          // You can optionally avoid performing the extra validations, 
          // if the previous validations are not fulfilled
          if(!$errors->any()){

            // Extra validations that are complex to perform in native array of laravel validations
            if($fields['field1'] != 'hello'){
              $errors->add('field1', 'The value of this field must be "hello"');
            }

            // Return data from here, allows you to use it in any subsequent step
            // For example: this allows you to validate by consulting a data in the database,
            // and reuse it in subsequent steps without having to consult it again
            // This data remains in session during all the steps, until it is revalidated
            return [
              'user' => ['id' => 1, 'names' => 'User', 'lastname' => 'my lastnames'],
            ];
          }
        }
      ]
    ]],
    // By default, when entering a page, the wizard does not validate the previous steps.
    // The "validatePrevSteps" field allows forcing the revalidation of all the previous steps.
    // This is useful when you need to update the data obtained from extra validations.
    ['step' => 'step2', 'name' => 'Step 2', 'validatePrevSteps' => true],
    ['step' => 'step3', 'name' => 'Step 3', 'forms' => [
      'onStep3' => [
        'validation' => ['select' => 'required'],
        'validation_messages' => [
          'select.required' => 'You must choose a value for :attribute field!'
        ],
        'extra_validation' => function($validator, $fields, $prevValidationsData){
        }
      ]
    ]],
    ['step' => 'step4', 'name' => 'Step 4'],
  ];
  
}

function onEnd()
{
  // To include this script, add the tag {% put scripts%} {% endput%} after jquery
  // This script shows and hides errors received from the server. Use bootstrap 4.x classes
  $this->addJs('/plugins/zimudec/wizard/assets/js/wizard.js');

  $wizard = $this['wizard'];

  if($wizard['stepCurrent'] == 'step1'){
    // This only runs when opening the page. At this point, no validations are performed
    $this['example_data'] = 'This is the step 1';
  } 
  elseif( $wizard['stepCurrent'] == 'step2' ){
    // You can get data received from the extra validations, and transfer it to the view
    $this['user'] = $wizard['prevValidationsData']['user'];

    // You can get the values of the fields that have been filled in previous steps
    $this['field2'] = $wizard['fields']['field2'];
    $this['field3'] = $wizard['fields']['field3'];
  }
  elseif( $wizard['stepCurrent'] == 'step3' ){
    $this['selectData'] = [
      ['id' => 1, 'name' => 'Name 1'],
      ['id' => 2, 'name' => 'Name 2'],
      ['id' => 3, 'name' => 'Name 3'],
    ];
  }

  // Set page title
  $this->page->title = $this->page->title . ' - '. $wizard['stepCurrentName'];
}

function onStep1()
{
  // When submitting the form in step1, this function will be executed and the extra validations and validations will be performed
  $data = $this->wizard->formsValidate();

  // Here you can perform any procedure before redirecting.
  // This procedure will only be done 1 time when submitting the form.
  // ...

  // Here the rediction will be made to the next step
  return redirect($data['stepNext']);
}

function onStep2()
{
  $data = $this->wizard->formsValidate();
  return redirect($data['stepNext']);
}

function onStep3()
{
  // By default, only the fields of the current form are validated, and not the previous steps.
  // When adding true as a parameter to the function,
  // will force validation of all previous steps, in addition to the current one.
  // This is useful for committing all the wizard data before doing something important, 
  // like inserting data into the database.
  $data = $this->wizard->formsValidate(true);
  return redirect($data['stepNext']);
}
?>
==
<section>
  {% partial '@nav_header.htm' title=(this.page.title) %}

  {% if wizard.stepCurrent == 'step1' %}

  <div class="text-center">{{ example_data }}</div>
  <form class="mx-auto" style="max-width: 400px;" data-request="onStep1" data-request-validate>
    {{ form_token() }}

    {% partial '@input_text.htm' label="Field 1 *" name="field1" %}
    {% partial '@input_text.htm' label="Field 2 *" name="field2" %}
    {% partial '@input_text.htm' label="Field 3" name="field3" %}

    {% partial '@nav_buttons.htm' %}
  </form>

  {% elseif wizard.stepCurrent == 'step2' %}

  {% partial '@header.htm' text=('Welcome ' ~ user.names) subtitle='This step does not require entering fields' %}
  <form class="mx-auto" style="max-width: 400px;" data-request="onStep2" data-request-validate>
    {{ form_token() }}
    {% partial '@input_text.htm' label="Field 2" value=(field2) readonly=true %}
    {% partial '@input_text.htm' label="Field 3" value=(field3) readonly=true %}
    {% partial '@nav_buttons.htm' %}
  </form>

  {% elseif wizard.stepCurrent == 'step3' %}

  {% partial '@header.htm' subtitle='This is the last step before finish the wizard' %}
  <form class="mx-auto" style="max-width: 400px;" data-request="onStep3" data-request-validate>
    {{ form_token() }}

    {% partial '@input_select.htm' label="Select *" name="select" items=(selectData)  %}
    {% partial '@nav_buttons.htm' %}
  </form>

  {% elseif wizard.stepCurrent == 'step4' %}

  <div class="mt-3 text-center">Wizard Finished. The wizard session was deleted. If you reload the page, it will go back to step1.</div>
  <hr >
  {% partial '@nav_buttons.htm' %}

  {% endif %}
</section>

Using translated customs error messages

When you define your steps, it is also possible to define custom error messages associated with your validations by using validation_messages key.

$this->wizard->steps = [
  [
    'step' => 'step1',
    'name' => 'Step 1',
    'forms' => [
      'onStep1' => [
        'validation' => ['myField' => 'required'],
        'validation_messages' => [
          'myField.required' => 'You must choose a value for :attribute field!'
        ],
        'extra_validation' => function($validator, $fields, $prevValidationsData){}
      ]
    ]
  ],
  // ...
]

If you need to get these messages in different languages, you can use per-language files.
For example, you can create a file per language, in the dedicated directory ./lang/[language key]/zimudec/wizard/validations.php, containing the messages définitions.

// ./lang/en/zimudec/wizard/validations.php
<?php

return [
    'myField_required' => 'You must choose a value for :attribute field!',
];

// ./lang/fr/zimudec/wizard/validations.php
<?php

return [
    'myField_required' => 'Vous devez choisir une valeur pour le champ :attribute !',
];

And then reference those definitions in your steps :

  'validation_messages' => [
    'myField.required' => Lang::get('zimudec.wizard::validations.myField_required')
  ],

If you need to learn more about validation in Winter CMS, check the documentation for Services/validation.

zimudec / wn-wizard-plugin

Maintainers

Details

README

Installation

Usage example

Using translated customs error messages