The Wonderful Wizard of AngularJS

Boy am I diggin’ AngularJS. There are so many cool bits to it. And the bits that don’t exist are fun to build…once you get the hang of it that is. Case in point, a nifty little wizard module. We here at RealCrowd use wizards on a few pages in our app. They are a nice mechanism to guide users thru multi-step or complex tasks. Translating a complex UI component into an AngularJS module can be a bit tricky. But because of the modular approach we’ve taken to development, we were able to develop a fairly robust implementation. For those more interested in code than an dissertation, here is a shortcut to our Github.

I personally have been known to re-invent the wheel from time to time, but when I find a good simple plug-in I like to use it. RealCrowd is also a fan of responsive design and use Twitter Bootstrap. We therefore choose to use the unofficial third-party Bootstrap Wizard Plug-in to base our angular module on. However, the current version was designed for Bootstrap version 2.3.2 and we use version 3.0.0. There needed to be some slight modifications for this to work with 3.0.0. We have forked the current plug-in here with a fix and have also submitted a pull request to the source branch (Update: The fix has now been merged into the source branch).

As with most projects, things seem relatively simple when looking at the high-level view. We just need a directive to apply our wizard plug-in. However, when we consider the nuances of the UI, things get a bit more complex. What about the backward and forward buttons? We want to hide the backward at sometimes and the forward at others. What if we want to validate at each step? What if we want to call a web-service and not move forward until completed? And what if you want to do all these things and not have a bomb or spaghetti code go off? Well lucky for you that bomb already went off for us, so we went back and cleaned-up the mess and came up with what we believe is a nice flexible, straight-forward approach.

Before we get into building this module, it is recommended you have a basic understanding of AngularJS and directives. Things can get a bit technical, but if you understand the basics it should be pretty informative. Now let’s start with some mark-up to define our wizard. The Bootstrap Wizard Plug-in utilizes the official Bootstrap JQuery Tab plug-in, so we just have to include the Bootstrap stylesheets and javascript (note: We are using Bootstrap v3.0.0 which is quite different from the old v.2.3.2. If not using v3.0.0, you’ll have to do a bit of work to translate this):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
    <div ng-app="SampleWizardApp" ng-controller="SampleWizardController">
      <ul class="nav nav-pills">
        <li class="active">
         <a class="active" href="#first" data-toggle="tab">
           <span class="badge">1</span>
           <span>First Step</span>
         </a>
       </li>
       <li>
         <a href="#second" data-toggle="tab">
           <span class="badge">2</span>
           <span>Second Step</span>
         </a>
       </li>
       <li>
         <a href="#last" data-toggle="tab">
           <span class="badge">3</span>
           <span>Last Step</span>
         </a>
       </li>
      </ul>
      <div class="tab-content">
        <div class="tab-pane active" id="first">
          <h2>Enter first step data</h2>
          <div class="form-group">
            <label class="control-label">First Name</label>
            <input name="firstName" class="form-control" type="text" 
              ng-model="user.firstName" />
          </div>
          <div class="form-group">
            <label class="control-label">Last Name</label>
            <input name="lastName" class="form-control" type="text" 
              ng-model="user.lastName" />
          </div>
        </div>
        <div class="tab-pane" id="second">
          <h2>Enter second step data</h2>
          <div class="form-group">
            <label class="control-label">Street Address</label>
            <input name="streetAddress" class="form-control" type="text" 
              ng-model="user.streetAddress" />
          </div>
          <div class="form-group">
            <label class="control-label">City</label>
            <input name="city" class="form-control" type="text" 
              ng-model="user.city" />
          </div>
          <div class="form-group">
            <label class="control-label">State</label>
            <input name="state" class="form-control" type="text" 
              ng-model="user.state" />
          </div>
          <div class="form-group">
            <label class="control-label">City</label>
            <input name="postalCode" class="form-control" type="text" 
              ng-model="user.postalCode" />
          </div>
        </div>
        <div class="tab-pane" id="last">
          <h2>Finish last step</h2>
          <div class="form-group">
            <label class="control-label">First Name:</label>
            <p class="form-control-static">{{ user.firstName }}</p>
          </div>
          <div class="form-group">
            <label class="control-label">Last Name:</label>
            <p class="form-control-static">{{ user.lastName }}</p>
          </div>
          <div class="form-group">
            <label class="control-label">Address:</label>
            <p class="form-control-static">
              {{ user.streetAddress }}
              <br />
              {{ user.city }}, {{ user.state }} {{ user.postalCode }}
            </p>
          </div>
        </div>
      </div>
      <div class="form-group">
        <div class="pull-right">
          <a class="btn btn-default">Back</a>
          <a class="btn btn-primary">Continue</a>
        </div>
      </div>
    </div>

