The Sheep-Pen of the Shaun

News

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.

Image Galleries

.NET

Today when I upgraded my application from Angular.js 1.3.9 to the latest 1.4, I got some bugs. After investigated a bit I found they are related with date properties and "angular.merge" function, which was included in 1.4.

In the official document, "angular.merge" is

Deeply extends the destination object "dst" by copying own enumerable properties from the "src" object(s) to "dst".

It also mentioned the different with "angular.extend", which had been included in previous versions.

Let's have a look on a very simple example. In code below I have a source object and custom object defined in scope. And I used "angular.extend" to copy custom object into source.

1: $scope.source = {

2: name: 'Shaun',

3: age: 35,

4: birthDate: new Date(1997, 5, 27),

5: skills: {

6: dotNet: {

7: level: 'expert',

8: years: 10

9: },

10: javaScript: {

11: level: 'newbie',

12: years: 2

13: }

14: },

15: mvp: [

16: 2011,

17: 2012,

18: 2013,

19: 2014,

20: 2015

21: ]

22: };

23:

24: $scope.custom = {

25: name: 'Ziyan',

26: age: 35,

27: skills: {

28: dotNet: {

29: level: 'hero',

30: years: 100,

31: active: true

32: },

33: },

34: mvp: [

35: 2016

36: ]

37: };

38:

39: $scope.extend = angular.extend({}, $scope.source, $scope.custom);

From the result we can see, since "angular.extend" performs shallow copy, primitive value property such as "name", "age" and "bitrhDate" are merged. But since "skills" and "mvp" are object and array, "angular.extend" will just copy the entire value, rather than their members.

Now let's using "angular.merge".

1: $scope.merge = angular.merge({}, $scope.source, $scope.custom);

Now we can see, when using "angular.merge", it will copy object properties recursively.

Everything looks great till now. But someone may find when using "angular.merge", one of the property, "birthDate" was been set as am empty object.

If we deep into the source code of Angular.js we will find, both "angular.extend" and "angular.merge" are invoking an internal function named "baseExtend". It merges objects to destination object, with a flag parameter indicates whether it's a deep merge or not.

Inside this function, it loops each enumerable properties, try to copy the value to destination object. If the source property is an object and need to be deeply copied, Angular.js will create an empty object in destination and perform this function against this property recursively.

1:function baseExtend(dst, objs, deep) {

2:var h = dst.$$hashKey;

3:

4:for (var i = 0, ii = objs.length; i < ii; ++i) {

5:var obj = objs[i];

6:if (!isObject(obj) && !isFunction(obj)) continue;

7:var keys = Object.keys(obj);

8:for (var j = 0, jj = keys.length; j < jj; j++) {

9:var key = keys[j];

10:var src = obj[key];

11:

12:if (deep && isObject(src)) {

13:if (!isObject(dst[key])) dst[key] = isArray(src) ? [] : {};

14: baseExtend(dst[key], [src], true);

15: } else {

16: dst[key] = src;

17: }

18: }

19: }

20:

21: setHashKey(dst, h);

22:return dst;

23: }

It works in almost all cases but Date. If we have a Date property defined, for example "birthDate", it will check if this property is an object by using "angular.isObject" and it will return "true". So it will create a property named "birthDate" in destination with an empty object, and invoke "baseExtend" against "birthDate". But since "birthDate" is a Date which is no enumerable property, so it will not assign any data. This is the reason we found in result, "birthDate" property is empty.

If I copied Angular.js "baseExtend" function to my scope, and changed the code as below, which will perform simple copy when the property is Date, it will work.

Directive is very powerful in Angular.js. I would like call it "User Control for Web". When I'm writing sx.wizard, sx.highlight and sx.tabs, I was using directives. And in directive, one of the most important concept is isolated scope.

Shared Scope

Let's start with an example. Assuming I have an Angular.js application. I have a controller contains an object, and display the content in the page. The code is very simple.

1:<bodyng-app="Demo">

2:<divclass="panel panel-info"ng-controller="HomeCtrl">

3:<divclass="panel-heading">Home Controller</div>

4:<divclass="panel-body">

5:<pre>{{person | json}}</pre>

6:

7:<hr>

8:</div>

9:</div>

10:

11:<script>

1:

2: (function() {

3:var app = angular.module('Demo', []);

4:

5: app.controller('HomeCtrl', function($scope) {

6: $scope.person = {

7: name: 'Shaun',

8: age: 36,

9: Company: 'IGT'

10: };

11: });

12: }());

