Smart Wizard 4: Documentation

The awesome jQuery step wizard plugin with Bootstrap support

Smart Wizard 4 is released! Checkout the latest features

Requirements

  1. Bootstrap 3+
  2. jQuery (supports jQuery 1.9+, jQuery 2+, jQuery 3+)

Installation

NPM

npm install smartwizard

Bower

bower install smartwizard

Composer

composer require techlab/smartwizard

Download

Get the latest source files from Github Download

How to use

Include Bootstrap CSS (ignore this if you have already included on the page)

You can use CDN or your own Bootstrap installation
<link href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.6/css/bootstrap.min.css" rel="stylesheet" />

Include SmartWizard CSS

<link href="../css/smart_wizard.css" rel="stylesheet" type="text/css" /> 
Optionally, If you want to use the theme include the corresponding theme css
<link href="../css/smart_wizard_theme_arrows.css" rel="stylesheet" type="text/css" />

Include HTML

This is the basic HTML markup for the Smart Wizard. You can customize it by adding your on steps contents.
<div id="smartwizard">
    <ul>
        <li><a href="#step-1">Step Title<br /><small>Step description</small></a></li>
        <li><a href="#step-2">Step Title<br /><small>Step description</small></a></li>
        <li><a href="#step-3">Step Title<br /><small>Step description</small></a></li>
        <li><a href="#step-4">Step Title<br /><small>Step description</small></a></li>
    </ul>

    <div>
        <div id="step-1" class="">
            Step Content
        </div>
        <div id="step-2" class="">
            Step Content
        </div>
        <div id="step-3" class="">
            Step Content
        </div>
        <div id="step-4" class="">
            Step Content
        </div>
    </div>
</div>

Include jQuery (ignore this if you have already included on the page)

<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>

Include SmartWizard JavaScript source

<script type="text/javascript" src="../js/jquery.smartWizard.min.js"></script>

Call the SmartWizard plugin

<script type="text/javascript">
$(document).ready(function(){
  $('#smartwizard').smartWizard();
});
</script>
That's it! You can see the wizard on the page.
Continue reading to know more about parameters, events and customization.
You can include all the JavaScripts just before the closing </body> tag to improve the page load speed.

Parameter Description:

Parameter Name Description Values Default Value
selected specify the selected step on the first load integer 0
keyNavigation enable/disable key navigation.
left/right keys are used if enabled
true/false true
autoAdjustHeight Automatically adjust content height true/false true
cycleSteps Allows to cycle the navigation of steps true/false false
backButtonSupport Enable the back button support true/false true
useURLhash Enable selection of the step based on url hash true/false true
showStepURLhash Show url hash based on step true/false true
contentURL Specify the ajax content url, setting null will disable ajax contents. If you want to use ajax content only for a specific step just add a data-content-url with the anchor tag of the step header null or a valid url null
disabledSteps an array of step numbers to show as disabled zero based array of step index
ex: [2,4]
[]
errorSteps an array of step numbers to show as error steps zero based array of step index
ex: [2,4]
[]
hiddenSteps an array of step numbers to be hidden zero based array of step index
ex: [2,4]
[]
theme name of the theme to use. Remember to include the theme css also String name of the theme 'default'
transitionEffect Animation effect on step navigation none/slide/fade none
transitionSpeed Number or String 400
toolbarSettings An array with grouped settings for the toolbar

Parameter Name Description Default Value
toolbarPosition Position of the toolbar (none, top, bottom, both) bottom
toolbarButtonPosition Position of the toolbar buttons (left, right) right
showNextButton show/hide a Next button true
showPreviousButton show/hide a Previous button true
toolbarExtraButtons Specify the extra buttons and its events to show on toolbar. []
anchorSettings An array with grouped settings for the anchor

Parameter Name Description Default Value
anchorClickable Enable or disable the click option on the step header anchors true
enableAllAnchors Enable all anchors on load false
markDoneStep Make already visited steps as done true
markAllPreviousStepsAsDone When a step selected by url hash, all previous steps are marked done true
removeDoneStepOnNavigateBack While navigate back done step after active step will be cleared false
enableAnchorOnDoneStep Enable/Disable the done steps navigation true
lang An array with language variables