So we basically are starting out with an ordinary tab layout with some buttons at the bottom. To be clear, all of the style classes used are from Bootstrap. When we use custom styling we will prefix our CSS classes with an ‘rc-‘. Because of Bootstrap’s many styling options, our tab control already looks more wizard-y than tab-y. Thanks Bootstrap! Next we need to start our wizard directive to wizard-ify the tabs’ behavior. In our directive we will need a controller to wrap the basic wizard features and track some state. We want to make the state available so we will make the controller available on the scope. This is similar to what we do for the rcSubmit controller (which we describe the ‘why’ and ‘how’ in Advanced AngularJS Form Validation). The start of our wizard looks something like this (A quick note on naming convention for those new to the blog; all our constructs are prefixed with ‘rc’ for ‘RealCrowd’. We use this as a namespace, the same way AngularJS uses ‘ng’):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
    var rcWizardDirective = {
     'rcWizard': function () {
       return {
         restrict: 'A',
         controller: ['$scope', function ($scope) {
 
           var self;
           var wizardElement;
           var wizardOptions = {};
 
           this.currentIndex = 0;
           this.firstIndex = 0;
           this.navigationLength = 0;
 
           this.forward = function () {
             self.onForward();
           };
 
           var onForward = function () {
             wizardElement.bootstrapWizard('next');
           };
 
           this.backward = function () {
             wizardElement.bootstrapWizard('previous');
           };
 
           var onTabChange = function (activeTab, navigation, currentIndex, nextTab) {
 
             self.currentIndex = nextTab;
             self.firstIndex = wizardElement.bootstrapWizard('firstIndex');
             self.navigationLength = wizardElement.bootstrapWizard('navigationLength');
 
             if (!$scope.$$phase) $scope.$apply();
           };
 
           var onTabClick = function (activeTab, navigation, currentIndex, clickedIndex) {
             return false;
           };
 
           var onTabShow = function (activeTab, navigation, currentIndex) {
 
             if (currentIndex > 0) {
               wizardElement
                 .find('.nav li:gt(' + (currentIndex - 1) + ')')
                 .removeClass("success");
               wizardElement
                 .find('.nav li:lt(' + currentIndex + ')')
                 .addClass("success");
             } else {
               wizardElement
                 .find('.nav li')
                 .removeClass("success");
             }
           };
 
           var updateWizard = function (options) {
 
             wizardOptions = options;
 
             if (wizardElement) {
               wizardElement.bootstrapWizard(options);
               self.currentIndex = wizardElement.bootstrapWizard('currentIndex');
               self.firstIndex = wizardElement.bootstrapWizard('firstIndex');
               self.navigationLength = wizardElement.bootstrapWizard('navigationLength');
 
               if (!$scope.$$phase) $scope.$apply();
             }
           };
 
           this.setWizardElement = function (element) {
             wizardElement = element;
             self = this;
             updateWizard({
               'onTabChange': onTabChange,
               'onTabShow': onTabShow,
               'onTabClick': onTabClick
             });
           };
         }],
         compile: function (cElement, cAttributes, transclude) {
           return {
             pre: function (scope, formElement, attributes, wizardController) {
               // put a reference to the wizardcontroller on the scope so we can use some of the 
               // properties in the markup
               scope.rc = scope.rc || {};
               scope.rc[attributes.rcWizard] = wizardController;
             },
             post: function (scope, element, attributes, wizardController) {
               // let the controller know about the element
               wizardController.setWizardElement(element);
               if (!scope.$$phase) scope.$apply();
             }
           };
         }
       }
     }
   };