13:

</script>

12:</body>

And below is what the page looks like.

Now let create a very simple directive which will show the object from the parent controller.

And now let's insert this directive into the controller we defined previously.

1:<divclass="panel panel-info"ng-controller="HomeCtrl">

2:<divclass="panel-heading">Home Controller</div>

3:<divclass="panel-body">

4:<pre>{{person | json}}</pre>

5:

6:<hr>

7:

8:<divclass="panel panel-success">

9:<divclass="panel-heading">Directive (Not Isolated Scope)</div>

10:<divclass="panel-body">

11:<divsx-isolated-scope-demo></div>

12:</div>

13:</div>

14:</div>

15:</div>

Well below is what the page looks like now. As you can see we can use variants defined in the parent scope of our directive. And when I changed the object content, parent scope also be changed as well.

This is OK for our demo, but there's a big problem. Our directive must be located in a controller where its scope contains a variant named "person". Also, anything changed against "person" inside the directive will affect the one in parent scope. As what you've seen in the screenshot above, "person" in both parent scope and directive scope are all changed when I specified new value. And even worst, if we defined some new variants in directive's scope, it will affect the scope in parent scope, which is definitively not what we want.

Isolated Scope

It's very simple to create an isolated scope in a directive. Below is what my directive with an isolated scope.

1: app.directive('sxIsolatedScopeDemo', function () {

2:return {

3: scope: {},

4: templateUrl: '/tpl.html'

5: };

6: });

Below is what it looks like now. Note that when we change something and add new variant inside the directive scope, it will NOT affect the parent scope.

Share Values in Isolated Scope

In order to make directive to be able to touch values defined in the parent scope we can specify in its scope options. Angular.js provides three ways: specify a variant, an expression, and a function.

We use "=" with attribute name to define a variant scope binding. Below I told my directive, there's an attribute named "the-person" defined in its HTML element, and the value of this attribute is the variant name defined in parent scope, which will be bind into the variant "me" inside the directive's scope.

1: app.directive('sxIsolatedScopeDemo', function () {

2:return {

3: scope: {

4: me: '=thePerson'

5: },

6: templateUrl: '/tpl.html'

7: };

8: });

And in the HTML part we added "the-person" attribute and point it to "person", which is the value we want to share from the parent scope.

Now we can see that the person information was passed into the directive in "scope.me". When we change the value inside this variant it will affect the parent scope. But if we add something new in directive's scope, for example "foo", it will NOT change the parent scope.

Another way to share value between parent scope and directive is to use "@" + expression. In this case, Angular.js will execute the expression defined in the attribute and set the result into the scope in directive. For example, if I have a scope property named "parentFoo" defined in parent scope and I'd like my directive scope to get its value I can use the code below.

1: app.directive('sxIsolatedScopeDemo', function () {

2:return {

3: scope: {

4: me: '=thePerson',

5: foo: '@theFoo'

6: },

7: templateUrl: '/tpl.html'

8: };

9: });

Changed the directive HTML element to bind it with an expression pointing to the "parentFoo".

Below is the result. Note that when using expression binding all changes in directive scope will NOT affect to the parent scope property.

Expression binding allows us to generate value from parent scope properties and pass the result to directive, as below.

1:<divsx-isolated-scope-demo

2:the-person="person"

3:the-foo="{{person.name}} is {{person.age}} years old working at {{person.company}}."></div>

Here is the result.

Sometimes we also need to invoke functions defined in the parent scope. In this case we can use "&" to tell the directive which function it will use. In the code below I added another directive scope options named "hi" which pointing to the attribute named "the-say-hi".

1: app.directive('sxIsolatedScopeDemo', function () {

2:return {

3: scope: {

4: me: '=thePerson',

5: foo: '@theFoo',

6: hi: '&theSayHi'

7: },

8: templateUrl: '/tpl.html'

9: };

10: });

In the page I bind it with a function in the scope named "sayHi".

1:<divsx-isolated-scope-demo

2:the-person="person"

3:the-foo="{{person.name}} is {{person.age}} years old working at {{person.company}}."

4:the-say-hi="sayHi(exp)"></div>

And below is the function defined in parent scope, which just popup a browser alert window.

1: app.controller('HomeCtrl', function($scope) {

2: $scope.person = {

3: name: 'Shaun',

4: age: 36,

5: company: 'IGT'

6: };

7: $scope.parentFoo = 'bar';

8: $scope.sayHi = function (exp) {

9: alert('Hi. ' + exp);

10: };

11: });

