Shaun Xu

The Sheep-Pen of the Shaun


News

logo

Shaun, the author of this blog is a semi-geek, clumsy developer, passionate speaker and incapable architect with about 10 years’ experience in .NET and JavaScript. He hopes to prove that software development is art rather than manufacturing. He's into cloud computing platform and technologies (Windows Azure, Amazon and Aliyun) and right now, Shaun is being attracted by JavaScript (Angular.js and Node.js) and he likes it.

Shaun is working at Worktile Inc. as the chief architect for overall design and develop worktile, a web-based collaboration and task management tool, and lesschat, a real-time communication aggregation tool.

MVP

My Stats

  • Posts - 122
  • Comments - 567
  • Trackbacks - 0

Tag Cloud


Recent Comments


Recent Posts


Archives


Post Categories


.NET


 

In my project I have a feature which needs user to specify a large amount of properties against an object. I though a wizard would be the best solution since it makes the user focus on part of the object in each steps. Then I checked the Internet to see if any existing Angular directives is OK to me. I found this, this and this. All of them are awesome but unfortunately none of them covers all my requirement. So I decided to create my own wizard, and below I would like to introduce how to use it.

 

Features & Demo

Below is the image I recorded. You can check the live demo here.

sx-wizard

I call this directive "sx.wizard" and it supports:

1. Open wizard in a bootstrap modal window.

2. Configure window size, wizard title, etc..

3. Add steps from JavaScript (your angular code not only in controller, but anywhere you like).

4. Specify wizard behaviors in each steps, such as input validation, configure which step will be navigated to when clicked "Next", add more buttons in the bottom, show "Finish" button or not, etc..

 

Install

To use "sx.wizard" you need the following pre-requirements:

1. Bootstrap: You need full package of bootstrap, includes CSS and JavaScript.

2. jQuery: In theory this is not necessary since Angular will inject jQLite if no jQuery installed. But as I've never tested it without jQuery I recommended to install.

3. Angular.js: Just make sure it's Angular 1.x. Angular 2.x is NOT supported right now (and in future I think).

4. UI-Bootstrap: I'm using Angular UI Bootstrap to show a modal window that contains the wizard.

5. Font Awesome: (Optional) I'm using font awesome to display icons for step entering and leaving. But this is not mandatory. The icon will not be shown if you skip this requirement.

 

After that just download and include template and source code of "sx.wizard".

1. Template: https://github.com/shaunxu/angular-toolkits/blob/master/wizard/sx-wizard-tpls.js

2. Source: https://github.com/shaunxu/angular-toolkits/blob/master/wizard/sx-wizard.js

 

Add dependencies in your angular root module.

   1: window.app = window.angular.module('Demo', [
   2:     'ui.bootstrap', 
   3:     'sx.wizard'
   4: ]);

You need to add "ui.bootstrap" as well since I'm using it to open bootstrap modal window.

 

Define Wizard in Controller

In the controller (in fact anywhere in your code), add parameter named "$wizard", which you can define a new instance of wizard, configure and add steps.

   1: app.controller('HomeController', function($scope, $wizard) {
   2:     var wizard = $wizard
   3:         .config({
   4:             title: 'Wizard - by Shaun\'s Angular Toolkits',
   5:             size: 'lg',
   6:             shadow: true,
   7:             successing: function($data, $step, $isLastStep, callback) {
   8:                 return callback(true);
   9:             }
  10:         });
  11: });

Use "config" function to define overall layout and behavior of this wizard. It accepts an object as options with properties listed below.

1. title: Title of the wizard. Default is "Wizard".

2. size: Size of the wizard modal window, same as the option in UI-Bootstrap you can use 'lg', or 'sm'. Default is 'lg'.

3. shadow: Boolean value to determine whether wizard will use a shadow "div" convers on the step area when it's entering or leaving, prevent user click while the step is loading or validating. I will cover this feature later. Default is "true".

4. backdrop: Bootstrap modal options. Default is 'static' which means user cannot dismiss the wizard until clicked "Cancel" button.

5. templateUrl: Specify the template URL of the wizard. "sx-wizard-tpls.js" will be used by default. Note that this is the template of wizard, not the steps.

