NativeScript: Edge of Tomorrow


This article is all about my experiences of building a Native Android application using NativeScript. NativeScript a framework for building cross-platform Android & iOS apps using Javascript and XML. For the reference, I am in the middle of migrating the same application to NativeScript + Angular combo (just for fun) as it leverages existing Angular skillset such as data-binding, event handling, routing, AuthGuard, etc, and makes it easy to reason about as well.

In a nutshell, NativeScript is not just a set of Javascript libraries but more of a runtime that enables to call Native Android and iOS apis using Javascript. It uses a Javascript virtual machine – V8 for Android and Webkit Core for iOS – that interprets and executes Javascript code at runtime to their respective native code. Hence, there is no limit in terms of which native API can be called in NativeScript, makes it a super powerful tool – worth adding in your arsenal 🙂

This article does not discuss about building Native apps in NativeScript because their documentation is pretty neat and covers it all.

Android ecosystem

Even though you were convinced to write native apps in pure Javascript, that fact is partially true. Meaning you still need to setup android SDK and tools in order to run your application on Emulator or Device. Oh boy, it was PITA in the beginning, especially when you are used to write for Web only – just Write. Refresh. Repeat!

One of such issues faced even before I could run their Sample Groceries app was the ANDROID_HOME environment variable is not set error, while running tns platform add android command. Although, there were tons of stack-overflow answers about that weirdo behavior but unfortunately all were suggesting to add ANDROID_HOME to the PATH environment variable – been there, done that already. At one point, I had decided to give up on NativeScript as I was this frustrated!

But soon the NativeScript community slack channel came to the rescue which I found on their troubleshooting documentation. That culprit is sudo – was running sudo tns platform add android like a rookie 👊. Nonetheless, I quickly got over it and set up the project with tns create FreshCall command.

NativeScript Plugins

The android application named FreshCall that I was building is a simple phone call management app to keep a tap on number of users being called on a daily/weekly basis, extract call charges for reimbursement purposes, and possibly record a phone conversation (with speakers on) for quality purposes. As you have already guessed that the application supposed to use android native APIs for most of the requirements such as ask permissions, choose or dial contact numbers, record conversation and upload it to Firebase, fetch call charges from USSD dialogs, etc. Luckily, the NativeScript community is flourished enough to have many plugins ready for most of the things I needed 😊

I realized that building traditional apps in NativeScript is far more easier than ones using native APIs. That’s why problems and worries did not stop for me at the rookie mistake made earlier, after all it was just the beginning.

Migrate Android code to NativeScript

Obvious thing for any phone management application is to detect Incoming calls and allow to make Outgoing calls using TelephonyManager. Truck load of articles and stack-overflow questions can be found on the topic, however, using them in NativeScript was a big deal. But Extending native classes section from the NativeScript documentation was quite useful that opened up ways for further exploration.

Below is the incoming call tracking code in Java (android):

private class CallStateListener extends PhoneStateListener {
  @Override
  public void onCallStateChanged(int state, String incomingNumber) {

  }
}
tm = (TelephonyManager) ctx.getSystemService(Context.TELEPHONY_SERVICE);
tm.listen(callStateListener, PhoneStateListener.LISTEN_CALL_STATE);

So the above Java code can be ported to NativeScript as follows:

var callStateListener = android.telephony.PhoneStateListener.extend({
onCallStateChanged: function (state, incomingNumber) {

}
var application = require("application");
var tm = application.android.context.getSystemService(android.content.Context.TELEPHONY_SERVICE);
tm.listen(new callStateListener(), android.telephony.PhoneStateListener.LISTEN_CALL_STATE);

How did I manage to port it so flawlessly? Here is a simple trick:

  1. Learn to extend android native classes in NativeScript.
  2. Search android documentation for a native property such as PhoneStateListener and refer the java.lang.Object path for the same i.e. android.telephony.PhoneStateListener.

The similar trick is applicable for application ctx, android Context, and tm.listen event.

Background Services

NativeScript community is so kind to give you all the tools to build a bridge, but the only condition is that you’ve to learn to build it yourself, 😄. I hope one day it will be a piece of cake as NativeScript grows and will be widely adopted as a standard to build native apps.

To track the USSD dialog’s response – the call charge window appears after the call ends – I needed a background service to keep an eye on it and extract the the call charge as soon as it shows up. Somehow I could write a background service myself with the help of the sample provided by NativeScript community and port the USSD parsing using the trick we just learned. However, the onServiceConnected() method – enables accessibility service to read USSD responses – was not getting registered even after enabling it for the application from the android settings.

During the salvation of this problem, I learned two things:

  1. When in doubt, always rebuild using tns build android (remove the existing application from the device before live-syncing again).
  2. Reinstall android packages if updates are available.
    Android SDK and tools
    Android SDK and tools

Wrap up

Experience of building the android application (without having any knowledge of Native Application Development before) was terribly empowering 😉. My advice to fellow developers is to keep Android Documentation open all the time!

Peter Kanev from NativeScript core team had been a great help. Also, special thanks to Brad Martin (who built many plugins I’ve been using) and Marek Maszay for their constant support and cheer on Slack.

Live on the Edge Of Tomorrow today with NativeScript!

Advertisements

Angular2: Data Binding


In the previous article, we had explored how dependency injection works in Angular2 compared to Angular1. In this article, I will walk you through the one-way vs two way data binding and how its different but quite similar in Angular2.

Angular1

As usual, we’ll quickly go through the Angular1 example. Let’s take a simple example (HTML) from my free ebook on Angular1 Directives that explores how data binding works in Angular1. Notice we have not written a single line of Javascript code to enable the data binding in the following example:

<html ng-app="App">
<head>
  <title>Two way Data Binding with Form Controls</title>
  <script src="../bower_components/angular/angular.js"></script>
</head>
<body>
  <input type='checkbox' ng-model='choose' />
  <div>{{choose}}</div>

  <button ng-click="choose=!choose">Toggle Checkbox</button>

  <script type="text/javascript">
    angular.module('App', []);
  </script>
</body>
</html>

Now that we’ve a working demo, let us migrate it to Angular2.

Angular2

Let us create a typescript file twoway-binding.ts first to lay our main component.

import { NgModule, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { BrowserModule } from '@angular/platform-browser';
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';

@Component({
  selector: 'ng-app',
  template: `
    <input type='checkbox' [(ngModel)]='choose' />
    <div>{{choose}}</div>
    <button (click)="choose=!choose">Toggle Checkbox</button>
  `
})
export class DataBindingComponent {
  choose: boolean = true;
}

@NgModule({
  declarations: [DataBindingComponent],
  imports:      [BrowserModule, FormsModule],
  bootstrap:    [DataBindingComponent]
})
export default class MyAppModule {}

platformBrowserDynamic().bootstrapModule(MyAppModule);

We are already familiar with Component, ES6 Class, bootstrap, etc. jargons from the first article as those are the backbone of Angular2. The only difference here is the template with data-binding expressions.

In Angular1, the two-way data binding was enabled by default, for one-way data binding the expression should be wrapped in {{choose}}. Also the attribute name supposed to be hyphenated. However, in Angular2 the attribute should be in camel-case with subtle differences that affect the way data flows:

  1. [Component -> Template]
    To show a model in a template which was defined in the component, use square-bracket or double-curly syntax a.k.a. One Way Binding.
  2. (Template -> Component)
    To broadcast an event from a template in order to update the model in the component, use round-bracket syntax a.k.a. One Way Binding.
  3. [(Component -> Template -> Component)]
    To have both behaviors simultaneously, use round-bracket inside square-bracket (or banana-in-the-box) syntax a.k.a. Two Way Binding.

This clearly means that the two-way binding in Angular2 is opt-in and can be enabled by importing BrowserModule to plug it in the NgModule.

In the above example, we want to toggle the expression choose from the template to the component using (click) when the button is clicked and update the checkbox in the template immediately using [ngModel]="choose". We also want to update the model choose in the component if the checkbox is toggled manually using [(ngModel)]="choose". Do not get confused with one-time binding in Angular1 i.e. {{::choose}} where the model used to be freezed once evaluated, there is no such thing in Angular2.

Now let us update HTML markup as usual.

<html>
<head>
  <title>Angular2: Two way Data Binding with Form Controls</title>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">

  <!-- 1. Load libraries -->
  <script src="../node_modules/core-js/client/shim.min.js"></script>
  <script src="../node_modules/zone.js/dist/zone.js"></script>
  <script src="../node_modules/reflect-metadata/Reflect.js"></script>
  <script src="../node_modules/systemjs/dist/system.src.js"></script>

  <!-- 2. Configure SystemJS -->
  <script src="../systemjs.config.js"></script>
  <script>
    System.import('ch01/twoway-binding').catch(function(err){ console.error(err); });
  </script>
</head>
<body>
  <!-- 3. Display the application -->
  <ng-app>Loading...</ng-app>
</body>
</html>

Wrap up

Remember, because of the simplified template syntax in Angular2, you can do lot of things easily such as,

  • {{textContent}} becomes [textContent]="textContent"
  • ng-bind-html="html" becomes [innerHTML]="html"
  • ng-mouseup="onMouseUp()" becomes (mouseup)="mouseUp()"
  • my-custom-event="fire()" becomes (customEvent)="fire()"

Fewer templating syntax means Faster learning! Head over to a live data binding in action.

Angular2: Dependency Injection


In the last article, we’ve explored basic differences between Angular 1 and 2 with respect to Component over Directive, TypeScript over ES5, ES6 Class over Controller, and Decorators/Annotations. We’ve pretty much got acquainted with setting up Angular2 in TypeScript with SystemJS to begin our journey with Angular2 in coming weeks. In this article, we’ll investigate how dependency injection that we always loved is different in Angular2 than Angular1. We are not going to cover what dependency injection is in this article though, so if you are not familiar with it yet, follow the documentation for more information.

Angular1

As usual, we’ll quickly go through the Angular1 example. Let’s take a simple example (HTML and JS) from my free ebook on Angular1 Directives that explores how DI works in Angular1. Notice we’ve used ngController directive in which we are going to inject a custom service. Also stare at ngApp directive which was a recommended way to bootstrap an application automatically in Angular1 rather than manually using angular.bootstrap method.

<html ng-app="DI">
<head>
  <title>AngularJS: DI</title>
  <script src="../bower_components/angular/angular.js"></script>
  <script src="../js/ch01/di.js"></script>
</head>
<body ng-controller="SayHi">

<h1>Check the console</h1>

</body>
</html>

Here is the JavaScript code for the above example. We have defined the custom service named Hello and later injected the same into the controller called SayHi.

var App = angular.module('DI', []);
App.service('Hello', function() {
  var self = this;
  self.greet = function(who) { 
    self.name = 'Hello ' + who;
  }
});

App.controller('SayHi', function(Hello) {
  Hello.greet('AngularJS');
  console.log(Hello.name);
});

Now that we’ve our demo up and running, it’s time to migrate it to Angular2.

Angular2

Let us first update the JS code first and walk through the changes.

import { NgModule, Component, Injectable } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';

@Injectable()
class HelloService {
  name: string;
  
  greet(who) {
    this.name = 'Hello ' + who;  
  }  
}

@Component({
  selector: 'ng-app',
  template: '<h1>Check the console</h1>'
})
export class DIComponent {
  constructor(public Hello: HelloService) {
    this.Hello.greet('Angular2');
    console.log(this.Hello.name);
  }
}

@NgModule({
  declarations: [DIComponent],
  imports:      [BrowserModule],
  providers:    [HelloService],
  bootstrap:    [DIComponent]
})
export default class MyAppModule {}

platformBrowserDynamic().bootstrapModule(MyAppModule);

We are already familiar with Component, ES6 Class, bootstrap, etc. jargons from the previous article as these are the backbone of Angular2. The only difference here is the service, HelloService. However, if you notice, the service is itself a ES6 Class similar to our application component, DI. Just like @Component annotation is there to tell Angular2 to treat a ES6 class as a component, the @Injectable annotation annotated the ES6 Class as an Angular2 Service that is injected elsewhere.

In the above example, we’ve injected the service via providers options in the @NgModule. This way the instance of the service will be available for the entire component only and its child components, if any. However, services in Angular2 are not singleton by nature unlike Angular1 which means if the same service is injected as a provider in a child component, a new instance of the service will be created. This is a confusing thing for beginners so watch out.

The public Hello: HelloService parameter in the constructor is equivalent to Hello: HelloService = new HelloService();. It means Hello is an instance of HelloService and of a type HelloService (optional). One benefit of annotations/decorators in Angular2 in my opinion is that there is no confusion over Factory vs Service vs Provider, instead it’s just a ES6 class.

Slight changes compared to the previous example is that we need to give more configurations in SystemJS for typescript compilers to emit decorator MetaData so that generated ES5 code will work fine in a browser.

{
  "compilerOptions": {
    "target": "ES5",
    "module": "commonjs",
    "moduleResolution": "node",
    "sourceMap": true,
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true,
    "removeComments": false,
    "noImplicitAny": false
  }
}

Remember experimentalDecorators flag enables experimental support for ES7 decorators in TypeScript and emitDecoratorMetadata flag emits design-type metadata for decorated declaration in ES5 output, especially, for public Hello: HelloService code in the constructor as we’d seen before. Using the alternative mentioned above will not need these flags though.

Now let us update HTML markup.

<html>
<head>
  <title>Angular2: DI</title>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">

  <!-- 1. Load libraries -->
  <script src="../node_modules/core-js/client/shim.min.js"></script>
  <script src="../node_modules/zone.js/dist/zone.js"></script>
  <script src="../node_modules/reflect-metadata/Reflect.js"></script>
  <script src="../node_modules/systemjs/dist/system.src.js"></script>

  <!-- 2. Configure SystemJS -->
  <script src="../systemjs.config.js"></script>
  <script>
    System.import('ch01/di').catch(function(err){ console.error(err); });
  </script>
</head>
<body>
  <!-- 3. Display the application -->
  <ng-app>Loading...</ng-app>
</body>
</html>

Wrap up

That’s it guys..! Wolksoftware‘s blog has covered a great intro to reflection in Typescript, if interested. In the next post, we’ll explore two-way databinding in Angular2, but meanwhile Checkout Dependency Injection in action.

Angular2: The First Time


Angular 2.0 is lot like Angular1 but still different in its own terms and you’ll see why as we go along. Purpose of this article is to migrate one of the simplest Angular1 examples to Angular2 and understand benefits as well as pain-points. For the record, Angular2 aimed to build web applications in three different languages or flavours i.e. JavaScript (ES5/ES6), Typescript(ES6+), and Dart. If you interested in other two then the 5-minute-session will give you a head-start to understand how it could be done. However, I’m going to use Typescript over JavaScript here because in my opinion it feels more natural. This article is for the ones who worked with Angular1 before.

Angular1

Let’s take a simple example (HTML and JS) from my free e-book on Angular1 Directives that explores how data binding works in Angular1. Let us quickly take a look at our good old Angular1 HTML template and then we’ll move to new shiny Angular2 version of it. But for now, notice we’ve used ngBind directive over double-curly notation for data-binding, obviously to avoid FOUC as we all know. Also checkout ngApp directive which was a recommended way to bootstrap an application automatically in Angular1 without using angular.bootstrap method.

<html ng-app="App">
<head>
  <title>HTML/DOM Template in AngularJS</title>
  <script type="text/javascript" src="../bower_components/angular/angular.js"></script>
  <script type="text/javascript" src="../js/ch01/angular-template.js"></script>
</head>
<body>
  <span>Hello, <span ng-bind="name"></span></span>
</body>
</html>

Here is the JavaScript code for the above example which simply binds a value of name property on the $rootScope.

var App = angular.module('App', []);
App.run(function($rootScope) {
  $rootScope.name = 'AngularJS';
});

Now that we’ve our demo up and running, its time to migrate it to Angular2.

Angular2

Let us first update the JS code and walk-through the changes. Give it a very long, hard stare to get familiar with the following snippet, I’ll wait.

import { NgModule, Component } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';

@Component({
  selector: 'ng-app',
  template: '<span>Hello, <span [textContent]="name"></span></span>'
})
class MyAppComponent {
  name: string = 'Angular2';
}

@NgModule({
  declarations: [MyAppComponent],
  imports:      [BrowserModule],
  bootstrap:    [MyAppComponent]
})
export default class MyAppModule {}

platformBrowserDynamic().bootstrapModule(MyAppModule);

Your first reaction would be, “Alright, that looks familiar..!”. Well it is except few things, let us go over one by one. But before that we must know that Angular2 moved from a concept of directives to components to leverage web-components specs so that developers can use Polymer components with Angular2 templates. Basic idea is to break down monolithic application into small pieces i.e. components and plug them together at the end under main component like we have here. Each component should have one or more Classes or Functions to store data (name in this case) and necessary methods (not defined in the example above). Please note we no longer use $scope in Angular2 as this is somewhat like CtrlAs syntax from Angular1. When Angular2 instantiates MyApp class, all properties or methods defined will be accessible via keyword this.

Update: As per RC5 release, angular2 introduced a concept of NgModule metadata which plays an important role in the compilation process, especially offline compilation. Because of NgModule, Angular2 will able to lazy load components on demand by resolving component dependencies efficiently. So every component should expose a NgModule for other components to import and reuse. Ideally, NgModule should be extracted into it’s own file importing various components, services, pipes, etc. but for the sake of readability, we’ll have it in the same file along with the component.

export statement

Angular2 has adopted modularity at its core unlike Angular1 wherein you could only define modules without any built-in support for lazy loading. Using ES6 export module syntax, you can export functions, objects, or primitives that other classes can use in Angular2. Having one export class per module recommended though. We’ve defined a property, name with a type string which is optional in TypeScript.

Import Statement

With the same export class syntax, Angular2 has organized its code base so that developers can import what they need in a module. In this example, we are only importing Component and NgModule annotations from angular2/core library and platformBrowserDynamic method from angular/platform-browser-dynamic modules. Note that the extension is optional in the definition.

Using platformBrowserDynamic().bootstrapModule method from angular2 browser module (similar to angular.bootstrap in Angular1), we can bootstrap the NgModule named MyAppModule. Angular2 is a lot different from Angular1 on the architectural level. Angular1 only targeted Desktop and Mobile web browsers, but Angular2 is platform agnostic, that means it can be used to write Native mobile apps using NativeScript or Cordova, run angular2 application inside web workers, and to enable server-side rendering with NodeJS or so. For now, we’ll just run it in a web browser by pulling down browser specific bootstrap method as above.

Annotation

The strange-looking syntax above the class called as a Class Decorator that annotates and modifies classes and properties at design time. Wolksoftware’s engineering blog has great articles on decorators and metadata in Typescript. In a nutshell, Angular2 uses decorators/annotations to make dependency injection possible. To simplify it, let us take a small requirement.

Imagine you want to log a function name and passed arguments to browser console every time a method invoked without modifying the function body. In the following example, @debug is a method decorator that attached a special behavior to the method body. overtime a method called, the decorator will find a method name being called and it’s parameter that we can log. Here is a working demo if interested.

export class AnnotationExample {
  @debug
  life(n: number) {
    return n;
  }
}

function debug(target: Function, fnName: string, fn: any) {
  return {
    value: function (argument: number) {
      document.getElementsByTagName('body')[0].textContent = `function "${fnName}" was called with argument "${argument}"`;
    }
  };
}

var whatIs = new AnnotationExample();
whatIs.life(42);

On the same note, @component annotation/decorator tells Angular2 that the defined class, MyApp is an Angular2 Component not just a ES6 class. And once it’s defined as the component, Angular2 needs to know how the component supposed to be consumed in HTML or which template to render once it’s registered. That’s why we need to pass the meta data as above such as selector, template, etc.

Notice selector name need not be the same as the class name unlike Angular1. There is no restrict option anymore, instead use a tag name (ng-app) or a property name (with square brackets [ng-app]) or a class name (.ng-app) directly as a selector (I think a comment selector is dropped..!). Also note that we have used a double curly notation for data binding here as there is no ngBind directive available, but you can use property binding (which we’ll explore in future posts) to get the same feeling with <span>Hello, <span [textContent]="name"></span></span>.

Now let us update HTML markup.

<html>
<head>
  <title>HTML/DOM Template in Angular2</title>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">

  <!-- 1. Load libraries -->
  <script src="../node_modules/core-js/client/shim.min.js"></script>
  <script src="../node_modules/zone.js/dist/zone.js"></script>
  <script src="../node_modules/reflect-metadata/Reflect.js"></script>
  <script src="../node_modules/systemjs/dist/system.src.js"></script>

  <!-- 2. Configure SystemJS -->
  <script src="../systemjs.config.js"></script>
  <script>
    System.import('ch01/angular-template').catch(function(err){ console.error(err); });
  </script>
</head>
<body>
  <!-- 3. Display the application -->
  <ng-app>Loading...</ng-app>
</body>
</html>

If you remember, we’d included just angular.js in Angular1 template before, however, Angular2 relies on couple of other JavaScript libraries that you need to inject along with it. But things may change eventually, as it’s just a RC release (at the time of writing this article, and who knows we have to just include one file as before).

Refer SystemJS Wiki for more details to suite your needs. And as you guessed already, we have created a custom element in the body at the end to kick it off.

Wrap up

Peek at a demo..!. That’s it guys..! This is the exact flow you’ll always be using to write new components in Angular2. I liked the progress with Angular2 and Typescript, I would recommend to use Visual Studio Code Editor over SublimeText to feel at home. Be hopeful that many of the things we explored would be simplified by the time it reaches 1.0 (stable), I mean 2.0 😉

Protractor: The Secret Service


This post is not about how to install and use Protractor. I believe setting up Protractor is a lot easy, so heading over to the documentation is an ideal choice to make. For those who have not heard of Protractor yet, it is nothing but an end-to-end test framework for AngularJS applications. However, it works seamlessly for non-angular applications as well, obviously, with a small tweak which is what this post is all about.

In a nutshell, Protractor runs tests against your application running in a real browser, interacting with it as a user would. That means you have to give a set of instructions for each test you write. But before that, let us create a small demo in jQuery (no AngularJS). Below demo is fairly simple but useful to put my point across about robustness of writing tests in Protractor. In this demo, we are having a dummy Google Sign In button loaded via a fake REST call to Google Developers APIs.

<!DOCTYPE html>
<html>
<head>
	<title>Protractor: The Secret Service</title>
	<script src="http://code.jquery.com/jquery-1.11.3.min.js"></script>
	<script>
	$(window).load(function() {
		// Simulating a REST call with Google APIs
		window.setTimeout(function() {
			$('#signin-placeholder').replaceWith(
				'<button id="signin">Google Sign In</button>'
			);

			$('#signin').click(function() {
				$(this).text('Sign Out');
			});
		}, 2000);
	});
	</script>
</head>
<body>
	<div id="signin-placeholder"></div>
</body>
</html>

Sleep

Now that we understood how our application works, it’s time to write E2E tests for it. Following test block might look sound and easy to grasp to you, but there are couple of hidden tricks have been used in order to pass it.

describe('Non EC Tests', function() {
	beforeEach(function() {
		browser.ignoreSynchronization = true;
		browser.get('demo.html');
	});

	it('Should', function() {
		browser.sleep(2 * 1000);
		element(by.id('signin')).click();
		expect(element(by.id('signin')).getText()).toBe('Sign Out');
	});
});

First line in the beforeEach block i.e. browser.ignoreSynchronization is to tell Protractor that, Hey, this is not an Angular application, so do not wait for Angular to load. Start running tests as soon as the page loads in a browser. This is the one and only trick to consider while using Protractor for non-angular applications which means if in case a webdriver control flow hangs while running tests, that’s the thing to look for in the Spec. Moving on to the it block which is our actual test. In the beginning, we make sure to wait for 2 seconds as per our business logic before we click the login button. Later we confirm the button text is changed to Sign Out.

The important thing to note here is that the browser.sleep method is a last resort most people use to make tests pass to prevent random failures, however, in our case, it is tightly coupled with the business logic. If we increase/decrease the timeout in the fake REST call, we’ll have to adjust the same to fix the broken test. In addition to it, the real REST call may or may not complete within the expected timeout making your test unstable. Let’s fix that…

Wait

Selenium webdriver exports a method called browser.driver.wait that schedules a command to wait for a condition to hold true. This means wait will repeatedly evaluate the condition until it returns a truthy value. You can pass a condition or a custom function that returns a promise to it. So we will simply replace the browser.sleep statement with,

browser.wait(element(by.id('signin')).isDisplayed, 2 * 1000);

In here browser will wait until isDisplayed method returns a truthy value. If it did not, it will time out after 2 seconds. Note in protractor version 2.0.0, due to changes in WebDriverJS, wait without a timeout will now default to waiting for 0 ms – which off-course forbids our business logic. So we chose to provide ideal explicit timeout. To your surprise the above statement will throw, Failed: No element found using locator: By.id("signin") error because it’s not available in the DOM yet. We could have used browser.waitForAngular method for Angular to render the button if we were using it in the demo. Protractor deals with such scenarios nicely, especially in Angular applications wherein it forces the webdriver to wait until Angular has finished rendering and has no outstanding $http or $timeout calls before continuing.

ExpectedConditions

No worries..! Selenium offers a different mechanism to handle the same for Protractor called as ExpectedConditions a.k.a. EC. It’s similar to protractor isDisplayed API that we saw earlier but especially for non-angular applications. Again the webdriver waits until the expected condition returns a truthy value. Moreover, you can mix it with multiple and, or, and not operators. So to fix the error, we’ll use,

browser.wait(protractor.ExpectedConditions.visibilityOf(
  element(by.id('signin'))
));

This will schedule a command for the webdriver to wait and repeatedly evaluate the condition to check if the element is available/visible in the DOM. There are various functions EC supports that you should take a look at http://www.protractortest.org/#/api?view=ExpectedConditions.

Wrap up

So that’s it. In a real-world project, I happened to encountered similar issues on staging environment where pages load slighly slow than local webserver and some of my tests started failing randomly because browser.sleep hack for HTTP or AJAX calls did not pan out :-). EC statements have helped me a lot while writing robust Protractor tests for non-angular apps and made tests more stable too, mostly, on Firefox and Safari.

Thanks for reading and keep Rocking \m/.

Building Pluggable Components in AngularJS


Although ng-boilerplate or angular-seed talks about the best-practice directory structure to ensure code re-usability and maximum scalability but sometimes having a separate directory per feature seems an ideal choice because it allows us to integrate loosely coupled components together and makes it easy to unplug it anytime without much hassle. The approach I’m proposing here may not be the best practice but it solves the real problem for us.

In our application, we’ve couple of icons (tools) grouped by a controller and whenever we wish to move any icon/tool from one controller to another we’d to migrate the respective code base also which was quite time consuming and risky (sometimes it breaks the feature during migration).

What we wanted to create was a pluggable component. By just including the JS file of the component (similar to Polymer Import) and placing an element anywhere should make the feature available.

So, I came up with the following directory structure:
app/scripts
└── features
│   ├── home
│   │   ├── home.js
│   │   └── home.tpl.html
│   └── profile
│   │   ├── profile.js
│   │   └── profile.tpl.html

Creating a Component

In angular, writing a custom directive is the best option to create a component. So lets begin with how we can use a particular component once it is ready.

<!-- index.html -->
<div ng-controller="OneCtrl">
    <div pc-home></div>
</div>

As I said earlier, in order to make it as pluggable as possible we’ll create a separate module for it so whenever required the module will be injected as a dependency. So below is the blueprint of the component:

// home.js
angular.module('tools.home', [])
  .directive('pcHome', function() {
    return {
      restrict: 'EA',
      replace: true,
      scope: {},
      controller: function($scope, $element, $attrs) {

      },
      template: '',
      link: function(scope, element, attrs) {

      }
    }
  });

We restricted the component to be used as an Element or Attribute, set an isolate scope for it so that it does not interfere with its parent scope (OneCtrl in this case – Prototypal Inheritance will not work either). The controller option will allow us to write all the logic related to the component and finally a template/templateUrl will replace the existing element on which the directive was placed.

We also want to activate a single tool at a time so in order to maintain the state of the tool, we’ll create a service just to share data between multiple components. openPanel property handles the state of the tool that is currently in use or selected.

App.factory('StateService', function() {
  return {
    openPanel: ''
  };
});

We’re going to use a button as a tool handler replacing the div[pc-home]. You can also use templateUrl in case your template is fat. As you can notice, we’ve injected StateService as a dependency for the component which then bound to $scope inside controller and later used within the template to toggle a CSS class.

angular.module('tools.home', [])
  .directive('pcHome', function(StateService) {
    return {
      restrict: 'EA',
      replace: true,
      scope: {},
      controller: function($scope, $element, $attrs) {
        $scope.stateService = StateService;
      },
      template: '<button class="btn home" ng-click="toggle()" ng-class="{true: \'btn-primary\', false: \'btn-success\'}[stateService.openPanel == \'home\']">Home</button>',
      link: function(scope, element, attrs) {

      }
    }
  });

Lets define toggle() method to perform some kind of action once the button is clicked. We’re just updating the property value of the StateService here. You can go and check the demo – click Home button and see it toggles its state when clicked. But as of now, the button does not do anything except toggling the background color.

angular.module('tools.home', [])
  .directive('pcHome', function(StateService) {
    return {
      restrict: 'EA',
      replace: true,
      scope: {},
      controller: function($scope, $element, $attrs) {
        $scope.stateService = StateService;
        
        $scope.toggle = function() {
          if (StateService.openPanel === 'home') {
            StateService.openPanel = '';
          } else {
            StateService.openPanel = 'home';                
          }
        };
      },
      template: '<button class="btn home" ng-click="toggle()" ng-class="{true: \'btn-primary\', false: \'btn-success\'}[stateService.openPanel == \'home\']">Home</button>',
      link: function(scope, element, attrs) {

      }
    }
  });

Final Trick

It is sometimes important to position an element relative to <body> not its parent. And thats why we can not merge the panel that we want to open ( when the button turns blue) inside the template. For that, we’ll have to add the panel markup dynamically inside index.html so that its available only if the component is in use or plugged. Lets put the panel markup in separate file named home.tpl.html.

<!-- home.tpl.html -->
<div class='home-template' ng-show="stateService.openPanel == 'home'">
  <ul>
    <li ng-repeat="choice in choices" ng-bind-template="{{$index + 1}}. {{choice}}"></li>
  </ul>
</div>

And finally we’ll change the link function where we’re simply injecting a <div> tag with ng-include attribute on it which allows us to include the template in <body> after getting compiled by $compile service with the same scope. The shared scope lets us use any method/property defined in our controller within the template as well which obviates the need for a separate controller specifically for home.tpl.html.

angular.module('tools.home', [])
  .directive('pcHome', function(StateService, $compile) {
    return {
      restrict: 'EA',
      replace: true,
      scope: {},
      controller: function($scope, $element, $attrs) {
        $scope.stateService = StateService;
        
        $scope.toggle = function() {
          if (StateService.openPanel === 'home') {
            StateService.openPanel = '';
          } else {
            StateService.openPanel = 'home';                
          }
        };

        $scope.choices = [
         'Share whats new...',
         'You may know',
         'Updates from followers',
         'Few posts from communities',
         'Scrolling now for more updates',
         'Loading...'
        ];
      },
      template: '<button class="btn home" ng-click="toggle()" ng-class="{true: \'btn-primary\', false: \'btn-success\'}[stateService.openPanel == \'home\']">Home</button>',
      link: function(scope, element, attrs) {
        angular.element(document.getElementsByTagName('body')).append(
          $compile('<div ng-include="\'home.tpl.html\'"></div>')(scope)
        );
      }
    }
  });

Word of Wisdom

By design the ng-include directive creates a new scope and in our case it will become a child scope of the original scope we compiled the template with. So beware of initializing a model inside the template itself using ng-model or ng-init. Is there a fix for this?

Yes! suppose you want to use ng-model="search" within the template then use $parent with it. i.e. ng-model="$parent.search". This will automatically bind the search model on the controller’s scope not the one created by ng-include.

The End

Last but not the least, whenever we need this component in our application we just have to resolve the dependency by introducing App.tools in main application module and you are free to use the component anywhere within the application without breaking a thing. Try moving components around.

var App = angular.module('App', ['App.tools']);
angular.module('App.tools', ['tools.home', 'tools.profile']);

In case you want to unplug the component then just delete the features/home directory, unreference the home.js and <div pc-home></div> from index.html, remove the module tools.home, and you are DONE.

Cautionary Tale for Angular Developers


Okay, now take a moment to watch this video

I’m sure after watching it, you may have realized that I’m not here to talk about why Neo falls into coma by stopping sentinels. Instead I’m going to talk about why my application got crashed the same way in Windows 8 RT webview and what I learned.

The Reality

An Application was built on top of Angular.js and Twitter Bootstrap for Desktop, Android, iOS, and Windows8. For touch devices, we’d created a Native wrapper around which loads the application in a webview. It looked fine in Android and iOS devices but was crashing in Windows8 RT upon opening a Bootstrap Modal popup. And I had no clue why Windows8 RT alone?

This is what I was using to open a modal window. I know its very bad to do the imperative DOM manipulation inside controller but as there were no directives bound to .modal I believed its safe to use it.

$('.modal').modal({backdrop: 'static'});

But I was wrong. In Windows8 RT, the above line was throwing an error “Object [object Object] has no method ‘modal'”. My guess is that I must be executing bootstrap code in middle of $digest cycle or something.

The Fix

To fix this issue I could either move that code in a custom directive and toggle modal’s state or use Angular UI Bootstrap. I decided to go with the latter. Finally I learned a very hard lesson while fixing the issue that one should spend some time to get it right than just get it done.

Follow the best practices or get ready to be bitten.

So I’ve used AngularUI Bootstrap modal directive to instead of doing DOM manipulation in the controller.

var App = angular.module('App', ['ui.bootstrap']);
App.run(function($rootScope) {
    $rootScope.opts = {
        backdrop: true,
        backdropClick: false,
    };
    
    $rootScope.modalOpen = false;
});

Finally updated the DOM as follows:

  <button class="btn btn-primary btn-large" ng-click="modalOpen = true">Open Modal</button>

  <div class="modal hide" options="opts" modal="modalOpen">
    <div class="modal-header">
      <h3>Modal Header</h3>
    </div>
    <div class="modal-body">
      Modal Body goes here...
    </div>
    <div class="modal-footer">
      <div class="btn" ng-click="modalOpen = false">Close</div>
    </div>
  </div>