Finally in my directive template I added a button to invoke the function defined in the isolated scope, then it will find the binding function defined in parent scope. Note that how I pass parameters into the function.

Summary

Directive is very powerful in Angular.js. It's very important to understand isolated scope when creating a reusable directive. In this post I described the different between shared scope and isolated scope. I also demonstrated how to pass data from parent scope into directive isolated scope through "=", "@" and "&", and the different between them.

When I'm working in my project, as well as development "sx.wizard" toolkit, I need to deal with asynchronous operation. For example, in "sx.wizard", template for each steps are loaded in parallel asynchronously. And the "$wizard" service will start to render UI once all templates are loaded successfully. In this case we need to use $q.

$q was explained in Angular.js document as follow.

A service that helps you run functions asynchronously, and use their return values (or exceptions) when they are done processing.

To me, when you have a function which the result will be returned in sometime in the future, and you need to continue your procedure based on the return value, then you need to consider using $q. Let's take a very simple example.

Handle Asynchronous Operation

Assuming I have an angular.js application which need to display "Hello Shaun!", and "Shaun" should be appeared 2 seconds later, the code could be as below.

If we want to continue our procedure we can simply add codes inside $timeout function as below.

1: app.controller('HomeCtrl', function ($scope, $timeout) {

2: $timeout(function () {

3: $scope.name = 'Shaun';

4: alert('Continue working...');

5: }, 2000);

6: });

In this case it seems no need to introduce $q. But let's assume the name will be retrieved from another service or component. Normally it might be retrieved some external web service through $http but in order to simplify the example let create service and let it return name value in 2 seconds.

1: app.factory('nameService', function ($timeout) {

2:return {

3: get: function () {

4: $timeout(function () {

5:return'Shaun';

6: }, 2000);

7: }

8: };

9: });

In controller we use this service.

1: app.controller('HomeCtrl', function ($scope, nameService) {

2: $scope.name = nameService.get();

3: });

Looks great. But when we launch our website we will find the name will never be shown in the page, even though in the service we returned in 2 seconds. This is because "nameService.get" function returned "undefined" after it processed $timeout. 2 seconds later we returned name value but our controller has no chance to get it.

In this case we can use $q to notify controller the name was retrieved please update scope.

1: app.factory('nameService', function ($q, $timeout) {

2:return {

3: get: function () {

4:return $q(function (resolve, reject) {

5: $timeout(function () {

6: resolve('Shaun');

7: }, 2000);

8: });

9: }

10: };

11: });

We use "$q" as a constructor, which takes a function with two parameters: resolve and reject, both of them are functions. When we got the value, we can invoke "resolve" with the value as the parameter. When there's an exception, we can invoke "reject" to tell the caller it failed. In the code above I invoked "resolve" after 2 seconds with "Shaun", the name value I got.

Back to the controller, after invoked "nameService.get" we got a promise created by $q. When the result was ready it will invoke a function defined through its "then" method as following.

1: app.controller('HomeCtrl', function ($scope, nameService) {

2:var getPromise = nameService.get();

3:

4: getPromise.then(function (name) {

5: $scope.name = name;

6: });

7: });

Invocation Chaining

We can return a new promise inside "then" function from an existing promise. This makes us very easy to manage multiple asynchronous functions especially when some are depends on others. Database operation is a good example. Normally we need to open the database, then it's opened we will query records, and then we got the records we will filter them, prepare data and insert or update, then we close the connection. Below is "database" service I created, note that each function returns a promise.

1: app.factory('database', function ($q, $timeout) {

2:return {

3: open: function (db) {

4:return $q(function (resolve, reject) {

5: $timeout(function () {

6: resolve(db + ' is connected.');

7: }, 2000);

8: });

9: },

10: query: function (db, query) {

11:return $q(function (resolve, reject) {

12: $timeout(function () {

13: resolve(db + ' [' + query + '] processed successuflly.');

14: }, 2000);

15: });

16: },

17: execute: function (db, command) {

18:return $q(function (resolve, reject) {

19: $timeout(function () {

20: resolve(db + ' [' + command + '] invoked successuflly.');

21: }, 2000);

22: });

23: },

24: close: function (db) {

25:return $q(function (resolve, reject) {

26: $timeout(function () {

27: resolve(db + ' is disconnected.');

28: }, 2000);

29: });

30: }

31: };

32: });