6. successing: Function which will be invoked when user clicked "Finished" button. This can be used for final validation. The parameters are described as below. In default it will do nothing and close the wizard.

  6.1 $data: Object passed into wizard.

  6.2 $step: The step where user clicked "Finish".

  6.3 $isLastStep: Indicates whether this is the last step.

  6.4: callback: Callback function with a boolean parameter, indicates whether wizard can be closed (valid) or not (invalid).

 

Next, you may need to prepare data which is going to pass into wizard, and user will update it in each steps. For example, in the code below I created an object in $scope with two properties.

   1: $scope.data = {
   2:     username: 'shaun',
   3:     email: 'jfarrio@gmail.com'
   4: };

 

Then you can open wizard with 3 parameters.

1. data: Object which user will update through each steps.

2. success: A function invoked when user completed wizard, with the filled data as the parameter.

  2.1:This method will be invoked only when it passed "successing" function in wizard configuration mentioned above.

  2.2:  Object in parameter is NOT the same one you passed in the first parameter. You can assign it back to the original object. This would be benefit when you don't want wizard to change your original data until user completed.

3. cancel: Function will be invoked when user dismissed the wizard. Usually you don't need to specify it.

   1: $scope.launch = function() {
   2:     wizard.open(
   3:         $scope.data,
   4:         function(result) {
   5:             $scope.result = result;
   6:         },
   7:         window.angular.noop);
   8: };

 

Add First Step

Use "wizard.addStep" to add a step into wizard before open it. You can chain this method with "config" as below.

   1: var wizard = $wizard
   2:     .config({
   3:         ... ...
   4:     })
   5:     .addStep({
   6:         id: 'step-1-welcome',
   7:         title: 'Welcome',
   8:         templateUrl: 'steps/step-01-welcome.html'
   9:     });

I added a step with

1. id: Must be unique in a wizard instance.

2. title: Title of this step. I will use "id" if not specified.

3. templateUrl: Specify the template URL of the step layout. We can use "template" as inline template, too.

The template of this step would be like this.

   1: <p>
   2:   This is the first step of the wizard. 
   3: </p>
   4: <p>
   5:   Below is the initial object we will going to fill in the following steps.
   6: </p>
   7:  
   8: <div class="panel panel-info">
   9:   <div class="panel-heading">
  10:     Data
  11:   </div>
  12:   <div class="panel-body">
  13:     <pre>{{$context.data | json}}</pre> 
  14:   </div>
  15: </div>

Now I can launch the wizard.

image

 

The initial data you passed though "wizard.config" can be retrieved and updated inside each steps, through the variant "$scope.$context.data". In fact, all properties under "$scope.$context" can be visited through all steps. So if you need to pass something in the whole wizard please add them into "$scope.$context".

 

Step Entering: Load Data

Sometimes we need to load some data when a step was entered. And in some cases we need to retrieve them through some external services via "$http". This means the loading operation might be asynchronous. Besides, we don't need load them every time this step was entered. For example, we don't need load them again if user clicked "Previous" button to navigate back.

"sx.wizard" handles this requirement by adding a function in "$scope.$context.behavior.entering" in step's controller. You can perform your logic to load data or any preparation when step is going to be shown. It contains two parameters.

1. options: Information related with this entering operation.

  1.1 fromStepId: The step id which navigated from. It might be "undefined" if this is the first step and in the wizard when it just opened.

  1.2: forward: Indicates whether it's navigated forward (from step defined previously). It only depended on the sequence of step definition.

  1.3: entered: Indicates whether this step had performed "entering". This is useful to prevent from load data again and again when navigated back and forth.

2. callback: Invoke this parameter-less function it indicate the entering operation had been finished. Don't forget to call it even though nothing to do.

 