As you can see we are just applying and configuring the Bootstrap Wizard plug-in to the element and wrapping some of its functionality (namely the ‘forward‘ and ‘backward‘ methods). The forward method is double-wrapped. This will be helpful later on. We also are providing access to some state (i.e. currentIndex, firstIndex, navigationLength) that will also be useful. You may notice we added a handler for the onTabClick events and return false. This is so the user can’t use the tab headings (now step headings) to navigate. Another handler we are using is onTabShow. We do this to add/remove a success CSS style class where appropriate which will allow us do some additional styling (Note: ‘success‘ is a contextual CSS class in Bootstrap). Now we just need to add a couple items to our markup to take advantage of our new directive (also don’t forget the reference to the Bootstrap Wizard plug-in):

1
2
3
    <div ng-app="SampleWizardApp" ng-controller="SampleWizardController" 
      rc-wizard="sampleWizard">
      <ul class="nav nav-pills">

77
78
79
80
81
82
83
84
85
86
87
88
89
      <div class="form-group">
        <div class="pull-right">
          <a class="btn btn-default" 
            ng-click="rc.sampleWizard.backward()"
            ng-hide="rc.sampleWizard.currentIndex > rc.sampleWizard.firstIndex">Back</a>
          <a class="btn btn-primary" 
            ng-click="rc.sampleWizard.forward()"
            ng-show="rc.sampleWizard.currentIndex < rc.sampleWizard.navigationLength">
            Continue
          </a>
        </div>
      </div>
    </div>

Now our wizard is behaving more like a proper wizard. The ‘Back’ and ‘Continue’ buttons not only work, they also hide themselves when they aren’t needed. This is the point where most blogs would probably leave you: with a simple directive that does basically what you want it to do. But that is always annoying because when you go to implement it there are all these practical requirements missing. In the case of this wizard, a big missing piece is validation.