In controller I invoked "database.open" method and handle and append a log entry when connected. Note that in this function I invoked "database.query", which return another promise.

1: app.controller('HomeCtrl', function ($scope, database) {

2: $scope.logs = [];

3:var db = 'shaun-db';

4:

5: database.open(db)

6: .then(function (result) {

7: $scope.logs.push(result);

8:return database.query(db, 'SELECT * FROM [Products]');

9: });

10: });

Now I can invoke "then" right after it, which called "invocation chaining", to perform my next operation.

Now let's run it you will see the operations are invoked one by one in series.

$q also supports execute asynchronous functions in parallel. In the example above we invoked one command when database was connected. It's a common case we can run some query in parallel, and when all of them are finished we will run some commands, then close the connection.

Below I tweaked "database" service a little bit in its "execute" method, allow user specify the timeout period.

1: execute: function (db, command, timeout) {

2:return $q(function (resolve, reject) {

3: $timeout(function () {

4: resolve(db + ' [' + command + '] invoked successuflly.');

5: }, timeout);

6: });

7: },

In controller when the database was connected and first query finished, I invoked 5 commands through "execute" method, which will be processed in parallel, and pushed the promises into an array, Then I was using "$q.all" method. This method accepts an array of promises and will invoke its "then" when all of them are resolved.

1: .then(function (result) {

2: $scope.logs.push(result);

3:var commandPromises = [];

4: commandPromises.push(database.execute(db, 'CMD 1', 1000));

5: commandPromises.push(database.execute(db, 'CMD 2', 500));

6: commandPromises.push(database.execute(db, 'CMD 3', 200));

7: commandPromises.push(database.execute(db, 'CMD 4', 200));

8: commandPromises.push(database.execute(db, 'CMD 5', 3000));

9:return $q.all(commandPromises);

10: })

After that I executed two commands in parallel in the same way, and close the database connection when all of them are finished.

1: .then(function (result) {

2: $scope.logs.push(result);

3:var commandPromises = [];

4: commandPromises.push(database.execute(db, 'CMD 6', 200));

5: commandPromises.push(database.execute(db, 'CMD 7', 300));

6:return $q.all(commandPromises);

7: })

When we run our application you will see the procedure was waiting for all parallel commands finished then process the next one.

Examples in Shaun's Angular Toolkits

Now let's take a look on how I used $q in the code of my angular toolkits. In "sx.wizard" user can specify step template URL or template inline code. When "template" property was specified I will use it directly, when "templateUrl" was specified I will load the content through $http, which is an asynchronous operation. Hence I have a function responsible for creating template promise.

In the code above I checked if "template" property was specified. If so I will wrap some HTML code and return a new promise through "$q.when". "$q.when" can be used when we are not pretty sure if an object is a normal object or a promise. It create a new promise wrapping this kind of object so that we can dealing it in $q. If the value passed in "$q.when" is a normal object it will be resolved immediately.

If "templateUrl" was specified I invoked "$http.get" to retrieve template content. Since "$http.get" returns a promise I use its "then" method to assign the content to step's template property.

Finally I returned the promise, no matter created by "$q.when" or "$http.get", into a local array.

1:var _stepTemplatePromises = [];

2:

3: ... ...

4:

5: wizard.addStep = function(step) {

6: ... ...

7: _stepTemplatePromises.push(_getTemplatePromise(step));

8:return wizard;

9: };

Then when the wizard is going to be shown, it will wait until all template are loaded successfully through "$q.all", then start to prepare scope and render UI.

1: wizard.open = function(data, success, cancel) {

2: ... ...

3: $q.all(_stepTemplatePromises).then(function() {

4:var instance = $modal.open({

5: ... ...

6: });

7: instance.result.then(function(data) {

8:return success(data);

9: }, function() {

10:return cancel();

11: });

12: });

13:return wizard;

14: };

Another example in "sx.tabs", which I'm going to introduce in the near future. User can specify tab content through inline template or URL. So I have the similar function for tab content loading.

Summary

Asynchronous function is very common in JavaScript. There are many libraries handles this scenario. Angular.js support it by using "$q". Comparing with others pattern "$q" is lightweight and simple, with enough functionalities. And all asynchronous components in Angular.js are built based on "$q" such as "$http", "$timeout", etc.

When your operation is asynchronous, and you need to invoke some following operations after it finished, you should think about "$q" firstly.