changed to msf:viewChanged alert, refactor methods, and provided progress bar example

mgildea · mgildea · commit d225443a7bd2 · 2017-06-02T21:47:16.000-07:00
diff --git a/README.md b/README.md
@@ -1,5 +1,9 @@
 # Multi-Step-Form-Js
-Multi Step Form with jQuery validation
+**Multi Step Form with jQuery validation**
+
+* utilizes jquery validation (with or without jquery unobtrusive validation) to validate the form at each step.
+* contains customizable header step classes to distinguish between active, complete, and incomplete steps.
+* triggers custom change events with relevant step data for custom processing (e.g. updating progress bars)
 
 ## Download
 
@@ -11,7 +15,10 @@ npm install multi-step-form-js
 
 ## Demo
 
-View a [jsfiddle here](http://jsfiddle.net/mgildea/ez94n125/17/show/)
+The following demo contains examples for listening to the 'msf:viewChanged' event to update a progress bar as well as defined header step classes to distinguish the current and completed steps.<br><br>
+View a [jsfiddle here](http://jsfiddle.net/mgildea/ez94n125/25/show/)
+
+
 
 ## Setup
 
@@ -23,7 +30,10 @@ and uses optional:<br>
     2. an *.msf-header* element with N required *.msf-step* elements<br>
     3. an *.msf-navigation* element with *.msf-nav-button* buttons; if buttons are not defined they will be generated <br>
 
-Example Html element with multi-step-from (msf) classes.  
+
+
+Example Html element with multi-step-form (msf) classes.  <br>
+As progress is made through each step the 'msf-step-active' and 'msf-step-complete' classes will be added to the element of 'msf-step' class.
 
 ```html
 <head>
@@ -120,7 +130,23 @@ Example Multi-Step-Form-Js initialization using unobtrusive validation
 ```
 
 
+
+Example jquery event listener to update some progress bar with object parameter containing properties: 'currentIndex', 'previousIndex', and 'totalSteps' 
+
+
+```html
+<script type="text/javascript">
+    $(document).on("msf:viewChanged", function(event, data){
+        var progress = Math.round((data.currentIndex / data.totalSteps)*100);
+        $(".progress-bar").css("width", progress + "%").attr('aria-valuenow', progress);
+    });
+
+</script>
+```
+
+
 ## Release History
+* 0.0.9 trigger 'msf:viewChanged' event when displaying a new view
 * 0.0.8 block form submit on enter if nonfinal view
 * 0.0.6 documentation updates
 * 0.0.4 allow parameters for non unobtrusive validation
diff --git a/example/index.html b/example/index.html
@@ -23,6 +23,12 @@
     <div id="wrapper">
 
         <div id="container body-content">
+
+            <div class="progress">
+                <div class="progress-bar progress-bar-success progress-bar-striped" role="progressbar" aria-valuenow="0" aria-valuemin="0" aria-valuemax="100" style="width: 0%">
+                    <span class="sr-only">0% Complete</span>
+                </div>
+            </div>
             <form class="form-horizontal msf">
                 <div class="msf-header">
                     <div class="row text-center">
@@ -108,17 +114,20 @@
                         </div>
 
                         <div class="row">
-                            <div class="col-md- col-md-offset-3">
+                            <div class="col-md-6 col-md-offset-3">
                                 <div class="form-group">
                                      <input id="additional" name="additional" type="text" class="form-control" placeholder="Additional Details"  data-val="true" data-val-required="name is required">    
                                 </div>
                             </div>
                         </div>
+                        
 
 
                     </div>
                 </div>
 
+                
+
                 <div class="msf-navigation">
                     <div class="row">
                         <div class="col-md-3">
@@ -176,8 +185,17 @@
 
         ko.applyBindings(viewModel);
 
+        $(document).on("msf:viewChanged", function(event, data){
+
+           var progress = Math.round((data.currentIndex / data.totalSteps)*100);
+
+            $(".progress-bar").css("width", progress + "%").attr('aria-valuenow', progress);   ;
+        });
+
+
+        $(".msf:first").multiStepForm();
 
-        $(".msf:first").multiStepForm({});
+        
 
     </script>
 
diff --git a/src/multi-step-form.js b/src/multi-step-form.js
@@ -16,8 +16,7 @@
         factory(jQuery);
     }
 }(function ($) {
-
-    "use strict";
+    'use strict';
 
     const msfCssClasses = {
         header: "msf-header",
@@ -28,15 +27,18 @@
         view: "msf-view",
         navigation: "msf-navigation",
         navButton: "msf-nav-button"
-
     };
 
     const msfNavTypes = {
         back: "back",
         next: "next",
         submit: "submit"
 
-    }
+    };
+
+    const msfEventTypes = {
+        viewChanged : "msf:viewChanged"
+    };
 
     $.fn.multiStepForm = function (options) {
         var form = this;
@@ -48,22 +50,43 @@
 
         var settings = $.extend({}, defaults, options);
 
+        //find the msf-content object
         form.content = this.find("." + msfCssClasses.content).first();
 
         if (form.content.length === 0) {
             throw new Error('Multi-Step Form requires a child element of class \'' + msfCssClasses.content + '\'');
         }
 
+        //find the msf-views within the content object
         form.views = $(this.content).find("." + msfCssClasses.view);
 
         if (form.views.length === 0) {
             throw new Error('Multi-Step Form\'s element of class \'' + msfCssClasses.content + '\' requires n elements of class \'' + msfCssClasses.view + '\'');
         }
 
         form.header = this.find("." + msfCssClasses.header).first();
+        form.navigation = this.find("." + msfCssClasses.navigation).first();
         form.steps = [];
 
-        form.navigation = this.find("." + msfCssClasses.navigation).first();
+        form.getActiveView = function() {
+            return form.views.filter(function () { return this.style && this.style.display !== '' && this.style.display !== 'none' });
+        };
+
+        form.setActiveView = function(index) {
+            var view = form.getActiveView();
+            var previousIndex = form.views.index(view);
+
+            view = form.views.eq(index);
+            view.show();
+            view.find(':input').first().focus();
+
+            //trigger the 'view has changed' event
+            form.trigger(msfEventTypes.viewChanged, {
+                currentIndex : index, 
+                previousIndex : previousIndex,
+                totalSteps : form.steps.length
+            });    
+        }
 
         form.init = function () {
 
@@ -133,17 +156,14 @@
                 var view = element,
                     $view = $(element);
 
-                view.init = function () {
-                    if (index === settings.activeIndex) {
-                        $view.show();
-                    }
-                };
-
-
                 $view.on('show', function (e) {
                     if (this !== e.target)
                         return;
 
+                    //hide whichever view is currently showing
+                    form.getActiveView().hide();
+              
+                    //choose which navigation buttons should be displayed based on index of view 
                     if (index > 0) {
                         form.backNavButton.show();
                     }
@@ -156,6 +176,7 @@
                         form.submitNavButton.hide();
                         form.nextNavButton.show();
 
+                        //if this is not the last view do not allow the enter key to submit the form as it is not completed yet
                         $(this).find(':input').keypress(function (e) {
                             if (e.which == 13) // Enter key = keycode 13
                             {
@@ -165,7 +186,7 @@
                         });
                     }
 
-
+                    //determine if each step is completed or active based in index
                     $.each(form.steps, function (i, element) {
                         if (i < index) {
                             $(element).removeClass(msfCssClasses.stepActive);
@@ -175,8 +196,6 @@
                         else if (i === index) {
                             $(element).removeClass(msfCssClasses.stepComplete);
                             $(element).addClass(msfCssClasses.stepActive);
-                            var currentProgress = Math.round((i / form.steps.length)*100);
-                            $(document).trigger('msf:updateProgress', [currentProgress]);    // Trigger an event to notify the progress has changed
                         }
                         else {
                             $(element).removeClass(msfCssClasses.stepComplete);
@@ -189,35 +208,22 @@
                     if (this !== e.target)
                         return;
 
+                    //hide all navigation buttons, display choices will be set on show event
                     form.backNavButton.hide();
                     form.nextNavButton.hide();
                     form.submitNavButton.hide();
                 });
-
-                view.init();
             });
 
+            form.setActiveView(settings.activeIndex);
         };
 
         form.init();
 
-        form.getActiveView = function() {
-            return form.views.filter(function () { return this.style && this.style.display !== '' && this.style.display !== 'none' });
-        };
-
-        form.setActiveView = function(index) {
-            var view = form.getActiveView();
-
-         //   var view = (currentView) ? currentView : form.getActiveView();
-
-            view.hide();
-            form.views.eq(index).show();
-            form.views.eq(index).find(':input').first().focus();
-        }
-
         form.nextNavButton.click(function () {
             var view = form.getActiveView();
 
+            //validate the input in the current view
             if (form.validate(settings.validate).subset(view)) {
                 var i = form.views.index(view);
 
@@ -228,7 +234,7 @@
         form.backNavButton.click(function () {
             var view = form.getActiveView();
             var i = form.views.index(view);
-
+            
             form.setActiveView(i-1);
         });
 