Wizard validation is a bit tricky. At first it may seem easy: just place a form around the wizard and handle it like any other form. However, in a wizard, you don’t want to just validate the wizard as a whole, you want to validate it per step. And until a step is valid you want to prevent navigation to the next step. Luckily we have some experience with form validation and disabling UI while busy that will come in handy here. We will be able to use the rcSubmit controller to tap into the validation process, namely onSubmitComplete. Since we need to validate on each step there will be a rcSubmit controller for every step. In order for our rcWizard controller to be able to handle that, we need to provide a way to track every step:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
    var rcWizardDirective = {
     'rcWizard': function () {
       return {
         restrict: 'A',
         controller: ['$scope', function ($scope) {
 
           var self;
           var wizardElement;
           var wizardOptions = {};
           var steps = []; 
           this.currentIndex = 0;
           this.firstIndex = 0;
           this.navigationLength = 0;
 
           this.addStep = function (step) {              steps.push(step);              if (!step.element || !step.submitController) return;              // if a rcSubmitController is being used, automatically add a _hidden_              // submit button so that               // in order to place an submit button that is still functional it              // has to technically be visible, so instead when place it way off              // screen             jQuery(step.element)               .append('<input type="submit" tabindex="-1"' +                       'style="position: absolute; left: -9999px; width: 1px; height: 1px;" />')               .attr('action', 'javascript:void(0);');              // bind to the submit complete event on the rcSubmitController and              // if the action was successful, trigger a next on the wizard.             step.submitController.onSubmitComplete(function (evt) {               if (evt.success) {                 self.onForward(step);               }             });           };
 
           this.forward = function () {
              var currentStep = (steps.length > self.currentIndex) ?                                steps[self.currentIndex] : null;              if (!currentStep) return;              if (currentStep.submitController) {               currentStep.submitController.submit();             } else {               self.onForward(currentStep);
             }
           };            var onForward = function(currentStep) {              if (currentStep.formController && currentStep.formController.$invalid) return; 
             wizardElement.bootstrapWizard('next');
           };

The addStep method takes in a ‘step‘ object that has useful information such as the step‘s element and its rcSubmit controller if it has one. Using this information we can tap into that step‘s submit logic using onSubmitComplete. Using that, we can now base moving forward in the wizard on the successful completion of a form submission. We can also do some other nifty things to make a better user experience. For instance, if these steps are represented by forms, when can automatically add a hidden submit input so that submit-on-enter behavior works. You’ll note this code is designed to work with or without the rcSubmit controller. We try not to require additional modules unless their functionality is being used.

The rcWizard controller now has methods to properly track our enhanced steps. Next we need code that actually adds the steps to the rcWizard‘s controller. This will involve another new directive, ‘rcStep‘:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
    var rcWizardStepDirective = {
      'rcStep': function () {
        return {
          restrict: 'A',
          require: ['^rcWizard', '?form', '?rcSubmit'],
          link: function (scope, element, attributes, controllers) {
 
            var wizardController = controllers[0];
 
            // find all the optional controllers for the step
            var formController = controllers.length > 1 ? controllers[1] : null;
            var submitController = controllers.length > 2 ? controllers[2] : null;
 
            // add the step to the wizard controller
            var step = wizardController.addStep({ 
              'element': element, 
              'attributes': attributes, 
              'formController': formController,
              'submitController': submitController });
          }
        };
      }
    };

This directive is simple enough. It merely calls the addStep method on the rcWizard controller including the element, and the optional ngFormController and rcSubmit controller. These are optional because they are not always necessary for a basic wizard to function.

That’s enough javascript coding. We now need to update the markup to take advantage of our new functionality:

1
2
3
4
5
6
7
8
    <div ng-app="SampleWizardApp" ng-controller="SampleWizardController"
         rc-wizard="sampleWizard">
      <ul class="nav nav-pills">
        <li class="active">
          <a class="active" href="#first" data-toggle="tab">
            <span>1</span> <span>First Step</span>
          </a>
        </li>

19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
      <div class="tab-content">
        <form class="tab-pane active" id="first" name="firstForm" novalidate rc-submit rc-step>
          <h2>Enter first step data</h2>
          <div class="form-group">
            <label class="control-label">First Name</label>
            <input name="firstName" class="form-control" type="text" 
              ng-model="user.firstName" required />
          </div>
          <div class="form-group">
            <label class="control-label">Last Name</label>
            <input name="lastName" class="form-control" type="text" 
              ng-model="user.lastName" required />
          </div>
        </form>
        <form class="tab-pane" id="second" name="secondForm" novalidate rc-submit rc-step>
          <h2>Enter second step data</h2>
          <div class="form-group">
            <label class="control-label">Street Address</label>
            <input name="streetAddress" class="form-control" type="text" 
              ng-model="user.streetAddress" />
          </div>
          <div class="form-group">
            <label class="control-label">City</label>
            <input name="city" class="form-control" type="text" 
              ng-model="user.city" />
          </div>
          <div class="form-group">
            <label class="control-label">State</label>
            <input name="state" class="form-control" type="text" 
              ng-model="user.state" />
          </div>
          <div class="form-group">
            <label class="control-label">City</label>
            <input name="postalCode" class="form-control" type="text" 
              ng-model="user.postalCode" />
          </div>
        </form>
        <form class="tab-pane" id="last" name="lastForm" novalidate rc-submit rc-step>
          <h2>Finish last step</h2>
          <div class="form-group">
            <label class="control-label">First Name:</label>
            <p class="form-control-static">{{ user.firstName }}</p>
          </div>
          <div class="form-group">
            <label class="control-label">Last Name:</label>
            <p class="form-control-static">{{ user.lastName }}</p>
          </div>
          <div class="form-group">
            <label class="control-label">Address:</label>
            <p class="form-control-static">
              {{ user.streetAddress }}
              <br />
              {{ user.city }}, {{ user.state }} {{ user.postalCode }}
            </p>
          </div>
        </form>
      </div>

All we did was convert all the tab-pane’s from div elements to form elements. We added our rcSubmit and rcStep directives as well. Now each step functions as its own validating form. In the first step we added some required attributes. Now if we attempt to continue to the next step it will not let us move forward until we fill out those fields.

This is all great and does exactly what we want to do. But since we are building based on some pretty cool directives, we can easily add some very helpful features. First, we can use our submission attempt tracking from this blog to highlight error’d fields when the user attempts to move forward too soon. Second, if we have a service call between steps that we need to wait for before moving forward and we want to disable the UI while we do so, we have rcDisabled from this blog. Using all these together we along with a little custom styling (i.e the rc-nav-wizard CSS class), we have an uber-wizard:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
   <div ng-controller="SampleWizardController" 
        rc-wizard="sampleWizard" rc-disabled="rc.firstForm.submitInProgress">
     <ul class="nav rc-nav-wizard">
       <li class="active">
         <a class="active" href="#first" data-toggle="tab">
           <span class="badge">1</span>
           <span>First Step</span>
         </a>
       </li>
       <li>
         <a href="#second" data-toggle="tab">
           <span class="badge">2</span>
           <span>Second Step</span>
         </a>
       </li>
       <li>
         <a href="#last" data-toggle="tab">
           <span class="badge">3</span>
           <span>Last Step</span>
         </a>
       </li>
     </ul>
     <div class="tab-content">
       <form class="tab-pane active" id="first" name="firstForm" 
             rc-submit="saveState()" rc-step novalidate>
         <h2>Enter first step data</h2>
         <div class="form-group"
              ng-class="{'has-error': rc.firstForm.needsAttention(firstForm.firstName)}">
           <label class="control-label">First Name</label>
           <input name="firstName" class="form-control" type="text" required
                  ng-model="user.firstName"/>
         </div>
         <div class="form-group"
              ng-class="{'has-error': rc.firstForm.needsAttention(firstForm.lastName)}">
           <label class="control-label">Last Name</label>
           <input name="lastName" class="form-control" type="text" required
                  ng-model="user.lastName" />
         </div>
       </form>

And there you have it. A nice little wizard module. This is also a great example of how building modular components can really boost future development. As usual, we’ve made a Plunker and the source and examples are available on our Github. (Please note, all solutions presented in this post are based on AngularJS 1.0.8 and Bootstrap 3.0.0)

AngularJS: Automatically Disable Groups of Elements During HTTP Calls…or Any Call

There are many instances where you need to collect data from a user and post it to a service. AngularJS makes this pretty easy using the $http service. However when you are submitting data, your app is in a sort of suspended state. Because of the issue of confusion and multiple submissions, you don’t want the user to interact with certain elements until the submission is complete. So we created what we think is a relatively simple way to disable/block the UI during form submission. If you are less concerned about the “why” and the “how” and just want to see some code, head on over to our GitHub and look at our rcDisabled module.

When developing directives it is sometimes helpful to begin with how you want that directive to be used. If you just start coding the directive, the resulting implementation can be less intuitive. We want a simple way to disable our UI when a form is submitting. Ideally we want to accomplish that with some simple mark-up like so:

   <form name="loginForm" novalidate="" ng-app="LoginApp" ng-controller="LoginController" 
         rc-submit="login()" rc-disabled="rc.loginForm.submitInProgress">
     <div class="form-group" 
          ng-class="{'has-error': rc.loginForm.needsAttention(loginForm.username)}">
       <input class="form-control" name="username" type="text" 
              placeholder="Username" required="" ng-model="session.username" />
       <span class="help-block" ng-show="loginForm.username.$error.required">Required</span>
     </div>
     <div class="form-group" 
          ng-class="{'has-error': rc.loginForm.needsAttention(loginForm.password)}">
       <input class="form-control" name="password" type="password" 
              placeholder="Password" required="" ng-model="session.password" />
       <span class="help-block" ng-show="loginForm.password.$error.required">Required</span>
     </div>
     <div class="form-group">
       <a class="btn btn-primary pull-right">
         Link Action
       </a>
       <span class="pull-right">&nbsp;</span>
       <button type="submit" class="btn btn-primary pull-right" value="Login" title="Login">
         <span>Login</span>
       </button>
     </div>
   </form>

Add here is how we get there…

In one of our earlier posts we explored advanced AngularJS form validation, using a simple login form. This post builds on that. On a login form (or any data entry form for that matter), you usually submit data to a service and wait for a response. Some people handle this by creating a busy flag and manipulating styles or the DOM to disable the interface until a result is returned. We saw two separate problems here: One, we wanted an intuitive way to easily provide this busy state information on any form we were submitting. And Two, a simple way to disable the interface while we were waiting.

The first problem involves tapping into the form submission process. Luckily we already started down this path in our previous blog with the rcSubmit directive. We bind to the form’s submit event then execute the specified method if the form is valid. However this just the beginning of the submit process. If we are calling a service method we need to know when its completed. In AngularJS it is common to use the $http service to call web service methods. This service utilizes promises which can be very useful to us. If we have a promise, we can respond when it is resolved or rejected. At the same time, we don’t want to require the use of promises in every instance. If you don’t need to know when it completes or if your method is synchronous, it still should just work. Bearing all that in mind, here is the resulting rcSubmit directive with our changes:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
   var rcSubmitDirective = {
     'rcSubmit': ['$parse', '$q', '$timeout', function ($parse, $q, $timeout) {       return {
         restrict: 'A',
         require: ['rcSubmit', '?form'],
         controller: ['$scope', function ($scope) {
 
           var formController = null;
           var submitCompleteHandlers = []; 
           this.attempted = false;
           this.submitInProgress = false; 
           this.setAttempted = function() {
             this.attempted = true;
           };
 
           this.setFormController = function(controller) {          
             formController = controller;
           };
 
           this.needsAttention = function (fieldModelController) {
             if (!formController) return false;
 
             if (fieldModelController) {
               return fieldModelController.$invalid && 
                      (fieldModelController.$dirty || this.attempted);
             } else {
               return formController && formController.$invalid && 
                      (formController.$dirty || this.attempted);
             }
           };
 
           this.onSubmitComplete = function (handler) {              submitCompleteHandlers.push(handler);           }; 
           this.setSubmitComplete = function (success, data) {              angular.forEach(submitCompleteHandlers, function (handler) {               handler({ 'success': success, 'data': data });             });           };         }],
         compile: function(cElement, cAttributes, transclude) {
           return {
             pre: function(scope, formElement, attributes, controllers) {
 
               var submitController = controllers[0];
               var formController = (controllers.length > 1) ? controllers[1] : null;
 
               submitController.setFormController(formController);
 
               scope.rc = scope.rc || {};
               scope.rc[attributes.name] = submitController;
             },
             post: function(scope, formElement, attributes, controllers) {
 
               var submitController = controllers[0];
               var formController = (controllers.length > 1) ? controllers[1] : null;
               var fn = $parse(attributes.rcSubmit);
 
               formElement.bind('submit', function () {
                 submitController.setAttempted();
                 if (!scope.$$phase) scope.$apply();
 
                 if (!formController.$valid) return false;
 
                 var doSubmit = function () {                    submitController.submitInProgress = true;                   if (!scope.$$phase) scope.$apply();                    var returnPromise = $q.when(fn(scope, { $event: event }));                    returnPromise.then(function (result) {                     submitController.submitInProgress = false;                     if (!scope.$$phase) scope.$apply();                     // This is a small hack.  We want the submitInProgress                     // flag to be applied to the scope before we actually                     // raise the submitComplete event. We do that by                     // using angular's $timeout service which even without                     // a timeout value specified will not fire until after                     // the scope is digested.                     $timeout(function() {                       submitController.setSubmitComplete(true, result);                     });                    }, function (error) {                     submitController.submitInProgress = false;                     if (!scope.$$phase) scope.$apply();                     submitController.setSubmitComplete(false, error);                   });                 }; 
                 if (!scope.$$phase) {                   scope.$apply(doSubmit);                 } else {                   doSubmit();                   if (!scope.$$phase) scope.$apply();                 }               });
             }
           };
         }
       };
     }]
   };

Starting in the post method, we have wrapped the result of the rcSubmit method using $q.when which gives us a promise no matter what. This allows us to handle the method the same way in all cases: First we set our state flag, submitInProgress. If it’s just a normal non-promisey method, it will execute and when its completed, we will unset the flag. If the method returns a promise, it will wait for the promise to be resolved/rejected and then unset the flag.

We also added a basic event infrastructure for onSubmitComplete. Although we may not use it in this instance, having a way to handle this event may be useful in the future.

On to our second problem. To accomplish the disabling, we first looked at ngDisabled. However, it is only supported directly on elements that support the disabled attribute (i.e. input and button elements). This is understandable but we needed more. We don’t want to have to repeat the same logic on every input/button on the form. In this instance it’s only a few elements, but it can get a little crazy on a more complex input form. In a perfect world, we want to be able to apply the directive on any element and the directive is smart enough to only apply the disabled attribute on the children that support it. Which brings us to ‘rcDisabled‘:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
   var rcDisabledDirective = {
     'rcDisabled': function () {
       return {
         restrict: 'A',
         link: function (scope, element, attributes) {
 
           scope.$watch(attributes.rcDisabled, function(isDisabled) {
             var jqElement = jQuery(rootElement);
 
             return jqElement
                      .find(':not([rc-disabled])')
                      .filter(function(index) {
                        return jQuery(this)
                                 .parents()
                                 .not(jqElement)
                                 .filter('[rc-disabled]').length === 0;
                      })
                     .filter('input:not([ng-disabled]), button:not([ng-disabled])')
                     .prop('disabled', isDisabled);
           });
         }
       }
     }
   };

Great! It does exactly what we wanted: added/removed the disabled attribute from all supported child elements. We even cleverly ignore sub items that are using their own rcDisabled or ngDisabled directive. This allows for more complex scenarios where nested disabling directives might have different logic. Also, you may notice the explicit use of jQuery. AngularJS includes a minimal version of jqLite, however we are using some methods (namely ‘filter‘ and ‘not‘) that are only available in the full version of jQuery. So when using this directive we have to recognize that jQuery is a dependency. Although we still require even more functionality. We here at RealCrowd also use Twitter Bootstrap (which is awesome by the way). And Bootstrap gives us the ability for links/anchors (‘<a>‘) to look and behave like buttons. However links do not support a disabled attribute. Bootstrap was smart about this and added a .disabled CSS class. We could modify our directive to take this into account, but we try to design our directives to be implementation-agnostic when possible. Instead of putting Bootstrap-specific logic in the directive, we want it to be configurable. In AngularJS, when you want something to be configurable, you can use a provider. We therefore created a rcDisabledProvider:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
   var rcDisabledProvider = function () {
 
     var defaultDisableHandler = function(rootElement, isDisabled) {
       var jqElement = jQuery(rootElement);
 
       return jqElement
               .find(':not([rc-disabled])')
               .filter(function(index) {
                 return jQuery(this)
                          .parents()
                          .not(jqElement)
                          .filter('[rc-disabled]').length === 0;
               })
               .filter('input:not([ng-disabled]), button:not([ng-disabled])')
               .prop('disabled', isDisabled);
     };
 
     var customDisableHandler;
 
     this.onDisable = function (customHandler) {
       customDisableHandler = customHandler;
     };
 
     this.$get = function () {
       return {
         disable: function (rootElement, isDisabled) {
           return (customDisableHandler) ? 
                  customDisableHandler(rootElement, isDisabled) : 
                  defaultDisableHandler(rootElement, isDisabled);
         }
       }
     };
   };

For those of you unfamiliar with providers, simply view them as a configurable service with state. In AngularJS you can configure a provider for a module/application and use it in any controllers or directives you want just as you would a service. The methods used for configuring are defined in the root provider function. In this case we have one such method called onDisabled. The actual rcDisabled service instance is defined by the special $get method. For the rcDisabledProvider, the common state is our method for disabling/re-enabling DOM objects. We have a default method that is the same logic as our original rcDisabled directive. However, we also have the option to configure the provider with a custom method using onDisabled. We now need to update the rcDisabled directive to use the rcDisabledProvider:

1
2
3
4
5
6
7
8
9
10
11
12
13
   var rcDisabledDirective = {
     'rcDisabled': ['rcDisabled', function (rcDisabled) {
       return {
         restrict: 'A',
         link: function (scope, element, attributes) {
 
           scope.$watch(attributes.rcDisabled, function(isDisabled) {
             rcDisabled.disable(element, isDisabled);           });
         }
       }
     }]
   };

A quick note on the above code. You’ll notice that the included dependency for the rcDisabledProvider just says ‘rcDisabled‘. The way providers work in AngularJS is they are defined without a ‘Provider‘ suffix just as you would a service. The only time the suffix is used is when you configure it (which we will show below). This may also cause confusion as the directive is also called ‘rcDisabled‘. This doesn’t cause any conflicts in Angular that I’m aware, but admittedly this may not be the best design. I have personally justified it thinking that confusion should not occur often in the actual use of this directive and provider. You will either be placing and rc-disabled attribute on an element or configuring this rcDisabledProvider in the application or module. Hopefully that clears things up.

The directive will now use either the default method or whatever custom method has been defined. If you were to use a custom method as we wish to do for our Bootstrap implementation, you would configure it like so:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
   angular.module('rcDisabledBootstrap', ['rcDisabled'])
   .config(['rcDisabledProvider', function(rcDisabledProvider) {
     rcDisabledProvider.onDisable(function(rootElement, isDisabled) {
       var jqElement = jQuery(rootElement);
 
       return jqElement
               .find(':not([rc-disabled])')
               .filter(function(index) {
                 return jQuery(this)
                          .parents()
                          .not(jElement)
                          .filter('[rc-disabled]').length === 0;
               })
               .filter('input:not([ng-disabled]), button:not([ng-disabled]), .btn, li')
               .add(jqElement)
               .toggleClass('disabled', isDisabled)
               .filter('input, button')
               .prop('disabled', isDisabled);
     });
   }]);

The above code creates an augmented module called ‘rcDisabledBootstrap‘ which just takes in our rcDisabled module and configures it using the rcDisabledProvider. Now our custom method not only toggles the supported disabled attributes, but also toggles the CSS disabled class on appropriate elements. The logic we used to set the disabled class was based on how and where we saw it used in the bootstrap.css file. With this code, we can apply this directive to the following markup:

   <form name="loginForm" novalidate="" ng-app="LoginApp" ng-controller="LoginController" 
         rc-submit="login()" rc-disabled="rc.loginForm.submitInProgress">
     <div class="form-group" 
          ng-class="{'has-error': rc.loginForm.needsAttention(loginForm.username)}">
       <input class="form-control" name="username" type="text" 
              placeholder="Username" required="" ng-model="session.username" />
       <span class="help-block" ng-show="loginForm.username.$error.required">Required</span>
     </div>
     <div class="form-group" 
          ng-class="{'has-error': rc.loginForm.needsAttention(loginForm.password)}">
       <input class="form-control" name="password" type="password" 
              placeholder="Password" required="" ng-model="session.password" />
       <span class="help-block" ng-show="loginForm.password.$error.required">Required</span>
     </div>
     <div class="form-group">
       <a class="btn btn-primary pull-right">
         Link Action
       </a>
       <span class="pull-right">&nbsp;</span>
       <button type="submit" class="btn btn-primary pull-right" value="Login" title="Login">
         <span>Login</span>
       </button>
     </div>
   </form>

This is a relatively simplified example. You may want to change the UI a bit more to better inform the user what is happening. But one of the great things about this directive is that its easily customizable. If you want to do additional DOM manipulation, you can add whatever you want in the configuration. And there you have it; a nice simple group disabler. We have created a Plunker to show this in action and as always the code and examples are available on our GitHub. (Please note, all solutions presented in this post are based on AngularJS 1.0.8 and Bootstrap 3.0.0)

Bonus

If using Bootstrap, you have the additional option of using some of their custom jQuery plug-ins. One of those is the “Button” plug-in which has some functionality that works nicely with the rcDisabled module. Specifically, it is stateful and allows you to define a data-loading-text attribute on your button. Then, using the plug-in, you can toggle the text when the UI is busy. We can make a slight modification to our Bootstrap version of the module and add our attribute to the markup:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
   angular.module('rcDisabledBootstrap', ['rcDisabled'])
   .config(['rcDisabledProvider', function(rcDisabledProvider) {
     rcDisabledProvider.onDisable(function(rootElement, isDisabled) {
       var jqElement = jQuery(rootElement);
 
       jqElement = jqElement
                     .find(':not([rc-disabled])')
                     .filter(function(index) {
                       return jQuery(this)
                                .parents()
                                .not(jqElement)
                                .filter('[rc-disabled]').length === 0;
                     })
                     .filter('input:not([ng-disabled]), button:not([ng-disabled]), .btn, li')
                     .add(jqElement);
 
       // if the Bootstrap "Button" jQuery plug-in is loaded, use it on those       // that have it configured       if (jqElement.button) {         jqElement.find('[data-loading-text]').button((isDisabled) ? 'loading' : 'reset');       } 
       jqElement.toggleClass('disabled', isDisabled)
       .filter('input, button')
       .prop('disabled', isDisabled);
     });
   }]);

16
17
18
19
20
21
22
23
24
25
26
     <div class="form-group">
       <a class="btn btn-primary pull-right">
         Link Action
       </a>
       <span class="pull-right">&nbsp;</span>
       <button type="submit" class="btn btn-primary pull-right" value="Login" title="Login"
         data-loading-text="Please Wait...">
         <span>Login</span>
       </button>
     </div>
   </form>

Now our button text will automatically change when we are in a busy state. Keep in mind that using this plugin adds the additional dependency of the Bootstrap javascript file. Though we have coded it so the module will still fallback if it isn’t loaded. And there you have a nice little bonus.

P.S. RealCrowd is always hiring. If you like what you see and are interested in a job, contact me or JD.