Parameter Name Description Default Value
next Text for next button next
previous Text for next previous previous

Example: Smart Wizard Initialize with all option parameters

This example shows how to call Smart Wizard using all option parameters, but you can pass the only options that you want to set a different value than the default.
<script type="text/javascript">
  $(document).ready(function() {
      
      // Smart Wizard
      $('#smartwizard').smartWizard({
            selected: 0,  // Initial selected step, 0 = first step 
            keyNavigation:true, // Enable/Disable keyboard navigation(left and right keys are used if enabled)
            autoAdjustHeight:true, // Automatically adjust content height
            cycleSteps: false, // Allows to cycle the navigation of steps
            backButtonSupport: true, // Enable the back button support
            useURLhash: true, // Enable selection of the step based on url hash
            lang: {  // Language variables
                next: 'Next', 
                previous: 'Previous'
            },
            toolbarSettings: {
                toolbarPosition: 'bottom', // none, top, bottom, both
                toolbarButtonPosition: 'right', // left, right
                showNextButton: true, // show/hide a Next button
                showPreviousButton: true, // show/hide a Previous button
                toolbarExtraButtons: [
                    {label: 'Finish', css: 'btn-info', onClick: function(){ alert('Finish Clicked'); }},
                    {label: 'Cancel', css: 'btn-danger', onClick: function(){ $('#smartwizard').smartWizard("reset"); }}
                  ]
            }, 
            anchorSettings: {
                anchorClickable: true, // Enable/Disable anchor navigation
                enableAllAnchors: false, // Activates all anchors clickable all times
                markDoneStep: true, // add done css
                enableAnchorOnDoneStep: true // Enable/Disable the done steps navigation
            },            
            contentURL: null, // content url, Enables Ajax content loading. can set as data data-content-url on anchor
            disabledSteps: [],    // Array Steps disabled
            errorSteps: [],    // Highlight step with errors
            theme: 'dots',
            transitionEffect: 'fade', // Effect on navigation, none/slide/fade
            transitionSpeed: '400'
      });
      
  }); 
</script>

Event Description:

Event Name Description Parameters
leaveStep Triggers when leaving a step.
This is a decision making event. based on its function return value (true/false) the current step navigation can be cancelled.
Object: object of the step anchor element.
Int: Index of the step.
String: Direction of the navigation. ex. forward, backward.
showStep Triggers when showing a step. Object: object of the step anchor element.
Int: Index of the step.
String: Direction of the navigation. ex. forward, backward. It will pass empty string on page load and reset since there is no direction associated.
beginReset Triggers when reset action starts.
This is a decision making event. based on its function return value (true/false) the reset action can be cancelled.
endReset Triggers when reset action ends. String: name of the theme.
themeChanged Triggers when theme is changed.

Example: Event Initialize

<script type="text/javascript">
  $(document).ready(function() {
      // Initialize Smart Wizard 
      $('#smartwizard').smartWizard();
      
      // Initialize the leaveStep event
      $("#smartwizard").on("leaveStep", function(e, anchorObject, stepNumber, stepDirection) {
         return confirm("Do you want to leave the step "+stepNumber+"?");
      });
      
      // Initialize the showStep event
      $("#smartwizard").on("showStep", function(e, anchorObject, stepNumber, stepDirection) {
         alert("You are on step "+stepNumber+" now");
      });

      // Initialize the beginReset event
      $("#smartwizard").on("beginReset", function(e) {
	 return confirm("Do you want to reset the wizard?");
      });
            
      // Initialize the endReset event
      $("#smartwizard").on("endReset", function(e) {
	 alert("endReset called");
      });  
            
      // Initialize the themeChanged event
      $("#smartwizard").on("themeChanged", function(e, theme) {
	 alert("Theme changed. New theme name: " + theme);
      });
      
  }); 
</script>

Programmer in PHP and C# with added interest in jQuery, Bootstrap, HTML and CSS. Believes that the code should be as beautiful as the design.

Comments