Feedback Laraform is now in maintenance mode. Read more on our GitHub.

Wizard & Tabs

#Wizard

Wizard breaks down the form into different steps. Let's create a simple profile form that we'll break down into different steps:

          
<?php

namespace App\Forms;

class WizardForm extends \Laraform
{
  public function wizard() {
    return [
      'personal_details' => [
        'label' => 'Personal details',
        'elements' => ['firstname', 'lastname'],
        'buttons' => [
          'previous' => false
        ]
      ],
      'contact_details' => [
        'label' => 'Contact details',
        'elements' => ['email', 'phone'],
        'labels' => [
          'previous' => 'Go back',
          'next' => 'Continue'
        ]
      ],
      'job_history' => [
        'label' => 'Job history',
        'elements' => ['previous_jobs']
      ]
    ];
  }

  public function schema() {
    return [
      'firstname' => [
        'type' => 'text',
        'label' => 'First name'
      ],
      'lastname' => [
        'type' => 'text',
        'label' => 'Last name'
      ],
      'email' => [
        'type' => 'text',
        'label' => 'Email'
      ],
      'phone' => [
        'type' => 'text',
        'label' => 'Phone'
      ]
    ];
  }
}

If you want to learn more about different wizard properties and methods check out wizard$ reference.

Note how Next, Previous and on the last step Finish buttons appear without defining any buttons. This is because these buttons implement a fairly complex logic to deal with validation, submission, etc. which might be too much to understand for a newcomer. Of course these buttons can be disabled by setting wizardControls to false on the form and implement you own solution.

Next Button

Next button's obvious goal is to proceed to the next step. The user however can be limited to do so if the current step has any invalid fields.

There is an option called validateOn which accepts 'step' as a possible value and it can be defined either at the form instance or globally in configuration. If 'step' is presented in this variable the next button will prevent the user to proceed to the next step, if the current one has any invalid fields.

Previous Button

By pressing Previous button the form steps back one step. By default it's disabled if the user is on the first step.

Finish Button

When the user arrives to the last step the Finish button will appear instead of Next. By clicking it, all the elements which weren't validated before are now being validated. In case of an async validation the form will wait for them to finish and determines if it has any invalid elements. If it does the submission aborts and the user is redirected to the first step which contains error. Otherwise it invokes form's .submit() method and submits the form.

If you want to create you own solution for steps check out wizard$ reference.

#Conditional Steps

Conditions can be binded to wizard steps just like to any element, via its conditions property. Each step is represented by an object, where you place the step's properties like label or elements, and this is where conditions is placed too.

The following example demonstrates how Company details can be optional during a registration where the user can check a Register as company checkbox in order to fill out company information:

      
<?php

namespace App\Forms;

class RegistrationForm extends \Laraform
{
  public function wizard() {
    return [
      'personal_details' => [
        'label' => 'Personal details',
        'elements' => ['name', 'register_company']
      ],
      'company_details' => [
        'label' => 'Company details',
        'elements' => ['company_name', 'company_address'],

        // Company details conditions
        'conditions' => [
          ['register_company', true]
        ]
      ],
      'account_details' => [
        'label' => 'Account details',
        'elements' => ['email', 'password'],
      ]
    ];
  }

  public function schema() {
    return [
      'name' => [
        'type' => 'text',
        'label' => 'Name',
        'rules' => 'required'
      ],
      'register_company' => [
        'type' => 'checkbox',
        'text' => 'Register as company'
      ],
      'company_name' => [
        'type' => 'text',
        'label' => 'Company name',
      ],
      'company_address' => [
        'type' => 'text',
        'label' => 'Company address',
      ],
      'email' => [
        'type' => 'text',
        'label' => 'Email address'
      ],
      'password' => [
        'type' => 'text',
        'label' => 'Password'
      ]
    ];
  }
}

#Tabs

Tabs and wizard are fairly similar in most of their aspects except that Tabs do not have controls and neither they are disabled before the user fills out the previous one.

#Creating Tabs

Tabs and wizard are also configured the same way, so instead of repeating ourselves let's just see the same example but using tabs instead of a wizard:

          
<?php

namespace App\Forms;

class TabsForm extends \Laraform
{
  public function tabs() {
    return [
      'personal_details' => [
        'label' => 'Personal details',
        'elements' => ['firstname', 'lastname'],
        'buttons' => [
          'previous' => false
        ]
      ],
      'contact_details' => [
        'label' => 'Contact details',
        'elements' => ['email', 'phone'],
        'labels' => [
          'previous' => 'Go back',
          'next' => 'Continue'
        ]
      ],
      'job_history' => [
        'label' => 'Job history',
        'elements' => ['previous_jobs']
      ]
    ];
  }

  public function schema() {
    return [
      'firstname' => [
        'type' => 'text',
        'label' => 'First name'
      ],
      'lastname' => [
        'type' => 'text',
        'label' => 'Last name'
      ],
      'email' => [
        'type' => 'text',
        'label' => 'Email'
      ],
      'phone' => [
        'type' => 'text',
        'label' => 'Phone'
      ]
    ];
  }
}

#Conditional Tabs

Similarly to wizard steps, tabs can also have conditions. They are defined exactly the same way as wizard step conditions: via conditions property:

      
<?php

namespace App\Forms;

class ProductForm extends \Laraform
{
  public function tabs() {
    return [
      'product_details' => [
        'label' => 'Product details',
        'elements' => ['name', 'description', 'has_gallery']
      ],
      'product_gallery' => [
        'label' => 'Product gallery',
        'elements' => ['gallery'],

        // Product gallery conditions
        'conditions' => [
          ['has_gallery', true]
        ]
      ]
    ];
  }

  public function schema() {
    return [
      'name' => [
        'type' => 'text',
        'label' => 'Product name'
      ],
      'description' => [
        'type' => 'text',
        'label' => 'Product description'
      ],
      'has_gallery' => [
        'type' => 'checkbox',
        'text' => 'Has gallery'
      ],
      'gallery' => [
        'type' => 'gallery',
        'label' => 'Gallery'
      ]
    ];
  }
}