In the code below I added another step where user can set more properties on "$scope.$context.data". I'm using "$timeout" to simulate asynchronous loading. I checked "options.entered" to make sure data will be loaded only the first time entered, and I called "callback()" even though "options.entered === true" to tell wizard entering is finished.

   1: var wizard = $wizard
   2:     .config({
   3:         ... ...
   4:     })
   5:     .addStep({
   6:         ... ...
   7:     })
   8:     .addStep({
   9:         id: 'step-2-update-data',
  10:         title: 'Update data, entering and validating',
  11:         templateUrl: 'steps/step-02-update-data.html',
  12:         controller: function($scope, $timeout) {
  13:             $scope.$context.behaviour.entering = function(options, callback) {
  14:                 $scope.basicInfoForm.$setPristine();
  15:                 if (options.entered) {
  16:                     return callback();
  17:                 } else {
  18:                     $timeout(function() {
  19:                         $scope.genders = ['Male', 'Female'];
  20:                         $scope.countries = ['China', 'US', 'UK'];
  21:                         return callback();
  22:                     }, 2000);
  23:                 }
  24:             };
  25:         }
  26:     });

The template would be like this.

   1: <p>
   2:   You can update data (add, remove or change properties) in each steps.
   3: </p>
   4: <p>
   5:   It support defines logic for data loading when step entered, as well as validation when leaving.
   6:   Both are in standard JavaScript callback-style.
   7: </p>
   8:  
   9: <form novalidate name="basicInfoForm">
  10:   <div class="form-group">
  11:     <label for="username">Username</label>
  12:     <input type="text" class="form-control" id="username" name="username" ng-model="$context.data.username" required>
  13:     <p class="help-block">Update exising property.</p>
  14:     <p ng-show="basicInfoForm.$submitted" class="text-danger">
  15:       <span ng-show="basicInfoForm.username.$error.required">This field is required.</span>
  16:     </p>
  17:   </div>
  18:   <div class="form-group">
  19:     <label for="email">Email</label>
  20:     <input type="email" class="form-control" id="email" name="email" ng-model="$context.data.email" required email>
  21:     <p class="help-block">Update exising property.</p>
  22:     <p ng-show="basicInfoForm.$submitted" class="text-danger">
  23:       <span ng-show="basicInfoForm.email.$error.required">This field is required.</span>
  24:       <span ng-show="basicInfoForm.email.$error.email">This field must be in email format.</span>
  25:     </p>
  26:   </div>
  27:   <hr>
  28:   <div class="form-group"> 
  29:     <label for="firstName">First name</label>
  30:     <input type="text" class="form-control" id="firstName" name="firstName" ng-model="$context.data.name.firstName">
  31:     <p class="help-block">Specify new property.</p>
  32:   </div>
  33:   <div class="form-group">
  34:     <label for="lastName">Last name</label>
  35:     <input type="text" class="form-control" id="lastName" name="lastName" ng-model="$context.data.name.lastName" required>
  36:     <p class="help-block">Specify new property.</p>
  37:     <p ng-show="basicInfoForm.$submitted" class="text-danger">
  38:       <span ng-show="basicInfoForm.lastName.$error.required">This field is required.</span>
  39:     </p>
  40:   </div>
  41:   <hr>
  42:   <div class="form-group">
  43:     <label>Gender</label>
  44:     <select class="form-control" name="gender" ng-model="$context.data.gender" required>
  45:       <option ng-repeat="gender in genders" value="{{gender}}">{{gender}}</option>
  46:     </select>
  47:     <p class="help-block">Async load options when entered (use <code>$timeout</code> to simulation.</p>
  48:     <p ng-show="basicInfoForm.$submitted" class="text-danger">
  49:       <span ng-show="basicInfoForm.gender.$error.required">This field is required.</span>
  50:     </p>
  51:   </div>
  52:   <div class="form-group">
  53:     <label>Country</label>
  54:     <select class="form-control" name="country" ng-model="$context.data.contry" required>
  55:       <option ng-repeat="contry in countries" value="{{contry}}">{{contry}}</option>
  56:     </select>
  57:     <p class="help-block">Async load options when entered (use <code>$timeout</code> to simulation.</p>
  58:     <p ng-show="basicInfoForm.$submitted" class="text-danger">
  59:       <span ng-show="basicInfoForm.country.$error.required">This field is required.</span>
  60:     </p>
  61:   </div>
  62: </form>

Now let start this wizard you can click "Next" to navigate to this step.

image

When wizard is performing step's entering logic, there will be an icon pulsing to prevent user touch the step UI, since at this point the UI may contain some invalid or partial data which might cause some errors.

You can remove this feature by setting "shadow = false" in "wizard.config()". If so there will be no icon and user can touch step UI even during entering phase.

Also the navigation buttons will also be disabled except "Cancel".

Once the entering function finished (developer called "callback()") the icon will be disappeared, user can use this step and navigation buttons will be enabled.

image

 

Step Leaving: Validation

In this step I have some input fields where user can specify more properties against the initial data stored in "$scope.$context.data". When user leave this step we need to validate. This can be done by using another function in step's controller name "$scope.$context.behavior.leaving".

Similar as "$scope.$context.behavior.entering", this method will be invoked when a step is going to be left, with the parameters as below.

1. options: Information related with this leaving operation.

  1.1 toStepId: Step id that is going to be navigated to.

  1.2 forward: Indicates whether it's navigated forward (from step defined previously). This might be useful when you don't want to perform validation when user click "Previous" button.

2. callback: Invoke this function it indicate the leaving operation had been finished, with a boolean parameter indicates whether this step can be left or not. You can put validation result as the parameter so user cannot move forward if any input were wrong. Don't forget to call it even move backward (options.forward === false).

 

Below is the code I put in this step for validation. I'm using "$timeout" to simulate asynchronous validation. Note that I checked "options.forward" so that the validation will only be invoked when moving forward. And note that I also called "callback(true)" even moving backward to make sure the step can be left.

   1: var wizard = $wizard
   2:     .config({
   3:         ... ...
   4:     })
   5:     .addStep({
   6:         ... ...
   7:     })
   8:     .addStep({
   9:         id: 'step-2-update-data',
  10:         title: 'Update data, entering and validating',
  11:         templateUrl: 'steps/step-02-update-data.html',
  12:         controller: function($scope, $timeout) {
  13:             $scope.$context.behaviour.entering = function(options, callback) {
  14:                 ... ...
  15:             };
  16:             $scope.$context.behavior.leaving = function(options, callback) {
  17:                 if (options.forward) {
  18:                     $timeout(function() {
  19:                         $scope.basicInfoForm.$setSubmitted();
  20:                         return callback($scope.basicInfoForm.$valid);
  21:                     }, 2000);
  22:                 } else {
  23:                     return callback(true);
  24:                 }
  25:             };
  26:         }
  27:     });

"sx.wizard" shows icon as well when performing step leaving if you specified "shadow = true". Same as when step was being entered.

image

If the validation was failed you cannot leave this step.

image

But you can click "Previous" button even though errors in this step. This is because I just perform validation when "options.forward === true".

 

Customize Next and Finish Buttons

Sometimes we want to customize "Next" button and "Finish" button. For example, when user provide contact information in a wizard, she might need skip "additional information" step if checked  "No additional information needed" box on in "basic information" step. Or, she might need to be able to click "Finish" button to save this contact if checked "No further information needed" on.

In "sx.wizard" you can configure which step will be navigated when user clicked "Next", as well as whether the "Finish" button will be shown, through two properties in "$scope.$context.navigation".

1. nextStepId: Return the step id when user clicked "Next" button.

2. showFinish: Indicates whether "Finish" button will be shown. Note that if this is the last step in wizard, "Finish" button will always be shown.

In order to demonstrate I added three steps in wizard.

   1: var wizard = $wizard
   2:     .config({
   3:         ... ...
   4:     })
   5:     .addStep({
   6:         ... ...
   7:     })
   8:     .addStep({
   9:         ... ...
  10:     }
  11:     .addStep({
  12:         id: 'step-3-config-next',
  13:         title: 'Configure the "Next" button behavior',
  14:         templateUrl: 'steps/step-03-config-next.html',
  15:         controller: function($scope) {
  16:             $scope.skipTemplateStep = false;
  17:  
  18:             $scope.$watch('skipTemplateStep', function(skipTemplateStep) {
  19:                 $scope.$context.navigation.nextStepId = skipTemplateStep ? 'step-6-summary' : null;
  20:             });
  21:         }
  22:     })
  23:     .addStep({
  24:         id: 'step-4-step-template',
  25:         title: 'Specify step layout with inline HTML',
  26:         template: '<p>Besides <code>templateUrl</code> you can specify step\'s layout by using inline HTML with <code>template</code>.</p>'
  27:     })
  28:     .addStep({
  29:         id: 'step-6-summary',
  30:         title: 'Summary',
  31:         templateUrl: 'steps/step-06-summary.html'
  32:     });

The layout of step 3 would be like this. I added two input fields in UI. The 'Next" and "Finish" button will be changed based on user's input.

When user checked the first box on, it will go to the last step "step-6-summary". Otherwise it will returned "null" which make "Next" button perform default action, go to next step.

   1: <div class="panel panel-default">
   2:     <div class="panel-body">
   3:         <p>You can specify which step will be navigated when user clicks "Next" button in your step's controller.</p>
   4:         <div class="checkbox">
   5:           <label>
   6:             <input type="checkbox" ng-model="skipTemplateStep"> Skip next step: Specify step layout in template.
   7:           </label>
   8:           <p class="help-block">Check this box on and press "Next" you will skip the next step.</p>
   9:           <p class="help-block">Note the the "Previous" button is smart enough to back to the previous step you visited.</p>
  10:         </div>
  11:     </div>
  12: </div>
  13:  
  14: <div class="panel panel-default">
  15:     <div class="panel-body">
  16:         <p>You can specify whether the "Finish" button should be shown.</p>
  17:         <div class="checkbox">
  18:           <label>
  19:             <input type="checkbox" ng-model="$context.navigation.showFinish"> Show finish button in this step.
  20:           </label>
  21:           <p class="help-block">Check this box on you will see "Finish" button.</p>
  22:           <p class="help-block">Wizard will show "Finish" button on its last step even though you spcified not to show.</p>
  23:         </div>
  24:     </div>
  25: </div>

When user checked the second box on, "Finish" button will be shown.

image

 

Add More Navigation Buttons

The default navigation buttons (previous, next, finish and cancel) may not be enough in all cases. Developer may need provide more options to user. Sample example, in "basic information" step we might want allow user to input additional information by clicking "Next", allow user go to "relationship step" by clicking "Select Relations" button, allow user go to "attachments step" by clicking "Add Attachments" and allow user to save the contact right now by clicking "Finish".

"sx.wizard" supports adding navigation buttons in step's controller via "$scope.$context.navigation.buttons". It's an array contains button objects displayed in this step with the properties of each button object.

1. text: Text shown as the button caption.

2. stepFn: A function which return the step id you want to navigate when user clicked.

 

Below is the step that have three buttons added.

   1: var wizard = $wizard
   2:     .config({
   3:         ... ...
   4:     })
   5:     .addStep({
   6:         ... ...
   7:     })
   8:     .addStep({
   9:         ... ...
  10:     }
  11:     .addStep({
  12:         ... ...
  13:     })
  14:     .addStep({
  15:         ... ...
  16:     })
  17:     .addStep({
  18:         id: 'step-5-customize-navigation',
  19:         title: 'Customize navigation buttions',
  20:         templateUrl: 'steps/step-05-custmize-nav.html',
  21:         controller: 'wizardStepCustmizeNavCtrl'
  22:     })
  23:     .addStep({
  24:         ... ...
  25:     });

The controller code was defined in a separated function as below. User will go to the first step when clicking the first button, go to the last step when clicking the second and the third one will lead user to step which she selected from UI.

   1: app.controller('wizardStepCustmizeNavCtrl', function($scope) {
   2:     $scope.steps = [];
   3:  
   4:     window.angular.forEach($scope.$context.steps, function(step, id) {
   5:         if (id !== $scope.$context.currentStepId) {
   6:             $scope.steps.push(step);
   7:         }
   8:     });
   9:  
  10:     $scope.$context.navigation.buttons = [{
  11:         text: 'Go First',
  12:         stepFn: function() {
  13:             return $scope.steps[0].id;
  14:         }
  15:     }, {
  16:         text: 'Go Last',
  17:         stepFn: function() {
  18:             return $scope.steps[$scope.steps.length - 1].id;
  19:         }
  20:     }, {
  21:         text: 'Go Dynamic',
  22:         stepFn: function() {
  23:             return $scope.targetStepId;
  24:         }
  25:     }, ];
  26: });

Below is the layout of this step.

   1: <p>You can specify more buttons in the navigation in your step's controller.</p>
   2: <p>Below we have 3 buttons</p>
   3: <ul>
   4:   <li>The first one will navigate to the welcome step (first step).</li>
   5:   <li>The second one will navigate to the summary step (last step).</li>
   6:   <li>The thrid one is dynamical, it will navigate to the step you selected.</li>
   7: </ul>
   8: <p>Also note that the controller of this step was defined in a separeated file with the controller name specified.</p>
   9:  
  10: <div class="form-group">
  11:   <label>3rd buttons targeting step</label>
  12:   <select class="form-control" name="targetStepId" ng-model="targetStepId">
  13:     <option ng-repeat="step in steps" value="{{step.id}}">{{step.title}}</option>
  14:   </select>
  15:   <p class="help-block">Select one step and click "Go Dynamic" button in navigation will lead you to that step.</p>
  16: </div>

When you navigated to this step you will find three buttons on the left side of navigation. They will go to steps you defined in your code.

image

 

Step Template & Controller

You may noticed that in one of step I defined the template as inline string rather than the URL. "sx.wizard" supports define step template using inline HTML or URL. It will check if "step.template" was defined. If so it will use the value as template, otherwise it will try to load the content from the address in "step.templateUrl".

image

Besides you can specify step controller as an inline anonymous function, or the name of the controller defined in your angular module.

image

 

Summary

There are many implementation of angular wizard directives as I mentioned at the beginning of this post. But I don't think I reinvented the wheel. "sx.wizard" provides some new features.

1. Wizard is defined and launched from angular factory named "$wizard" which means you can use it in any where in your code, controllers, directives and services.

2. You specify template and controller for each steps separately, which is clear, and can be used in other wizards.

3. Handling step entering and leaving event where you can organize your data loading and validation code better. Both of them are designed for asynchronous operations.

4. Customize navigation buttons in each step. You can change which step will be navigated when user clicked "Next", you can add more buttons, and you can specify whether the "Finish" button should be shown in each step's controller.

5. Step template can be defined inline or through URL, controller can be inline or through the name.

 

"sx.wizard" is published under MIT license. So feel free to use it in your projects. Any issues, comments or suggestion please raise. Also I would like to dig into its source code to explain how I implemented in the future.

 

Hope this helps,

Shaun

All documents and related graphics, codes are provided "AS IS" without warranty of any kind.
Copyright © Shaun Ziyan Xu. This work is licensed under the Creative Commons License.

 

In my project I'm using SignalR and Angular.js to make the page real-time. But I found a slightly problem. It's a little bit hard to notice user when something changed if there are a lot of fields in the page. Hence I decided to create a small directive which will apply highlight style when it the model value was changed.

 

Below is how it looks like. And you can play with it on my Plunker.

ezgif.com-optimize (1)

Step 1

Download and include the source code of this directive from Github.

 

Step 2

Add dependency to your Angular.js application. Just like the code in Plunker.

   1: var app = angular.module("Demo", ['sx.changeHighlight']);

 

Step 3

Apply this directive in any element you want. It will apply the "text-shadow" style for this element. Also need to specify which value in $scope it will be watching, which means when the value was changed, it will apply highlight style on this element.

In the code below my directive is monitoring $scope.name and when it's changed, the "p" element will apply highlight style.

   1: <p sx-change-highlight ng-model="name">
   2:   Hello, my name is {{name}}.
   3: </p>

It's worth mentioning that you can monitor on anything in $scope, regardless whether it will be displayed in the content your directive was attached or in your page. And besides, you can apply this directive in any element.

In the code below, I applied this directive in a table row.

   1: <td sx-change-highlight ng-model="target.status" ng-class="getStatusTextClass(target.status)">{{target.status | jobStatus}}</td>

 

Step 4 (Optional)

There are some options you can define for the highlight style listed below.

Attribute Description Default Value
timeout How long the highlight style will be faded out. 1 second.
interval Interval highlight style will be faded out from highlight style to normal style. 0.1 second.
skip How many times it will NOT apply highlight style when model changed. This is useful if it's changed when page loaded. 1
blurRadius The redius value of "text-shadow" style. 10
color The highlight color. #337ab7

 

Hope this helps,

Shaun

All documents and related graphics, codes are provided "AS IS" without warranty of any kind.
Copyright © Shaun Ziyan Xu. This work is licensed under the Creative Commons License.