Raible Designs

Life as an Open Source Developer

Matt Raible — Thu, 3 Nov 2016 16:29:01 -0600

It's been a little over a month since I started my new gig at Stormpath. I gotta say, life is great as an open source developer! Yes, I did start working for them as a consultant in April, so it's not a huge change for me. However, I only recently realized I haven't written a single line of proprietary code the entire time. My GitHub contributions look pretty good this year. They're nothing like @mojavelinux, or @dsyer, but I'll get there.

It's also been a bit more stress than I'm used to. I think this comes from a couple things: 1) turning my hobby into my job and 2) I've set a lot of high expectations for myself. As a developer evangelist, I get to create my own job. That means I can speak at the conferences I want to, write the code I want to, create the blog posts I want to, and everything else in between.

At the end of September, I finished updating the JHipster Mini-Book for JHipster 3.x. It's gone through tech editing and it's being copy-edited right now. I hope to release it within a week.

In early October, I said I'd commit to writing one blog post per week, develop a JHipster module for Stormpath, and help get their Angular 2 support good enough for an alpha release. I'm happy to report I've been able to accomplish most of these and I hope to show off our Angular 2 support soon.

I then channeled my efforts into integrating Stormpath's Java SDK with their AngularJS directives. You can read about how I did that in Get Started with AngularJS, Spring Boot, and Stormpath. Unlike my previous AngularJS tutorial, this one connects to a backend and shows how to communicate with Spring Boot cross-domain.

If you like to read code more than words, you can look at the example project's commits on GitHub.

Create an AngularJS UI: search and edit features
Create a Spring Boot app with Stormpath: app from start.stormpath.io
Develop an API to CRUD people with Spring Data REST: /api/people
Integrate AngularJS and Spring Boot apps: cross-domain
Integrate Stormpath into AngularJS for login, registration and forgot password: Stormpath Angular SDK

Last week, I released a JHipster module that integrates Stormpath. This exercise was good because I was able to identify some gaps in Stormpath's SDKs and fix them. Getting something to work made me feel good; having the ability to improve the developer experience was even better! Of course, I blogged about what I learned.

This week, I edited and code reviewed some posts from Karl Penzhorn on React with Spring Boot and using webpack with React. I also got to bang my head against the wall writing Angular 2 tests. If you're writing a module for Angular 2, generator-angular2-module provides a nice starting point.

Last, but certainly not least, I'll be speaking at a few events about Microservices, JHipster, Angular 2 and Stormpath in the near feature.

Rocky Mountain Software Symposium, November 19
The Rich Web Experience, December 9
A joint talk at Denver JUG with the infamous Josh Long, December 14

If you have any questions about developer evangelism, the technologies I mentioned in this post, or Stormpath, please let me know. Otherwise, I hope to see you on the road soon!

Getting Started + Testing with Angular CLI and Angular 2 (RC5)

Matt Raible — Tue, 23 Aug 2016 17:18:41 -0600

I started creating Angular 2 applications when it was in beta (back in March). To keep up with Angular 2's changes, I wrote a tutorial about developing with RC1 in June. Earlier this month, RC5 was released and many things changed once again. I think Scott Davis sums it up nicely in a tweet.

They keep saying "Release Candidate", but I don't think it means what they think it means...

/cc #angular2 #rc5 https://t.co/WmNalTYgTN
— Scott Davis (@scottdavis99) August 10, 2016

To keep up with the rapid pace of change in Angular 2, I decided to write another tutorial, this time using Angular CLI. The biggest change I found since writing the last tutorial is testing infrastructure changes. Since Angular's Testing documentation hasn't been updated recently, hopefully this tutorial will help.

Below is a table of contents in case you want to skip right to a particular section.

What you'll build

You'll build a simple web application with Angular CLI, a new tool for Angular 2 development. You'll create an application with search and edit features.

What you'll need

About 30-40 minutes.
A favorite text editor or IDE. I recommend IntelliJ IDEA and its Angular 2 TypeScript Live Templates plugin.
Node.js and npm installed. I recommend using nvm.
Angular CLI installed. If you don't have Angular CLI installed, install it using npm install -g angular-cli@latest.

The latest release of Angular CLI (beta 10) uses Angular 2 RC4. Because of this, I used the master branch of Angular CLI to create this tutorial. To do this, clone angular-cli and run npm link in the directory you cloned it into. If you have issues, see #1733.

Angular Augury is a Google Chrome Dev Tools extension for debugging Angular 2 applications. I haven't needed it much myself, but I can see how it might come in handy.

Create your project

Create a new project using the ng new command:

ng new ng2-demo

This will create a ng2-demo project and run npm install in it. It takes about a minute to complete, but will vary based on your internet connection speed.

[mraible:~/dev] 45s $ ng new ng2-demo
installing ng2
  create .editorconfig
  create README.md
  create src/app/app.component.css
  create src/app/app.component.html
  create src/app/app.component.spec.ts
  create src/app/app.component.ts
  create src/app/environment.ts
  create src/app/index.ts
  create src/app/shared/index.ts
  create src/favicon.ico
  create src/index.html
  create src/main.ts
  create src/system-config.ts
  create src/tsconfig.json
  create src/typings.d.ts
  create angular-cli-build.js
  create angular-cli.json
  create config/environment.dev.ts
  create config/environment.js
  create config/environment.prod.ts
  create config/karma-test-shim.js
  create config/karma.conf.js
  create config/protractor.conf.js
  create e2e/app.e2e-spec.ts
  create e2e/app.po.ts
  create e2e/tsconfig.json
  create e2e/typings.d.ts
  create .gitignore
  create package.json
  create public/.npmignore
  create tslint.json
  create typings.json
Successfully initialized git.
- Installing packages for tooling via npm
  -- es6-shim (global)
  -- angular-protractor (global dev)
  -- jasmine (global dev)
  -- selenium-webdriver (global dev)

Installed packages for tooling via npm.
[mraible:~/dev] 1m5s $

You can see the what version of Angular CLI you're using with ng --version.

$ ng --version
angular-cli: local (v1.0.0-beta.11-webpack.2, branch: master)
node: 4.4.7
os: darwin x64

Run the application

The project is configured with a simple web server for development. To start it, run:

ng serve

You should see a screen like the one below at http://localhost:4200.

You can make sure your new project's tests pass, run ng test:

$ ng test
Built project successfully. Stored in "dist/".
...
Chrome 52.0.2743 (Mac OS X 10.11.6): Executed 2 of 2 SUCCESS (0.039 secs / 0.012 secs)

Add a search feature

To add a search feature, open the project in an IDE or your favorite text editor. For IntelliJ IDEA, use File > New Project > Static Web and point to the ng2-demo directory.

The Basics

In a terminal window, cd into your project's directory and run the following command. This will create a search component.

$ ng g component search
installing component
  create src/app/search/search.component.css
  create src/app/search/search.component.html
  create src/app/search/search.component.spec.ts
  create src/app/search/search.component.ts
  create src/app/search/index.ts

Adding a Search Route
In previous versions of CLI, you could generate a route and a component. However, since beta 8, route generation has been disabled. This will likely be re-enabled in a future release.

The Router documentation for Angular 2 RC5 provides the information you need to setup a route to the SearchComponent you just generated. Here's a quick summary:

Create src/app/app.routing.ts to define your routes.

import { Routes, RouterModule } from '@angular/router';
import { SearchComponent } from './search/index';

const appRoutes: Routes = [
  { path: 'search', component: SearchComponent },
  { path: '', redirectTo: '/search', pathMatch: 'full' }
];

export const appRoutingProviders: any[] = [];

export const routing = RouterModule.forRoot(appRoutes);

Without the last path to redirect, there's a Cannot match any routes: '' console error.

In src/app/app.module.ts, import the two constants you exported and configure them in @NgModule:

import { routing, appRoutingProviders } from './app.routing';

import { SearchComponent } from './search/search.component';

@NgModule({
  ...
  imports: [
    ...
    routing
  ],
  providers: [appRoutingProviders],
  ...
})
export class AppModule { }

In src/app/app.component.html, add a RouterOutlet to display routes.

<!-- Routed views go here -->
<router-outlet></router-outlet>

Now that you have routing setup, you can continue writing the search feature.

To allow navigation to the SearchComponent, you can add a link in src/app/app.component.html.

<nav>
  <a routerLink="/search" routerLinkActive="active">Search</a>
</nav>

Open src/app/search/search.component.html and replace its default HTML with the following:

<h2>Search</h2>
<form>
  <input type="search" name="query" [(ngModel)]="query" (keyup.enter)="search()">
  <button type="button" (click)="search()">Search</button>
</form>
<pre>{{searchResults | json}}</pre>

If you still have ng serve running, your browser should refresh automatically. If not, navigate to http://localhost:4200, and you should see the search form.

If you want to add CSS for this components, open src/app/search/search.component.css and add some CSS. For example:

:host {
  display: block;
  padding: 0 20px;
}

This section has shown you how to generate a new component to a basic Angular 2 application with Angular CLI. The next section shows you how to create a use a JSON file and localStorage to create a fake API.

The Backend

To get search results, create a SearchService that makes HTTP requests to a JSON file. Start by generating a new service.

ng g service search

Move the generated search.service.ts and its test to app/shared/search. You will likely need to create this directory.

Then, create src/app/shared/search/data/people.json to hold your data.

[
  {
    "id": 1,
    "name": "Peyton Manning",
    "phone": "(303) 567-8910",
    "address": {
      "street": "1234 Main Street",
      "city": "Greenwood Village",
      "state": "CO",
      "zip": "80111"
    }
  },
  {
    "id": 2,
    "name": "Demaryius Thomas",
    "phone": "(720) 213-9876",
    "address": {
      "street": "5555 Marion Street",
      "city": "Denver",
      "state": "CO",
      "zip": "80202"
    }
  },
  {
    "id": 3,
    "name": "Von Miller",
    "phone": "(917) 323-2333",
    "address": {
      "street": "14 Mountain Way",
      "city": "Vail",
      "state": "CO",
      "zip": "81657"
    }
  }
]

Modify src/app/shared/search/search.service.ts and provide Http as a dependency in its constructor. In this same file, create a getAll() method to gather all the people. Also, define the Address and Person classes that JSON will be marshalled to.

import { Injectable } from '@angular/core';
import { Http, Response } from '@angular/http';

@Injectable()
export class SearchService {
  constructor(private http: Http) {}

  getAll() {
    return this.http.get('app/shared/search/data/people.json').map((res: Response) => res.json());
  }
}

export class Address {
  street: string;
  city: string;
  state: string;
  zip: string;

  constructor(obj?: any) {
    this.street = obj && obj.street || null;
    this.city = obj && obj.city || null;
    this.state = obj && obj.state || null;
    this.zip = obj && obj.zip || null;
  }
}

export class Person {
  id: number;
  name: string;
  phone: string;
  address: Address;

  constructor(obj?: any) {
    this.id = obj && Number(obj.id) || null;
    this.name = obj && obj.name || null;
    this.phone = obj && obj.phone || null;
    this.address = obj && obj.address || null;
  }
}

To make these classes available for consumption by your components, edit src/app/shared/index.ts and add the following:

export * from './search/search.service';

In search.component.ts, add imports for these classes.

import { Person, SearchService } from '../shared/index';

You can now add query and searchResults variables. While you're there, modify the constructor to inject the SearchService.

export class SearchComponent implements OnInit {
  query: string;
  searchResults: Array<Person>;

  constructor(private searchService: SearchService) {}

Then implement the search() method to call the service's getAll() method.

search(): void {
  this.searchService.getAll().subscribe(
    data => { this.searchResults = data; },
    error => console.log(error)
  );
}

At this point, you'll likely see the following message in your browser's console.

ORIGINAL EXCEPTION: No provider for SearchService!

To fix the "No provider" error from above, update app.component.ts to import the SearchService and add the service to the list of providers.

import { SearchService } from './shared/index';

@Component({
  ...
  styleUrls: ['app.component.css'],
  viewProviders: [SearchService]
})

Now clicking the search button should work. To make the results look better, remove the <pre> tag and replace it with a <table>.

<table *ngIf="searchResults">
  <thead>
  <tr>
    <th>Name</th>
    <th>Phone</th>
    <th>Address</th>
  </tr>
  </thead>
  <tbody>
  <tr *ngFor="let person of searchResults; let i=index">
    <td>{{person.name}}</td>
    <td>{{person.phone}}</td>
    <td>{{person.address.street}}<br/>
      {{person.address.city}}, {{person.address.state}} {{person.address.zip}}
    </td>
  </tr>
  </tbody>
</table>

Then add some additional CSS to improve its table layout.

table {
  margin-top: 10px;
  border-collapse: collapse;
}

th {
  text-align: left;
  border-bottom: 2px solid #ddd;
  padding: 8px;
}

td {
  border-top: 1px solid #ddd;
  padding: 8px;
}

Now the search results look better.

But wait, we still don't have search functionality! To add a search feature, add a search() method to SearchService.

search(q: string) {
  if (!q || q === '*') {
    q = '';
  } else {
    q = q.toLowerCase();
  }
  return this.getAll().map(data => {
    let results: any = [];
    data.map(item => {
      if (JSON.stringify(item).toLowerCase().includes(q)) {
        results.push(item);
      }
    });
    return results;
  });
}

Then refactor SearchComponent to call this method with its query variable.

search(): void {
  this.searchService.search(this.query).subscribe(
    data => { this.searchResults = data; },
    error => console.log(error)
  );
}

Now search results will be filtered by the query value you type in.

This section showed you how to fetch and display search results. The next section builds on this and shows how to edit and save a record.

Add an edit feature

Modify search.component.html to add a click handler for editing a person.

<td><a (click)="onSelect(person)">{{person.name}}</a></td>

In previous versions of Angular 2, you could embed a link with parameters directly into the HTML. For example:

<a [routerLink]="['/edit', person.id]">

Unfortunately, this doesn't work with RC5. Another issue is adding href="" causes the page to refresh. Without href, the link doesn't look like a link. If you know of a solution to this problem, please send me a pull request.

Then add onSelect(person) to search.component.ts. You'll need to import Router and set it as a local variable to make this work.

import { Router } from '@angular/router';
...
export class SearchComponent implements OnInit {
  ...

  constructor(private searchService: SearchService, private router: Router) { }

  ...

  onSelect(person: Person) {
    this.router.navigate(['/edit', person.id]);
  }
}

Run the following command to generate an EditComponent.

$ ng g component edit
installing component
  create src/app/edit/edit.component.css
  create src/app/edit/edit.component.html
  create src/app/edit/edit.component.spec.ts
  create src/app/edit/edit.component.ts
  create src/app/edit/index.ts

Add a route for this component in app.routing.ts:

import { EditComponent } from './edit/index';

const appRoutes: Routes = [
  { path: 'search', component: SearchComponent },
  { path: 'edit/:id', component: EditComponent },
  { path: '', redirectTo: '/search', pathMatch: 'full' }
];

Update src/app/edit/edit.component.html to display an editable form. You might notice I've added id attributes to most elements. This is to make things easier when writing integration tests with Protractor.

<div *ngIf="person">
  <h3>{{editName}}</h3>
  <div>
    <label>Id:</label>
    {{person.id}}
  </div>
  <div>
    <label>Name:</label>
    <input [(ngModel)]="editName" name="name" id="name" placeholder="name"/>
  </div>
  <div>
    <label>Phone:</label>
    <input [(ngModel)]="editPhone" name="phone" id="phone" placeholder="Phone"/>
  </div>
  <fieldset>
    <legend>Address:</legend>
    <address>
      <input [(ngModel)]="editAddress.street" id="street"><br/>
      <input [(ngModel)]="editAddress.city" id="city">,
      <input [(ngModel)]="editAddress.state" id="state" size="2">
      <input [(ngModel)]="editAddress.zip" id="zip" size="5">
    </address>
  </fieldset>
  <button (click)="save()" id="save">Save</button>
  <button (click)="cancel()" id="cancel">Cancel</button>
</div>

Modify EditComponent to import model and service classes and to use the SearchService to get data.

import { Component, OnInit, OnDestroy } from '@angular/core';
import { Address, Person, SearchService } from '../shared/index';
import { Subscription } from 'rxjs';
import { ActivatedRoute, Router } from '@angular/router';

@Component({
  selector: 'app-edit',
  templateUrl: 'edit.component.html',
  styleUrls: ['edit.component.css']
})
export class EditComponent implements OnInit, OnDestroy {
  person: Person;
  editName: string;
  editPhone: string;
  editAddress: Address;

  sub: Subscription;

  constructor(private route: ActivatedRoute,
              private router: Router,
              private service: SearchService) {
  }

  ngOnInit() {
    this.sub = this.route.params.subscribe(params => {
      let id = + params['id']; // (+) converts string 'id' to a number
      this.service.get(id).subscribe(person => {
        if (person) {
          this.editName = person.name;
          this.editPhone = person.phone;
          this.editAddress = person.address;
          this.person = person;
        } else {
          this.gotoList();
        }
      });
    });
  }

  ngOnDestroy() {
    this.sub.unsubscribe();
  }

  cancel() {
    this.router.navigate(['/search']);
  }

  save() {
    this.person.name = this.editName;
    this.person.phone = this.editPhone;
    this.person.address = this.editAddress;
    this.service.save(this.person);
    this.gotoList();
  }

  gotoList() {
    if (this.person) {
      this.router.navigate(['/search', {term: this.person.name} ]);
    } else {
      this.router.navigate(['/search']);
    }
  }
}

Modify SearchService to contain functions for finding a person by their id, and saving them. While you're in there, modify the search() method to be aware of updated objects in localStorage.

search(q: string) {
  if (!q || q === '*') {
    q = '';
  } else {
    q = q.toLowerCase();
  }
  return this.getAll().map(data => {
    let results: any = [];
    data.map(item => {
      // check for item in localStorage
      if (localStorage['person' + item.id]) {
        item = JSON.parse(localStorage['person' + item.id]);
      }
      if (JSON.stringify(item).toLowerCase().includes(q)) {
        results.push(item);
      }
    });
    return results;
  });
}

get(id: number) {
  return this.getAll().map(all => {
    if (localStorage['person' + id]) {
      return JSON.parse(localStorage['person' + id]);
    }
    return all.find(e => e.id === id);
  });
}

save(person: Person) {
  localStorage['person' + person.id] = JSON.stringify(person);
}

You can add CSS to src/app/edit/edit.component.css if you want to make the form look a bit better.

:host {
  display: block;
  padding: 0 20px;
}

button {
  margin-top: 10px;
}

At this point, you should be able to search for a person and update their information.

The <form> in src/app/edit/edit.component.html calls a save() function to update a person's data. You already implemented this above. The function calls a gotoList() function that appends the person's name to the URL when sending the user back to the search screen.

gotoList() {
  if (this.person) {
    this.router.navigate(['/search', {term: this.person.name} ]);
  } else {
    this.router.navigate(['/search']);
  }
}

Since the SearchComponent doesn't execute a search automatically when you execute this URL, add the following logic to do so in its constructor.

import { Router, ActivatedRoute } from '@angular/router';
import { Subscription } from 'rxjs';
...
  sub: Subscription;

  constructor(private searchService: SearchService, private router: Router, private route: ActivatedRoute) {
    this.sub = this.route.params.subscribe(params => {
      if (params['term']) {
        this.query = decodeURIComponent(params['term']);
        this.search();
      }
    });
  }

You'll want to implement OnDestroy and define the ngOnDestroy method to clean up this subscription.

import { Component, OnInit, OnDestroy } from '@angular/core';

export class SearchComponent implements OnInit, OnDestroy {
...
  ngOnDestroy() {
    this.sub.unsubscribe();
  }
}

After making all these changes, you should be able to search/edit/update a person's information. If it works - nice job!

Testing

Now that you've built an application, it's important to test it to ensure it works. The best reason for writing tests is to automate your testing. Without tests, you'll likely be testing manually. This manual testing will take longer and longer as your application grows.

In this section, you'll learn to use Jasmine for unit testing controllers and Protractor for integration testing. Angular's testing documentation lists good reasons to test, but doesn't currently have many examples.

Unit test the SearchService

Modify src/app/shared/search/search.service.spec.ts and setup the test's infrastructure using MockBackend and BaseRequestOptions.

import { MockBackend } from '@angular/http/testing';
import { Http, ConnectionBackend, BaseRequestOptions, Response, ResponseOptions } from '@angular/http';
import { SearchService } from './search.service';
import { tick, fakeAsync } from '@angular/core/testing/fake_async';
import { inject, TestBed } from '@angular/core/testing/test_bed';

describe('SearchService', () => {
  beforeEach(() => {

    TestBed.configureTestingModule({
      providers: [
        {
          provide: Http, useFactory: (backend: ConnectionBackend, defaultOptions: BaseRequestOptions) => {
          return new Http(backend, defaultOptions);
        }, deps: [MockBackend, BaseRequestOptions]
        },
        {provide: SearchService, useClass: SearchService},
        {provide: MockBackend, useClass: MockBackend},
        {provide: BaseRequestOptions, useClass: BaseRequestOptions}
      ]
    });
  });
});

If you run ng test, you will likely see some errors about the test stubs that Angular CLI created for you. You can ignore these for now.

ERROR in [default] /Users/mraible/ng2-demo/src/app/edit/edit.component.spec.ts:10:20
Supplied parameters do not match any signature of call target.

ERROR in [default] /Users/mraible/ng2-demo/src/app/search/search.component.spec.ts:10:20
Supplied parameters do not match any signature of call target.

Add the first test of getAll() to search.service.spec.ts. This test shows how MockBackend can be used to mock results and set the response.

TIP: When you are testing code that returns either a Promise or an RxJS Observable, you can use the fakeAsync helper to test that code as if it were synchronous. Promises are be fulfilled and Observables are notified immediately after you call tick().

The test below should be on the same level as beforeEach.

it('should retrieve all search results',
  inject([SearchService, MockBackend], fakeAsync((searchService: SearchService, mockBackend: MockBackend) => {
    let res: Response;
    mockBackend.connections.subscribe(c => {
      expect(c.request.url).toBe('app/shared/search/data/people.json');
      let response = new ResponseOptions({body: '[{"name": "John Elway"}, {"name": "Gary Kubiak"}]'});
      c.mockRespond(new Response(response));
    });
    searchService.getAll().subscribe((response) => {
      res = response;
    });
    tick();
    expect(res[0].name).toBe('John Elway');
  }))
);

Notice that tests continually run as you add them when using ng test. You can run tests once by using ng test --watch=false. You will likely see "Executed 5 of 5 (1 FAILED)" in your terminal. Add a couple more tests for filtering by search term and fetching by id.

it('should filter by search term',
  inject([SearchService, MockBackend], fakeAsync((searchService: SearchService, mockBackend: MockBackend) => {
    let res;
    mockBackend.connections.subscribe(c => {
      expect(c.request.url).toBe('app/shared/search/data/people.json');
      let response = new ResponseOptions({body: '[{"name": "John Elway"}, {"name": "Gary Kubiak"}]'});
      c.mockRespond(new Response(response));
    });
    searchService.search('john').subscribe((response) => {
      res = response;
    });
    tick();
    expect(res[0].name).toBe('John Elway');
  }))
);

it('should fetch by id',
  inject([SearchService, MockBackend], fakeAsync((searchService: SearchService, mockBackend: MockBackend) => {
    let res;
    mockBackend.connections.subscribe(c => {
      expect(c.request.url).toBe('app/shared/search/data/people.json');
      let response = new ResponseOptions({body: '[{"id": 1, "name": "John Elway"}, {"id": 2, "name": "Gary Kubiak"}]'});
      c.mockRespond(new Response(response));
    });
    searchService.search('2').subscribe((response) => {
      res = response;
    });
    tick();
    expect(res[0].name).toBe('Gary Kubiak');
  }))
);

Unit test the SearchComponent

To unit test the SearchComponent, create a MockSearchProvider that has spies. These allow you to spy on functions to check if they were called.

Create src/app/shared/search/mocks/search.service.ts and populate it with spies for each method, as well as methods to set the response and subscribe to results.

import { SpyObject } from './helper';
import { SearchService } from '../search.service';
import Spy = jasmine.Spy;

export class MockSearchService extends SpyObject {
  getAllSpy: Spy;
  getByIdSpy: Spy;
  searchSpy: Spy;
  saveSpy: Spy;
  fakeResponse: any;

  constructor() {
    super( SearchService );

    this.fakeResponse = null;
    this.getAllSpy = this.spy('getAll').andReturn(this);
    this.getByIdSpy = this.spy('get').andReturn(this);
    this.searchSpy = this.spy('search').andReturn(this);
    this.saveSpy = this.spy('save').andReturn(this);
  }

  subscribe(callback: any) {
    callback(this.fakeResponse);
  }

  setResponse(json: any): void {
    this.fakeResponse = json;
  }
}

In this same directory, create a helper.ts class to implement the SpyObject that MockSearchService extends.

import {StringMapWrapper} from '@angular/core/src/facade/collection';

export interface GuinessCompatibleSpy extends jasmine.Spy {
  /** By chaining the spy with and.returnValue, all calls to the function will return a specific
   * value. */
  andReturn(val: any): void;
  /** By chaining the spy with and.callFake, all calls to the spy will delegate to the supplied
   * function. */
  andCallFake(fn: Function): GuinessCompatibleSpy;
  /** removes all recorded calls */
  reset();
}

export class SpyObject {
  static stub(object = null, config = null, overrides = null) {
    if (!(object instanceof SpyObject)) {
      overrides = config;
      config = object;
      object = new SpyObject();
    }

    let m = StringMapWrapper.merge(config, overrides);
    StringMapWrapper.forEach(m, (value, key) => { object.spy(key).andReturn(value); });
    return object;
  }

  constructor(type = null) {
    if (type) {
      for (let prop in type.prototype) {
        let m = null;
        try {
          m = type.prototype[prop];
        } catch (e) {
          // As we are creating spys for abstract classes,
          // these classes might have getters that throw when they are accessed.
          // As we are only auto creating spys for methods, this
          // should not matter.
        }
        if (typeof m === 'function') {
          this.spy(prop);
        }
      }
    }
  }

  spy(name) {
    if (!this[name]) {
      this[name] = this._createGuinnessCompatibleSpy(name);
    }
    return this[name];
  }

  prop(name, value) { this[name] = value; }

  /** @internal */
  _createGuinnessCompatibleSpy(name): GuinessCompatibleSpy {
    let newSpy: GuinessCompatibleSpy = <any>jasmine.createSpy(name);
    newSpy.andCallFake = <any>newSpy.and.callFake;
    newSpy.andReturn = <any>newSpy.and.returnValue;
    newSpy.reset = <any>newSpy.calls.reset;
    // revisit return null here (previously needed for rtts_assert).
    newSpy.and.returnValue(null);
    return newSpy;
  }
}

Alongside, create routes.ts to mock Angular's Router and ActivatedRoute.

import { ActivatedRoute, Params } from '@angular/router';
import { Observable } from 'rxjs';

export class MockActivatedRoute extends ActivatedRoute {
  params: Observable<Params>

  constructor(parameters?: { [key: string]: any; }) {
    super();
    this.params = Observable.of(parameters);
  }
}

export class MockRouter {
  navigate = jasmine.createSpy('navigate');
}

With mocks in place, you can TestBed.configureTestingModule() to setup SearchComponent to use these as providers.

import { ActivatedRoute, Router } from '@angular/router';
import { MockActivatedRoute, MockRouter } from '../shared/search/mocks/routes';
import { MockSearchService } from '../shared/search/mocks/search.service';
import { SearchComponent } from './search.component';
import { TestBed } from '@angular/core/testing/test_bed';
import { FormsModule } from '@angular/forms';
import { SearchService } from '../shared/search/search.service';

describe('Component: Search', () => {
  let mockSearchService: MockSearchService;
  let mockActivatedRoute: MockActivatedRoute;
  let mockRouter: MockRouter;

  beforeEach(() => {
    mockSearchService = new MockSearchService();
    mockActivatedRoute = new MockActivatedRoute({'term': 'peyton'});
    mockRouter = new MockRouter();

    TestBed.configureTestingModule({
      declarations: [SearchComponent],
      providers: [
        {provide: SearchService, useValue: mockSearchService},
        {provide: ActivatedRoute, useValue: mockActivatedRoute},
        {provide: Router, useValue: mockRouter}
      ],
      imports: [FormsModule]
    });
  });
});

Add two tests, one to verify a search term is used when it's set on the component, and a second to verify search is called when a term is passed in as a route parameter.

it('should search when a term is set and search() is called', () => {
  let fixture = TestBed.createComponent(SearchComponent);
  let searchComponent = fixture.debugElement.componentInstance;
  searchComponent.query = 'M';
  searchComponent.search();
  expect(mockSearchService.searchSpy).toHaveBeenCalledWith('M');
});

it('should search automatically when a term is on the URL', () => {
  let fixture = TestBed.createComponent(SearchComponent);
  fixture.detectChanges();
  expect(mockSearchService.searchSpy).toHaveBeenCalledWith('peyton');
});

After adding these tests, you should see the first instance of all tests passing (Executed 8 of 8 SUCCESS).

Update the test for EditComponent, verifying fetching a single record works. Notice how you can access the component directly with fixture.debugElement.componentInstance, or its rendered version with fixture.debugElement.nativeElement.

import { MockSearchService } from '../shared/search/mocks/search.service';
import { EditComponent } from './edit.component';
import { TestBed } from '@angular/core/testing/test_bed';
import { SearchService } from '../shared/search/search.service';
import { MockRouter, MockActivatedRoute } from '../shared/search/mocks/routes';
import { ActivatedRoute, Router } from '@angular/router';
import { FormsModule } from '@angular/forms';

describe('Component: Edit', () => {
  let mockSearchService: MockSearchService;
  let mockActivatedRoute: MockActivatedRoute;
  let mockRouter: MockRouter;

  beforeEach(() => {
    mockSearchService = new MockSearchService();
    mockActivatedRoute = new MockActivatedRoute({'id': 1});
    mockRouter = new MockRouter();

    TestBed.configureTestingModule({
      declarations: [EditComponent],
      providers: [
        {provide: SearchService, useValue: mockSearchService},
        {provide: ActivatedRoute, useValue: mockActivatedRoute},
        {provide: Router, useValue: mockRouter}
      ],
      imports: [FormsModule]
    });
  });

  it('should fetch a single record', () => {
    const fixture = TestBed.createComponent(EditComponent);

    let person = {name: 'Emmanuel Sanders', address: {city: 'Denver'}};
    mockSearchService.setResponse(person);

    fixture.detectChanges();
    // verify service was called
    expect(mockSearchService.getByIdSpy).toHaveBeenCalledWith(1);

    // verify data was set on component when initialized
    let editComponent = fixture.debugElement.componentInstance;
    expect(editComponent.editAddress.city).toBe('Denver');

    // verify HTML renders as expected
    let compiled = fixture.debugElement.nativeElement;
    expect(compiled.querySelector('h3').innerHTML).toBe('Emmanuel Sanders');
  });
});

You should see "Executed 8 of 8 SUCCESS (0.238 secs / 0.259 secs)" in the shell window that's running ng test. If you don't, try cancelling the command and restarting.

Integration test the search UI

To test if the application works end-to-end, you can write tests with Protractor. These are also known as integration tests, since they test the integration between all layers of your application.

To verify end-to-end tests work in the project before you begin, run the following commands in three different console windows.

ng serve
ng e2e

All tests should pass.

$ ng e2e

> ng2-demo@0.0.0 pree2e /Users/mraible/dev/ng2-demo
> webdriver-manager update

Updating selenium standalone to version 2.52.0
downloading https://selenium-release.storage.googleapis.com/2.52/selenium-server-standalone-2.52.0.jar...
Updating chromedriver to version 2.21
downloading https://chromedriver.storage.googleapis.com/2.21/chromedriver_mac32.zip...
chromedriver_2.21mac32.zip downloaded to /Users/mraible/dev/ng2-demo/node_modules/protractor/selenium/chromedriver_2.21mac32.zip
selenium-server-standalone-2.52.0.jar downloaded to /Users/mraible/dev/ng2-demo/node_modules/protractor/selenium/selenium-server-standalone-2.52.0.jar

> ng2-demo@0.0.0 e2e /Users/mraible/dev/ng2-demo
> protractor "config/protractor.conf.js"

[00:01:07] I/direct - Using ChromeDriver directly...
[00:01:07] I/launcher - Running 1 instances of WebDriver
Spec started

  ng2-demo App
    ✔ should display message saying app works

Executed 1 of 1 spec SUCCESS in 0.684 sec.
[00:01:09] I/launcher - 0 instance(s) of WebDriver still running
[00:01:09] I/launcher - chrome #01 passed

All end-to-end tests pass.

Testing the search feature

Create end-to-end tests in e2e/search.e2e-spec.ts to verify the search feature works. Populate it with the following code:

describe('Search', () => {

  beforeEach(() => {
    browser.get('/search');
    element(by.linkText('Search')).click();
  });

  it('should have an input and search button', () => {
    expect(element(by.css('app-root app-search form input')).isPresent()).toEqual(true);
    expect(element(by.css('app-root app-search form button')).isPresent()).toEqual(true);
  });

  it('should allow searching', () => {
    let searchButton = element(by.css('button'));
    let searchBox = element(by.css('input'));
    searchBox.sendKeys('M');
    searchButton.click().then(() => {
      var list = element.all(by.css('app-search table tbody tr'));
      expect(list.count()).toBe(3);
    });
  });
});

Testing the edit feature

Create a e2e/edit.e2e-spec.ts test to verify the EditComponent renders a person's information and that their information can be updated.

describe('Edit', () => {

  beforeEach(() => {
    browser.get('/edit/1');
  });

  let name = element(by.id('name'));
  let street = element(by.id('street'));
  let city = element(by.id('city'));

  it('should allow viewing a person', () => {
    expect(element(by.css('h3')).getText()).toEqual('Peyton Manning');
    expect(name.getAttribute('value')).toEqual('Peyton Manning');
    expect(street.getAttribute('value')).toEqual('1234 Main Street');
    expect(city.getAttribute('value')).toEqual('Greenwood Village');
  });

  it('should allow updating a name', function () {
    let save = element(by.id('save'));
    // send individual characters since sendKeys passes partial values sometimes
    // https://github.com/angular/protractor/issues/698
    ' Won!'.split('').forEach((c) => name.sendKeys(c));
    save.click();
    // verify one element matched this change
    var list = element.all(by.css('app-search table tbody tr'));
    expect(list.count()).toBe(1);
  });
});

Run ng e2e to verify all your end-to-end tests pass. You should see a success message similar to the one below in your terminal window.

If you made it this far and have all your specs passing - congratulations! You're well on your way to writing quality code with Angular 2 and verifying it works.

You can see the test coverage of your project by opening coverage/index.html in your browser. You might notice that the new components and service could use some additional coverage. If you feel the need to improve this coverage, please send me a pull request!

Continuous Integration

At the time of this writing, Angular CLI did not have any continuous integration support. However, it's easy to add with Travis CI. If you've checked in your project to GitHub, you can easily use Travis CI. Simply login and enable builds for the GitHub repo you created the project in. Then add the following .travis.yml in your root directory and git push. This will trigger the first build.

language: node_js
sudo: true

cache:
  directories:
    - node
    - node_modules

dist: trusty

node_js:
  - '5.6.0'

branches:
  only:
  - master

before_install:
 - npm install -g angular-cli
 - export CHROME_BIN=/usr/bin/google-chrome
 - export DISPLAY=:99.0
 - sh -e /etc/init.d/xvfb start
 - sudo apt-get update
 - sudo apt-get install -y libappindicator1 fonts-liberation
 - wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
 - sudo dpkg -i google-chrome*.deb

script:
 - ng test --watch false # http://mseemann.de/frontend/2016/05/31/setup-angular-2-app-part-1.html
 - ng serve &
 - ng e2e

notifications:
  webhooks:
    on_success: change  # options: [always|never|change] default: always
    on_failure: always  # options: [always|never|change] default: always
    on_start: false     # default: false

Here is a build showing all unit and integration tests passing.

Source code

A completed project with this code in it is available on GitHub at https://github.com/mraible/ng2-demo. If you have ideas for improvements, please leave a comment or send a pull request.

This tutorial was originally written using Asciidoctor. This means you can read it using DocGist if you like.

Summary

I hope you've enjoyed this in-depth tutorial on how to get started with Angular 2 and Angular CLI. Angular CLI takes much of the pain out of setting up an Angular 2 project and using Typescript. I expect great things from Angular CLI, mostly because the Angular 2 setup process can be tedious and CLI greatly simplifies things.

Testing Angular 2.0 RC1 Applications

Matt Raible — Mon, 6 Jun 2016 09:57:13 -0600

As mentioned on Friday, there's been quite a bit that's changed with Angular 2 between its Beta 9 and RC 1 releases. This article is an update to the Testing Angular 2 Applications I wrote in March. That tutorial was based on Angular 2.0 Beta 9. Rather than simply updating that tutorial and blog post for 2.0 RC1, I decided to create a new version for posterity's sake. The 2.0 Beta 9 version will remain on my blog and I've tagged the source on GitHub.

If you've already read the first version of Testing Angular 2 Applications, checkout the diff of the Asciidoctor version to see what's changed.

What you'll build

You'll learn to use Jasmine for unit testing controllers and Protractor for integration testing. See Angular 2's guide to unit testing if you'd like more information on testing and why it's important.

The best reason for writing tests is to automate your testing. Without tests, you'll likely be testing manually. This manual testing will take longer and longer as your codebase grows.

What you'll need

About 15-30 minutes.
A favorite text editor or IDE. I recommend IntelliJ IDEA.
Git installed.
Node.js and npm installed. I recommend using nvm.

Get the tutorial project

Clone the angular2-tutorial repository, checkout the testing-start branch, and install its dependencies.

git clone https://github.com/mraible/angular2-tutorial.git
cd angular2-tutorial
git checkout testing-start
npm install

If you haven't completed the Getting Started with Angular 2.0 RC1 tutorial, you should peruse it so you understand how this application works. You can also simply start the app with npm start and view it in your browser at http://localhost:5555/.

Unit test the SearchService

Create src/client/app/shared/search/search.service.spec.ts and setup the test's infrastructure using MockBackend and BaseRequestOptions.

import {
  beforeEachProviders,
  it,
  describe,
  expect,
  inject,
  fakeAsync,
  tick
} from '@angular/core/testing';
import { MockBackend } from '@angular/http/testing';
import { provide } from '@angular/core';
import { Http, ConnectionBackend, BaseRequestOptions, Response, ResponseOptions } from '@angular/http';
import { SearchService } from './search.service';

export function main() {
  describe('Search Service', () => {
    beforeEachProviders(() => {
      return [BaseRequestOptions, MockBackend, SearchService,
        provide(Http, {
          useFactory: (backend:ConnectionBackend, defaultOptions:BaseRequestOptions) => {
            return new Http(backend, defaultOptions);
          }, deps: [MockBackend, BaseRequestOptions]
        }),
      ];
    });
  });
}

If you run npm test, all tests will pass, but you don't see "Search Service" as a listed test. You can fix this by adding the first test of getAll(). This test shows how MockBackend can be used to mock results and set the response.

TIP: When you are testing code that returns either a Promise or an RxJS Observable, you can use the fakeAsync helper to test that code as if it were synchronous. Promises are be fulfilled and Observables are notified immediately after you call tick().

The test below should be on the same level as beforeEachProviders.

it('should retrieve all search results',
  inject([SearchService, MockBackend], fakeAsync((searchService:SearchService, mockBackend:MockBackend) => {
    var res:Response;
    mockBackend.connections.subscribe(c => {
      expect(c.request.url).toBe('app/shared/search/data/people.json');
      let response = new ResponseOptions({body: '[{"name": "John Elway"}, {"name": "Gary Kubiak"}]'});
      c.mockRespond(new Response(response));
    });
    searchService.getAll().subscribe((response) => {
      res = response;
    });
    tick();
    expect(res[0].name).toBe('John Elway');
  }))
);

Running npm test should result in "12 tests completed". Add a couple more tests for filtering by search term and fetching by id.

it('should filter by search term',
  inject([SearchService, MockBackend], fakeAsync((searchService:SearchService, mockBackend:MockBackend) => {
    var res;
    mockBackend.connections.subscribe(c => {
      expect(c.request.url).toBe('app/shared/search/data/people.json');
      let response = new ResponseOptions({body: '[{"name": "John Elway"}, {"name": "Gary Kubiak"}]'});
      c.mockRespond(new Response(response));
    });
    searchService.search('john').subscribe((response) => {
      res = response;
    });
    tick();
    expect(res[0].name).toBe('John Elway');
  }))
);

it('should fetch by id',
  inject([SearchService, MockBackend], fakeAsync((searchService:SearchService, mockBackend:MockBackend) => {
    var res;
    mockBackend.connections.subscribe(c => {
      expect(c.request.url).toBe('app/shared/search/data/people.json');
      let response = new ResponseOptions({body: '[{"id": 1, "name": "John Elway"}, {"id": 2, "name": "Gary Kubiak"}]'});
      c.mockRespond(new Response(response));
    });
    searchService.search('2').subscribe((response) => {
      res = response;
    });
    tick();
    expect(res[0].name).toBe('Gary Kubiak');
  }))
);

If you want to have tests continually run as you add them, you can run the following commands in separate shell windows.

npm run build.test.watch
npm run karma.start

NOTE: See Running Unit Tests on Karma to learn how to run your tests from IntelliJ IDEA.

Unit test the SearchComponent

To unit test the SearchComponent, create a MockSearchProvider that has spies. These allow you to spy on functions to check if they were called.

Create src/client/app/shared/search/mocks/search.service.ts and populate it with spies for each method, as well as methods to set the response and subscribe to results.

import { provide } from '@angular/core';
import { SpyObject } from './helper';

import { SearchService } from '../search.service';
import Spy = jasmine.Spy;

export class MockSearchService extends SpyObject {
  getAllSpy:Spy;
  getByIdSpy:Spy;
  searchSpy:Spy;
  saveSpy:Spy;
  fakeResponse:any;

  constructor() {
    super(SearchService);

    this.fakeResponse = null;
    this.getAllSpy = this.spy('getAll').andReturn(this);
    this.getByIdSpy = this.spy('get').andReturn(this);
    this.searchSpy = this.spy('search').andReturn(this);
    this.saveSpy = this.spy('save').andReturn(this);
  }

  subscribe(callback:any) {
    callback(this.fakeResponse);
  }

  setResponse(json:any):void {
    this.fakeResponse = json;
  }

  getProviders():Array<any> {
    return [provide(SearchService, {useValue: this})];
  }
}

In this same directory, create a helper.ts class to implement the SpyObject that MockSearchService extends.

import {StringMapWrapper} from '@angular/core/src/facade/collection';

export interface GuinessCompatibleSpy extends jasmine.Spy {
  /** By chaining the spy with and.returnValue, all calls to the function will return a specific
   * value. */
  andReturn(val: any): void;
  /** By chaining the spy with and.callFake, all calls to the spy will delegate to the supplied
   * function. */
  andCallFake(fn: Function): GuinessCompatibleSpy;
  /** removes all recorded calls */
  reset();
}

export class SpyObject {
  static stub(object = null, config = null, overrides = null) {
    if (!(object instanceof SpyObject)) {
      overrides = config;
      config = object;
      object = new SpyObject();
    }

    var m = StringMapWrapper.merge(config, overrides);
    StringMapWrapper.forEach(m, (value, key) => { object.spy(key).andReturn(value); });
    return object;
  }

  constructor(type = null) {
    if (type) {
      for (var prop in type.prototype) {
        var m = null;
        try {
          m = type.prototype[prop];
        } catch (e) {
          // As we are creating spys for abstract classes,
          // these classes might have getters that throw when they are accessed.
          // As we are only auto creating spys for methods, this
          // should not matter.
        }
        if (typeof m === 'function') {
          this.spy(prop);
        }
      }
    }
  }

  spy(name) {
    if (!this[name]) {
      this[name] = this._createGuinnessCompatibleSpy(name);
    }
    return this[name];
  }

  prop(name, value) { this[name] = value; }

  /** @internal */
  _createGuinnessCompatibleSpy(name): GuinessCompatibleSpy {
    var newSpy: GuinessCompatibleSpy = <any>jasmine.createSpy(name);
    newSpy.andCallFake = <any>newSpy.and.callFake;
    newSpy.andReturn = <any>newSpy.and.returnValue;
    newSpy.reset = <any>newSpy.calls.reset;
    // revisit return null here (previously needed for rtts_assert).
    newSpy.and.returnValue(null);
    return newSpy;
  }
}

Alongside, create routes.ts to mock Angular's RouteSegment and passing parameters between components.

import { RouteSegment } from '@angular/router';

export class MockRouteSegment implements RouteSegment {
  urlSegments:any;
  parameters:any;
  outlet:string;
  _type:any;
  _componentFactory:any;
  type:any;
  stringifiedUrlSegments:string;

  constructor(parameters?:{ [key:string]:any; }) {
    this.parameters = parameters;
  }

  getParam(param:string) {
    return this.parameters[param];
  }
}

With mocks in place, you can create a spec for SearchComponent that uses these as providers. Create a file at src/search/components/search.component.spec.ts and populate it with the following code.

import { provide } from '@angular/core';
import { TestComponentBuilder } from '@angular/compiler/testing';
import {
  it,
  describe,
  expect,
  inject,
  beforeEachProviders,
} from '@angular/core/testing';

import { RouteSegment } from '@angular/router';
import { MockRouteSegment } from '../shared/search/mocks/routes';
import { MockSearchService } from '../shared/search/mocks/search.service';

import { SearchComponent } from './search.component';

export function main() {
  describe('Search component', () => {
    var mockSearchService:MockSearchService;

    beforeEachProviders(() => {
      mockSearchService = new MockSearchService();

      return [
        mockSearchService.getProviders(),
        provide(RouteSegment, { useValue: new MockRouteSegment({ 'term': 'peyton' }) })
      ];
    });
  });
}

Add two tests, one to verify a search term is used when it's set on the component and a second to verify search is called when a term is passed in as a route parameter.

it('should search when a term is set and search() is called', inject([TestComponentBuilder], (tcb:TestComponentBuilder) => {
  return tcb.createAsync(SearchComponent).then((fixture) => {
    let searchComponent = fixture.debugElement.componentInstance;
    searchComponent.query = 'M';
    searchComponent.search();
    expect(mockSearchService.searchSpy).toHaveBeenCalledWith('M');
  });
}));

it('should search automatically when a term is on the URL', inject([TestComponentBuilder], (tcb:TestComponentBuilder) => {
  return tcb.createAsync(SearchComponent).then((fixture) => {
    fixture.detectChanges();
    expect(mockSearchService.searchSpy).toHaveBeenCalledWith('peyton');
  });
}));

Add a spec for the EditComponent as well, verifying fetching a single record works. Notice how you can access the component directly with fixture.debugElement.componentInstance, or its rendered version with fixture.debugElement.nativeElement. Create a file at src/search/components/edit.component.spec.ts and populate it with the code below.

import { provide } from '@angular/core';
import { TestComponentBuilder } from '@angular/compiler/testing';
import {
  it,
  describe,
  expect,
  inject,
  beforeEachProviders,
} from '@angular/core/testing';

import { RouteSegment } from '@angular/router';
import { ROUTER_FAKE_PROVIDERS } from '@angular/router/testing';
import { MockRouteSegment } from '../shared/search/mocks/routes';
import { MockSearchService } from '../shared/search/mocks/search.service';

import { EditComponent } from './edit.component';

export function main() {
  describe('Edit component', () => {
    var mockSearchService:MockSearchService;

    beforeEachProviders(() => {
      mockSearchService = new MockSearchService();

      return [
        mockSearchService.getProviders(),
        ROUTER_FAKE_PROVIDERS,
        provide(RouteSegment, { useValue: new MockRouteSegment({ 'id': '1' }) })
      ];
    });

    it('should fetch a single record', inject([TestComponentBuilder], (tcb:TestComponentBuilder) => {
      return tcb.createAsync(EditComponent).then((fixture) => {
        let person = {name: 'Emmanuel Sanders', address: {city: 'Denver'}};
        mockSearchService.setResponse(person);

        fixture.detectChanges();
        // verify service was called
        expect(mockSearchService.getByIdSpy).toHaveBeenCalledWith(1);

        // verify data was set on component when initialized
        let editComponent = fixture.debugElement.componentInstance;
        expect(editComponent.editAddress.city).toBe('Denver');

        // verify HTML renders as expected
        var compiled = fixture.debugElement.nativeElement;
        expect(compiled.querySelector('h3')).toHaveText('Emmanuel Sanders');
      });
    }));
  });
}

You should see "✔ 22 tests completed" in the shell window that's running npm run karma.start. If you don't, try cancelling the command and restarting.

Integration test the search UI

To test if the application works end-to-end, you can write tests with Protractor. These are also known as integration tests, since they test the integration between all layers of your application.

To verify end-to-end tests work in the project before you begin, run the following commands in three different console windows.

# npm run webdriver-update <- You will need to run this the first time
npm run webdriver-start
npm run serve.e2e
npm run e2e

You should receive an error stating that the "nav text for About" is incorrect.

This happens because we added a Search link to the navbar and didn't update the test (in app.component.e2e.ts) that looks for the last child.

it('should have correct nav text for About', () => {
    expect(element(by.css('sd-app sd-navbar nav a:last-child')).getText()).toEqual('ABOUT');
});

Replace this test with the one below, and add a new one to verify the Search link is last.

it('should have correct nav text for About', () => {
  expect(element(by.css('sd-app sd-navbar nav a:nth-child(2)')).getText()).toEqual('ABOUT');
});

it('should have correct nav text for Search', () => {
  expect(element(by.css('sd-app sd-navbar nav a:last-child')).getText()).toEqual('SEARCH');
});

Now when you run npm run e2e, all specs should pass.

Testing the search feature

Create a new search.component.e2e-spec.ts spec in the same directory as your SearchComponent. Add tests to verify elements are rendered correctly and search works. At the time of this writing, Protractor's by.model and by.repeater don't work with Angular 2. For this reason, I used by.css to verify the HTML renders as expected.

describe('Search', () => {

  beforeEach(() => {
    browser.get('/search');
  });

  it('should have an input and search button', () => {
    expect(element(by.css('sd-app sd-search form input')).isPresent()).toEqual(true);
    expect(element(by.css('sd-app sd-search form button')).isPresent()).toEqual(true);
  });

  it('should allow searching', () => {
    let searchButton = element(by.css('button'));
    let searchBox = element(by.css('input'));
    searchBox.sendKeys('M');
    searchButton.click().then(() => {
      // doesn't work as expected - results in 0
      //expect(element.all(by.repeater('person of searchResults')).count()).toEqual(3);
      var list = element.all(by.css('sd-search table tbody tr'));
      expect(list.count()).toBe(3);
    });
  });
});

Testing the edit feature

Create a edit.component.e2e-spec.ts spec to verify the EditComponent renders a person's information and that you can update their information.

describe('Edit', () => {

  beforeEach(() => {
    browser.get('/edit/1');
  });

  let name = element(by.id('name'));
  let street = element(by.id('street'));
  let city = element(by.id('city'));

  it('should allow viewing a person', () => {
    expect(element(by.css('h3')).getText()).toEqual('Peyton Manning');
    expect(name.getAttribute('value')).toEqual('Peyton Manning');
    expect(street.getAttribute('value')).toEqual('1234 Main Street');
    expect(city.getAttribute('value')).toEqual('Greenwood Village');
  });

  it('should allow updating a name', function () {
    let save = element(by.id('save'));
    // send individual characters since sendKeys passes partial values sometimes
    // https://github.com/angular/protractor/issues/698
    ' Won!'.split('').forEach((c) => name.sendKeys(c));
    save.click();
    // verify one element matched this change
    var list = element.all(by.css('sd-search table tbody tr'));
    expect(list.count()).toBe(1);
  });
});

Run npm run e2e to verify all your end-to-end tests pass. You might receive a failure for the "Home" test.

If you do, open src/client/app/+home/home.component.e2e-spec.ts and change line 17 from this:

element(by.css('sd-home form input')).sendKeys('Tim Berners-Lee');

To this:

let input = element(by.css('sd-home form input'));
'Tim Berners-Lee'.split('').forEach((c) => input.sendKeys(c));

Run npm run e2e again. You should see a success message similar to the one below in your terminal window.

If you made it this far and have all 13 specs passing - congratulations! You're well on your way to writing quality code with Angular 2 and verifying it works.

Continuous Integration

The angular2-seed project ships with a .travis.yml that you can use to run continuous integration for this application through Travis CI. To enable builds on Travis CI, login and enable builds for the GitHub repo you created the project in. Then trigger your first build with a git push.

When I first tried this, I received a failure because Protractor on Travis CI is unable to navigate directly to the search and edit components. I was able to workaround this by modifying search.component.e2e-spec.ts to start at the top and navigate to the component.

beforeEach(() => {
  browser.get('/');
  element(by.linkText('SEARCH')).click();
});

I did something similar with edit.component.e2e-spec.ts:

beforeEach(() => {
  browser.get('/');
  element(by.linkText('SEARCH')).click();
  let search = element(by.css('sd-search form input'));
  'Man'.split('').forEach((c) => search.sendKeys(c));
  element(by.css('sd-search form button')).click();
  element(by.linkText('Peyton Manning')).click();
});

After making these changes, all e2e tests passed in Travis CI.

Source code

A completed project with this code in it is available on GitHub at https://github.com/mraible/angular2-tutorial. If you have ideas for improvements, please leave a comment or send a pull request.

I wrote this tutorial in Asciidoctor so you can also read this tutorial on GitHub or using DocGist.

Summary

I hope you've enjoyed this quick-and-easy tutorial on testing Angular 2.0 RC1 applications. You can see the test coverage of your project by running npm run serve.coverage. You'll notice that the new components and service could use some additional coverage. I'll leave that as a task for the reader.

I learned a lot about testing from ng-book 2 and its Testing chapter. If you have any Angular 2 testing tips and tricks you'd like to share, I'd love to hear about them.

Getting Started with Angular 2.0 RC1

Matt Raible — Fri, 3 Jun 2016 07:16:18 -0600

A few months ago, I wrote a tutorial on Getting Started with Angular 2. That tutorial was based on Angular 2.0.0 Beta 9. Rather than simply updating that tutorial and blog post for 2.0.0 RC1, I decided to create a new version for posterity's sake. The 2.0 Beta 9 version will remain on my blog and I've tagged the source on GitHub. This is an updated version of Getting Started with Angular 2, complete with the largely undocumented component router, and lazy-loaded components.

If you'd just like to see what's changed since the last release of this tutorial, you can view the pull request on GitHub. Note that I did sync my angular2-tutorial project with angular2-seed. This made it fairly easy to upgrade, believe it or not. My upgrade notes are in a gist. The best diff to read to see what changed is likely the diff of this tutorial.

What you'll build

You'll build a simple web application with Angular 2 and TypeScript. You'll add search and edit features with mock data.

What you'll need

About 15-30 minutes.
A favorite text editor or IDE. I recommend IntelliJ IDEA.
Git installed.
Node.js and npm installed. I recommend using nvm.

Create your project

Clone the angular2-seed repository using git:

git clone https://github.com/mgechev/angular2-seed.git angular2-tutorial
cd angular2-tutorial

NOTE: The angular2-seed project requires node v4.x.x or higher and npm 2.14.7. I used node v4.2.6 and npm 3.9.3.

Install the project's dependencies:

npm install

Run the application

The project is configured with a simple web server for development. To start it, run:

npm start

You should see a screen like the one below at http://localhost:5555.

You can see your new project's test coverage by running npm test:

=============================== Coverage summary ===============================
Statements   : 96.36% ( 159/165 )
Branches     : 62.5% ( 120/192 )
Functions    : 100% ( 35/35 )
Lines        : 100% ( 129/129 )
================================================================================

Add a search feature

To add a search feature, open the project in an IDE or your favorite text editor. For IntelliJ IDEA, use File > New Project > Static Web and point to the directory you cloned angular2-seed to.

The Basics

Create a src/client/app/+search folder and a search.component.html file in it. The + prefix is an indicator to Angular that you want to lazy-load the components in this directory. Populate the HTML file you created with the following:

<h2>Search</h2>
<form>
  <input type="search" [(ngModel)]="query" (keyup.enter)="search()">
  <button type="button" (click)="search()">Search</button>
</form>
<div *ngIf="loading">loading...</div>
<pre>{{searchResults | json}}</pre>

Create src/client/app/+search/search.component.ts to define the SearchComponent and point to this template.

import { Component } from '@angular/core';
import { CORE_DIRECTIVES, FORM_DIRECTIVES } from '@angular/common';
import { ROUTER_DIRECTIVES } from '@angular/router';

@Component({
  selector: 'sd-search',
  moduleId: module.id,
  templateUrl: 'search.component.html',
  directives: [FORM_DIRECTIVES, CORE_DIRECTIVES, ROUTER_DIRECTIVES]
})
export class SearchComponent {
  loading: boolean;
  query: string;
  searchResults: any;

  constructor() {
    console.log('initialized search component');
  }
}

Create src/client/app/+search/index.ts to export SearchComponent.

/**
* This barrel file provides the export for the lazy loaded SearchComponent.
*/
export * from './search.component';

Update src/client/app/app.component.ts to import this component and include its route.

import { SearchComponent } from './+search/index';

@Routes([
  { path: '/', component: HomeComponent },
  { path: '/about', component: AboutComponent },
  { path: '/search', component: SearchComponent }
])

Your browser should refresh automatically, thanks to Browsersync. Navigate to http://localhost:5555/search and you should see the search component.

You can see it needs a bit of styling. Angular 2 allows you to provide styles specific for your component using a styleUrls property on your component. Add this property to search.component.ts like you see below.

templateUrl: 'search.component.html',
styleUrls: ['search.component.css'],
directives: [FORM_DIRECTIVES, CORE_DIRECTIVES, ROUTER_DIRECTIVES]

Create src/client/app/+search/search.component.css and add some CSS.

:host {
  display: block;
  padding: 0 16px;
}

There, that looks better!

Finally, update src/client/app/shared/navbar/navbar.component.html to include a link to the search route.

<nav>
  <a [routerLink]="['/']">HOME</a>
  <a [routerLink]="['/about']">ABOUT</a>
  <a [routerLink]="['/search']">SEARCH</a>
</nav>

This section has shown you how to add a new component to a basic Angular 2 application. The next section shows you how to create a use a JSON file and localStorage to create a fake API.

The Backend

To get search results, create a SearchService that makes HTTP requests to a JSON file. Start by creating src/client/app/shared/search/data/people.json to hold your data.

[
  {
    "id": 1,
    "name": "Peyton Manning",
    "phone": "(303) 567-8910",
    "address": {
      "street": "1234 Main Street",
      "city": "Greenwood Village",
      "state": "CO",
      "zip": "80111"
    }
  },
  {
    "id": 2,
    "name": "Demaryius Thomas",
    "phone": "(720) 213-9876",
    "address": {
      "street": "5555 Marion Street",
      "city": "Denver",
      "state": "CO",
      "zip": "80202"
    }
  },
  {
    "id": 3,
    "name": "Von Miller",
    "phone": "(917) 323-2333",
    "address": {
      "street": "14 Mountain Way",
      "city": "Vail",
      "state": "CO",
      "zip": "81657"
    }
  }
]

Create src/client/app/shared/search/search.service.ts and provide Http as a dependency in its constructor. In this same file, define the Address and Person classes that JSON will be marshalled to.

import { Injectable } from '@angular/core';
import { Http, Response } from '@angular/http';

@Injectable()
export class SearchService {
  constructor(private http:Http) {}

  getAll() {
    return this.http.get('app/shared/search/data/people.json').map((res:Response) => res.json());
  }
}

export class Address {
  street:string;
  city:string;
  state:string;
  zip:string;

  constructor(obj?:any) {
    this.street = obj && obj.street || null;
    this.city = obj && obj.city || null;
    this.state = obj && obj.state || null;
    this.zip = obj && obj.zip || null;
  }
}

export class Person {
  id:number;
  name:string;
  phone:string;
  address:Address;

  constructor(obj?:any) {
    this.id = obj && Number(obj.id) || null;
    this.name = obj && obj.name || null;
    this.phone = obj && obj.phone || null;
    this.address = obj && obj.address || null;
  }
}

In search.component.ts, add imports for these classes.

import { Person, SearchService } from '../shared/index';

You can now add a type to the searchResults variable. While you're there, modify the constructor to inject the SearchService.

searchResults: Array<Person>;

constructor(public searchService: SearchService) {}

Then implement the search() method to call the service's getAll() method.

search(): void {
  this.searchService.getAll().subscribe(
    data => {this.searchResults = data;},
    error => console.log(error)
  );
}

At this point, you'll likely see the following message in your browser's console.

ORIGINAL EXCEPTION: No provider for SearchService!

This happens because the app hasn't provided this service to components. To fix this, create src/client/app/shared/search/index.ts and populate it with the following.

/**
 * This barrel file provides the export for the shared SearchService.
 */
export * from './search.service';

Then add a reference to this file in src/client/app/shared/index.ts so its included in the shared export.

/**
 * This barrel file provides the exports for the shared resources (services, components).
 */
export * from './name-list/index';
export * from './navbar/index';
export * from './toolbar/index';
export * from './search/index';

To fix the "No provider" error from above, update app.component.ts to import the SearchService and add the service to the list of provider.

import { NameListService, NavbarComponent, ToolbarComponent, SearchService } from './shared/index';

@Component({
  selector: 'sd-app',
  viewProviders: [NameListService, SearchService, HTTP_PROVIDERS]
  moduleId: module.id,

Now clicking the search button should work. To make the results look better, remove the <pre> tag in search.component.html and replace it with a <table>.

<table *ngIf="searchResults">
  <thead>
  <tr>
    <th>Name</th>
    <th>Phone</th>
    <th>Address</th>
  </tr>
  </thead>
  <tbody>
  <tr *ngFor="let person of searchResults; let i=index">
    <td>{{person.name}}</td>
    <td>{{person.phone}}</td>
    <td>{{person.address.street}}<br/>
      {{person.address.city}}, {{person.address.state}} {{person.address.zip}}
    </td>
  </tr>
  </tbody>
</table>

Then add some additional CSS for this component in search.component.css.

table {
  margin-top: 10px;
  border-collapse: collapse;
}

th {
  text-align: left;
  border-bottom: 2px solid #ddd;
  padding: 8px;
}

td {
  border-top: 1px solid #ddd;
  padding: 8px;
}

Now the search results look better.

But wait, we still don't have search functionality! To add a search feature, add a search() method to search.service.ts.

search(q:string) {
  if (!q || q === '*') {
    q = '';
  } else {
    q = q.toLowerCase();
  }
  return this.getAll().map(data => {
    let results:any = [];
    data.map(item => {
      if (JSON.stringify(item).toLowerCase().includes(q)) {
        results.push(item);
      }
    });
    return results;
  });
}

Then refactor SearchComponent to call this method with its query variable.

search(): void {
  this.searchService.search(this.query).subscribe(
    data => {this.searchResults = data;},
    error => console.log(error)
  );
}

Now search results will be filtered by the query value you type in.

This section showed you how to fetch and display search results. The next section builds on this and shows how to edit and save a record.

Add an edit feature

Modify search.component.html to add a link for editing a person.

<td><a [routerLink]="['/edit', person.id]">{{person.name}}</a></td>

Create src/client/app/+edit/edit.component.html to display an editable form. You might notice I've added id attributes to most elements. This is to make things easier when writing integration tests with Protractor.

<div *ngIf="person">
  <h3>{{editName}}</h3>
  <div>
    <label>Id:</label>
    {{person.id}}
  </div>
  <div>
    <label>Name:</label>
    <input [(ngModel)]="editName" id="name" placeholder="name"/>
  </div>
  <div>
    <label>Phone:</label>
    <input [(ngModel)]="editPhone" id="phone" placeholder="Phone"/>
  </div>
  <fieldset>
    <legend>Address:</legend>
    <address>
      <input [(ngModel)]="editAddress.street" id="street"><br/>
      <input [(ngModel)]="editAddress.city" id="city">,
      <input [(ngModel)]="editAddress.state" id="state" size="2">
      <input [(ngModel)]="editAddress.zip" id="zip" size="5">
    </address>
  </fieldset>
  <button (click)="save()" id="save">Save</button>
  <button (click)="cancel()" id="cancel">Cancel</button>
</div>

Create an EditComponent in src/search/components/edit.component.ts that references this template and handles communication with the SearchService.

import { Component, OnInit } from '@angular/core';
import { Person, Address, SearchService } from '../shared/index';
import { RouteSegment, Router } from '@angular/router';

@Component({
  selector: 'sd-edit',
  moduleId: module.id,
  templateUrl: 'edit.component.html',
  styleUrls: ['edit.component.css']
})
export class EditComponent implements OnInit {

  person: Person;
  editName: string;
  editPhone: string;
  editAddress: Address;

  constructor(
    private _service: SearchService,
    private _router: Router,
    private _routeSegment: RouteSegment
  ) { }

  ngOnInit() {
    let id = +this._routeSegment.getParam('id');
    this._service.get(id).subscribe(person => {
      if (person) {
        this.editName = person.name;
        this.editPhone = person.phone;
        this.editAddress = person.address;
        this.person = person;
      } else {
        this.gotoList();
      }
    });
  }

  cancel() {
    this._router.navigate(['/search']);
  }

  save() {
    this.person.name = this.editName;
    this.person.phone = this.editPhone;
    this.person.address = this.editAddress;
    this._service.save(this.person);
    this.gotoList();
  }

  gotoList() {
    if (this.person) {
      this._router.navigate(['/search', {term: this.person.name} ]);
    } else {
      this._router.navigate(['/search']);
    }
  }
}

Create src/client/app/+edit/index.ts to export EditComponent.

/**
 * This barrel file provides the export for the lazy loaded EditComponent.
 */
export * from './edit.component';

Modify SearchService to contain functions for finding a person by their id, and saving them. While you're in there, modify the search() method to be aware of updated objects in localStorage.

search(q:string) {
  if (!q || q === '*') {
    q = '';
  } else {
    q = q.toLowerCase();
  }
  return this.getAll().map(data => {
    let results = [];
    data.map(item => {
      // check for item in localStorage
      if (localStorage['person' + item.id]) {
        item = JSON.parse(localStorage['person' + item.id]);
      }
      if (JSON.stringify(item).toLowerCase().includes(q)) {
        results.push(item);
      }
    });
    return results;
  });
}

get(id: number) {
  return this.getAll().map(all => {
    if (localStorage['person' + id]) {
      return JSON.parse(localStorage['person' + id]);
    }
    return all.find(e => e.id === id);
  });
}

save(person: Person) {
  localStorage['person' + person.id] = JSON.stringify(person);
}

To make the app aware of this new component, add an import and route configuration in app.component.ts.

import { EditComponent } from '../+edit/index';

@Routes([
  { path: '/', component: HomeComponent },
  { path: '/about', component: AboutComponent },
  { path: '/search', component: SearchComponent },
  { path: '/edit/:id', component: EditComponent }
])

Then create src/client/app/+edit/edit.component.css to make the form look a bit better.

:host {
  display: block;
  padding: 0 16px;
}

button {
  margin-top: 10px;
}

At this point, you should be able to search for a person and update their information.

The <form> in src/client/app/+edit/edit.component.html calls a save() function to update a person's data. You already implemented this above. The function calls a gotoList() function that appends the person's name to the URL when sending the user back to the search screen.

gotoList() {
  if (this.person) {
    this._router.navigate(['/search', {term: this.person.name} ]);
  } else {
    this._router.navigate(['/search']);
  }
}

Since the SearchComponent doesn't execute a search automatically when you execute this URL, add the following logic to do so in its constructor.

constructor(public searchService: SearchService, routeSegment: RouteSegment) {
  if (routeSegment.getParam('term')) {
    this.query = decodeURIComponent(routeSegment.getParam('term'));
    this.search();
  }
}

You'll need to import RouteSegment in order for everything to compile.

import { ROUTER_DIRECTIVES, RouteSegment } from '@angular/router';

After making all these changes, you should be able to search/edit/update a person's information. If it works - nice job!

Source code

A completed project with this code in it is available on GitHub at https://github.com/mraible/angular2-tutorial. If you have ideas for improvements, please leave a comment or send a pull request.

I originally wrote this tutorial in Asciidoctor because it has a slick feature where you can include the source code from files rather than copying and pasting. Since GitHub doesn't support includes, I changed things so the code is now embedded in the document. You can now read this tutorial on GitHub or using DocGist.

Summary

I hope you've enjoyed this quick-and-easy tutorial on how to get started with Angular 2.0 RC1. In a future tutorial, I'll show you how to write unit tests and integration tests for this application.

Resources

I used a number of resources while creating this application. ng-book 2 was an invaluable resource and I highly recommend it if you're learning Angular 2. I found Chariot Solution's article on Angular2 Observables, Http, and separating services and components to be quite helpful. Finally, the angular-cli project was a big help, especially its ng generate route <object> feature.

Kudos to all the pioneers in Angular 2 land that've been using it and writing about it on blogs and Stack Overflow. Getting started with Angular 2 would've been a real pain without your trailblazing.

Devoxx France 2016: Springtime in Paris

Matt Raible — Tue, 26 Apr 2016 07:13:18 -0600

I had the good fortune to visit Paris last week for Devoxx France. When traveling to conferences in exotic locations, I like to bring a travel partner. This time, I asked my daughter, Abbie, to join me. She gladly accepted. Springtime in Paris can be a beautiful event. The grass is green, the flowers are blooming and the sun's rays blanket the city.

We arrived in Paris on Tuesday, April 19 and quickly found our way to our hotel. Its location was ideal: across the street from Le Palais des Congrès de Paris convention center and mall. Since the conference was at the convention center, it made logistics for my talks very convenient. We grabbed a quick bite after settling in, then took a 15-minute stroll to the Arc de Triomphe.

That evening, we joined Ippon developers and friends at a special event for Java Hipsters. Their rooftop location had great views, cold "Java" beer and I met a lot of enthusiastic developers. I especially enjoyed talking with the original Java Hipster and founder of JHipster, Julien Dubois.

The sunset over Paris provided a splendid backdrop for the festivities.

On Wednesday, Abbie and I got up early and headed to Versailles. We toured Château de Versailles, the Gardens and Marie-Antoinette's estate. I'd never visited this area of Versailles and never realized what I was missing. We rented a boat and practiced rowing on the Grand Canal to get ready for rafting season.

That evening, we stopped by the Restaurant Le Sud for the speaker's dinner. It was fun seeing familiar faces and meeting new folks.

Thursday was my first talk, but we had the morning free to explore. We headed for the Eiffel Tower and rode its north elevator straight to the top. The views where spectacular and Abbie got goosebumps from the gentle sway.

I transformed from an old-fashioned, whiskey-drinking Java developer to a Java Hipster a few hours later. You can see the slides from my "Get Hip with JHipster" presentation below, or on SlideShare.

We wanted to see the Catacombs of Paris that night, and made it just minutes before it closed. Seeing the remains of millions of people's bones stacked on top of each other frightened Abbie more than standing on the glass floor in the Eiffel Tower. I experienced more heebie jeebies from the floor. We popped out of the Catacombs near the excellent Thai Paragon and stopped for a delicious meal. Abbie tried duck for the first time and loved it.

I had two talks on Friday, a quickie on how to write an InfoQ Mini-Book with Asciidoctor and a 45-minute session on The Art of Angular in 2016. I wrote the InfoQ Mini-Book presentation using Asciidoctor's Bespoke support and really enjoyed the experience. Thanks to Dan Allen for assembling this easy to use starter template! Dan was also a great help in getting the JHipster Book printed for the first time and I was pumped to have a copy with me to show off.

You can view the presentation online and checkout its repository on GitHub.

For my Angular presentation, I invited Abbie to kick things off, so she could experience what it's like to speak at a conference.

She did great and I followed her intro with my presentation on working with Angular 2. You can see my presentation below or check it out on SlideShare.

At the end of the conference, we attended the Les Cast Codeurs Podcast. It was all in French, but you could tell everyone was having a good time from the smiles and laughter in the audience. During the session, the Devoxx Crew surprised me with a Java Champion award. I was very surprised and humbled to receive this recognition. It was pretty cool having Abbie with me for such an honor.

Testing Angular 2 Applications

Matt Raible — Tue, 29 Mar 2016 08:08:58 -0600

Click here to see an updated version of this tutorial that's been upgraded for Angular 2.0 RC1.

This article is the second in a series about learning Angular 2. It describes how to test a simple Angular 2 application. In a previous article, Getting Started with Angular 2, I showed how to develop a simple search and edit feature. In this tutorial, I did my best to keep the tests similar to last year's Testing AngularJS Applications so you can compare the code between AngularJS and Angular 2.

What you'll build

You'll learn to use Jasmine for unit testing controllers and Protractor for integration testing. Angular's documentation has a good guide to unit testing if you'd like more information on testing and why it's important.

The best reason for writing tests is to automate your testing. Without tests, you'll likely be testing manually. This manual testing will take longer and longer as your codebase grows.

What you'll need

About 15-30 minutes.
A favorite text editor or IDE. I recommend IntelliJ IDEA.
Git installed.
Node.js and npm installed. I recommend using nvm.

Get the tutorial project

Clone the angular2-tutorial repository using git and install its dependencies.

git clone https://github.com/mraible/angular2-tutorial.git
cd angular2-tutorial
npm install

If you haven't completed the Getting Started with Angular 2 tutorial, you should peruse it so you understand how this application works. You can also simply start the app with npm start and view it in your browser at http://localhost:5555/.

Unit test the SearchService

Create src/shared/services/search.service.spec.ts and setup the test's infrastructure using MockBackend and BaseRequestOptions.

import {it, describe, expect, inject, fakeAsync, beforeEachProviders, tick} from 'angular2/testing';
import {MockBackend} from 'angular2/http/testing';
import {provide} from 'angular2/core';
import 'rxjs/add/operator/map';
import {Http, ConnectionBackend, BaseRequestOptions, Response, ResponseOptions} from 'angular2/http';

import {SearchService} from './search.service';

export function main() {
  describe('Search Service', () => {
    beforeEachProviders(() => {
      return [BaseRequestOptions, MockBackend, SearchService,
        provide(Http, {
          useFactory: (backend:ConnectionBackend, defaultOptions:BaseRequestOptions) => {
            return new Http(backend, defaultOptions);
          }, deps: [MockBackend, BaseRequestOptions]
        }),
      ];
    });
  });
}

If you run npm test, you'll get a failed build from a number of unused imports. You can fix those by adding the first test of getAll(). This test shows how MockBackend can be used to mock results and set the response.

When you are testing code that returns either a Promise or an RxJS Observable, you can use the fakeAsync helper to test that code as if it were synchronous. Promises are be fulfilled and Observables are notified immediately after you call tick().

The test below should be on the same level as beforeEachProviders.

it('should retrieve all search results',
  inject([SearchService, MockBackend], fakeAsync((searchService:SearchService, mockBackend:MockBackend) => {
    var res:Response;
    mockBackend.connections.subscribe(c => {
      expect(c.request.url).toBe('shared/data/people.json');
      let response = new ResponseOptions({body: '[{"name": "John Elway"}, {"name": "Gary Kubiak"}]'});
      c.mockRespond(new Response(response));
    });
    searchService.getAll().subscribe((response) => {
      res = response;
    });
    tick();
    expect(res[0].name).toBe('John Elway');
  }))
);

Running npm test should result in "10 tests completed". Add a couple more tests for filtering by search term and fetching by id.

it('should filter by search term',
  inject([SearchService, MockBackend], fakeAsync((searchService:SearchService, mockBackend:MockBackend) => {
    var res:Response;
    mockBackend.connections.subscribe(c => {
      expect(c.request.url).toBe('shared/data/people.json');
      let response = new ResponseOptions({body: '[{"name": "John Elway"}, {"name": "Gary Kubiak"}]'});
      c.mockRespond(new Response(response));
    });
    searchService.search('john').subscribe((response) => {
      res = response;
    });
    tick();
    expect(res[0].name).toBe('John Elway');
  }))
);

it('should fetch by id',
  inject([SearchService, MockBackend], fakeAsync((searchService:SearchService, mockBackend:MockBackend) => {
    var res:Response;
    mockBackend.connections.subscribe(c => {
      expect(c.request.url).toBe('shared/data/people.json');
      let response = new ResponseOptions({body: '[{"id": 1, "name": "John Elway"}, {"id": 2, "name": "Gary Kubiak"}]'});
      c.mockRespond(new Response(response));
    });
    searchService.search('2').subscribe((response) => {
      res = response;
    });
    tick();
    expect(res[0].name).toBe('Gary Kubiak');
  }))
);

If you want to have tests continually run as you add them, you can run the following commands in separate shell windows.

npm run build.test.watch
npm run karma.start

NOTE: See Running Unit Tests on Karma to learn how to run your tests from IntelliJ IDEA.

Unit test the SearchComponent

To unit test the SearchComponent, create a MockSearchProvider that has spies. These allow you to spy on functions to check if they were called.

Create src/shared/services/mocks/search.service.ts and populate it with spies for each method, as well as methods to set the response and subscribe to results.

import {provide} from 'angular2/core';
import {SpyObject} from 'angular2/testing_internal';

import {SearchService} from '../search.service';
import Spy = jasmine.Spy;

export class MockSearchService extends SpyObject {
  getAllSpy:Spy;
  getByIdSpy:Spy;
  searchSpy:Spy;
  saveSpy:Spy;
  fakeResponse;

  constructor() {
    super(SearchService);

    this.fakeResponse = null;
    this.getAllSpy = this.spy('getAll').andReturn(this);
    this.getByIdSpy = this.spy('get').andReturn(this);
    this.searchSpy = this.spy('search').andReturn(this);
    this.saveSpy = this.spy('save').andReturn(this);
  }

  subscribe(callback) {
    callback(this.fakeResponse);
  }

  setResponse(json: any): void {
    this.fakeResponse = json;
  }

  getProviders(): Array<any> {
    return [provide(SearchService, {useValue: this})];
  }
}

In this same directory, create routes.ts to mock Angular's Router, RouteParams and RouterProvider.

import {provide} from 'angular2/core';
import {
  ComponentInstruction,
  Router,
  RouteParams
} from 'angular2/router';
import {ResolvedInstruction} from 'angular2/src/router/instruction';
import {SpyObject} from 'angular2/testing_internal';

export class MockRouteParams extends SpyObject {
  private ROUTE_PARAMS = {};

  constructor() { super(RouteParams); }

  set(key: string, value: string) {
    this.ROUTE_PARAMS[key] = value;
  }

  get(key: string) {
    return this.ROUTE_PARAMS[key];
  }
}

export class MockRouter extends SpyObject {
  constructor() { super(Router); }
  isRouteActive(s) { return true; }
  generate(s) {
    return new ResolvedInstruction(new ComponentInstruction('detail', [], null, null, true, '0'), null, {});
  }
}

export class MockRouterProvider {
  mockRouter: MockRouter = new MockRouter();
  mockRouteParams: MockRouteParams = new MockRouteParams();

  setRouteParam(key: string, value: any) {
    this.mockRouteParams.set(key, value);
  }

  getProviders(): Array<any> {
    return [
      provide(Router, {useValue: this.mockRouter}),
      provide(RouteParams, {useValue: this.mockRouteParams}),
    ];
  }
}

import {
  it,
  describe,
  expect,
  injectAsync,
  beforeEachProviders,
  TestComponentBuilder,
} from 'angular2/testing';

import {MockRouterProvider} from '../../shared/services/mocks/routes';
import {MockSearchService} from '../../shared/services/mocks/search.service';

import {SearchComponent} from './search.component';

export function main() {
  describe('Search component', () => {
    var mockSearchService:MockSearchService;
    var mockRouterProvider:MockRouterProvider;

    beforeEachProviders(() => {
      mockSearchService = new MockSearchService();
      mockRouterProvider = new MockRouterProvider();

      return [
        mockSearchService.getProviders(), mockRouterProvider.getProviders()
      ];
    });
  });
}

Add two tests, one to verify a search term is used when it's set on the component and a second to verify search is called when a term is passed in as a route parameter.

it('should search when a term is set and search() is called', injectAsync([TestComponentBuilder], (tcb:TestComponentBuilder) => {
  return tcb.createAsync(SearchComponent).then((fixture) => {
    let searchComponent = fixture.debugElement.componentInstance;
    searchComponent.query = 'M';
    searchComponent.search();
    expect(mockSearchService.searchSpy).toHaveBeenCalledWith('M');
  });
}));

it('should search automatically when a term is on the URL', injectAsync([TestComponentBuilder], (tcb:TestComponentBuilder) => {
  mockRouterProvider.setRouteParam('term', 'peyton');
  return tcb.createAsync(SearchComponent).then((fixture) => {
    fixture.detectChanges();
    expect(mockSearchService.searchSpy).toHaveBeenCalledWith('peyton');
  });
}));

import {
  it,
  describe,
  expect,
  injectAsync,
  beforeEachProviders,
  TestComponentBuilder,
} from 'angular2/testing';

import {MockRouterProvider} from '../../shared/services/mocks/routes';
import {MockSearchService} from '../../shared/services/mocks/search.service';

import {EditComponent} from './edit.component';

export function main() {
  describe('Edit component', () => {
    var mockSearchService:MockSearchService;
    var mockRouterProvider:MockRouterProvider;

    beforeEachProviders(() => {
      mockSearchService = new MockSearchService();
      mockRouterProvider = new MockRouterProvider();

      return [
        mockSearchService.getProviders(), mockRouterProvider.getProviders()
      ];
    });

    it('should fetch a single record', injectAsync([TestComponentBuilder], (tcb:TestComponentBuilder) => {
      mockRouterProvider.setRouteParam('id', '1');
      return tcb.createAsync(EditComponent).then((fixture) => {
        let person = {name: 'Emmanuel Sanders', address: {city: 'Denver'}};
        mockSearchService.setResponse(person);

        fixture.detectChanges();
        // verify service was called
        expect(mockSearchService.getByIdSpy).toHaveBeenCalledWith(1);

        // verify data was set on component when initialized
        let editComponent = fixture.debugElement.componentInstance;
        expect(editComponent.editAddress.city).toBe('Denver');

        // verify HTML renders as expected
        var compiled = fixture.debugElement.nativeElement;
        expect(compiled.querySelector('h3')).toHaveText('Emmanuel Sanders');
      });
    }));
  });
}

You should see "? 20 tests completed" in the shell window that's running npm run karma.start. If you don't, try cancelling the command and restarting.

Integration test the search UI

To test if the application works end-to-end, you can write tests with Protractor. These are also known as integration tests, since they test the integration between all layers of your application.

To verify end-to-end tests work in the project before you begin, run the following commands in three different console windows.

# npm run webdriver-update <- You will need to run this the first time
npm run webdriver-start
npm run serve.e2e
npm run e2e

You should receive an error stating that the "nav text for About" is incorrect.

This happens because we added a Search link to the navbar and didn't update the test (in app.component.e2e.ts) that looks for the last child.

it('should have correct nav text for About', () => {
    expect(element(by.css('sd-app sd-navbar nav a:last-child')).getText()).toEqual('ABOUT');
});

Replace this test with the one below, and add a new one to verify the Search link is last.

it('should have correct nav text for About', () => {
  expect(element(by.css('sd-app sd-navbar nav a:nth-child(2)')).getText()).toEqual('ABOUT');
});

it('should have correct nav text for Search', () => {
  expect(element(by.css('sd-app sd-navbar nav a:last-child')).getText()).toEqual('SEARCH');
});

Now when you run npm run e2e, all specs should pass.

Testing the search feature

Create a new search.component.e2e.ts spec in the same directory as your SearchComponent. Add tests to verify elements are rendered correctly and search works. At the time of this writing, Protractor's by.model and by.repeater don't work with Angular 2. For this reason, I used by.css to verify the HTML renders as expected.

describe('Search', () => {

  beforeEach(() => {
    browser.get('/search');
  });

  it('should have an input and search button', () => {
    expect(element(by.css('sd-app sd-search form input')).isPresent()).toEqual(true);
    expect(element(by.css('sd-app sd-search form button')).isPresent()).toEqual(true);
  });

  it('should allow searching', () => {
    let searchButton = element(by.css('button'));
    let searchBox = element(by.css('input'));
    searchBox.sendKeys('M');
    searchButton.click().then(() => {
      // doesn't work as expected - results in 0
      //expect(element.all(by.repeater('person of searchResults')).count()).toEqual(3);
      var list = element.all(by.css('sd-search table tbody tr'));
      expect(list.count()).toBe(3);
    });
  });
});

Testing the edit feature

Create a edit.component.e2e.ts spec to verify the EditComponent renders a person's information and that you can update their information.

describe('Edit', () => {
 
  beforeEach(() => {
    browser.get('/edit/1');
  });
 
  let name = element(by.id('name'));
  let street = element(by.id('street'));
  let city = element(by.id('city'));
 
  it('should allow viewing a person', () => {
    expect(element(by.css('h3')).getText()).toEqual('Peyton Manning');
    expect(name.getAttribute('value')).toEqual('Peyton Manning');
    expect(street.getAttribute('value')).toEqual('1234 Main Street');
    expect(city.getAttribute('value')).toEqual('Greenwood Village');
  });
 
  it('should allow updating a name', function () {
    let save = element(by.id('save'));
    // send individual characters since sendKeys passes partial values sometimes
    // https://github.com/angular/protractor/issues/698
    ' Won!'.split('').forEach((c) => name.sendKeys(c));
    save.click();
    // verify one element matched this change
    var list = element.all(by.css('sd-search table tbody tr'));
    expect(list.count()).toBe(1);
  });
});

Run npm run e2e to verify all your end-to-end tests pass. You should see a success message similar to the one below in your terminal window.

If you made it this far and have all 13 specs passing - congratulations! You're well on your way to writing quality code with Angular 2 and verifying it works.

Source code

A completed project with this code in it is available on GitHub at https://github.com/mraible/angular2-tutorial. If you have ideas for improvements, please leave a comment or send a pull request.

I originally wrote this tutorial in Asciidoctor because it has a slick feature where you can include the source code from files rather than copying and pasting. Unfortunately, GitHub doesn't support includes. You can use DocGist to view this tutorial, but includes don't work there either.

If you'd like to see the Asciidoctor-generated version of this tutorial, you can install the gem, checkout the project from GitHub, and then run asciidoctor TESTING.adoc to produce a TESTING.html file.

Summary

I hope you've enjoyed this quick-and-easy tutorial on testing Angular 2 applications. You can see the test coverage of your project by running npm run serve.coverage. You'll notice that the new components and service could use some additional coverage. I'll leave that as a task for the reader.

I learned a lot about testing from ng-book 2 and its Testing chapter. If you have any Angular 2 testing tips and tricks you'd like to share, I'd love to hear about them.

Getting Started with Angular 2

Matt Raible — Wed, 23 Mar 2016 09:23:53 -0600

Click here to see an updated version of this tutorial that's been upgraded for Angular 2.0 RC1.

I was hired by one of my current clients in November to help them develop a project management application with AngularJS. I'm proud to say we've built the application, it looks great, and it's scheduled to be released next month. The team had lots of experience with ExtJS, but was new to AngularJS. While using AngularJS worked, they're keen on moving to Angular 2 shortly after it's released.

To help them learn Angular 2, I decided to write a couple tutorials similar to the AngularJS tutorials I wrote last year. In this tutorial, I did my best to keep the functionality and features similar to Getting Started with AngularJS so you can compare the code between the two.

What you'll build

You'll build a simple web application with Angular 2 and TypeScript. You'll add search and edit features with mock data.

What you'll need

About 15-30 minutes.
A favorite text editor or IDE. I recommend IntelliJ IDEA.
Git installed.
Node.js and npm installed. I recommend using nvm.

Create your project

Clone the angular2-seed repository using git:

git clone https://github.com/mgechev/angular2-seed.git angular2-tutorial
cd angular2-tutorial

NOTE: The angular2-seed project requires node v4.x.x or higher and npm 2.14.7. I used node v4.2.6 and npm 3.6.0.

Install ts-node for TypeScript:

npm install -g ts-node

Install the project's dependencies:

npm install

Run the application

The project is configured with a simple web server for development. To start it, run:

npm start

You should see a screen like the one below at http://localhost:5555.

You can see your new project's test coverage by running npm test:

=============================== Coverage summary ===============================
Statements : 86.11% ( 93/108 )
Branches : 48.28% ( 70/145 )
Functions : 100% ( 25/25 )
Lines : 94.32% ( 83/88 )
================================================================================

Add a search feature

To add a search feature, open the project in an IDE or your favorite text editor. For IntelliJ IDEA, use File > New Project > Static Web and point to the directory you cloned angular2-seed to.

The Basics

Create a file at src/search/components/search.component.html with the following HTML:

<h2>Search</h2>
<form>
  <input type="search" [(ngModel)]="query" (keyup.enter)="search()">
  <button type="button" (click)="search()">Search</button>
</form>
<div *ngIf="loading">loading...</div>
<pre>{{searchResults | json}}</pre>

Create src/search/components/search.component.ts to define the SearchComponent and point to this template.

import {Component} from 'angular2/core';
import {CORE_DIRECTIVES, FORM_DIRECTIVES} from 'angular2/common';
import {ROUTER_DIRECTIVES} from 'angular2/router';

@Component({
  selector: 'sd-search',
  moduleId: module.id,
  templateUrl: './search.component.html',
  directives: [FORM_DIRECTIVES, CORE_DIRECTIVES, ROUTER_DIRECTIVES]
})
export class SearchComponent {
  loading: boolean;
  query: string;
  searchResults: any;

  constructor() {
    console.log('initialized search component');
  }
}

Update src/app/components/app.component.ts to import this component and include its route.

import {SearchComponent} from '../../search/components/search.component';

@RouteConfig([
  { path: '/',      name: 'Home',  component: HomeComponent  },
  { path: '/about', name: 'About', component: AboutComponent },
  { path: '/search', name: 'Search', component: SearchComponent }

Your browser should refresh automatically, thanks to Browsersync. Navigate to http://localhost:5555/search and you should see the search component.

templateUrl: './search.component.html',
styleUrls: ['./search.component.css'],
directives: [FORM_DIRECTIVES, CORE_DIRECTIVES, ROUTER_DIRECTIVES]

Create src/search/components/search.component.css and add some CSS.

:host {
  display: block;
  padding: 0 16px;
}

There, that looks better!

Finally, update src/app/components/navbar.component.html to include a link to the search route.

<nav>
  <a [routerLink]="['Home']">HOME</a>
  <a [routerLink]="['About']">ABOUT</a>
  <a [routerLink]="['Search']">SEARCH</a>
</nav>

This section has shown you how to add a new component to a basic Angular 2 application. The next section shows you how to create a use a JSON file and localStorage to create a fake API.

The Backend

To get search results, create a SearchService that makes HTTP requests to a JSON file. Start by creating src/shared/data/people.json to hold your data.

[
  {
    "id": 1,
    "name": "Peyton Manning",
    "phone": "(303) 567-8910",
    "address": {
      "street": "1234 Main Street",
      "city": "Greenwood Village",
      "state": "CO",
      "zip": "80111"
    }
  },
  {
    "id": 2,
    "name": "Demaryius Thomas",
    "phone": "(720) 213-9876",
    "address": {
      "street": "5555 Marion Street",
      "city": "Denver",
      "state": "CO",
      "zip": "80202"
    }
  },
  {
    "id": 3,
    "name": "Von Miller",
    "phone": "(917) 323-2333",
    "address": {
      "street": "14 Mountain Way",
      "city": "Vail",
      "state": "CO",
      "zip": "81657"
    }
  }
]

Create src/shared/services/search.service.ts and provide Http as a dependency in its constructor. In this same file, define the Address and Person classes that JSON will be marshalled to.

import {Injectable} from 'angular2/core';
import {Http, Response} from 'angular2/http';

@Injectable()
export class SearchService {
  constructor(private http:Http) {}

  getAll() {
    return this.http.get('shared/data/people.json').map((res:Response) => res.json());
  }
}

export class Address {
  street:string;
  city:string;
  state:string;
  zip:string;

  constructor(obj?:any) {
    this.street = obj && obj.street || null;
    this.city = obj && obj.city || null;
    this.state = obj && obj.state || null;
    this.zip = obj && obj.zip || null;
  }
}

export class Person {
  id:number;
  name:string;
  phone:string;
  address:Address;

  constructor(obj?:any) {
    this.id = obj && Number(obj.id) || null;
    this.name = obj && obj.name || null;
    this.phone = obj && obj.phone || null;
    this.address = obj && obj.address || null;
  }
}

In search.component.ts, add imports for these classes.

import {Person, SearchService} from '../../shared/services/search.service';

You can now add a type to the searchResults variable. While you're there, modify the constructor to inject the SearchService.

searchResults: Array<Person>;

constructor(public searchService: SearchService) {}

Then implement the search() method to call the service's getAll() method.

search(): void {
  this.searchService.getAll().subscribe(
    data => {this.searchResults = data;},
    error => console.log(error)
  );
}

At this point, you'll likely see the following message in your browser's console.

EXCEPTION: No provider for SearchService! (SearchComponent -> SearchService)

This happens because the app hasn't provided this service to components. To fix this, modify app.component.ts to import this component and add the service to the list of providers.

import {NameListService} from '../../shared/services/name-list.service';
import {SearchService} from '../../shared/services/search.service';

@Component({
  selector: 'sd-app',
  viewProviders: [NameListService, SearchService],
  moduleId: module.id,

Next, you'll likely get an error about the Http dependency in SearchService.

EXCEPTION: No provider for Http! (SearchComponent -> SearchService -> Http)

To solve this problem, modify src/main.ts to import the Http service and make it available to the app.

import {HTTP_PROVIDERS} from 'angular2/http';

bootstrap(AppComponent, [
  HTTP_PROVIDERS, ROUTER_PROVIDERS,
  provide(APP_BASE_HREF, { useValue: '<%= APP_BASE %>' })
]);

Now the page will load without errors. However, when you click on the button, you'll see the following error.

ORIGINAL EXCEPTION: TypeError: this.http.get(...).map is not a function

I was stuck here for quite some time when I first encountered this issue. I was able to solve it with a simple import in main.ts.

import 'rxjs/add/operator/map';

Now clicking the search button should work. To make the results look better, remove the <pre> tag in search.component.html and replace it with a <table>.

<table *ngIf="searchResults">
  <thead>
  <tr>
    <th>Name</th>
    <th>Phone</th>
    <th>Address</th>
  </tr>
  </thead>
  <tbody>
  <tr *ngFor="#person of searchResults; #i=index">
    <td>{{person.name}}</td>
    <td>{{person.phone}}</td>
    <td>{{person.address.street}}<br/>
      {{person.address.city}}, {{person.address.state}} {{person.address.zip}}
    </td>
  </tr>
  </tbody>
</table>

Then add some additional CSS for this component in search.component.css.

table {
  margin-top: 10px;
  border-collapse: collapse;
}

th {
  text-align: left;
  border-bottom: 2px solid #ddd;
  padding: 8px;
}

td {
  border-top: 1px solid #ddd;
  padding: 8px;
}

Now the search results look better.

But wait, we still don't have search functionality! To add a search feature, add a search() method to search.service.ts.

search(q:string) {
  if (!q || q === '*') {
    q = '';
  } else {
    q = q.toLowerCase();
  }
  return this.getAll().map(data => {
    let results = [];
    data.map(item => {
      if (JSON.stringify(item).toLowerCase().includes(q)) {
        results.push(item);
      }
    });
    return results;
  });
}

Then refactor SearchComponent to call this method with its query variable.

search(): void {
  this.searchService.search(this.query).subscribe(
    data => {this.searchResults = data;},
    error => console.log(error)
  );
}

Now search results will be filtered by the query value you type in.

This section showed you how to fetch and display search results. The next section builds on this and shows how to edit and save a record.

Add an edit feature

Modify search.component.html to add a link for editing a person.

<td><a [routerLink]="['Edit', { id: person.id }]">{{person.name}}</a></td>

Create src/search/components/edit.component.html to display an editable form. You might notice I've added id attributes to most elements. This is to make things easier when writing integration tests with Protractor.

<div *ngIf="person">
  <h3>{{editName}}</h3>
  <div>
    <label>Id:</label>
    {{person.id}}
  </div>
  <div>
    <label>Name:</label>
    <input [(ngModel)]="editName" id="name" placeholder="name"/>
  </div>
  <div>
    <label>Phone:</label>
    <input [(ngModel)]="editPhone" id="phone" placeholder="Phone"/>
  </div>
  <fieldset>
    <legend>Address:</legend>
    <address>
      <input [(ngModel)]="editAddress.street" id="street"><br/>
      <input [(ngModel)]="editAddress.city" id="city">,
      <input [(ngModel)]="editAddress.state" id="state" size="2">
      <input [(ngModel)]="editAddress.zip" id="zip" size="5">
    </address>
  </fieldset>
  <button (click)="save()" id="save">Save</button>
  <button (click)="cancel()" id="cancel">Cancel</button>
</div>

Create an EditComponent in src/search/components/edit.component.ts that references this template and handles communication with the SearchService.

import {Component, OnInit} from 'angular2/core';
import {Person, Address, SearchService} from '../../shared/services/search.service';
import {RouteParams, Router} from 'angular2/router';
import {CanDeactivate, ComponentInstruction} from 'angular2/router';

@Component({
  selector: 'sd-edit',
  moduleId: module.id,
  templateUrl: './edit.component.html',
  styleUrls: ['./edit.component.css']
})
export class EditComponent implements OnInit, CanDeactivate {

  person: Person;
  editName: string;
  editPhone: string;
  editAddress: Address;

  constructor(
    private _service: SearchService,
    private _router: Router,
    private _routeParams: RouteParams
  ) { }

  ngOnInit() {
    let id = +this._routeParams.get('id');
    this._service.get(id).subscribe(person => {
      if (person) {
        this.editName = person.name;
        this.editPhone = person.phone;
        this.editAddress = person.address;
        this.person = person;
      } else {
        this.gotoList();
      }
    });
  }

  routerCanDeactivate(next: ComponentInstruction, prev: ComponentInstruction): any {
    if (!this.person || this.person.name === this.editName || this.person.phone === this.editPhone
      || this.person.address === this.editAddress) {
      return true;
    }

    return new Promise<boolean>((resolve, reject) => resolve(window.confirm('Discard changes?')));
  }

  cancel() {
    this._router.navigate(['Search']);
  }

  save() {
    this.person.name = this.editName;
    this.person.phone = this.editPhone;
    this.person.address = this.editAddress;
    this._service.save(this.person);
    this.gotoList();
  }

  gotoList() {
    if (this.person) {
      this._router.navigate(['Search', { term: this.person.name }]);
    } else {
      this._router.navigate(['Search']);
    }
  }
}

Modify SearchService to contain functions for finding a person by their id, and saving them. While you're in there, modify the search() method to be aware of updated objects in localStorage.

search(q:string) {
  if (!q || q === '*') {
    q = '';
  } else {
    q = q.toLowerCase();
  }
  return this.getAll().map(data => {
    let results = [];
    data.map(item => {
      // check for item in localStorage
      if (localStorage['person' + item.id]) {
        item = JSON.parse(localStorage['person' + item.id]);
      }
      if (JSON.stringify(item).toLowerCase().includes(q)) {
        results.push(item);
      }
    });
    return results;
  });
}

get(id: number) {
  return this.getAll().map(all => {
    if (localStorage['person' + id]) {
      return JSON.parse(localStorage['person' + id]);
    }
    return all.find(e => e.id === id);
  });
}

save(person: Person) {
  localStorage['person' + person.id] = JSON.stringify(person);
}

To make the app are of this new component, add an import and route configuration in app.component.ts.

import {EditComponent} from '../../search/components/edit.component';

@RouteConfig([
  { path: '/',      name: 'Home',  component: HomeComponent  },
  { path: '/about', name: 'About', component: AboutComponent },
  { path: '/search', name: 'Search', component: SearchComponent },
  { path: '/edit/:id', name: 'Edit', component: EditComponent }
])

Then create src/search/components/edit.component.css to make the form look a bit better.

:host {
  display: block;
  padding: 0 16px;
}

button {
  margin-top: 10px;
}

At this point, you should be able to search for a person and update their information.

The <form> in src/search/components/edit.component.html calls a save() function to update a person's data. You already implemented this above. The function calls a gotoList() function that appends the person's name to the URL when sending the user back to the search screen.

gotoList() {
  if (this.person) {
    this._router.navigate(['Search', { term: this.person.name }]);
  } else {
    this._router.navigate(['Search']);
  }
}

Since the SearchComponent doesn't execute a search automatically when you execute this URL, add the following logic to do so in its constructor.

constructor(public searchService: SearchService, params: RouteParams) {
  if (params.get('term')) {
    this.query = decodeURIComponent(params.get('term'));
    this.search();
  }
}

You'll need to import RouteParams in order for everything to compile.

import {ROUTER_DIRECTIVES, RouteParams} from 'angular2/router';

After making all these changes, you should be able to search/edit/update a person's information. If it works - nice job!

Source code

A completed project with this code in it is available on GitHub at https://github.com/mraible/angular2-tutorial. If you have ideas for improvements, please leave a comment or send a pull request.

If you'd like to see the Asciidoctor-generated version of this tutorial, you can install the gem, checkout the project from GitHub, and then run asciidoctor README.adoc to produce a README.html file.

Summary

I hope you've enjoyed this quick-and-easy tutorial on how to get started with Angular 2. In a future tutorial, I'll show you how to write unit tests and integration tests for this application. I've also started looking into creating an ES6 version of this tutorial using Soós Gábor's angular2-es6-starter. If you know of a better starter for Angular 2 and ES6, please let me know.

Resources

Kudos to all the pioneers in Angular 2 land that've been using it and writing about it on blogs and Stack Overflow. Getting started with Angular 2 would've been a real pain without your trailblazing.

How to Implement a Smart Chunking Bootstrap Carousel with AngularJS

Matt Raible — Tue, 15 Mar 2016 09:47:30 -0600

I've been helping a client develop a project management application for the last several months. One of the features I implemented uses UI Bootstrap's carousel directive to display a list of project templates to choose from when creating a new project. Rather than displaying one at a time, we wanted to display as many as the user's screen would allow. That is, if they were on a large monitor, we wanted to display five templates, a medium size monitor would display three and so on. This is a story of how I implemented a smart chunking carousel.

To begin, I made it possible to show groups of items in the carousel using array chunking.

  function chunk(arr, size) {
    var newArr = [];
    var arrayLength = arr.length;
    for (var i = 0; i < arrayLength; i += size) {
      newArr.push(arr.slice(i, i + size));
    }
    return newArr;
  }

Using UI Bootstrap's example code, I created $scope.chunkedSlides from $scope.slides.

$scope.chunkSize = 5;

// chunk slides so there's two per chunk by default
$scope.chunkedSlides = chunk($scope.slides, $scope.chunkSize);

Next, I changed the HTML template to read the grouped slides, and show each one.

<uib-carousel active="active" interval="0" no-wrap="true">
  <uib-slide ng-repeat="row in chunkedSlides">
    <div class="row">
      <div ng-repeat="slide in row track by $index" class="slide">
        <img ng-src="{{slide.image}}">
        <div class="carousel-caption">
          <h4>Slide {{slide.id}}</h4>
          <p>{{slide.text}}</p>
        </div>
      </div>
    </div>
  </uib-slide>
</uib-carousel>

This was enough to get five squares on a large monitor.

However, I wanted to go further and reduce the number per group on smaller monitors. I created a SmartChunking service that defined how many per group for each possible width.

angular.module('app').service('SmartChunking', function() {
  var large = 1600;
  var medium = 1200;
  var small = 1024;
  var xsmall = 800;

  this.getChunkSize = function(width) {
    var chunkSize;
    if (width >= large) {
      chunkSize = 5;
    } else if (width >= medium) {
      chunkSize = 4;
    } else if (width >= small) {
      chunkSize = 3;
    } else if (width >= xsmall) {
      chunkSize = 2;
    } else {
      chunkSize = 1;
    }
    return chunkSize;
  }
});

I wrote a smart-chunking directive to fire an event with the chunk size.

angular.module('app').directive('smartChunking', function($window, SmartChunking) {
  return {
    restrict: 'A',
    link: function($scope) {
      var w = angular.element($window);

      // window.outerWidth works on desktop, screen.height on iPad (width returns 768)
      var width = ($window.outerWidth > 0) ? $window.outerWidth : screen.height;
      var chunkSize = SmartChunking.getChunkSize(width);
      if (chunkSize !== 5) {
        $scope.$emit('change-chunk-size', chunkSize);
      }

      $scope.getWidth = function() {
        return ($window.outerWidth > 0) ? $window.outerWidth : screen.width;
      };

      $scope.$watch($scope.getWidth, function(newValue, oldValue) {
        if (newValue !== oldValue) {
          var chunkSize = SmartChunking.getChunkSize(newValue);
          $scope.$emit('change-chunk-size', chunkSize);
        }
      });

      w.bind('resize', function() {
        $scope.$apply();
      });
    }
  }
});

Then I added a listener for this in the controller that populated the carousel.

$scope.$on('change-chunk-size', function(event, data) {
  if (data !== $scope.chunkSize) {
    $scope.chunkedSlides = chunk($scope.slides, data);
    $scope.chunkSize = data;
  }
});

The final step was adding the smark-chunking directive to each slide and dynamically determining its col-sm-* class.

<div ng-repeat="slide in row track by $index" class="slide" ng-class="getSlideClass(chunkSize)" smart-chunking>

The controller contains a map of classes that map to chunk sizes:

var classMap = {
  5: 'col-sm-2',
  4: 'col-sm-3',
  3: 'col-sm-4',
  2: 'col-sm-5',
};

$scope.getSlideClass = function(chunkSize) {
  if (classMap[chunkSize]) {
    return classMap[chunkSize];
  } else {
    return 'col-sm-10';
  }
}

I did find that adding some CSS made things look quite a bit better.

.carousel-caption {
  padding-bottom: 0;
}

.carousel-control.left,
.carousel-control.right {
  background-image: none;
}

.carousel-indicators {
  display: none;
}

.carousel-inner {
  padding-left: 10%;
  overflow: visible;
}

.carousel-control .glyphicon-chevron-left,
.carousel-control .glyphicon-chevron-right {
  font-size: 100px;
  margin-top: -60px;
  font-style: normal;
  font-weight: 100;
}

.carousel-control .glyphicon-chevron-left {
  margin-left: -100px;
}

.carousel-control .glyphicon-chevron-right {
  margin-right: -40px;
}

/* make slide widths more responsive */
@media only screen and (min-width: 1600px) {
  .col-sm-2 {
    width: 18%;
  }
}

@media only screen and (min-width: 1200px) {
  .col-sm-3 {
    width: 22%;
  }
  .carousel-control .glyphicon-chevron-left {
    margin-left: -70px;
  }
  .carousel-control .glyphicon-chevron-right {
    margin-right: -20px;
  }
}

@media only screen and (max-width: 1200px) {
  .col-sm-4 {
    width: 29%;
  }
  .carousel-control .glyphicon-chevron-left {
    margin-left: -70px;
  }
  .carousel-control .glyphicon-chevron-right {
    margin-right: -20px;
  }
}

@media only screen and (max-width: 800px) {
  .col-sm-10 {
    width: 90%;
  }
}

I hope this tip helps you if you need to implement a similar feature. I've published a demo on Plunkr (best experienced in embedded view).

Angular Summit 2015

Matt Raible — Thu, 1 Oct 2015 10:29:31 -0600

I was in Boston this week, speaking and attending the very first Angular Summit. I had the privilege of delivering the opening keynote on Monday. I spoke about the Art of Angular and used a slide deck similar to last time. I did update the presentation to show the astronomical growth of AngularJS in terms of candidate skills (on LinkedIn) and job opportunities (on Dice.com)¹.

I mentioned the recently announced good news for Angular 2:

We're enabling mixing of Angular 1 and Angular 2 in the same application.
You can mix Angular 1 and Angular 2 components in the same view.
Angular 1 and Angular 2 can inject services across frameworks.
Data binding works across frameworks.

In related news, Craig Doremus recently posted a state-geo-angular project that shows how you can develop an Angular 1.x application that will be easy to upgrade to Angular 2.x. Thanks Craig!

Download | SlideShare

After my keynote, I attended Pratik Patel's session on High Performance JavaScript Web Apps. Pratik pointed out mobitest.akamai.com for testing an app's performance and seeing its blocking resources. He also mentioned speedgun.io (currently unavailable) for capturing performance numbers as part of a continuous integration process. Finally, he recommended Addy Somani's JavaScript Memory Management Masterclass.

My second presentation was about JHipster. Near the end of the presentation, I mentioned that I hope to finish the JHipster Book this month. Writing presentations for SpringOne 2GX and the Angular Summit occupied a lot of my free time in September. Now that it's October, I'll be dedicating my free time to finishing the book. In fact, I think I can finish the rough draft this week!

Download | SlideShare

For the last session of the day, I attended John Lindquist's session on Angular 2 Components. John showed us how everything is a component in Angular 2. He also said "now is the time to learn ES6" and built an Angular 2 ToDo App using ES6 and a bit of TypeScript. You might recognize John's name; he's the founder of egghead.io, an excellent site for learning Angular with bite-sized videos.

Tuesday morning started with a Angular 2.0 keynote from Peter Pavlovich. I really enjoyed this session and received lots of good tips about getting ready for Angular 2. The tweet below from Ksenia Dmitrieva shows his advice.

Best Practices for #angularjs 1.X if you plan to switch to 2.0 by @ppavlovich #AngularSummit pic.twitter.com/9nobqDc9G9
— Ksenia Dmitrieva (@KseniaDmitrieva) September 29, 2015

My biggest takeaway was to start following John Papa's Angular Style Guide ASAP.

The first session I attended on Tuesday was Judd Flamm's Google Material Design & Angular. I'm using Material Design for Bootstrap on a side project, so I was interested in learning more about its inspiration. We learned that Google Design has everything you need to know about why Material Design exists. We also learned about Angular Material and spent most of the session looking at its components. Judd recommended Angular Material-Start for those looking to get started quickly with both frameworks. Judd was a very entertaining speaker; I highly recommend you attend one of his talks if you get the opportunity.

After being dazzled by Peter's knowledge of Angular 2 in Tuesday's keynote, I attended two more of his talks: one on Meteor and another on Aurelia. I've known about Meteor for a while, but have become more intrigued by it lately with its 1.2 release and Angular support. Meteor's command line tools that auto-inject CSS and JS demoed very well, as did it's installable features like a LESS support and Facebook authentication.

After hearing all the good things about Angular 2 from Peter, it was interesting to hear him downplay it in his Aurelia talk later that day. When he started showing code, it was pretty obvious that Aurelia is doing a great job of simplifying JavaScript MVC syntax for developers. You can develop components with almost half the code that Angular 2 requires, and it uses ES6, jspm and SystemJS. If you're developing JavaScript, learning these tools will help prepare you for the future. It's cool that Aurelia encourages learning things you should learn anyway.

Aurelia and Angular 2 are both still in Alpha, so I'm not sure it makes sense to use them on a project this year. However, I do think it's important to track them both. I especially think it's interesting that the founder of Aurelia, Rob Eisenberg, left the Angular Team in November 2014 and announced Aurelia in January 2015 (Hacker News thread). Peter mentioned several times that Aurelia wants to help developers write apps, while AngularJS is more tied to helping Google write apps.

There were around 400 people at Angular Summit, which I think is pretty good for a first-run conference. As with most No Fluff Just Stuff shows, it ran smoothly, had plenty of time between sessions and was filled with knowledgeable, entertaining speakers. It was fun doing my first keynote and I look forward to speaking again in November (at Devoxx) and December (at The Rich Web Experience).

1. I know Dice.com is probably not a great site, but it makes sense to use it since I've been tracking JavaScript MVC framework job stats on it since February 2014.

SpringOne 2GX 2015: My Presentations on Comparing Hot JavaScript Frameworks and NoXML

Matt Raible — Sun, 20 Sep 2015 12:29:00 -0600

Last week, I had the pleasure of traveling to Washington, DC to speak at the annual SpringOne 2GX conference. I was pretty stressed for the last few weeks because I had to create two new presentations from scratch, and both had to be 90 minutes long. I was also hoping to finish the JHipster Book before the conference started. I was able to finish both presentations in the nick of time, but did not find the time to write the last chapter in the JHipster Book.

The first presentation was titled Comparing Hot JavaScript Frameworks: AngularJS, Ember.js and React.js. I started by revisiting the Comparing JVM Web Frameworks talk I did at vJUG last February. I explained how I think traditional web frameworks are no longer relevant in 2015, but I do believe server-side rendering is still very relevant. From there, I used Yevgeniy Brikman’s framework scorecard (from his Node.js vs. Play Framework presentation) to rank each framework by a number of different criteria. You can see the final results on slide 160. Since the scores were so close, I believe you could tweak some scores a bit (or add weights to the different criteria) and make any of the frameworks come out on top.

You can click through the presentation below, download it from my presentations page, or see it on SlideShare.

I started writing the second presentation a week before I had to deliver it. On Thursday, September 10th, I stayed up late, trying to figure out how to create a good presentation on NoXML and finish the last part of the JHipster Book. Then it came to me, I needed to parallelize and do them both at the same time. I decided to compare AppFuse (which is similar to a legacy Spring application with lots of XML) to JHipster (which hardly contains any XML).

I wrote a 10-page Google Doc on how I planned to do this, then went rafting and camping with my family for the weekend. I finished most of the presentation on Monday night, but then realized the presentation wouldn't be long enough to fill 90 minutes. So I hunkered down at midnight, created a new AppFuse application and removed a bunch of its XML. This took me until 3:30am, and I was able to accomplish the following tasks:

Spring XML to Java
Spring Security Configuration to Java
web.xml to WebApplicationInitializer
Spring MVC to Java
Migrated to Spring Boot
Maven to Groovy

I was pretty pumped when I completed my final goal: converting to Spring Boot and getting a test to pass. I made commits to an appfuse-noxml project on GitHub as I accomplished each step. You can see all the changes in the project's commit log. While I'd figured everything out, I still needed to complete the presentation. Luckily, I found time to do this the night before, the morning of, and in the final hour before I had to deliver the talk. You can imagine my relief when I was done delivering both talks.

You can click through the presentation below, download it from my presentations page, or view it on SlideShare.

While I didn't get to spend much time at the conference, I did have a lot of fun while I was there. I got to meet some new folks, reconnect with old friends, and enjoy beers and dinner with a smiling crew on Thursday night. The Broncos victory late that night was the icing on the cake.

Best Practices for using Foundation with AngularJS Revisited

Matt Raible — Thu, 19 Feb 2015 09:38:42 -0700

A couple weeks ago I wrote about using Foundation with AngularJS. Based on research I'd done, I concluded that it was best to use Foundation for Apps for any webapps my client created and Foundation for Sites for any websites (e.g. a WordPress-based intranet).

After doing my initial research, I did some prototyping with Foundation for Apps (F4A). What I discovered is that F4A does not include all the same components as Foundation for Sites (F5). For example, the top-bar and dropdown functionality are missing. I posted my issues to the Foundation Forums.

The response I received:

It should work. You would need to copy over all the Scss and global mixins that you used in top-bar or at least all the output CSS from it. Otherwise there is no reason the components won't fit into the grid.

I was able to import Foundation for Sites into my project by adding it to bower.json:

  "dependencies": {
    "foundation-apps": "~1.0.2",
    "foundation": "~5.5.1"
  }

After doing this, I added the new path to Gulpfile.js:

var sassPaths = [
  'client/assets/scss',
  'bower_components/foundation/scss',
  'bower_components/foundation-apps/scss'
];

After making this change, the top-bar rendered and my dropdowns worked. Since there was no jQuery in the page, I thought this might be a viable option. However, Jason Demitri quickly pointed out it probably wouldn't work with mobile. He was right.

While using F4A, I noticed that its components, and much of its look-n-feel, was different than F5. If you look at its Email App template, you'll see it looks kinda like a mobile app, even in a desktop browser. After trying F4A myself, I decided that F4A wasn't for us. First of all, it doesn't seem to provide a consistent look and feel with a website that's written using F5. Furthermore, F4A only supports IE10+. In the healthcare industry, there's a lot of older browsers out there, so my client needs to support IE9 as a minimum.

For these reasons, I decided to try Angular directives for Foundation. I took a prototype I'd written with F5, removed its JavaScript, added Angular Foundation + Foundation dependencies to bower.json, added references to the respective scripts in index.html and added 'mm.foundation' as a dependency in app.js. The experiment worked beautifully and I was quite happy with the results. I shared my findings with the team and we decided Angular Foundation is the best way to integrate Foundation and AngularJS.

F4A is pretty new and I imagine it'll add more of F5's features as it evolves. However, I don't know if the two will ever be so similar that they can live side-by-side and allow a seamless experience for users. If you're interested in mixing F4A and F5, you might want to watch Jason Demitri's foundationUltra. This project combines Angular Foundation, Foundation for Sites, Foundation for Apps and Font Awesome. You can see a demo at http://relutiondev.github.io/foundationUltra/.

Best Practices for using Foundation with AngularJS

Matt Raible — Thu, 5 Feb 2015 09:21:50 -0700

I was recently tasked with doing some research to figure out the best way to use Foundation with AngularJS. Goals for this research included:

Identify use cases of Foundation for Sites vs Foundation for Apps and recommend when to use each.
Look at pros and cons of using AngularJS with Foundation for Sites.

I'm writing this blog post to get feedback from you, fellow web developers, on your experience with Foundation. Have you tried using Foundation for Sites with AngularJS? If so, did you experience any pain?

From what I can tell, it looks like Foundation for Apps (FA) was created because folks had issues making AngularJS and Foundation 5 play nicely together. The Next Foundation explains why FA was created. Reddit's web_design zone has quite a few comments related to this article.

From there, I found a few ZURB blog posts that describe FA's three main advantages over Foundation for Sites (FS):

This thread on the Foundation forums seems to indicate that FA would be good for developing applications while FS would be good for an intranet built on WordPress (since it's more of a website than a webapp).

Foundation for apps is for making responsive web apps vs responsive web sites. The difference is in the structure of an app. They usually take up the screen and instead of the page scrolling, content in the app scrolls. Apps employ stateful views, so a view can change without reloading the app, creating a better user experience.

This other thread backs up that notion.

Foundation for Apps will be an additional version of Foundation - not a replacement.

This means Foundation for Sites will continue on along side the new Apps version. Ink will be Foundation for Emails.

Having said that, choosing which one to use simply depends on the type of site you need to build. The Apps grid is better suited to make web apps or apps that can be wrapped for native.

The syntax is different (on purpose) and we are taking great care to make it easy to get.

You should continue using Foundation for sites as long as you need traditional scrolling websites. We don't expect people to convert an existing site to an app unless they need to re-do their site anyways.

I also found Angular Foundation which is a "a port of the AngularUI team's excellent angular-bootstrap project for use in the Foundation framework".

The problem I see with using Angular Foundation over Foundation for Apps is that it's maintained by folks that aren't developing Foundation. It's more of a "here's some Bootstrap widgets as Foundation widgets".

It could also come down to IE support. Angular Foundation supports IE9+ while Foundation for Apps is IE10+. From What You Need To Know About Zurb Foundation for Apps:

Foundation for Apps works with all of the modern browsers including Internet Explorer 10. It doesn't support IE9 and other older browsers because of the new CSS3 features and issues of AngularJS in older browsers. Below is the snapshot of the compatibility list grabbed from Zurb website.

I wrote this article in order to publish my research findings about Foundation for Apps vs. Foundation for Sites. It seems like the natural thing to do is to use FA for any webapps we create and FS for any websites (e.g. WordPress sites). Do you agree with these findings? Any other recommended practices for integrating Foundation with AngularJS?

Sidenote: For the project I'm working on, we haven't chose a backend framework yet. We've chosen Heroku as our deployment platform, so there's a plethora of languages and frameworks to choose from. It's too bad JHipster doesn't support Foundation. I could probably sell the team on Java + Spring Boot pretty easily if it did.

The Art of AngularJS in 2015

Matt Raible — Wed, 4 Feb 2015 09:14:57 -0700

I've been tracking statistics on jobs and skills for JavaScript MVC frameworks ever since I Compared JVM Web Frameworks at Devoxx France in 2013. At that time, Backbone was the dominant framework.

Last year, I updated those statistics for a presentation on AngularJS at Denver's Derailed. Angular had a similar amount of jobs as Backbone and a lot of people added it to their LinkedIn profiles. I found that Ember had grown around 300%, Backbone 200% and Angular 1000%!

Before presenting on AngularJS at last night's Denver Open Source Users Group, I updated these statistics once again. The charts below show how the number of jobs for Angular has doubled in the last year, while jobs for Ember and Backbone have fallen slightly. As far as skills, developers learning Ember and Backbone has increased 200%, while skilled Angular folks has risen 400%.

Yes, AngularJS has experienced huge growth in the last couple of years. You might even say it's the Struts of the JavaScript world. I like to say that Struts 1.x was the 'Killer App' for J2EE back in the day.

For the presentation I delivered last night, I made a number of improvements over last year's. I added a live coding demo based on my Getting Started with AngularJS tutorial. I used IntelliJ's live templates to make it look easy. However, since the audience was quiet, and some were falling asleep, I skipped over the testing demo.

I added a few slides on Foundation for Apps (FA). We've selected AngularJS and Foundation on my current project, and I've been researching how to integrate the two lately. FA is one solution I've found, Angular Foundation is another. If you know of others, please let me know.

For Java developers getting started with Angular, I recommended JHipster. I talked about its foundational frameworks and project options when creating your project. I included screenshots of its slick metrics UI and code generation features.

I also added a slide for Dave Syer's excellent five-part series on Spring and AngularJS:

Finally, I added a number of slides on Angular 2.0. I encouraged folks to checkout The Twelve-Factor App and James Ward's Java Doesn’t Suck – You’re Just Using it Wrong.

The discussion with the audience was great, particularly around HTTP/2 and minification/concatenation of assets. Thanks to all who attended, I really enjoyed having the opportunity to share what I've learned.

You can click through my presentation below, download it from my presentations page, or view it on SlideShare.

If you live in Denver, there's a number of interesting meetups happening in the next couple months.

Monday, February 16: Introduction to ReactJS at HTML5 Denver
Tuesday & Wednesday, March 3rd and 4th: ThingMonk at a distillery!
Wednesday, April 8: I'll be speaking about JHipster at Denver Java User Group

I'm also looking for speakers to teach programming to kids at Devoxx4Kids Denver. Let me know if you have a fun topic you'd like to present.

Testing AngularJS Applications

Matt Raible — Mon, 2 Feb 2015 10:11:56 -0700

This article is the second in a series about learning AngularJS. It describes how to test a simple AngularJS application. In a previous article, Getting Started with AngularJS, I showed how to develop a simple search and edit feature.

What you'll learn

You'll learn to use Jasmine for unit testing controllers and Protractor for integration testing. Angular's documentation has a good developer's guide to unit testing if you'd like more information on testing and why it's important.

The best reason for writing tests is to automate your testing. Without tests, you'll likely be testing manually. This manual testing will take longer and longer as your codebase grows.

What you'll need

About 15-30 minutes
A favorite text editor or IDE. We recommend IntelliJ IDEA.
Git installed.
Node.js and NPM installed.

Get the tutorial project

Clone the angular-tutorial repository using git and install the dependencies.

git clone https://github.com/mraible/angular-tutorial.git
cd angular-tutorial
npm install

If you haven't completed the Getting Started with AngularJS tutorial, you should peruse it so you understand how this application works. You can also simply start the app with "npm start" and view it in your browser at http://localhost:8000/app/.

Test the SearchController

Create app/search/search_test.js and populate it with the basic test infrastructure. This code sets up a mock SearchService that has the first function we want to test: query(term). It uses $provide to override the default SearchService. Angular unit-test controllers - mocking service inside controller was a useful question on Stack Overflow for figuring out how to mock services in controllers.
```
'use strict';

describe('myApp.search module', function() {
    var mockSearchService;

    beforeEach(module('myApp.search', function($provide) {
        mockSearchService = {query: function(term) {}};
        $provide.value("SearchService", mockSearchService);
    }));
});
```

Modify karma.conf.js (in the root directory) to add the search implementation and test.

files : [
  ...
  'app/components/**/*.js',
  'app/search/search.js',
  'app/search/search_test.js',
  'app/view*/**/*.js'
],

Add the first test to search_test.js. This test verifies that setting a search term and executing the search() function will call the service and return results. You can see the results returned from the service are mocked with deferred.resolve(). The deferred.resolve() call is how to handle promises in unit tests.

describe('search by term', function() {
    var scope, rootScope, controller, deferred;

	// setup the controller with dependencies.
    beforeEach(inject(function($rootScope, $controller, $q) {
        rootScope = $rootScope;
        scope = $rootScope.$new();
        controller = $controller('SearchController', {$scope: scope, SearchService: mockSearchService });
        deferred = $q.defer();
    }));

    it('should search when a term is set and search() is called', function() {
        spyOn(mockSearchService, 'query').andReturn(deferred.promise);
        scope.term = 'M';
        scope.search();
        deferred.resolve({data: {name: "Peyton Manning"}});
        rootScope.$apply();
        expect(scope.searchResults).toEqual({name: "Peyton Manning"});
    });
});

Related: Introduction to Unit Test: Spies is a good introduction to using spies in unit tests.

Run the following command on the command line to start the Karma test runner. You can leave this process running and new tests will be run automatically. You can change the mocked data and expectation to see your test fail.
```
npm test
```
Running Tests from IntelliJ IDEA
See Running Unit Tests on Karma to learn how to run your tests from IntelliJ IDEA.

Add a test to verify a search occurs automatically when the term is in the URL. Notice how the code structure had to change a bit to handle $routeParams.

describe('search by term automatically', function() {
    var scope, rootScope, controller, location, deferred;

    beforeEach(inject(function($rootScope, $controller, $q) {
        rootScope = $rootScope;
        scope = $rootScope.$new();

        // in this case, expectations need to be setup before controller is initialized
        var routeParams = {"term": "peyton"};
        deferred = $q.defer();
        spyOn(mockSearchService, 'query').andReturn(deferred.promise);
        deferred.resolve({data: {name: "Peyton Manning"}});

        controller = $controller('SearchController', {$scope: scope, $routeParams: routeParams, SearchService: mockSearchService });
    }));

    it('should search automatically when a term is on the URL', function() {
        rootScope.$apply();
        expect(scope.searchResults).toEqual({name: "Peyton Manning"});
    });
});

Add a test to verify the EditController works as expected.

describe('edit person', function() {
    var scope, rootScope, controller, location, deferred;

    beforeEach(inject(function($rootScope, $controller, $q) {
        rootScope = $rootScope;
        scope = $rootScope.$new();

        // expectations need to be setup before controller is initialized
        var routeParams = {"id": "1"};
        deferred = $q.defer();
        spyOn(mockSearchService, 'fetch').andReturn(deferred.promise);
        deferred.resolve({data: {name: "Peyton Manning", address: {street: "12345 Blake Street", city: "Denver"}}});

        controller = $controller('EditController', {$scope: scope, $routeParams: routeParams, SearchService: mockSearchService });
    }));

    it('should fetch a single record', function() {
        rootScope.$apply();
        expect(scope.person.name).toBe("Peyton Manning");
        expect(scope.person.address.street).toBe("12345 Blake Street");
    });
});

After adding this test, you'll likely see the following error in your terminal.

Chrome 40.0.2214 (Mac OS X 10.10.2) myApp.search module edit person should fetch a single record FAILED
	fetch() method does not exist
	TypeError: Cannot read property 'name' of undefined

This happens because the mockSearchService does not have a fetch method defined. Modify the beforeEach() on line 7 to add this function.

mockSearchService = {query: function(term) {}, fetch: function(id) {}};

Extra Credit

Create a test for saving a person. Here's a question on Stack Overflow that might help you verify the location after a save has been performed.

Test the Search Feature

To test if the application works end-to-end, you can write scenarios with Protractor. These are also known as integration tests, as they test the integration between all layers of your application.

To verify end-to-end tests work in the project before you begin, run the following command in one terminal window:

npm start

Then in another window, run the following to execute the tests:

npm run protractor

Write your first integration test to verify you can navigate to /search and enter a search term to see results. Add the following to e2e-tests/scenarios.js:

describe('search', function() {
  var searchTerm = element(by.model('term'));
  var searchButton = element(by.id('search'));

  beforeEach(function() {
    browser.get('index.html#/search');
  });

  it('should allow searching at /search', function() {
    searchTerm.sendKeys("M");
    searchButton.click().then(function() {
      expect(element.all(by.repeater('person in searchResults')).count()).toEqual(3);
    });
  });
});

The "searchTerm" variable represents the input field. The by.model() syntax binds to the "ng-model" attribute you defined in the HTML.

Run "npm run protractor". This should fail with the following error.

[launcher] Running 1 instances of WebDriver
Selenium standalone server started at http://172.16.6.39:64230/wd/hub
...F
Failures:
  1) my app search should allow searching at /search
   Message:
     NoSuchElementError: No element found using locator: By.id("search")

To fix, you need to add an "id" attribute to the Search button in app/search/index.html.

<form ng-submit="search()">
    <input type="search" name="search" ng-model="term">
    <button id="search">Search</button>
</form>

Run the tests again using "npm run protractor". They should all pass this time.

Write another test to verify editing a user displays their information.

describe('edit person', function() {
  var name = element(by.model('person.name'));
  var street = element(by.model('person.address.street'));
  var city = element(by.model('person.address.city'));

  beforeEach(function() {
    browser.get('index.html#/edit/1');
  });

  it('should allow viewing a person', function() {
    // getText() doesn't work with input elements, see the following for more information:
    // https://github.com/angular/protractor/blob/master/docs/faq.md#the-result-of-gettext-from-an-input-element-is-always-empty
    expect(name.getAttribute('value')).toEqual("Peyton Manning");
    expect(street.getAttribute('value')).toEqual("1234 Main Street");
    expect(city.getAttribute('value')).toEqual("Greenwood Village");
  });
});

Verify it works with "npm run protractor".

Finally, write a test to verify you can save a person and their details are updated. Figuring out how to verify the URL after it changed was assisted by this issue.

describe('save person', function() {
  var name = element(by.model('person.name'));
  var save = element(by.id('save'));

  beforeEach(function() {
    browser.get('index.html#/edit/1');
  });

  it('should allow updating a name', function() {
    name.sendKeys(" Updated");
    save.click().then(function() {
      // verify url set back to search results
      browser.driver.wait(function() {
        return browser.driver.getCurrentUrl().then(function(url) {
          expect(url).toContain('/search/Peyton%20Manning%20Updated');
          return url;
        });
      });
      // verify one element matched this change
      expect(element.all(by.repeater('person in searchResults')).count()).toEqual(1);
    });
  });
});

When you run this test with "npm run protractor", it should fail because there's no element with id="save" in app/search/edit.html. Add it to the Save button in this file and try again. You should see something similar to the following:
```
Finished in 4.478 seconds
6 tests, 9 assertions, 0 failures
```

Source Code

A completed project with this code in it is available on GitHub at https://github.com/mraible/angular-tutorial on the testing branch.

There are two commits that make the changes for the two main steps in this tutorial:

Summary

I hope you've enjoyed this quick-and-easy tutorial on testing AngularJS applications. The first couple AngularJS applications I developed didn't have tests and required a lot of manual testing to verify their quality. After learning that testing AngularJS apps is pretty easy, I now do it on all my projects. Hopefully this tutorial motivates you to do do the same.

Getting Started with AngularJS

Matt Raible — Thu, 29 Jan 2015 11:12:38 -0700

I was hired by my current client in November to help them choose a technology stack for developing modern web applications. In our first sprint, we decided to look at JavaScript MVC frameworks. I suggested AngularJS, Ember.js and React. Since most of the team was new to JavaScript MVC, I decided to create a tutorial for them. I tried to make it easy so they could learn how to write a simple web application with AngularJS. I thought others could benefit from this article as well, so I asked (and received) permission from my client to publish it here.

What you'll build

You'll build a simple web application with AngularJS. You'll also add search and edit features with mock data.

What you'll need

About 15-30 minutes
A favorite text editor or IDE. I recommend IntelliJ IDEA.
Git installed.
Node.js and NPM installed.

Create a simple web application

Clone the angular-seed repository using git:

git clone https://github.com/angular/angular-seed.git angular-tutorial
cd angular-tutorial

There are two kinds of dependencies in this project: tools and angular framework code. The tools help manage and test the application.
- To get the tools that depend upon via npm, the node package manager.
- To get the angular code via bower, a client-side code package manager.
The project has preconfigured npm to automatically run bower so you can simply do:
```
npm install
```

Run the application

The project is configured with a simple development web server. The simplest way to start this server is:

npm start

Now browse to the app at http://localhost:8000/app/.

Add a search feature

To add a search feature, open the project in an IDE or your favorite text editor. For IntelliJ IDEA, use File > New Project > Static Web and point to the directory you cloned angular-seed to.

The Basics

Create an app/search/index.html file with the following HTML:

<form ng-submit="search()">
    <input type="search" name="search" ng-model="term">
    <button>Search</button>
</form>

Create app/search/search.js and define the routes (URLs) and controller for the search feature.

angular.module('myApp.search', ['ngRoute'])

    .config(['$routeProvider', function ($routeProvider) {
        $routeProvider
            .when('/search', {
                templateUrl: 'search/index.html',
                controller: 'SearchController'
            })
    }])

    .controller('SearchController', function () {
        console.log("In Search Controller...");
    });

Modify app/app.js and add the "myApp.search" module you created above.

angular.module('myApp', [
  'ngRoute',
  'myApp.view1',
  'myApp.view2',
  'myApp.version',
  'myApp.search'
])

Modify app/index.html and add a link to the search.js file.

<script src="view2/view2.js"></script>
<script src="search/search.js"></script>
<script src="components/version/version.js"></script>

Refresh your browser and navigate to http://localhost:8000/app/#/search. You should see an input field and search button. You should also see a log message printed in your browser's console. In Chrome, you can view the console using View > Developer > JavaScript Console. You can make it easier to navigate to this page by adding a menu item in app/index.html.
```
<ul class="menu">
  <li><a href="#/view1">view1</a></li>
  <li><a href="#/view2">view2</a></li>
  <li><a href="#/search">search</a></li>
</ul>
```

This section has shown you how to add a new controller and view to a basic AngularJS application. This was fairly simple to create. The next section shows you how to create a fake backend API.

The Backend

To get search results, you're going to create a SearchService that makes HTTP requests. These HTTP requests will be handled by a mock backend using some of Angular's built-in mocking tools. The backend implementation was created using AngularJS Backend-less Development Using a $httpBackend Mock.

Add a SearchService to app/search/search.js. This is done in Angular using its Factory Recipe. Make sure to remove the semicolon from the .controller code block.

.controller('SearchController', function () {
    console.log("In Search Controller...");
})

.factory('SearchService', function ($http) {
    var service = {
        query: function (term) {
            return $http.get('/search/' + term);
        }
    };
    return service;
});

Inject the SearchService into the SearchController and use it to get results from the backend. The form in app/search/index.html calls the search() function. The "term" is defined by the input field in this page with ng-model="term".

.controller('SearchController', function ($scope, SearchService) {
    $scope.search = function () {
        console.log("Search term is: " + $scope.term);
        SearchService.query($scope.term).then(function (response) {
            $scope.searchResults = response.data;
        });
    };
})

If you try to search for a "foo" term now, you'll see the following error in your console.

Search term is: foo
GET http://localhost:8000/search/foo 404 (Not Found)

Create app/search/mock-api.js for the fake backend. Populate it with the following JavaScript.

// We will be using backend-less development
// $http uses $httpBackend to make its calls to the server
// $resource uses $http, so it uses $httpBackend too
// We will mock $httpBackend, capturing routes and returning data
angular.module('myApp')
    .service('ServerDataModel', function ServerDataModel() {
        this.data = [
            {
                id: 1,
                name: "Peyton Manning",
                phone: "(303) 567-8910",
                address: {
                    street: "1234 Main Street",
                    city: "Greenwood Village",
                    state: "CO",
                    zip: "80111"
                }
            },
            {
                id: 2,
                name: "Demaryius Thomas",
                phone: "(720) 213-9876",
                address: {
                    street: "5555 Marion Street",
                    city: "Denver",
                    state: "CO",
                    zip: "80202"
                }
            },
            {
                id: 3,
                name: "Von Miller",
                phone: "(917) 323-2333",
                address: {
                    street: "14 Mountain Way",
                    city: "Vail",
                    state: "CO",
                    zip: "81657"
                }
            }
        ];

        this.getData = function () {
            return this.data;
        };

        this.search = function (term) {
            if (term == "" || term == "*") {
                return this.getData();
            }
            // find the name that matches the term
            var list = $.grep(this.getData(), function (element, index) {
                term = term.toLowerCase();
                return (element.name.toLowerCase().match(term));
            });

            if (list.length === 0) {
                return [];
            } else {
                return list;
            }
        };
    })
    .run(function ($httpBackend, ServerDataModel) {

        $httpBackend.whenGET(/\/search\/\w+/).respond(function (method, url, data) {
            // parse the matching URL to pull out the term (/search/:term)
            var term = url.split('/')[2];

            var results = ServerDataModel.search(term);

            return [200, results, {Location: '/search/' + term}];
        });

        $httpBackend.whenGET(/search\/index.html/).passThrough();
        $httpBackend.whenGET(/view/).passThrough();
    });

This file uses jQuery.grep(), so you'll need to install jQuery. Modify bower.json and add jQuery to the list of dependencies.
```
"dependencies": {
  ...
  "html5-boilerplate": "~4.3.0",
  "jquery": "~1.10.x"
}
```
Stop the npm process, run "npm install" to download and install jQuery, then "npm start" again.

Modify app/app.js and add a dependency on ngMockE2E.

angular.module('myApp', ['ngMockE2E',
  'ngRoute',
  ...

Modify app/index.html to include references to jquery.js, angular-mocks.js and mock-api.js.

<script src="bower_components/angular-route/angular-route.js"></script>
<script src="bower_components/angular-mocks/angular-mocks.js"></script>
<script src="bower_components/jquery/jquery.js"></script>
...
<script src="search/mock-api.js"></script>
<script src="components/version/version.js"></script>

Add the following HTML to app/search/index.html to display the search results.
```
<div>
    <pre>{{ searchResults | json}}</pre>
</div>
```
After making this change, you should be able to search for "p", "d" or "v" and see results as JSON.

To make the results more readable, change the above HTML to use a <table> and Angular's ng-repeat directive.

<table ng-show="searchResults.length" style="width: 100%">
    <thead>
    <tr>
        <th>Name</th>
        <th>Phone</th>
        <th>Address</th>
    </tr>
    </thead>
    <tbody>
    <tr ng-repeat="person in searchResults">
        <td>{{person.name}}</td>
        <td>{{person.phone}}</td>
        <td>{{person.address.street}}<br/>
            {{person.address.city}}, {{person.address.state}} {{person.address.zip}}
        </td>
    </tr>
    </tbody>
</table>

This section has shown you how to fetch and display search results. The next section builds on this and shows how to edit and save a record.

Add an Edit Feature

Modify app/search/index.html to add a link for editing a person.

<table ng-show="searchResults.length" style="width: 100%">
    ...
    <tr ng-repeat="person in searchResults">
        <td><a href="" ng-click="edit(person)">{{person.name}}</a></td>
        ...
    </tr>
</table>

Add an edit() function to SearchController. Notice that the $location service dependency has been added to the controller's initialization function.

.controller('SearchController', function ($scope, $location, SearchService) {
    ...

    $scope.edit = function (person) {
        $location.path("/edit/" + person.id);
    }
})

Create a route to handle the edit URL in app/search/search.js.

.config(['$routeProvider', function ($routeProvider) {
    $routeProvider
        .when('/search', {
            templateUrl: 'search/index.html',
            controller: 'SearchController'
        })
        .when('/edit/:id', {
            templateUrl: 'search/edit.html',
            controller: 'EditController'
        });
}])

Create app/search/edit.html to display an editable form. The HTML below shows how you can use HTML5's data attributes to have valid attributes instead of ng-*.

<form ng-submit="save()">
    <div>
        <label for="name">Name:</label>
        <input type="text" data-ng-model="person.name" id="name">
    </div>
    <div>
        <label for="phone">Phone:</label>
        <input type="text" data-ng-model="person.phone" id="phone">
    </div>
    <fieldset>
        <legend>Address:</legend>
        <address style="margin-left: 50px">
            <input type="text" data-ng-model="person.address.street"><br/>
            <input type="text" data-ng-model="person.address.city">,
            <input type="text" data-ng-model="person.address.state" size="2">
            <input type="text" data-ng-model="person.address.zip" size="5">
        </address>
    </fieldset>
    <div>
        <button type="submit">Save</button>
    </div>
</form>

Modify SearchService to contain functions for finding a person by their id, and saving them.

.factory('SearchService', function ($http) {
    var service = {
        query: function (term) {
            return $http.get('/search/' + term);
        },
        fetch: function (id) {
            return $http.get('/edit/' + id);
        },
        save: function(data) {
            return $http.post('/edit/' + data.id, data);
        }
    };
    return service;
});

Create EditController in app/search/search.js. $routeParams is an Angular service that allows you to grab parameters from a URL.

.controller('EditController', function ($scope, $location, $routeParams, SearchService) {
    SearchService.fetch($routeParams.id).then(function (response) {
        $scope.person = response.data;
    });

    $scope.save = function() {
        SearchService.save($scope.person).then(function(response) {
            $location.path("/search/" + $scope.person.name);
        });
    }
})

At the bottom of app/search/mock-api.js, in its run() function, add the following:

$httpBackend.whenGET(/\/search/).respond(function (method, url, data) {
    var results = ServerDataModel.search("");

    return [200, results];
});

$httpBackend.whenGET(/\/edit\/\d+/).respond(function (method, url, data) {
    // parse the matching URL to pull out the id (/edit/:id)
    var id = url.split('/')[2];

    var results = ServerDataModel.find(id);

    return [200, results, {Location: '/edit/' + id}];
});

$httpBackend.whenPOST(/\/edit\/\d+/).respond(function(method, url, data) {
    var params = angular.fromJson(data);

    // parse the matching URL to pull out the id (/edit/:id)
    var id = url.split('/')[2];

    var person = ServerDataModel.update(id, params);

    return [201, person, { Location: '/edit/' + id }];
});

$httpBackend.whenGET(/search\/edit.html/).passThrough();

Further up in the same file, add find() and update() methods to ServerDataModel.

this.getData = function () {
    return this.data;
};

this.search = function (term) {
    ...
};

this.find = function (id) {
    // find the game that matches that id
    var list = $.grep(this.getData(), function (element, index) {
        return (element.id == id);
    });
    if (list.length === 0) {
        return {};
    }
    // even if list contains multiple items, just return first one
    return list[0];
};

this.update = function (id, dataItem) {
    // find the game that matches that id
    var people = this.getData();
    var match = null;
    for (var i = 0; i < people.length; i++) {
        if (people[i].id == id) {
            match = people[i];
            break;
        }
    }
    if (!angular.isObject(match)) {
        return {};
    }
    angular.extend(match, dataItem);
    return match;
};

The <form> in app/search/edit.html calls a save() function to update a person's data. You already implemented this above. The function executes the logic below.

$location.path("/search/" + $scope.person.name);

Since the SearchController doesn't execute a search automatically when you execute this URL, add the following logic to do so in app/search/search.js. Note that $routeParams is added to the list of injected dependencies.

.controller('SearchController', function ($scope, $location, $routeParams, SearchService) {
    if ($routeParams.term) {
        SearchService.query($routeParams.term).then(function (response) {
            $scope.term = $routeParams.term;
            $scope.searchResults = response.data;
        });
    }
    ...
})

You'll also need to add a new route so search/term is recognized.

.config(['$routeProvider', function ($routeProvider) {
    $routeProvider
        .when('/search', {
            templateUrl: 'search/index.html',
            controller: 'SearchController'
        })
        .when('/search/:term', {
            templateUrl: 'search/index.html',
            controller: 'SearchController'
        })
        ...
}])

After making all these changes, you should be able to refresh your browser and search/edit/update a person's information. If it works - nice job!

Source Code

A completed project with this code in it is available on GitHub at https://github.com/mraible/angular-tutorial.

There are three commits that make the changes for the three main steps in this tutorial:

Extra Credit

Deploy your completed app to Heroku. See running version of this tutorial at https://angular-123.herokuapp.com.

Summary

I hope you've enjoyed this quick-and-easy tutorial on how to get started with AngularJS. In a future tutorial, I'll show you how to write unit tests and integration tests for this application. If you're in Denver next Tuesday, I'll be speaking about AngularJS at Denver's Open Source Users Group.

If you're a Java developer that's interested in developing with AngularJS and Spring Boot, you might want to checkout the recently released JHipster 2.0.

The Art of AngularJS

Matt Raible — Thu, 27 Feb 2014 09:44:29 -0700

Last night, I had the pleasure of speaking at Denver's DeRailed about AngularJS. Fernand (the group's leader) asked me to speak in December, just after I'd finished a European speaking tour. The Modern Java Web Developer talk I created for that tour included a 20-minute AngularJS Deep Dive screencast. I figured it wouldn't be much work to augment the screencast and create an hour long talk, so I agreed.

When I started creating the presentation last week, I decided I didn't want to make the audience watch my screencast as part of the presentation. They could easily do that on their own time. So I wrote, from scratch, a brand new presentation on AngularJS. I tried to include all the things about Angular that I thought were important and useful for me in my learning process. The result is a presentation I'm proud of and enjoyed delivering.

You can click through it below, download it from my presentations page, or view it on SlideShare.

You might notice the presentation has a whole lot of code in it. Normally, when I copy/paste code into a presentation, I use IntelliJ IDEA and everything works. This time, there was something amiss between IDEA 13 and Keynote 6. I tried using IDEA's plugins (namely Copy on steroids and Copy as HTML), but none of them worked. IDEA 12 resulted in the same problem. Then I turned to other solutions. I installed highlight and copied code from the command line. This worked, but the fonts and colors weren't to my liking. Finally, I decided to try another editor: Sublime Text with SublimeHighlight. This worked great and I'm very happy with the results.

Most of my presentations end with a Questions/Contact slide. For this one, I added a few more: people to follow on Twitter, resources to learn from and projects with useful code. Below are a handful of links that greatly enhanced my AngularJS knowledge in the last year.

Devoxx 2012 - Re-imagining the browser with AngularJS. This is the original video I watched about AngularJS. I learned enough from this one video to start developing my first app for a client. I wrote about it in a four-part series on Developing with AngularJS.
ng-book: The Complete Book on AngularJS. A great book with all the nitty-gritty Angular details you ever wanted to know.
David Mosher's Testing Strategies for AngularJS. I stumbled upon this a week ago and it's greatly enhanced my knowledge of how to test AngularJS apps. It also introduced me to Lineman, which I'm thankful for.
Egghead.io - bit-sized videos of AngularJS knowledge. Very useful for when you want to learn how to do a specific thing quickly.
AngularJS + REST + Spring Security. This is a sample application from Philip Sorst (ported to Spring Boot by my good friend Josh Long) that shows how to integrate AngularJS with Spring Security for stateless, token-based authentication.

One of the audience members at DeRailed recommended thinkster.io as a good resource too.

Thanks to Fernand for inviting me to speak and causing me to write this presentation. Creating it greatly improved my AngularJS knowledge and I learned about some new tools in the process. If you'd like to tap into my wealth of knowledge, I'm available for a new gig in April.

Devoxx 2013 + a Nordic Countries Speaking Tour

Matt Raible — Thu, 28 Nov 2013 12:07:26 -0700

Two weeks ago, Trish and I boarded a flight for one of our favorite conferences: Devoxx. After a brief layover in Frankfurt, we arrived in Amsterdam and took a train to Antwerp. Within hours, we'd settled into our hotel near the center of Antwerp and strolled over to the dungeonous, yet cozy, Pelgrom restaurant. We were hoping for a delicious dinner, but found much more. We ran into James Ward, Dick Wall and a number of other enthusiastic speakers from the conference. Since I had to speak the next day, we didn't stay long, but we did share a number of laughs with some great people.

Tuesday (November 12), was a University Day at Devoxx, and I had my talk that afternoon. I spent a couple hours finishing up my talk that morning, then grabbed a taxi to head to the conference. I was honored with the opportunity to speak in Room 8, which is a huge theater that holds several hundred people.

I presented a lengthened version of The Modern Java Web Developer presentation I did early this year (at Denver's JUG and JavaOne). Based on your feedback, I chose to do deep dives on AngularJS, Bootstrap and Page Speed. I've always enjoyed speaking at Devoxx because attendees are so enthusiastic and passionate about the conference. I received an immense amount of feedback, both in praises and criticisms. The critics indicated there were too many buzzwords and not enough substance. Others complained that the AngularJS Lipsync that I did was too deep.

I made sure to review and process everyone's comments, and then used them to improve the presentation throughout the following week. I learned to elaborate on the fact that many of the technologies were important to know about, but not important to know through-and-through. I made sure to mention that the use of CoffeeScript and LESS is often limited (or embraced) by team members and their willingness to try new things. If you're not writing thousands of lines of JavaScript or CSS, it probably doesn't make sense to use these languages. Furthermore, if your team members are struggling to write JavaScript or CSS, introducing a new language is probably not the best thing. I also reminded people to be skeptical of new technology, but also to be open-minded and give everything a chance. The 10-minute, download-and-try test, is a great way to do that.

You can find my presentation below, download it from my presentations page, or view it on SlideShare.

Within this presentation, there are links to each of the deep dives. The last two are screencasts that I added audio to a few days ago.

Bootstrap 3 | AngularJS Deep Dive | Page Speed Demo

We stayed in Antwerp until Friday, attending the conference, taking pictures, networking over beers and having a fabulous time with everyone attending Devoxx.

Thursday night, we dined at Matty, one of the best restaurants in Antwerp. The food was excellent and provided a nice start for a night that included the Devoxx Party at Noxx and a journey to Bier Central.

On Friday, we traveled to Brussels for a weekend in one of the best beer cities in the world. Trish booked us a room at the Hotel Saint Michel, which was right on the most beautiful square in Europe. Their pre-Christmas light show was spectacular. The beer was delicious, the location was magnificent and we thoroughly enjoyed ourselves, especially the mussels in Brussels. Thanks in particular to Stéphane and Philip for your recommendations.

Nordic Countries Speaking Tour
On Sunday (November 17), we flew to Stockholm to being the second half our trip. Nordea hired me to deliver my Devoxx presentation as part their Java Competence Network. Nordea's Jonny Berggren first contacted me in March 2010 about this opportunity, so it was fun to see it finally happen. We agreed that I'd speak at their four main locations: Stockholm, Helsinki, Oslo and Copenhagen.

Mattias Karlsson (of Jfokus fame) also presented me with an opportunity to speak at his company while I was in Sweden.

I started the week delivering my talk on Monday afternoon at Nordea. Then we met up with Mattias, walked to his company and I delivered it again 45 minutes later. It was exhausting to talk for six hours in one day, but it all seemed to go well. I especially enjoyed the enthusiasm of Mattias's Avega Group.

That evening, we took the train to the airport, boarded a flight to Helsinki and arrived just after midnight. While on the train, we sat next to a Finlander, Karol, that gave us all kinds of great advice on what to do. Tuesday in Helsinki was cold and dreary; perfect sauna weather. We walked around a bit in the rain that morning and visited Senate Square on Karol's recommendation. I mentioned to the developers there that my Mom's grandparents were from Finland (Oulu and Hamina), and that I'd grown up in a rustic cabin built by my Finish grandfather, Matti Hill.

We flew to Oslo Tuesday evening, rode the super-fast train from the airport and got to bed just before midnight. Wednesday morning, we walked around the Vigelandsparken Sculpture Park, and then I headed to the Nordea office while Trish did a walkabout and rode a Viking ship around the bay. We met up afterwards at the wonderful Beer Palace for some pizza and delicious German/Belgian beer.

Copenhagen was our last stop, a city which neither of us have ever traveled to. After arriving, we quickly got a hint that Copenhagen was a special place. We did a bit of research on Wikipedia and learned it was The City of Bikes and their craft brewing industry has blossomed in the last decade, now sporting over 100 microbreweries. My last talk on Thursday morning went very well, especially since my presentation and advice was well polished by that point.

That afternoon, we rented bikes from our hotel, slowly ate sushi on the top of the Tivoli Hotel, and then rode to Tivoli Gardens. Tivoli Gardens was decorated as a Christmas wonderland and their amusement park made us smile and giggle with glee. We stayed there for hours before riding home. Biking around town with hundreds of other cyclists was really cool and fun. I hope Denver gets Copenhagenized someday, the abundance of bike-only roads is simply awesome.

Our Nordic countries tour was especially pleasant because Christmas decorations were everywhere. In the US, many folks look down upon Christmas decorations before Thanksgiving, but since Europeans don't celebrate Thanksgiving - there's no reason not to ease into the Christmas spirit. We figured Abbie and Jack would have a blast at Tivoli in a future November or December. Yes, it was a bit chilly (20-30°F) in most of the countries, but we were well dressed for it. Unfortunately, we didn't get to see any snow.

Many thanks to Devoxx, Nordea, Mattias's Avega Group and the hundreds of developers who listened to me talk about being a modern web developer. We had a wonderful time speaking, laughing, photographing, drinking your delicious beer and seeing all your smiling faces.

For more photos of this whirlwind trip, see Trish's EU and Scandanavian Speaking Tour 2013, while mine are in Devoxx 2013 and Nordic Speaking Tour.

Developing with AngularJS - Part IV: Making it Pop

Matt Raible — Thu, 12 Sep 2013 10:54:29 -0600

Welcome to the final article in a series on my experience developing with AngularJS. I learned its concepts, beat my head against-the-wall with and finally tamed it enough to create a "My Dashboard" feature for a client. For previous articles, please see the following:

The last mile of development for the My Dashboard feature was to spice things up a bit and make it look better. We hired a design company to come up a new look and feel and they went to work. Within a week, we had a meeting with them and they presented a few different options. We picked the one we liked the best and went to work. Below are screenshots that I used to implement the new design.

At first, I thought implementing this design might take quite a bit of effort, since it looked like it used custom fonts. It's true we could use CSS3's @font-face, but I knew it might take awhile to find the right fonts with the appropriate licenses. When I received the screenshot below, I was pleased to see that all fonts were web-safe.

Design Elements

There are a number of elements in this new design that I had to create. For example, if numbers were only 1 digit, we had to add a leading zero to them in the summary band. Other design elements we needed to implement are listed below:

A background image that filled the page
Fade to white on summary widget titles
A responsive grid for summary widgets
Provide a colored background for odd rows in the summary grid
Add a "Show More" band at the bottom of Tasks, Summary and Reports when there's more items to display

In addition to these elements, there was quite a bit of work to conform to the new colors, fonts and drop-shadows. I implemented all of these using CSS3 (border-radius, box-shadow, box-sizing, linear-gradient), and lots of trial-and-error. To use the best fonts across various devices, I used CSS-Trick's Font Stacks.

New Background

The new background shown in the screenshots above has a light source in the middle of it. Therefore, it's impossible to tile/repeat it across the page since it's not uniform. To make it work, I used a 1024 x 768 image and CSS3's background-size: cover. For more information on background-size, see SitePoint's How to Resize Background Images with CSS3. This worked great on smaller screens, but we noticed some issues on 30" monitors. Therefore, we ended up getting a new repeatable background and stopped using background-size.

LeadingZero filter

For the first leading zero feature, I wrote an Angular filter. I put the code for this in filters.js:

filter('leadingZero', function() {
    return function(input) {
        if (input.length === 1) {
            return "0" + input;
        } else if (input.length > 2) {
            return "+99";
        } else {
            return input;
        }
    }
});

This filter is used in the HTML template as follows:

<div class="summary-value">{{widget.value | leadingZero}}</div>

Text Fade Out

To implement the fade-to-white text in summary titles, I started with this tutorial. I quickly discovered that it worked best for vertical text blocks and not for horizontal text. Then I found Text Ellipsis with Gradient Fade in Pure CSS, which uses :after to position a block over the text that fades to white. Since the title is not the right-most element (the numbers are), I had to figure out best positioning that worked cross-browser. Below is the CSS I used to implement this feature.

.dashboard .summary-title:after {
    display: block;
    position: absolute;
    right: 66px;
    top: 5px;
    bottom: 5px;
    width: 30px;
    background: -moz-linear-gradient(left,  rgba(255,255,255,0) 0%, #fff 20px); /* FF3.6+ */
    background: -webkit-linear-gradient(left,  rgba(255,255,255,0) 0%, #fff 20px); /* Chrome10+,Safari5.1+ */
    background: -o-linear-gradient(left,  rgba(255,255,255,0) 0%, #fff 20px); /* Opera 11.10+ */
    background: -ms-linear-gradient(left,  rgba(255,255,255,0) 0%, #fff 20px); /* IE10+ */
    background: linear-gradient(to right,  rgba(255,255,255,0) 0%, #fff 20px); /* W3C */
    filter: progid:DXImageTransform.Microsoft.gradient( startColorstr='#00ffffff', endColorstr='#ffffff',GradientType=1 ); /* IE6-9 */
    content: "";
}

Responsive Grid

To implement the responsive grid of summary widgets, I started with Codrops' Responsive Full Width Grid Tutorial. This proved to be a great model and I used the following CSS to position all the <li>'s appropriately. In the code below, .summary-item is the class on the <li> elements.

.dashboard .summary-item {
    border-right: 1px solid #d1d1d1;
    border-bottom: 1px solid #d1d1d1;
    /* put the border on the inside of the box */
    -webkit-box-sizing: border-box;
    -moz-box-sizing: border-box;
    -ms-box-sizing: border-box;
    box-sizing: border-box;
    font-family: Constantia, "Lucida Bright", Lucidabright, "Lucida Serif", Lucida, "DejaVu Serif", "Bitstream Vera Serif", "Liberation Serif", Georgia, serif;
    font-size: 14px;
    color: #666;
    height: 50px;
    box-shadow: inset 0 0 6px rgba(0,0,0, 0.25);
    /* responsive grid */
    position: relative;
    float: left;
    overflow: hidden;
    width: 25% /* Fallback */
    width: -webkit-calc(100% / 4);
    width: calc(100% / 4);
}

@media screen and (max-width: 1400px) {
    .dashboard .summary-item {
        width: 33.33333333333333%; /* Fallback */
        width: -webkit-calc(100% / 3);
        width: calc(100% / 3);
    }
}

@media screen and (max-width: 1000px) {
    .dashboard .summary-item {
        width: 50%; /* Fallback */
        width: -webkit-calc(100% / 2);
        width: calc(100% / 2);
    }
}

This worked great in most browsers, but we did find an issue with IE9. When squishing/expanding the browser window, sometimes there would be a blank column on the right side. To fix this, I changed the width on the default .summary-item to be 25%, and removed the lines with calc.

.dashboard .summary-item {
    ...
    width: 25%
}

Coloring Odd Rows

Coloring odd rows in a table is easy, but when the rows are in a responsive grid, that's a whole different story. For tables, the CSS rules are extremely simple:

tr:nth-child(even) {background: #CCC}
tr:nth-child(odd) {background: #FFF}

Via Twitter, @tomaslin advised me that the nth-child selector could probably be used for this, but it'd likely require some JavaScript to make it responsive. I found the excellent Master of the :nth-child and began trying to figure it out. The following function is what we now use to color odd rows in the Summary Bar.

function colorRows() {
    var lisInRow = 0;
    var items = $('.summary-items li');
    items.each(function() {
        if($(this).prev().length > 0) {
            if($(this).position().top != $(this).prev().position().top) return false;
            lisInRow++;
        }
        else {
            lisInRow++;
        }
    });
    var rows = items.length / lisInRow;
    for (var i = 0; i < rows; i++) {
        var selector = "nth-child(n+{x}):nth-child(-n+{y})";
        var x = (lisInRow * i) + 1;
        var y = x + (lisInRow - 1);
        selector = selector.replace('{x}', '' + x);
        selector = selector.replace('{y}', '' + y);
        if (i % 2) {
            $('.summary-items li:' + selector).addClass('odd');
        } else {
            $('.summary-items li:' + selector).removeClass('odd');
        }
    }
}

The above code is in dashboard.js and is called anytime the browser window is resized (to adapt to the responsive grid).

$(window).resize(colorRows);

It's also called when summary widgets are re-ordered, in the updateOrder() function of WidgetController.

$scope.updateOrder = function(event, ui) {
    ...
    Preferences.saveWidgetOrder(type, {items: items});
    if (type === 'summary') {
        colorRows();
    }
};

I'd like to figure out how to make this more Angular-esque, but all the "how to hook into window.resize" articles I found make it seem harder than this.

Show More

The last feature I had to implement was the "Show More" bar that appears when widgets are hidden. This was the most difficult thing to implement and I tried many different things before arriving at a solution that works. First of all, the widgets bars that can be expanded are put into their original (collapsed) state using max-height and overflow: hidden. From there, I look at the list inside the bar and compare the height's of the two elements. If the list is taller than the bar, the Show More bar is added.

I originally looked at the list's :last-child to see if it was visible, but jQuery's :hidden selector only works on items that are hidden by display: none rather than ones that are hidden by overflow.

As you can see from the code below, there's special logic needed to expand the min-height of the Summary Bar since it doesn't have enough room at the bottom to add the bar in its collapsed state.

function showMore(element) {
    var bar = element.parent().parent();
    var list = element.parent();
    var barId = bar.attr('id');
    var listHeight = list.height();
    var barHeight = bar.height();
    var isSummaryBar = (barId.indexOf('summary') > -1);
    var summaryBarMinHeight = 260;
    var showMoreShouldBeVisible = (isSummaryBar && element.position().top >= 200) ? true : listHeight > barHeight;
    if (showMoreShouldBeVisible) {
        var messages = {};
        // the variables below are defined in the host page, before this file is loaded
        messages.more = showMoreText;
        messages.less = showLessText;

        var showMore = $('<div class="show-more"/>').html(messages.more + " <b class='caret'></b>");
        showMore.appendTo(bar);
        // summary bar doesn't have enough room for the Show More bar in its collapsed state,
        // so change it from 242 to 260
        if (isSummaryBar) {
            bar.css({'min-height': summaryBarMinHeight + 'px', 'max-height': ''});
        }

        showMore.bind('click', function (e) {
            var element = $(this);
            var parent = element.parent();

            if (element.hasClass('less')) {
                parent.css({"max-height": ''});
                if (isSummaryBar) {
                    parent.css({"min-height": summaryBarMinHeight + 'px'}).animate(200);
                } else {
                    parent.css({"min-height": ''}).animate(200);
                }
                element.removeClass('less');
                element.html(messages.more + ' <b class="caret"></b>');
            } else {
                parent.css({
                    "max-height": 9999,
                    "min-height": 'auto'
                }).animate({
                        "min-height": parent.height() + 19
                    }, 200);

                element.addClass('less');
                element.html(messages.less + ' <b class="caret caret-up"></b>');
            }

            // prevent jump-down
            return false;
        });
    } else {
        // Remove show-more in case it was previously added
        if (bar.find('.show-more').length > 0) {
            if (isSummaryBar) {
                bar.css('min-height', summaryBarMinHeight - 18)
            } else {
                bar.attr('style', '');
            }

            bar.find('.show-more').remove();
        }
    }
}

function showMoreOnResize() {
    var dataItems = $('.task-items,.summary-items,.report-items');
    dataItems.each(function() {
        var lastItem = $(this).find('li:last-child');
        if (lastItem.length > 0) {
            showMore(lastItem);
        }
    });
}

At first, I wrote this logic as a directive, but when I needed it for responsiveness, I moved it into dashboard.js. The showMoreOnResize() function is called on window resize.

$(window).resize(showMoreOnResize);

I also found that I had to add it to the Preferences service after widgets were saved (since the number displayed could change).

factory('Preferences', function ($filter) {
    return {
        ...
        // Save hidden and visible (and order) widgets from config dialog
        saveWidgetPreferences: function (type, widgets) {
            ...
            DWRFacade.saveDashboardWidgetPreference(type, preferences, {
                callback: function() {
                    // recalculate show more bar
                    showMoreOnResize();
                },
                errorHandler: function (errorString) {
                    alert(errorString);
                }
            });
        }
    }
});

To implement the .caret-up (the .caret class is from Bootstrap), I found a caret-right howto and used it to create .caret-up:

.caret-up {
    border-left: 4px solid transparent;
    border-right: 4px solid transparent;
    border-top: 4px solid transparent;
    border-bottom: 4px solid black;
}

Summary

The final My Dashboard feature is something that I'm quite proud of. A fellow developer, Vlad, did an excellent job of implementing the backend and admin portions. The Product Team's vision and desire to make it Pop! created something great. The fact that we didn't have to support IE8 helped a lot in the implementation. Below is a screenshot of how My Dashboard looked when we completed the project.

Angular isn't mentioned much in this article. That's because we didn't have to do much to the existing Angular code to implement the new design. It was just a matter of writing/modifying some CSS as well as introducing some JavaScript for colored rows and show more. If you know how these features could be written in a more Angular Way, I'd love to hear about it.

If you'd still like to learn more about Angular and why it's good to integrate it little by little, I encourage you to read 5 reasons to use AngularJS in the corporate app world.

Developing with AngularJS - Part III: Services

Matt Raible — Tue, 25 Jun 2013 07:03:26 -0600

This is the 3rd article in a series on my experience developing with AngularJS. I used AngularJS for several months to create a "My Dashboard" feature for a client and learned a whole bunch of Angular goodness along the way. For previous articles, please see Part I: The Basics and Part II: Dialogs and Data.

Angular offers several ways to interact with data from the server. The easiest way is to use the $resource factory, which lets you interact with RESTful server-side data sources. When we started the My Dashboard project, we were hoping to interact with a REST API, but soon found out that it didn't have all the data we needed. Rather than loading the page and then making another request to get its data, we decided to embed the JSON in the page. For communication back to the server, we used our tried-and-true Ajax solution: DWR.

In Angular-speak, services are singletons that carry out specific tasks common to web apps. In other words, they're any $name object that can be injected into a controller or directive. However, as a Java Developer, I tend to think of services as objects that communicate with the server. Angular's documentation on Creating Services shows you various options for registering services. I used the angular.Module api method.

When I last worked on the project, there were only two services in My Dashboard: Widget and Preferences.

The Widget service is used to retrieve the visible widgets for the user. It has two functions that are exposed to controllers: getUserWidgets(type) and getHiddenWidgets(type). The former function is used at the top of WidgetController, while the latter is used for the configuration dialog mentioned in the previous article.

The code for this service is in services.js. The bulk of the logic is in its filterData() function, where it goes through a 4-step process:

Get all the widgets by type, ensuring they're unique.
Remove the widgets that are hidden by the user's preferences.
Build an array that's ordered by user's preferences.
Add any new widgets that aren't hidden or ordered.

The code for the Widget object is as follows:

angular.module('dashboard.services', []).
    factory('Widget',function ($filter, Preferences) {
        var filter = $filter('filter');
        var unique = $filter('unique');

        function filterData(array, query) {
            // get all possible widgets for a particular type
            var data = filter(array, query);
            data = unique(data);

            // remove widgets that are hidden by users preference
            var hidden = Preferences.getHiddenWidgets(query.type);
            for (var i = 0; i < hidden.length; i++) {
                var w = filter(data, {id: hidden[i]});
                $.each(w, function (index, item) {
                    var itemId = item.id;
                    if (hidden.indexOf(itemId) > -1) {
                        data.splice(data.indexOf(item), 1);
                    }
                });
            }

            // build an array that's ordered by users preference
            var ordered = [];
            var visible = Preferences.getUserWidgets(query.type);
            for (var j = 0; j < visible.length; j++) {
                var v = filter(data, {id: visible[j]});
                $.each(v, function (index, item) {
                    var itemId = item.id;
                    if (visible.indexOf(itemId) > -1) {
                        ordered.push(item)
                    }
                });
            }

            // loop through data again and add any new widgets not in ordered
            $.each(data, function (index, item) {
                if (ordered.indexOf(item) === -1) {
                    ordered.push(item);
                }
            });

            return ordered;
        }

        return {
            getUserWidgets: function (type) {
                return filterData(widgetData, {type: type})
            },

            getHiddenWidgets: function (type) {
                var hidden = Preferences.getHiddenWidgets(type);
                var widgetsForType = filter(widgetData, {type: type});
                widgetsForType = unique(widgetsForType);
                var widgets = [];
                for (var j = 0; j < hidden.length; j++) {
                    var v = filter(widgetsForType, {id: hidden[j]});
                    $.each(v, function (index, item) {
                        if (widgetsForType.indexOf(item) > -1) {
                            widgets.push(item)
                        }
                    });
                }
                return widgets;
            }
        }
    })

Once you have a service configured like this, you can inject it by name. For example, WidgetController has Widget injected into its constructor:

function WidgetController($dialog, $scope, Widget, Preferences) {

Preferences Service

The Preferences service is used to get and save user preferences. It's pretty straightforward and the bulk of its code is interacting with DWR. This service has 5 methods:

getHiddenWidgets(type) - used by Widget service
getUserWidgets(type) - used by Widget service
saveBarOrder(bars) - called from WidgetController
saveWidgetOrder(type, widgets) - called from WidgetController
saveWidgetPreferences(type, widgets) - called from WidgetController

First, let's take a look at the save*Order() functions. There are two parts of the page that use the ui-sortable directive to initialize drag-and-drop functionality. The first is on the main <ul> that holds the 3 bars on the left.

<ul class="widgets" ui-sortable="{handle:'.heading', update: updateBars}">

The "update" property in the configuration JSON indicates which method to call in the controller. Similarly, the tasks and summary items call an updateOrder function.

<ul class="summary-items" ng-model="summaryWidgets" ui-sortable="{update: updateOrder}">
...
<ul class="task-items" ng-model="taskWidgets" ui-sortable="{update: updateOrder}">

These functions are in WidgetController and build an array of widget ids to pass to the Preferences service.

$scope.updateBars = function(event, ui) {
    var bars = [];
    $.each($(ui.item).parent().children(), function (index, item) {
        bars.push(item.id.substring(0, item.id.indexOf('-')))
    });
    Preferences.saveBarOrder(bars);
};

$scope.updateOrder = function(event, ui) {
    var parentId = $(ui.item).parent().parent().attr('id');
    var type = parentId.substring(0, parentId.indexOf('-'));
    var items = [];
    $.each($(ui.item).parent().children(), function (index, item) {
        items.push(item.id.substring(item.id.indexOf('-') + 1))
    });
    Preferences.saveWidgetOrder(type, {items: items});
};

The bar order is used when the page is loaded. The following scriptlet code exists at the bottom of the app's page, in its $(document).ready:

<%  String barOrder = user.getDashboardBarSortOrder();
    if (barOrder != null) { %>
    sortBars(['<%= barOrder %>']);
<% } %>

The sortBars() function is in a dashboard.js file (where we put all non-Angular functions):

function sortBars(barOrder) {
    // Sort bars according to user preferences
    $.each(barOrder, function(index, item) {
        var bar = $('#' + item + '-bar');
        if (bar.index() !== index) {
            if (index === 0) {
                bar.insertBefore($('.widgets>li:first-child'));
            } else if (index === (barOrder.length - 1)) {
                bar.insertAfter($('.widgets>li:last-child'));
            } else {
                bar.insertBefore($('.widgets>li:eq(' + index + ')'));
            }
        }
    });
}

Now that you've seen where Preferences is called from, let's take a look at the code for the service.

The checks for undefined and uniqueness in the code below shouldn't be necessary, but I prefer defensive coding.

factory('Preferences', function ($filter) {
    var unique = $filter('unique');

    return {
        // Get in-page variable: hiddenWidgets
        getHiddenWidgets: function (type) {
            var items = hiddenWidgets[type];
            return (angular.isUndefined(items) ? [] : unique(items));
        },

        // Get in-page variable: userWidgets
        getUserWidgets: function (type) {
            var items = userWidgets[type];
            return (angular.isUndefined(items) ? [] : unique(items));
        },

        // Save main bar (task, summary, chart) order
        saveBarOrder: function (bars) {
            DWRFacade.saveDashboardBarSortOrder(bars, {
                errorHandler: function (errorString) {
                    alert(errorString);
                }
            })
        },

        // Save order of widgets from sortable
        saveWidgetOrder: function (type, widgets) {
            userWidgets[type] = widgets.items;
            DWRFacade.saveDashboardWidgetPreference(type, widgets, {
                errorHandler: function (errorString) {
                    alert(errorString);
                }
            });
        },

        // Save hidden and visible (and order) widgets from config dialog
        saveWidgetPreferences: function (type, widgets) {
            // widgets is a map of hidden and visible
            var hiddenIds = [];
            $.each(widgets.hidden, function (index, item) {
                hiddenIds.push(item.id);
            });
            var visibleIds = [];
            $.each(widgets.items, function (index, item) {
                visibleIds.push(item.id);
            });
            var preferences = {
                hidden: hiddenIds,
                items: visibleIds
            };
            // reset local variables in page
            hiddenWidgets[type] = hiddenIds;
            userWidgets[type] = visibleIds;
            DWRFacade.saveDashboardWidgetPreference(type, preferences, {
                errorHandler: function (errorString) {
                    alert(errorString);
                }
            });
        }
    }
})

Using $http and Receiving Data

In this particular application, we didn't do any reading from the server with Angular. We simply wrote preferences to the server, and updated embedded variables when data changed. Real-time functionality of the app wouldn't be noticeable if a write failed.

In my current Angular project, it's more of a full-blown application that does as much reading as writing. For this, I've found it useful to either 1) pass in callbacks to services or 2) use Angular's event system to publish/subscribe to events.

The first method is the easiest, and likely the most familiar to JavaScript developers. For example, here's the controller code to remove a profile picture:

Profile.removePhoto($scope.user, function (data) {
    // close the dialog
    $scope.close('avatar');
    // success message using toastr: http://bit.ly/14Uisgm
    Flash.pop({type: 'success', body: 'Your profile picture was removed.'});
})

And the Profile.removePhoto() method:

removePhoto: function (user, callback) {
    $http.post('/profile/removePhoto', user).success(function (response) {
        return callback(response);
    });
}

The second, event-driven method works equally as well, but can easily suffer from typos in event names.

// controller calling code
Profile.getUser();

// service code
getUser: function () {
    $http.get('/profile').success(function (data) {
        if (data.username) {
            $log.info('Profile for ' + data.username + ' retrieved!');
            $rootScope.$broadcast('event:profile', data);
        }
    });
}

// controller receiving code
$rootScope.$on('event:profile', function (event, data) {
    $scope.user = data;
});

I like both methods, but the event-driven one seems like it could offer more extensibility in the future.

Summary

Using in-page variables and DWR doesn't seem to be recommended by the Angular Team. However, it worked well for us and seems like a good way to construct Angular services. Even if a REST API becomes available to get all the data, I think using in-page variables to minimize requests is a good idea.

When retrieving data, you can use callbacks or Angular's pub/sub event system ($broadcast and $on) to get data in your controllers. If you want to learn more about this technique, see Eric Terpstra's Communicating with $broadcast. In his article, Eric mentions Thomas Burleson's pub/sub module that acts as a message queue. If you've used Thomas's MessageQueue (or something similar) with Angular, I'd love to hear about your experience.

In the next article, I'll talk about how we redesigned My Dashboard and used CSS3 and JavaScript to implement new ideas.

Developing with AngularJS - Part II: Dialogs and Data

Matt Raible — Thu, 20 Jun 2013 08:45:13 -0600

A couple of days ago, I wrote an article on how I started developing with AngularJS. I used AngularJS for several months to develop a "My Dashboard" feature for a client's product and learned a whole bunch of stuff along the way.

This article provides an overview of how I changed some of My Dashboard's features to use Angular instead of jQuery. After finishing the prototype work in January, we started moving bits and pieces into the main application. We kept the same file names for our Angular-related files and copied them into the project.

All these files are packaged up into a dashboard.js file that's included at the bottom of our Dashboard page. While our prototype used jQuery 1.9 and jQuery UI 1.10, the application's codebase used jQuery 1.7.1 and jQuery UI 1.8.3. Luckily, this didn't present a problem as everything continued to work as expected.

Around this time, we also had many discussions with the Product Team about charts. Since Highcharts required we purchase a license, we took at look at AnyChart, which we were already using. We were able to get AnyChart to work with our existing chart directive with minimal changes. Most changes were in the JSON itself.

We committed the first pass (with sample data still hard-coded) in mid-February.

Angular UI's Carousel

While finishing our initial prototype, I learned about Angular UI's Carousel, an implementation of Bootstrap's Carousel. It required a 70% less HTML and is quite a bit easier to read. Below is the refactored carousel section.

<carousel interval="-1" class="oneup">
    <slide ng-repeat="widget in widgets | filter: {type: 'chart'} | orderBy: 'order'" active="slide.active" class="chart">
        <chart class="widget" value="{{widget}}" type="{{widget.chartType}}"></chart>
    </slide>
</carousel>
<carousel interval="-1" class="twoup">
    <slide ng-repeat="widget in widgets | filter: {type: 'chart'} | chunk: 2 | orderBy: 'order'" active="slide.active" class="chart">
        <chart class="widget" value="{{widget[0]}}" type="{{widget[0].chartType}}"></chart>
        <chart class="widget" value="{{widget[1]}}" type="{{widget[1].chartType}}"></chart>
    </slide>
</carousel>

I was also able to remove the JavaScript that once initialized the carousel.

-    var carousel = $('.carousel');
-    $(carousel).carousel({
-        interval: 0
-    });

While integrating this directive, I found a way to improve it by hiding navigation indicators if there's only one slide. And thus my first contribution to Angular UI was born.

Angular UI's Sortable

Next, I switched from using JavaScript to Angular UI's sortable to initialize drag-and-drop functionality. This was as simple as removing 5 lines of JavaScript and adding "ui-sortable" as an attribute to HTML tags.

<div class="container-widgets" ng-controller="WidgetController" ng-cloak>
     <div class="row-fluid">
         <div class="span9">
-                <ul class="widgets">
+                <ul class="widgets" ui-sortable="{handle:'.heading'}">
                 <li id="summary-bar">
                     <div class="heading">Summary <a href='#' class='configure'></a></div>
-                        <ul class="tiles">
+                        <ul class="tiles" ui-sortable>
                         <li class="span3" ng-repeat="widget in widgets | filter:{type: 'summary'} | orderBy: 'order'">
                             <h3>{{widget.value}}</h3>
@@ -36,7 +36,7 @@
                 </li>
                 <li id="task-bar">
                     <div class="heading">My Tasks <a href='#' class='configure'></a></div>
-                        <ul class="tasks">
+                        <ul class="tasks" ui-sortable>
@@ -151,55 +131,44 @@
-    $('.widgets').sortable({
-        cursor: "move",
-        handle: ".heading"
-    }).disableSelection();
-    $('.tiles,.tasks').sortable();

This directive uses jQuery UI under the covers, so it accepts all the same arguments you'd normally use.

Dialogs with jQuery

The next feature I implemented was a dialog that allowed end users to add/remove widgets from their dashboard. Since I knew how to do this with jQuery, that's the path I started down. I figured it'd be easier to get something working quickly and then refactor to Angular later. I put the HTML for the dialog at the bottom of the page:

<script type="text/javascript" src="js/move.js"></script>
<script type="text/javascript" src="js/upDown.js"></script>
<div id="configure-widgets" class="hidden" data-title="Bar Configuration" data-close="Close">
    <div class="row-fluid center">
        Decide which items you would like to display and set the display order.
        <div class="span5" style="margin-left: 25px">
            <label for="available-widgets" class="bold">Available Widgets</label>
            <select size=10 id="available-widgets" multiple class="width100pr"></select>
        </div>
        <div class="span1 arrows" style="padding-top: 50px">
            <img src="images/arrow_up.png" class="arrow arrow-up" alt="Move Up" onclick="return moveUp($('#assigned-widgets')[0]);"/>
            <img src="images/arrow_right.png" class="arrow arrow-right" alt="Move Right" onclick="return move($('#available-widgets')[0], $('#assigned-widgets')[0]);"/>
            <img src="images/arrow_left.png" class="arrow arrow-left" alt="Move Left" onclick="return move($('#assigned-widgets')[0], $('#available-widgets')[0]);"/>
            <img src="images/arrow_down.png" class="arrow arrow-down" alt="Move Down" onclick="return moveDown($('#assigned-widgets')[0]);"/>
        </div>
        <div class="span5">
            <label for="assigned-widgets" class="bold">Assigned Widgets</label>
            <select size=10 id="assigned-widgets" multiple class="width100pr"></select>
        </div>
    </div>
</div>

Then I changed the WidgetController to split the widgets variable into variables for each widget type.

+    var filter = $filter('filter');
+    var orderBy = $filter('orderBy');
+
+    $scope.summaryWidgets = filterData($scope.widgets, {type: 'summary'}, filter, orderBy);
+    $scope.taskWidgets = filterData($scope.widgets, {type: 'task'}, filter, orderBy);
+    $scope.chartWidgets = filterData($scope.widgets, {type: 'chart'}, filter, orderBy);
+}
+
+function filterData(array, query, filter, orderBy) {
+    var data = filter(array, query);
+    return orderBy(data, 'order');
+}

Finally, I added a new config directive and hooked it into the page by adding config="type" to each heading (e.g. <div class="heading" config="task">My Tasks</div>).


.directive('config', function ($sanitize, $filter) {
    return {
        restrict: 'A',
        link: function (scope, element, attrs) {
            var configBtn = $('<a href="#"/>').addClass('configure');
            configBtn.appendTo(element);
            var widgets = scope[attrs.config + 'Widgets'];
             
            // availableWidgets is defined as a global variable embedded in the page
            var allWidgets = availableWidgets; 
            $(configBtn).on('click', function (e) {
                e.preventDefault();
                var configDialog = $('#configure-widgets');
                var availableWidgets = $('#available-widgets');
                availableWidgets.empty();
                var filter = $filter('filter');
                var orderBy = $filter('orderBy');
                allWidgets = filter(allWidgets, {type: attrs.config});
                allWidgets = orderBy(allWidgets, 'order');
                var unselectedWidgets = jQuery.grep(allWidgets, function(item) {
                    return jQuery.inArray(item, widgets) < 0;
                });
                $.each(unselectedWidgets, function(index, item) {
                    var title = (item.title) ? item.title.replace(/&quot;/g, '"') : 'No Title';
                    availableWidgets.append(new Option(title, item.id));
                });
                var assignedWidgets = $('#assigned-widgets');
                assignedWidgets.empty();
                $.each(widgets, function(index, item) {
                    var title = (item.title) ? item.title.replace(/&quot;/g, '"') : 'No Title';
                    assignedWidgets.append(new Option(title, item.id));
                });
                configDialog.dialog({
                    title: $(element).text() + ' ' + configDialog.attr('data-title'),
                    width: 600,
                    modal: true,
                    buttons: [{
                            text: configDialog.attr('data-close'),
                            'class': 'btn',
                            click: function() {
                                $(this).dialog("close");
                            }
                        }]
                });
            });
        }
    }
})

As you can tell, this is quite a bit of code, and it doesn't even show you the JavaScript in move.js and upDown.js (included at the top of the dialog HTML). While writing this code, I could tell that I was not doing things the Angular Way.

To refactor, I did some research, found the $dialogProvider service and went to work.

Dialogs with Angular

I started by refactoring the config directive to be much shorter.

.directive('config', function() {
    return {
        restrict: 'A',
        link: function (scope, element, attrs) {
            var configBtn = $('<a href=""/>').addClass('configure');
            configBtn.appendTo(element);
            configBtn.bind('click', function(e) {
                e.preventDefault();
                e.stopPropagation();
                scope.$apply(scope.configureDialog(attrs.config, $(element).text()))
            });
        }
    }
})

Line #10 that starts with scope.$apply is what makes the magic happens.This calls the configureDialog() function in WidgetController. The $dialog service you see below is injected by adding it as a parameter to the WidgetController function.


$scope.configureDialog = function (type, title) {
    var dialog = $dialog.dialog({
        dialogClass: 'modal draggable',
        modalFade: false,
        backdropClick: true,
        controller: 'ConfigController',
        template: $('#configure-widgets').html(),
        resolve: {
            title: function() {
                return title;
            },
            hiddenItems: function () {
                return Widget.getHiddenWidgets(type);
            },
            items: function () {
                return angular.copy($scope[type + 'Widgets']);
            }
        }
    });
    dialog.open().then(function(results) {
        if (!angular.isUndefined(results)) {
            $scope[type + 'Widgets'] = results.items;
            Preferences.saveWidgetPreferences(type, results);
        }
    });
};

draggable directive
If you look closely, you'll see this dialog is initialized with a 'draggable' class. I created a draggable directive that gives draggability using jQuery UI to any elements with this class.

.directive('draggable', function() {
    return {
        restrict: 'C',
        link: function(scope, elem, attr, ctrl) {
            elem.draggable({handle: '.modal-header'});
        }
    };
});

The interesting parts of this file are the controller, template, and resolve parameters. The controller is just another function in controllers.js, the template is HTML in the page (so text could be i18n-ized) and resolve has the variables to pass to the controller. Widget and Preferences are services I'll talk about in the Part 3. The reason angular.copy() is used is so the widget arrays aren't modified while the dialog is displayed (we want to wait until the user clicks "Save").

The ConfigController function started quite simply:

function ConfigController($scope, $sanitize, dialog, title, hiddenItems, items) {
    $scope.title = title;
    $scope.hiddenItems = hiddenItems;
    $scope.items = items;
}

The HTML (defined by the aforementioned template parameter) is as follows. You can see that title, hiddenItems and items are the variables defined in $scope and used to render the data.

<div id="configure-widgets" class="modal hidden">
    <div class="modal-header" style="border: 0">
        <button type="button" class="close" ng-click="close(false)" aria-hidden="true" style="margin-top: -3px">&times;</button>
        <h4>{{title}} Bar Configuration</h4>
    </div>
    <div class="modal-body">
        Decide which items you would like to display and set the display order.
        <div class="row-fluid center">
            <div class="span4" style="width: 320px; margin-left: 25px">
                <label for="available-widgets" class="bold">Available Widgets</label>
                <select size=10 id="available-widgets" ng-model="items.available" ng-options="i.title for i in hiddenItems"
                        class="width100pr" multiple="multiple"></select>
            </div>
            <div class="span1 arrows" style="padding-top: 50px">
                <img src="images/arrow_up.png" class="arrow arrow-up" alt="Move Up" ng-click="moveUp(items.selected, items)"/>
                <img src="images/arrow_right.png" class="arrow arrow-right" alt="Move Right" ng-click="moveItem(items.available, hiddenItems, items)"/>
                <img src="images/arrow_left.png" class="arrow arrow-left" alt="Move Left" ng-click="moveItem(items.selected, items, hiddenItems)"/>
                <img src="images/arrow_down.png" class="arrow arrow-down" alt="Move Down" ng-click="moveDown(items.selected, items)"/>
            </div>
            <div class="span4" style="width: 320px">
                <label for="assigned-widgets" class="bold">Assigned Widgets</label>
                <select size=10 id="assigned-widgets" ng-model="items.selected" ng-options="i.title for i in items"
                        class="width100pr" multiple="multiple"></select>
            </div>
        </div>
    </div>
    <div class="modal-footer">
        <button ng-click="close(true)" class="btn btn-primary">Save and Close</button>
    </div>
</div>

There's a couple of new directives introduced by this code: ngOptions and ngClick. The former is used to display options in a <select>, the latter to call functions in the controller. These functions are defined in ConfigController:

$scope.moveUp = function(items, list) {
    angular.forEach(items, function(item) {
        var idx = list.indexOf(item);
        if (idx != -1) {
            list.splice(idx - 1, 0, list.splice(idx, 1)[0]);
        }
    });
};

$scope.moveDown = function(items, list) {
    angular.forEach(items, function(item) {
        var idx = list.indexOf(item);
        if (idx != -1) {
            list.splice(idx + 1, 0, list.splice(idx, 1)[0]);
        }
    });
};

$scope.moveItem = function(items, from, to) {
    angular.forEach(items, function(item) {
        var idx = from.indexOf(item);
        if (idx != -1) {
            from.splice(idx, 1);
            to.push(item);
        }
    });
};

$scope.close = function(save) {
    if (save) {
        dialog.close({
            hidden: $scope.hiddenItems,
            items: $scope.items
        });
    } else {
        dialog.close();
    }
};

As you can see, Angular allows you to easily access and manipulate the data. Its two-way binding feature is great because when you modify the object in JavaScript, it auto-updates the displayed HTML.The only thing you need to do to the HTML is to add the ngModel directive.

<ul class="tasks" ng-model="taskWidgets" ui-sortable>

The dialog's close() method is called in the header (where it passes false) and in the footer (where it passes true). The configureDialog() function handles saving if the user indicates they wanted to do so. The 3rd line (starts with $scope) is all that's needed to update the UI. The Preferences service is covered in the next article.

dialog.open().then(function(results) {
    if (!angular.isUndefined(results)) {
        $scope[type + 'Widgets'] = results.items;
        Preferences.saveWidgetPreferences(type, results);
    }
});

Modals with Data

Displaying the widgets in a consolidated dashboard is a nice product feature, but we wanted to take it a step further and allow users to "click through" to see the data. To do this, I added an "event" directive that could read from our JSON data and act upon it accordingly. We decided on 2 types of events: function and href. The href event type is for report widgets, because we want to allow users to click on the widget and it takes them directly to the report. For function, we simply eval() what's passed in. The function is expected to have a container argument that it can use to render data in a modal window.

Using the event directive, you can attach this behavior to a widget simply by adding a class.

<h3 class="events">{{widget.value}}</h3>

The event directive that attaches click behavior is below:

directive('events', function () {
    // This is necessary because widgets may be chunked when charts are displayed 2-up
    function getWidget(element, widget, scope) {
        if (element.hasClass('chart-title')) {
            if (element.parent().hasClass('first')) {
                widget = scope.widget[0];
            } else if (element.parent().hasClass('second')) {
                widget = scope.widget[1];
            } else {
                widget = scope.widget;
            }
        } else {
            widget = scope.widget;
        }
        return widget;
    }
    return {
        restrict: 'C',
        link: function (scope, element, attrs) {
            var widget = getWidget(element, widget, scope);
            if (angular.isUndefined(widget)) {
                return;
            }
            var events = widget.events;
            if (!angular.isUndefined(events)) {
                for (var e in events) {
                    if (e === 'function') {
                        if ($('#dialog-frame').length === 0) {
                            $('<div id="dialog-frame" class="modal hide"/>').appendTo('body');
                            var header = $('<div class="modal-header">');
                            header.append($('<button type="button" class="close" data-dismiss="modal">×</button>'));
                            header.append($('<h4/>').append(scope.widget.title));
                            header.appendTo('#dialog-frame');
                            $('<div class="modal-body"/>').appendTo('#dialog-frame');
                        }
                        element.bind('click', function(event) {
                            event.preventDefault();
                            event.stopPropagation();
                            var dialog = $('#dialog-frame');
                            var title = widget.title;
                            dialog.find('h4').html(title);
                            var dialogBody = dialog.find('.modal-body');
                            dialogBody.empty();
 
                            // display a checking for new data message when widget's value is 0
                            var checkingMessage = $('#wait-checking').html();
                            if (scope.widget.value === "0") {
                                dialogBody.html(checkingMessage);
                            // otherwise, display a loading message
                            } else {
                                dialogBody.html($('#wait-loading').html());
                            }
 
                            // center the dialog on the page
                            dialog.css({
                                width: '560px',
                                'margin-left': function() {
                                    return -($(this).width() / 2);
                                }
                            });
 
                            dialog.modal('show');
                            var container = dialogBody;
                            eval(events[e]);
                        });
                    } else if (e === "href") {
                        element.bind('click', function() {
                            location.href = events[e];
                        })
                    } else {
                        console.log('Event type "' + e + '" not supported.');
                    }
                }
            }
        }
    }
})

Empty Widgets Message

When there are no widgets for a particular type, we wanted to display a message telling the end user. To do this, I used the ngHide directive and passed in the array's length as an expression. I originally had this on a <li> in the respective widget list, but noticed it causes issues when dragging and dropping.

<div ng-hide="summaryWidgets.length" class="widgets-empty">
    No Summary Bar Widgets currently visible
</div>

Summary

This article has provided an overview of how I changed some of My Dashboard's features to use Angular instead of jQuery. I hope it's helped to show how powerful directives can be and how MVC works in Angular. I particularly enjoyed learning how to use the $dialog service. As a word of warning, its usage might change in future releases since it is currently being rewritten to be more maintainable.

In the next article, I'll talk about how I developed Services and integrated DWR. If you see any code that can be improved upon, or issues with the code/architecture in this article, please leave a comment.

Developing with AngularJS - Part I: The Basics

Matt Raible — Tue, 18 Jun 2013 09:06:52 -0600

There's many, many different introductions to AngularJS available on the internet. This article is not another introduction, but rather a story about my learning experience. It all started way back in January of this year. I was working as a UI Architecture Consultant at Taleo/Oracle, my client for the last 21 months. My gig there ended last month, but they agreed to let me publish a series of articles about the knowledge I gained.

Project Background

The Director of Product Management had been working on the concepts for a new project - codenamed "Visual MyView". Below is a mockup he created for our kickoff meeting on January 4th.

From his original email about the above mockup:

The intent here is that one of the columns has rows that have a similar width. The rows could be dragged and dropped into a different order – or potentially the two columns could also be reordered. The rows will basically be comprised of similar widgets. You can see in the mockup how the first two rows might look – and sample widgets. The widgets shown can be configured by the end user, as well as the order in which they are displayed. Other requirements given to us were the following.

Row 1 is comprised of 'summary' widgets that are 'todo' items. Reviews needing done – approvals required – etc.
Row 2 will be a graph row – having graphs and charts to display information – larger squares will build this row.
Row 3's content was not determined yet.

I started the initial layout with static HTML and CSS and had a wireframe to show by mid January.

By the end of January, we'd renamed the project to My Dashboard and had a working prototype using CoolClock and moment.js for the clock in the top right, AngularJS to display widget data, jQuery UI for drag-n-drop of rows and widgets, Bootstrap's Carousel for holding charts and Highcharts for rendering charts. For this prototype, we included 4 types of widgets:

Summary
Tasks
Charts
Reports

To create widgets, we had to decide on a common schema for them.

"id": 1, // not necessary for display, but likely needed if we modify and save preferences
"title": "Appointments Today",
"type": "summary", // others include: task, chart, report
"value": 3, 
"description": "10:30 Jim Smith",
"events": "url", // this can have click events
"order": 1 // used to determine order

Below is a screenshot of our wireframe with some sample widgets.

Angular Basics

The decision to use AngularJS came early on in the project, after I read Tyler Renelle's Rant: Backbone, Angular, Meteor, Derby. To learn AngularJS, I briefly looked at its homepage documentation and played with some examples. Then I stumbled upon Misko Hevery and Igor Minar's AngularJS Presentation from Devoxx 2012. At that time, the video wasn't publicly available (it's free now), so I had to buy a Parley's subscription ($79). It was well worth the money because that one hour video greatly contributed to my understanding of how AngularJS works. Another resource I used frequently to figure out how to do things was John Lindquist's egghead.io.

To begin with, we wrote the JSON for a bunch of sample widgets and embedded them into the page as a widgetData JavaScript variable.

var widgetData = [
    {"id": 1, "title": "Appointments Today", "type": "summary", "value": 3, "description": "10:30 Jim Smith", "events": {"click": "alert('foo');"}, "order": 1},
    {"id": 12, "order": 2, "title": "Offer Approvals", "type": "task", "class": "sticky-note", "value": 1},
    {"id": 103, "title": "Browser market shares at a specific website, 2010", "order": 1, "type": "chart", "chartType": "pie", 
         "tooltip": {"pointFormat": "{series.name}: <b>{point.percentage}%</b>", "percentageDecimals": 1}, "series": [
         {"type": "pie", "name": "Browser share", "data": [
             ["Firefox", 45.0],
             ["IE", 26.8],
             {"name": "Chrome", "y": 12.8, "sliced": true, "selected": true},
             ["Safari", 8.5],
             ["Opera", 6.2],
             ["Others", 0.7]
         ]}
    ]},
    ...
];

I used angular-seed to create the initial structure of the prototype, and continued using the same JavaScript file names when we moved it into the product I worked on. Since the application takes a while to login and render the My Dashboard page (when working remotely), I decided not to use the Karma testing framework that ships with Angular. Below is what our directory structure looked like for our prototype.

The JavaScript files in the "js" folder are the most important for Angular. The first file, app.js, loads the other files:

angular.module('dashboard', ['dashboard.filters', 'dashboard.services', 'dashboard.directives']);

The controllers.js file contains the Controllers (functions) that get the data and make it available to the page. Here's the code for our first controller:

'use strict';

/* Controllers */
function WidgetController($scope) {
    $scope.widgets = widgetData;
}

This puts the widgets in scope and then we were able to render them using Angular's ngRepeat directive and the following HTML:

<div ng-app="dashboard" class="dashboard">
    <div class="container-widgets" ng-controller="WidgetController" ng-cloak>
        <div class="row-fluid">
            <div class="span9">
                <ul class="widgets">
                    <li id="summary-bar">
                        <div class="heading">Summary</div>
                        <ul class="tiles">
                            <li class="span3" ng-repeat="widget in widgets | filter:{type: 'summary'} | orderBy: 'order'">
                                <h3 class="events">{{widget.value}}</h3>
                                <div class="title">{{widget.title}}</div>
                                <div class="desc">{{widget.description}}</div>
                            </li>
                        </ul>
                    </li>
                    <li id="task-bar">
                        <div class="heading">My Tasks</div>
                        <ul class="tasks">
                            <li class="task {{widget.class}}" ng-repeat="widget in widgets | filter: {type: 'task'} | orderBy: 'order'">
                                <div class="title events">{{widget.title}}</div>
                                <div class="value">{{widget.value}}</div>
                            </li>
                        </ul>
                    </li>
                    <li id="chart-bar">
                        <div class="heading">Charts</div>
                        <div id="chartCarousel" class="carousel slide">
                            <ol class="carousel-indicators">
                                <li data-target="#chartCarousel"
                                    ng-repeat="widget in widgets | filter: {type: 'chart'} | orderBy: 'order'"
                                    data-slide-to="{{$index}}" ng-class="{active: $index == 0}"></li>
                            </ol>
                            <div class="carousel-inner">
                                <div class="item chart"
                                     ng-repeat="widget in widgets | filter: {type: 'chart'} | orderBy: 'order'"
                                     ng-class="{active: $index == 0}">
                                    <chart class="widget" value="{{widget}}" type="{{widget.chartType}}"></chart>
                                </div>
                            </div>
                            <a class="left carousel-control" href="#chartCarousel" data-slide="prev">‹</a>
                            <a class="right carousel-control" href="#chartCarousel" data-slide="next">›</a>
                        </div>
                    </li>
                </ul>
            </div>
            <div class="span3">
                <!-- clock and reports -->
            </div>
    </div>
</div>

The beginning of this HTML shows how Angular is instantiated: ng-app matches the name defined in app.js, ng-controller instantiates the WidgetController and ng-cloak is used to hide everything until its processed.

<div ng-app="dashboard" class="dashboard">
    <div class="container-widgets" ng-controller="WidgetController" ng-cloak>

If you take a closer look at the way ng-repeat attributes, you'll see how filters are used to filter data. There's filter and orderBy filters that are built in and allow you to filter data. The filter filter allows you to query arrays by strings, objects and even functions. In the following code block, "task" widgets are filtered, ordered and displayed.

<li class="task {{widget.class}}" ng-repeat="widget in widgets | filter: {type: 'task'} | orderBy: 'order'">
    <div class="title events">{{widget.title}}</div>
    <div class="value">{{widget.value}}</div>
</li>

This was pretty straightforward, but we quickly noticed that if a widget had HTML in its title, it didn't display correctly (rendering the raw HTML). To process the HTML, we had to use the ngBindHtml directive (tip: directives are camelCase, but written with dashes in HTML).

<div class="title events" ng-bind-html="widget.title"></div>

After getting this to work, we noticed that some titles weren't fully rendered because they were hidden with overflow: hidden. We tried adding a tooltip with title="{{widget.title}}", but ran into the same issue. I sent an email to the AngularJS Google Group and received a solution: create an htmlTitle directive:

.directive('htmlTitle', function ($sanitize) {
    return {
        restrict: 'A',
        link: function (scope, element, attrs) {
            attrs.$observe('htmlTitle', function (title) {
                // convert &value; to HTML
                var html = angular.element('<div></div>').html($sanitize(title)).text();
                element.attr('title', html);
                element.html(html);
            });
        }
    }
})

Usage:

<div class="title events" ng-bind-html="widget.title" html-title="{{widget.title}}"></div>

Drag-and-Drop

To implement drag-and-drop functionality, I originally used jQuery UI's sortable. At the bottom of the page, the following code initialized sorting for the various lists:

$(document).ready(function() {
    $('.widgets').sortable({
        cursor: "move",
        handle: ".heading"
    }).disableSelection();
    $('.tiles,.tasks').sortable();
    var carousel = $('.carousel');
    $(carousel).carousel({
        interval: 0
    });
};

As you can see, it also initializes the carousel and stops it from cycling automatically.

Carousel Issues

The first problem I ran into with Bootstrap's Carousel was a strange error from Highcharts. If you look in the above HTML, you'll see there's a <chart> element. This is processed by a highcharts directive. When I tried to use this directive for Highcharts in a carousel, it results in the following error:

TypeError: Cannot read property 'length' of undefined at Object.ob.setMaxTicks

This seemed to be caused by the following css in Bootstrap:

.carousel-inner > .item { display: none }

When I added an override with "display: block" to my stylesheet, everything worked, but the charts were stacked instead of in a carousel. To fix this, I modified the directive to show/hide the "item" element so Highcharts was able to write to it. I also logged an issue for this.

if (element.parent().not(':visible')) {
    element.parent().show();
}
var chart = new Highcharts.Chart(newSettings);
element.parent().attr('style', '');

ngRepeat and Grouping

The last thing I accomplished in our end-of-January prototype was rendering 2 charts side-by-side. I got it working with plain HTML, created a "groupBy" filter for Angular and tried to get it to work with the following:

<div id="chartCarousel" class="carousel slide">
    <ol class="carousel-indicators">
        <li data-target="#chartCarousel" ng-repeat="widget in widgets | filter: {type: 'chart'} | groupBy"
            data-slide-to="{{$index}}" ng-class="{active: $index == 0}"></li>
    </ol>
    <div class="carousel-inner">
        <div class="item" ng-repeat="widget in widgets | filter: {type: 'chart'} | groupBy" ng-class="{active: $index == 0}">
            <div class="widget">{{widget[0].title}}</div>
            <div class="widget">{{widget[1].title}}</div>
        </div>
    </div>
    <a class="left carousel-control" href="#chartCarousel" data-slide="prev">‹</a>
    <a class="right carousel-control" href="#chartCarousel" data-slide="next">›</a>
</div>

This all worked like I expected it to in Chrome, but I the following errors showed in my console.

Error: 10 $digest() iterations reached. Aborting! Watchers fired in the last 5 iterations:

I sent an email to the Angular Google Group and received a link to a discussion where I found a "chunk" filter that solved the problem. This worked great, but I wanted to make it more responsive.

If the user has a screen size big enough to fit 2 charts, show 2 charts and paginate by 2.
If the user has a small screen size that only fits 1 chart, show 1 and paginate by 1.

To solve #1 and #2, I ended up rendering two different sections (with classes .oneup and .twoup) and displayed them based on screen size.

<li id="chart-bar">
    <div class="heading">Charts</div>
    <div id="chartCarousel1" class="carousel slide oneup" style="display: none">
        <ol class="carousel-indicators">
            <li data-target="#chartCarousel1"
                ng-repeat="widget in widgets | filter: {type: 'chart'} | orderBy: 'order'"
                data-slide-to="{{$index}}" ng-class="{active: $index == 0}"></li>
        </ol>
        <div class="carousel-inner">
            <div class="item chart"
                 ng-repeat="widget in widgets | filter: {type: 'chart'} | orderBy: 'order'"
                 ng-class="{active: $index == 0}">
                <chart class="widget" value="{{widget}}" type="{{widget.chartType}}"></chart>
            </div>
        </div>
        <a class="left carousel-control" href="#chartCarousel1" data-slide="prev">‹</a>
        <a class="right carousel-control" href="#chartCarousel1" data-slide="next">›</a>
    </div>
    <div id="chartCarousel2" class="carousel slide twoup" style="display: none">
        <ol class="carousel-indicators">
            <li data-target="#chartCarousel2"
                ng-repeat="widget in widgets | filter: {type: 'chart'} | chunk: 2 | orderBy: 'order'"
                data-slide-to="{{$index}}" ng-class="{active: $index == 0}"></li>
        </ol>
        <div class="carousel-inner">
            <div class="item chart"
                 ng-repeat="widget in widgets | filter: {type: 'chart'} | chunk: 2 | orderBy: 'order'"
                 ng-class="{active: $index == 0}">
                <chart class="widget" value="{{widget[0]}}" type="{{widget[0].chartType}}"></chart>
                <chart class="widget" value="{{widget[1]}}" type="{{widget[1].chartType}}"></chart>
            </div>
        </div>
        <a class="left carousel-control" href="#chartCarousel2" data-slide="prev">‹</a>
        <a class="right carousel-control" href="#chartCarousel2" data-slide="next">›</a>
    </div>
</li>

The JavaScript to show the correct number of charts is below:

var chartBar = $('#chart-bar');
function showCharts() {
    if (chartBar.width() < 960) {
        chartBar.find('.oneup').show();
        chartBar.find('.twoup').hide();
    } else {
        chartBar.find('.twoup').show();
        chartBar.find('.oneup').hide();
    }
}

$(document).ready(function () {
    showCharts();
});

$(window).resize(showCharts);

Summary

Even though I got everything to work for our initial prototype using Angular and jQuery, it didn't quite feel like I was taking full advantage of Angular's power. In particular, I learned that Angular UI Bootstrap had their own carousel and Angular UI had a sortable directive. My suspicions were confirmed when I read How do I "think in AngularJS" if I have a jQuery background?

In the next article, I'll talk about how I migrated to use Angular UI's carousel and sortable directives, as well as integrating dialogs.

The HTML5 Roadshow Rocks!

Matt Raible — Thu, 14 Mar 2013 15:16:58 -0600

In early February, as I was creating my Modern Java Web Developer presentation, I came across a training event that was similarly named. Since I happened to know the instructor, I shot him off an email asking more about it. He promptly replied a week later with an intriguing description. The following sentence really stood out for me:

They are NOT beginning workshops -- newbie information is easily found online, in books, at UG meetings, etc. They are targeted at working professionals who want to take their game to the next level.

The other thing that really struck me about this training was it was à la carte; meaning you could pick and pay for just the days you wanted to attend. Scott gave me a two-for-one deal and I signed up for the following workshops:

Normally, attending a training course would have an opportunity cost for me. However, since I work remotely and it doesn't matter where I work, I decided to work from the class. It turned out to be a great idea because it had the same feel of a productive day at the coffeeshop, but it was a coffeeshop full of knowledge. Instead of looking up and doing some people watching or getting distracted by social media, I would look up and learn something new. I actually ended up getting more done in those two training classes than I normally do at my LoDo Office.

Advanced JavaScript
The Advanced JavaScript workshop was taught by Kyle Simpson. This was my first time meeting Kyle and I was immediately impressed by his resume, especially his worked on Firefox Developer Tools for 9 months credentials. He started out talking about good JavaScript documentation on sites such as MDN and Principles of Writing Consistent, Idiomatic JavaScript. Tip: append "mdn" to any searches for JavaScript topics and you're likely to get better results. Not only that, but MDN is a wiki so you can improve it too. From there, we moved onto DOM Events, event propagation (e.g. bubbling vs. capturing), event management, scopes, this, closures and design patterns. It was a very deep dive into JavaScript and I enjoyed every minute of it.

Airplane-Mode HTML5
The Airplane-Mode HTML5 workshop was taught by Scott Davis (his site is currently down, should be fixed next week). Scott talked about many things I was already familiar with, but I still managed to learn a bunch of new tips and tricks. He started by having us install Node, volo and creating projects. He showed how package.json is the JS project's equivalent of pom.xml.

Next, he plunged into viewports, orientation and how to use CSS3 media queries. I've always used min-device-width and max-device-width in my media queries, so orientation: portrait and orientation: landscape was a useful tip. He taught us about CSS3's pseudo-classes (esp. for validation) and pointed us to the Forward Thinking Form Validation article. We learned about using findmebyIP.com and how it can be a useful tool for finding your browser's capabilities, particularly when you're in a black box environment (e.g. a browser on a TV). I knew about Modernizr, but wasn't aware of has.js for JavaScript feature detection.

Scott talked about many more topics, from HTML5 forms and mobile links to geolocation and maps. He ended the day talking about local storage and application cache.

The Good
First of all, the price was perfect at around $250 per day. The best part for me was that I learned more than I expected to. Not only that, but I didn't have to endure any opportunity cost to attend these workshops. There were times I wish I didn't have to work, but it was cool to have "learning stuff" as a distraction rather than social media.

The Bad
The Location. I ride my bike to work year-round and only sit in traffic a few times per year. So I know I'm biased. The location was in Louisville and while it should be only a 30-minute commute, I spent 2 hours in the car each day. Once I got there, the facility was great, the internet was fast and the lunch choices were splendid.

To see if the HTML5 Roadshow is coming to your town, checkout ThirstyHead on Eventbrite or follow them on Twitter.

What have I been working on at Taleo?

Matt Raible — Fri, 9 Dec 2011 12:57:36 -0700

2011 has been a year of great clients for me. I started working with O.co and very much enjoyed my time there, especially on powder days in Utah. The people were great, the contract was great (no end date), but the work was not my forte. I was on a project to modularize the main shopping site's codebase, which involved mostly refactoring. By refactoring, I mean creating new Maven projects, modifying lots of pom.xml files and literally moving files from one directory to another. IntelliJ made this easy, the hard part was refactoring tests, moving from EasyMock to Mockito and splitting classes into interfaces and implementations where appropriate. As a developer who likes developing UIs and visually seeing my accomplishments, the project wasn't that exciting. However, I knew that it was strategically important to O.co, so I didn't complain much.

In mid-May, I received a LinkedIn message from the Director of Software Engineering at Taleo.

This is OB, I am the Director of Software Engineering at Taleo. We are the 2nd largest Software as a Service company. I am building a new specialist UI team that will take the product to the next level. I am looking for someone to lead this initiative. If you are interested to have a chat about it, please let me know.

At that time, I'd never heard of Taleo and quickly recommended they not hire me.

This probably isn't the best position for me. While I am a good leader, I'm not willing to relocate from Denver. I've found that leaders usually do best when face-to-face with their developers.

This conversation continued back-and-forth where I explained how I wasn't willing to go full-time and I didn't want to leave Overstock. In the end, OB was persistent and explained how the position would entail lots of UI work and wouldn't require me to travel much. Our negotiations trailed off in June and resumed in July after I returned from vacation in Montana. Shortly after, we met each other's expectations, agreed on a start date and I started working at Taleo in early September.

When I started, there were three features they wanted to add to to Taleo Business Edition: Profile Pictures, Talent Cards and Org Charts. They knew the schedule was tight (8 weeks), but I was confident I could make it happen. At first, I groaned at the fact that they were using Ant to build the project. Then I smiled when I learned they'd standardized on IntelliJ and set things up so you could do everything from the IDE. After using Maven for many years, this setup has actually become refreshing and I rarely have to restart or long for something like JRebel. Of course, a new kick-ass laptop and awesome IDE make it so I rarely wait for anything to happen.

To give you a taste of how I implemented each of these new features in 8 weeks, I've broken them into sections below.

Profile Pictures
Adding profile pictures was a pretty simple concept, one you see on my social networking sites today. I needed to give users the ability to upload a JPEG or PNG and crop it so it looked good. The uploading was a pretty straightforward process and I used a lot of internal APIs to grab the file from the request and save it to disk. The more difficult part was scaling the image to certain dimensions on upload (to save space) and allowing users to crop it after.

Most of Taleo Business Edition (TBE) is written in good ol' servlets and JSPs, with lots of scriptlets in their JSPs. When I saw the amount of HTML produced from Java, I laughed out loud and cringed. Soon after, I breathed a sigh of relief when I learned that any new features could be written using FreeMarker templates, which IntelliJ has excellent support for.

For image resizing on upload, I used Chris Campbell's Image.getScaledInstance() tutorial. For creating thumbnails, I used a combination of scaling, getSubimage() and the Java Image I/O API. I made sure to write to BufferedOutputStream for scalability. For cropping images client-side, I used jQuery UI's Dialog and Jcrop, the jQuery image cropping plugin. Below is a screenshot of what the cropping UI looks like:

Talent Cards
Talent Cards were a whole different beast. Not only did they need to display profile pictures, they also needed to contain contact information, work history and a number of other data points. Not just for employees, but for candidates as well. They also needed to be rendered with tabs at the bottom that allowed you to navigate between different data sections.

I'll admit, most of the hard work for this feature was done by the server-side developers (Harish and Vlad) on my team. Vlad built the tabbed interface and Harish built the administrative section that allows you to add/remove/sort fields, as well as show and hide certain tabs. I performed most of my magic with jQuery, its clueTip plugin and good ol' CSS. I was particularly thankful for CSS3 and its border-radius, box-shadow and Justin Maxwell's tutorial on CSS String Truncation with Ellipsis. I used DWR to fetch all the data from the server using Ajax.

Talent Cards are a slick feature in TBE 11.5 and I think they're a great way to see a lot of information about someone very quickly. If you enable them for your company, you'll be able to mouse over any employee or candidate's names and see their information.

Org Chart
The last feature I completed in this 8-week sprint was creating an organization chart. For this, I was given a rough prototype based on Caprica Software's JQuery/CSS Organisation Chart. When I received it, it had all kinds of cool CSS 3 transformations (like this one), but they only worked in Safari and Chrome. I ended up removing the transformations and adding the ability to navigate up and down the org tree with Ajax (we currently only show three levels at a time).

The Org Chart feature also allows you to see how many direct/indirect reports an employee has, as well as access their Talent Card by hovering over their name. It's one of my favorite features because it's so visual and because it builds upon all the other features we've built.

Summary
As you might've guessed by now, I've been having a lot of fun doing UI development over the last few months. While I seem to have a knack for backend Java development, I enjoy developing UIs a lot more. The smile you see on people's faces during demos is priceless. I can't help but think this kind of thing contributes greatly to my developer happiness. All these features will be in next week's release of TBE and I couldn't be happier.

If you'd like to work on my team at Taleo (or even take over my current role as UI Architect), please drop me a line. If you live near their headquarters (Dublin, CA), it'd also be great to see you at the next Silicon Valley Spring User Group meetup. I'll be speaking about What's New in Spring 3.1 on February 1st.

PhoneGap for Hybrid App Development

Matt Raible — Wed, 16 Nov 2011 10:22:16 -0700

This afternoon, I attended Brian LeRoux's talk on PhoneGap for Hybrid App Development at Devoxx. You might remember that I tried PhoneGap last week and really enjoyed my experience. Below are my notes from Brian's talk.

PhoneGap is a project for creating native applications using HTML, CSS and JavaScript. PhoneGap started out as a hack. In 2007, Apple shipped the iPhone and Steve Jobs told everyone they should develop webapps. PhoneGap started in 2008 as a lofty summertime hack and gained traction as a concept at Nitobi with Android and Blackberry implementations in the fall. In 2009, people started to pay attention when PhoneGap got rejected by Apple. They added Symbian and webOS support and Sony Ericsson started contributing to the project. They got rejected because all PhoneGap-developed apps were named "PhoneGap". This turned out to be good press for the project and Apple let them in shortly after.

In 2010, IBM began tag-teaming with Nitobi and added 5 developers to the project after meeting them at OSCON. In 2011, RIM started contributing as well as Microsoft. Then Adobe bought the company, so they're obviously contributing.

PhoneGaps Goals: the web is a first class platform, so let people create installable web apps. Their second goal is to cease to exist and get browsers to adopt their model.

PhoneGap is NOT a runtime or a compiler/transpiler. It's not an IDE or predefined framework or proprietary lockin. It's Apache, MIT and BSD licensed to guarantee it's as free as free software gets. You can do whatever you want to do with it. PhoneGap has recently been contributed to the Apache Software Foundation.

As far as Adobe vs. PhoneGap is concerned, the Nitobi team remains contributors to PhoneGap. Adobe is a software tools company and has Apache and WebKit contributors. PhoneGap/Build integration will be added to Creative Cloud.

The biggest issues with contributing PhoneGap to Apache is renaming the project and source control. I'm not sure why it needs to be renamed, but it's likely that Apache Callback is out. There seems to be some consensus on Apache Cordova. Apache likes SVN and the PhoneGap community currently uses Git. They're trying to find a medium road there, but would prefer to stay on Git.

The PhoneGap technique is colloquially called "the bridge". It's a 3 step process: they instantiate a WebView, then they call JavaScript from native code, then they call native code from JavaScript. Apparently, all device APIs are available via JavaScript in a WebView.

The primary platforms supported are iOS >= 3, Android >= 1.5 and BlackBerry >= 5.x. They also support webOS, Symbian, Samsung Bada and Windows Phone. No mobile dev platform supports as many deploy targets as PhoneGap. Primary contributors are Adobe, IBM, RIM and Microsoft.

Documentation for PhoneGap is available at http://docs.phonegap.com. Device APIs for PhoneGap 1.0 included sensors, data and outputs, which all devices have. Examples of sensors are geolocation and camera. Data examples are the filesystem, contacts and media. Outputs are screens, speakers and the speaker jack. All PhoneGap APIs are plugins, but any native API is permitted.

What about security? Brian recommends looking at the HTML5 Security Cheatsheet. PhoneGap has added a lot of security measures since they've found the native API pretty much opens up everything.

PhoneGap doesn't bundle a UI framework, but they support any JavaScript framework that works in the browser. PhoneGap is just a fancy browser, so your code run in less fancy web browsers too. This means you can develop and test your app in your desktop browser and only use PhoneGap to package and distribute your app.

Competition? PhoneGap has no competition.

PhoneGap/Build is for compiling your apps in the cloud and free for open source projects. The biggest reason they did this is because they couldn't redistribute all the SDKs and it was a pain for developers to download and install SDKs in training classes.

For mobile app development, you should have a singular goal. Do one thing really well if you want to be successful. Great UX happens iteratively. You know that the web works and has been widely successfully cross-platform. It's likely you've already invested in the web. Start by building a mobile web client and use PhoneGap as a progressive enhancement technique.

Shipping and unit testing should be a daily activity. Automate everything so you can have one-click builds (test/dev/release). For web client design, constraints are your ally in the battle against complexity and "clients who are not chill". Phones suck and consume a lot: cpu, ram, bandwidth, battery, network... everything! Start with a benchmark of app performance and monitor that benchmark. If you have tons and tons of features, consider splitting into multiple apps.

The mobile web is not WebKit! Opera is huge, Firefox is making strides and IE still happens. For layouts: use flex-box rules (anyone got a link to these?), css media queries and meta tags for viewport. You should try to develop your app without frameworks because they come with a ton of code and can effect the size of your app.

Looks can kill: aesthetics that can hurt performance: border-radius, box-shadow and gradients can slow down your apps. Chances are, you really don't need these features. Design your app for your brand, not for the device manufacturer. An app that looks like an iPhone app on Android doesn't give a positive impression.

For JavaScript libraries, start with your problem, not a generic solution like Sencha or jQuery Mobile. Zepto and its older brother XUI are all you need to start. Jo is a fantastic option. Backbone and Spine are worth watching.

For testing, QUnit and Jasmine are pretty popular. For deployment, concat, minify and obfuscate your JavaScript and CSS. Or you can inline everything into the markup to minimize HTTP chatter. Gmail inlines and comments all their JavaScript and then evals it.

From there, Brian recommended leveraging HTML5's AppCache and and using RESTful JSON endpoints for legacy systems. Next, he tried to show us a demo of a photo sharing application. Unfortunately, the Demo Gods were grumpy and Brian couldn't get his computer to recognize his Android phone. He did show us the client code and it's pretty impressive you can use 1 line of code to take a picture on a phone.

The last thing we looked at was debug.phonegap.com. This is an app that's powered by weinre. It lets you enter a line of JavaScript in your client and then remotely debug it in a tool that looks like Chrome's Web Inspector. Very cool stuff if you ask me.

Summary
I really enjoyed learning more about PhoneGap, particularly because Brain emphasized all my web development skills can be used. I don't have to learn Objective-C or Android to develop native apps and I don't even have to install an SDK if I use PhoneGap/Build. Of course, my mobile developer friends might disagree with this approach. In the meantime, I look forward to using PhoneGap to turn my mobile web clients into native apps and finding out if it's really as good as they say it is.

Scaling Flash Movies to match Browser Zoom Levels

Matt Raible — Tue, 13 Jul 2010 12:18:42 -0600

Recently I was tasked with figuring out how to scale the Flash assets in the web application I'm working on. In the app, there's two different Flash assets: a Spotlight (cycles through images) and a Video Player. Before I started working on the issue, our assets would stay the same fixed size no matter what the browser zoom level. You can see this issue in action by going to Hulu or Fancast and zooming in/out (Command +/- on Mac, Control +/- on Windows). The Flash assets don't scale with the browser's text.

I found a lot of references for how to trap and handle resizing in JavaScript, so that's the initial path I took. I ended up having issues trapping the resize event in IE, as well as persisting the appropriate zoom level on page reload. Because of this, I ended up using a pure ActionScript solution that works much better. This article shows how I implemented both solutions.

Regardless of implementation, the first change I had to make was to move the height and width from the Flash asset (object/embed/JS) to its surrounding tag (<section> in our app). Then I changed the height/width to 100% on the Flash asset.

JavaScript Implementation
To allow zooming in ActionScript, I modified our main class to expose a "zoom" method to JavaScript:

ExternalInterface.addCallback("zoom", _zoom);

...

private function _zoom(scale:Number):void {
    _view.scaleX = _view.scaleX * scale;
    _view.scaleY = _view.scaleY * scale;
}

In the code above, _view refers to the container that holds all the items in the player. To call this method in JavaScript, I added the following code:

var windowHeight;
var documentHeight;

$(document).ready(function() { 
    ...
    windowHeight = $(window).height();
    documentHeight = $(document).height();

    $(window).resize(resizeWindow);
}

// Resize Flash assets when page is zoomed
function resizeWindow() {
    var newWindowHeight = $(window).height();
    var newDocumentHeight = $(document).height();
    // if document height hasn't changed, it's a browser window resize
    // event instead of a text zoom - don't change anything
    if (newDocumentHeight === documentHeight) {
        return;
    } else {
        documentHeight = newDocumentHeight;
    }
    var scale = (windowHeight / newWindowHeight); 

    var player = getFlashMovie('playerId');
    if (player && player.zoom) {
        player.zoom(scale);
    }
    var spotlight = getFlashMovie('spotlightId');
    if (spotlight && spotlight.zoom) {
        spotlight.zoom(scale);
    }

    windowHeight = newWindowHeight;
}

This seemed to work well in Firefox, Safari and Opera, but not in IE. I found this explanation about why it might not work, but I was unsuccessful in getting IE to recognize a resize/zoom event.

To fix scaling in our Spotlight asset, I used a similar solution. However, since the Spotlight didn't have all its elements in a container (they were being added directly to the stage), I had to refactor the code to add a SpotlightView (extends Sprite) that contains the bulk of the code.

Browsers persist the zoom level you've set for a site. The problem with the solution used here is it only scales up and down properly if you start from scale = 1 and revert to scale = 1 before leaving the site. If you zoom in and close your browser, when you come back the flash movies will be scale = 1 while the rest of the site is zoomed in. To solve this problem, I attempted to save the scale value in a cookie. This worked, and I was able to read the cookie in the *.as files to scale the movie correctly. However, I experienced some issues with this approach and didn't like having to delete cookies when I wanted the Flash assets to scale correctly.

ActionScript Implementation
After discovering issues with the JavaScript implementation, I did some research to see if it was possible to listen for the browser resize event in ActionScript. The Flash Fluid Layouts and Stage Resize in AS3 tutorial clued me in that the stage could listen for a resize event.

stage.addEventListener(Event.RESIZE, resizeListener);

After adding the above line in the initialization, I added a resizeListener function that scales based on the default dimensions. It also ensures no scaling happens in full screen mode.

private function resizeListener(e:Event):void {
    // don't scale if entering full screen mode
    if (stage.displayState == StageDisplayState.FULL_SCREEN)  {
        _view.scaleX = 1;
        _view.scaleY = 1;
    } else {
        _view.scaleX = stage.stageWidth / 964;
        _view.scaleY = stage.stageHeight / 586;
    }
}

For the Spotlight asset, there are a number of different layouts (home, featured and news). The main class has a resizeListener function that scales accordingly to which layout type is being used.

private function resizeListener(e:Event):void {
    var type:String = _view.getLayoutType();

    if (type == "featured") { 
        _view.scaleX = stage.stageWidth / 958;
       _view.scaleY = stage.stageHeight / 180;
   } else if (type == "home") { 
        _view.scaleX = stage.stageWidth / 964;
        _view.scaleY = stage.stageHeight / 428;
    } else if (type == "news") {
        _view.scaleX = stage.stageWidth / 964;
        _view.scaleY = stage.stageHeight / 189;
    }
}

Because the layout type isn't set until the XML is loaded, I listen for that event in my URLLoader.

xmlLoader.addEventListener(Event.COMPLETE, resizeListener);

With the pure ActionScript implementation, the zoom level is automatically persisted. The Event.RESIZE event is fired by the Flash plugin when the page first loads if the dimensions are not the default.

That's it! Special thanks to James Ward for clueing me into scaleX and scaleY. Hopefully Hulu and Comcast can use this tutorial to scale their video players too.

Introduction to Objective-J and Cappuccino with Tom Robinson

Matt Raible — Thu, 3 Dec 2009 11:21:59 -0700

This morning, I attended Tom Robinson's talk on Objective-J and Cappuccino. Tom is one of the founders of 280 North and creators of the Cappuccino framework and Objective-J language, so I was very interested in hearing about Cappuccino from the source. The text below are my notes, but they're also mostly Tom's words, not mine. I've added a "Thoughts" section at the end that are my words.

Tom's Team was Cocoa programmers before they started building Cappuccino. They wanted to focus on building Desktop Class Web Applications (for example, Google Maps, Meebo and 280 Slides). Tom showed a demo of 280 Slides and how it can rotate and scale images very easily, something you don't often see in web applications.

To build desktop class web applications, you can use Flash or Silverlight, but they're controlled by Adobe and Microsoft. Also, they have no iPhone support and poor Mac and Linux performance. The other option is JavaScript + DOM. They're open standards, available almost everywhere (including mobile devices) and its a very rich ecosystem with lots of competition. The downside to JavaScript is standards bodies, many incompatibilities, technical limitations (e.g. can't access web cam) and the DOM is very document-centric.

The bottom line is we can't fix Flash, but we can fix JavaScript.

This is what 280 North is trying to do with Objective-J. It's a proper superset of JavaScript, has a few syntax additions, has a powerful runtime and is implemented in JavaScript. Objective-J is analogous to Objective-C. It adds to JavaScript like Objective-C adds to C.

One of the first things Objective-J adds is Dependency Management. You can import from search paths:

@import <Foundation/CPObject.j>

Or from relative paths:

@import "ApplicationController.j"

@import prevents duplicate loads has asynchronous downloading and synchronous execution. That means all files are downloaded before evaluation begins, but to the programmer, it seems to happen synchronously.

The thing that sets Cappuccino apart from other libraries is its inheritance model. It uses classical OO inheritance (using Objective-C syntax).

@implementation Person : CPObject {
    String firstName @accessors;
    String lastName @accessors;
}

- (String) fullName {
    return firstName + lastName;
}

@end

The type definitions (String) are ignored for now and primarily used for documentation. In the future, they plan to add optional static typing, hence the reason for having them. Tom is unsure if you can leave off the String type or if the compiler requires it.

@implementation has proper support for super and language syntax support. One of the reasons they chose Objective-C is because classical inheritance works great for UI Frameworks.

Objective-J uses "send a message" syntax instead of "call a method" syntax. In the code snippets below, the first line is JavaScript, the second is Objective-J:

object.method()
[object method]

object.methodWithFoot(arg1)
[object methodWithFoo:arg1]

object.methodWithFooBar(arg1, arg2)
[object methodWithFoo:arg1 bar:arg2]

Dynamic Dispatch is one of the most interesting parts of Objective-J. forwardInvocation in Objective-C is like method_missing in Ruby. Methods can be used as references, for example:

var action = @selector(someMethod:);

Runtime mutability is important for KeyValueCoding (KVC) and KeyValueObserving (KVO). KVC allows you to swap classes at runtime and KVO allows you to listen for when property values change. At runtime, a $KVO_ClassName is generated. This class notifies any registered observers when values are changed and then calls the original class to change the property.

Cappuccino
Cappuccino is an application framework, not a library. It uses the Hollywood Principle: "Don't call us, we'll call you".

The Framework handles document management (open, save, revert), content editing (undo, redo, copy, paste) and graphics manipulation. The DOM is designed for documents (same is true for HTML and CSS). Tom doesn't like the DOM as its not a good API for building applications. Proof is all the JavaScript libraries built to make the DOM better.

Cappuccino has an MVC framework and CPView is its View. It's analogous to a <div> and represents a rectangle on the screen. Everything visible is a CPView or one of its subclasses. It defines resizing and layout behavior. CoreGraphics is Cappuccino's canvas-like drawing API. It uses VML on IE, canvas on everything else.

Very little of the code in Cappuccino talks to the DOM (less than 2%). It's not just about providing widgets that work in all browsers, it's a way to write platform independent display code.

Events are done very differently than most JavaScript libraries. Browser's dispatching is not used. A single event listener is registered for each type of event on the window. These events are captured and sent to the objects that need to know about them. This allows for consistent events across all browsers, even keyboard events. It also allows for creating custom event flows and easily creating custom events. Cappuccino events allow you to get around a common problem with DOM Events where you can't click on overlapping rectangles.

Notifications can be registered and sent very easily. Both "scoped" and private notifications can be created.

Undo Management is included in Cappuccino. It manages a stack of undos for you. Redos are "free" and undo functionality is part of the document architecture. This makes it easy to integrate with auto-save functionality.

Run loops (also called event loops) are an advanced feature of Cappuccino. They allow you to perform actions on every run loop. This enables complex optimizations for DOM/Graphic operations and undo grouping.

The final part of Cappuccino is Keyed Archiving. Keyed Archiving stores a graph of Objective-J objects. It handles reference cycles, conditional inclusions, has an efficient data format and works on the client and server (Objective-J can be run on the server). The data format is similar like binary, but it's UTF-8. Keyed Archiving is used for archiving views and used heavily in 280 Slides for storing, retrieving, and exporting presentations.

Other applications implemented with Cappuccino include almost.at and Mockingbird. EnStore uses it too, but only for its admin interface.

An interesting extension for Rails developers is CPActiveRecord, a reimplementation of Rails' ActiveRecord in Cappuccino.

There are several tools included with Cappuccino:

objj: command line Objective-J
objcc: "compile" ahead of time
press: optimize code and resources
nib2cib: convert Mac OS X nibs
capp: project creation

All these tools are built on Narwhal (which conforms to the CommonJS standard).

CommonJS
CommonJS is an effort among server-side JavaScript projects to standardize non-browser JavaScript APIs. There's numerous API specifications (so far):

Binary, File, IO
stdin, stdout, stderr, args, env
Web server gateway (JSGI) - similar to WSGI and Rack for Python and Ruby

To learn more about CommonJS, see CommonJS effort sets JavaScript on path for world domination.

Narwhal is 280 North's implementation of CommonJS APIs. It works with multiple JavaScript engines, including Rhino, JavaScriptCore (SquirrelFish) and XUL Runner. According to Tom, Rhino is an order of magnitude slower than JavaScriptCore and V8. Of course, Narwhal supports Objective-J too.

Aristo
Aristo is the new default theme in Cappuccino and was created by the Sofa design firm. It includes windows, tabs and menus and is open source so you can modify.

Atlas
Atlas is an IDE for Cappuccino, focused on building user interfaces graphically. Atlas is a downloadable application for OS X. It's written almost entirely in Cappuccino. The desktop version bridges Cappuccino windows to native windows. Tom did a demo of Atlas and showed how its layout feature allows you pin, center and align very easily. It's all done with JavaScript because doing layouts with CSS is often very painful. After that, he showed us how can you Atlas to very easily build a Web Application and then export it as a native OS X application without changing a line of code. Atlas includes Mozilla's Bespin for code editing.

To learn more about Aristo and Atlas, you might want to checkout Ajaxian's Big News from Cappuccino: Aristo and Atlas from earlier this year.

Atlas has a $20 Beta Program if you're interested in trying it out.

My Thoughts
Cappuccino looks like a very cool web framework. It reminds me of GWT in that you have to learn a new language to use it. However, Atlas takes a lot of that pain away. I particularly like how it has document and undo/redo support built-in. On my current GWT project, this would be very useful as we've had to build this functionality by hand.

JavaScript and CSS Concatenation with wro4j

Matt Raible — Mon, 9 Nov 2009 10:44:44 -0700

This past weekend, I decided it was about time to fix my YSlow score on this site. I did the easiest thing first by moving all my JavaScript files to the bottom of each page. Then I turned on GZip compression using Roller's built-in CompressionFilter. These changes helped, but the most glaring problem continued to be too many requests. To solve this, I turned to wro4j (as recommended on Twitter) to concatenate my JS and CSS files into one.

I have to say, I'm very happy with the results. I'm now sitting at a YSlow (V2) score of 75; 90 if I use the "Small Site or Blog" ruleset. I believe I can improve this by adding expires headers to my images, js and css. More than anything, I'm impressed with wro4j, its great support and easy setup. I was looking for a runtime solution (b/c I didn't want to have to rebuild Roller) and it seems to be perfect for the job. Furthermore, wro4j minifies everything on the fly and they'll have an expires header filter in the next release.

JAWR and the YUI Compressor are other alternatives to this filter, but I'm currently sold on wro4j. First of all, it passed the 10-minute test. Secondly, it didn't require me to modify Roller's build system.

At this point, if I'm going to implement JS/CSS concatenation and minification in AppFuse and Roller, wro4j seems like the best option. If you disagree, I'd love to hear your reasoning.

TIP: See Javascript Compression in Nexus for information on using YUI Compressor with Maven.

JSON Parsing with JavaScript Overlay Types in GWT

Matt Raible — Wed, 24 Jun 2009 09:52:49 -0600

A reader recently asked:

I would love to see a snippet of how to eval the JSON coming from RequestBuilder into the OverlayTypes. What is the mapping like? I used OverlayTypes to read in static data that I render into the head section of the hosted page, which is pretty easy and fast, but I don't know how to do this "reading" dynamically at runtime.

If you're not familiar with GWT's Overlay Types (added in 1.5), see Getting to really know GWT, Part 2: JavaScript Overlay Types. In our project, we're using Overlay Types to simplify JSON parsing and make our application lean-and-mean as possible.

First of all, we have a JSOModel class that acts as our overlay type:

import java.util.HashSet;
import java.util.Set;

import com.google.gwt.core.client.JavaScriptObject;
import com.google.gwt.core.client.JsArray;
import com.google.gwt.core.client.JsArrayString;

/**
 * Java overlay of a JavaScriptObject.
 */
public abstract class JSOModel extends JavaScriptObject {

    // Overlay types always have protected, zero-arg constructors
    protected JSOModel() {
    }

    /**
     * Create an empty instance.
     * 
     * @return new Object
     */
    public static native JSOModel create() /*-{
        return new Object();
    }-*/;

    /**
     * Convert a JSON encoded string into a JSOModel instance.
     * <p/>
     * Expects a JSON string structured like '{"foo":"bar","number":123}'
     *
     * @return a populated JSOModel object
     */
    public static native JSOModel fromJson(String jsonString) /*-{
        return eval('(' + jsonString + ')');
    }-*/;

    /**
     * Convert a JSON encoded string into an array of JSOModel instance.
     * <p/>
     * Expects a JSON string structured like '[{"foo":"bar","number":123}, {...}]'
     *
     * @return a populated JsArray
     */
    public static native JsArray<JSOModel> arrayFromJson(String jsonString) /*-{
        return eval('(' + jsonString + ')');
    }-*/;

    public final native boolean hasKey(String key) /*-{
        return this[key] != undefined;
    }-*/;

    public final native JsArrayString keys() /*-{
        var a = new Array();
        for (var p in this) { a.push(p); }
        return a;
    }-*/;

    @Deprecated
    public final Set<String> keySet() {
        JsArrayString array = keys();
        Set<String> set = new HashSet<String>();
        for (int i = 0; i < array.length(); i++) {
            set.add(array.get(i));
        }
        return set;
    }

    public final native String get(String key) /*-{
        return "" + this[key];
    }-*/;

    public final native String get(String key, String defaultValue) /*-{
        return this[key] ? ("" + this[key]) : defaultValue;
    }-*/;

    public final native void set(String key, String value) /*-{
        this[key] = value;
    }-*/;

    public final int getInt(String key) {
        return Integer.parseInt(get(key));
    }

    public final boolean getBoolean(String key) {
        return Boolean.parseBoolean(get(key));
    }

    public final native JSOModel getObject(String key) /*-{
        return this[key];
    }-*/;

    public final native JsArray<JSOModel> getArray(String key) /*-{
        return this[key] ? this[key] : new Array();
    }-*/;
}

This class alone allows you to easily parse JSON returned in a callback. For example, here's an example of parsing Twitter's User Timeline in my OAuth with GWT application.

private class TwitterApiCallback implements RequestCallback {
    public void onResponseReceived(Request request, Response response) {
        if (response.getStatusCode() == 200) {
            JsArray<JSOModel> data = JSOModel.arrayFromJson(response.getText());
            List<JSOModel> statuses = new ArrayList<JSOModel>();
            for (int i = 0; i < data.length(); i++) {
                statuses.add(data.get(i));
            }

            // populate textarea with returned statuses
            for (JSOModel status : statuses) {
                payload.setValue(payload.getValue() + status.get("text") + "\n\n");
            }
            
            Label success = new Label("API call successful!");
            success.setStyleName("success");
            form.add(success);
        } else {
            onError(request, new RequestException(response.getText()));
        }
    }

    public void onError(Request request, Throwable throwable) {
        Window.alert("Calling API failed. " + OAuthPage.STANDARD_ERROR + "\n\n" + throwable.getMessage());
    }
}

To simply things even more, we created a BaseModel class that can be extended.

import java.util.Map;
import java.util.HashMap;

import com.google.gwt.core.client.JsArrayString;
import com.google.gwt.user.client.Element;
import com.google.gwt.user.client.DOM;

public abstract class BaseModel {

    protected JSOModel data;

    public BaseModel(JSOModel data) {
        this.data = data;
    }

    public String get(String field) {
        String val = this.data.get(field);
        if (val != null && "null".equals(val) || "undefined".equals(val)) {
            return null;
        } else {
            return escapeHtml(val);
        }
    }

    public Map<String, String> getFields() {
        Map<String, String> fieldMap = new HashMap<String, String>();

        if (data != null) {
            JsArrayString array = data.keys();

            for (int i = 0; i < array.length(); i++) {
                fieldMap.put(array.get(i), data.get(array.get(i)));
            }
        }
        return fieldMap;
    }

    private static String escapeHtml(String maybeHtml) {
        final Element div = DOM.createDiv();
        DOM.setInnerText(div, maybeHtml);
        return DOM.getInnerHTML(div);
    }
}

You can extend this class and create model objects that represent a more Java-like view of your data. For example, I could create a Status class with the following code:

public class Status extends BaseModel {
    
    public Status(JSOModel data) {
        super(data);
    }

    public String getText() {
        return get("text");
    }
}

Then I could change my JSON parsing in TwitterApiCallback to be:

    private class TwitterApiCallback implements RequestCallback {
    public void onResponseReceived(Request request, Response response) {
        if (response.getStatusCode() == 200) {
            JsArray<JSOModel> data = JSOModel.arrayFromJson(response.getText());
            List<Status> statuses = new ArrayList<Status>();
            for (int i = 0; i < data.length(); i++) {
                Status s = new Status(data.get(i));
                statuses.add(s);
            }

            // populate textarea with returned statuses
            for (Status status : statuses) {
                payload.setValue(payload.getValue() + status.getText() + "\n\n");
            }

            Label success = new Label("API call successful!");
            success.setStyleName("success");
            form.add(success);
        } else {
            onError(request, new RequestException(response.getText()));
        }
    }

    public void onError(Request request, Throwable throwable) {
        Window.alert("Calling API failed. " + OAuthPage.STANDARD_ERROR + "\n\n" + throwable.getMessage());
    }
}

That's how we're doing lightweight JSON parsing with GWT. I've updated my GWT with OAuth demo with this code. You can also download the source. Please let me know if you have any questions.

Update October 20, 2009: I recently had to enhance the JSOModel and BaseModel classes in my project to handle nested objects and arrays. In my project, I have a Conversation object that has a Channel and a List of Task objects. These objects are available in the JSOModel of my BaseModel, I just needed to grab them a bit differently.

public Channel getChannel() {
    return new Channel(data.getObject("channel"));
}

public List<Task> getTasks() {
    JsArray<JSOModel> array = data.getArray("tasks");
    List<Task> tasks = new ArrayList<Task>(array.length());

    for (int i = 0; i < array.length(); i++) {
        Task task = new Task(array.get(i));
        tasks.add(task);
    }
    
    return tasks;
}

To set a Channel, it's as simple as:

data.set("channel", channel.toJson().toString());

To allow setting Lists, I had to enhance JSOModel by adding the following two methods:

public final void set(String key, List<JSOModel> values) {
    JsArray<JSOModel> array = JavaScriptObject.createArray().cast();
    for (int i=0; i < values.size(); i++) {
        array.set(i, values.get(i));
    }
    setArray(key, array);
}

protected final native void setArray(String key, JsArray<JSOModel> values) /*-{
    this[key] = values;
}-*/;

After making this change, I was able to convert my List to List and set it on the underlying JSOModel.

public void setTasks(List<Task> tasks) {
    List<JSOModel> values = new ArrayList<JSOModel>();
    for (Task task : tasks) {
        values.add(task.getModel());
    }

    data.set("tasks", values);
}

To allow the task.getModel() method to work, I added a getter to BaseModel to allow retrieving the underlying JSOModel. Currently, I'm using a homegrown JSON.java class to produce JSON from my BaseModel objects. It all seems to work great and I'm pumped I can receive and send all my JSON using overlay types.

Implementing OAuth with GWT

Matt Raible — Thu, 18 Jun 2009 13:59:13 -0600

I've heard about OAuth for quite some time, but never had an opportunity to implement it on a project. For a good explanation of what OAuth is, see its Introduction. Here's an excerpt:

...it allows you the User to grant access to your private resources on one site (which is called the Service Provider), to another site (called Consumer, not to be confused with you, the User). While OpenID is all about using a single identity to sign into many sites, OAuth is about giving access to your stuff without sharing your identity at all (or its secret parts).

The reason I needed OAuth was to interact with the Google Contacts API. I've always hated how sites make you import all your contacts from Gmail. I wanted to develop a system that'd let you simply read your contacts from Google in real-time.

Since the application I'm working on uses GWT, I chose to implement an OAuth client in GWT. After googling for "gwt oauth", I found two examples. Unfortunately, neither worked out-of-the-box.

The good news is I did manage to create a working solution. The bad news is it only seems to work at random. That's right folks, I created a solution that only works 50% of the time. I'm somewhat embarrassed to post it here, but I also realize the power of open source and community. By sharing, I hope we can find the flaws in my logic and come up with a solution for all GWT applications.

The best project for OAuth libraries seems to be oauth on Google Code. However, you'll notice that there is no JavaScript implementation listed on the homepage. I did look at the Java implementation, but quickly realized it wouldn't be usable in GWT. Therefore, I opted for the JavaScript implementation.

OAuth consists of several steps. The following diagram explains the authentication flow nicely.

In a nutshell, you have to complete the following steps:

Get a token from the service provider.
Redirect user to service provider to grant access and redirect back to application.
Request access token to access protected resources.
Access protected resources and pull/push data.

To access a service provider's OAuth service, you'll likely need to start by registering your application. For Google, OAuth Authentication for Web Applications is an excellent resource. Google's OAuth Playground is a great way to with the Google Data APIs after you've registered.

Now that you know how OAuth works, let's look at how I implemented it with GWT. I started by adding the necessary JavaScript references to my *.gwt.xml file.

<script src="//oauth.googlecode.com/svn/code/javascript/oauth.js"/>
<script src="//oauth.googlecode.com/svn/code/javascript/sha1.js"/>

Next, I needed a way to sign the request. I tried to use Sergi Mansilla's OAuth.java for this, but discovered issues with how the parameters were being written with GWT 1.6. I opted for Paul Donnelly's makeSignedRequest function instead. By adding this to my application's HTML page, I'm able to call it using the following JSNI method:

public native static String signRequest(String key, String secret, String tokenSecret, String url) /*-{
    return $wnd.makeSignedRequest(key, secret, tokenSecret, url);
}-*/;

After the URL is signed, it needs to be sent to the provider to get a request token. To do this, I used GWT's RequestBuilder and created a send() method:

protected void send(RequestCallback cb, String URL) {
    RequestBuilder builder = new RequestBuilder(RequestBuilder.GET, URL);
    builder.setTimeoutMillis(10000);
    builder.setCallback(cb);
    
    Request req = null;
    try {
        req = builder.send();
    } catch (RequestException e) {
        cb.onError(req, e);
    }
}

If you try this with Google's Request Token URL in GWT's hosted mode, nothing will happen. Compile/browse to Safari and you'll still see nothing. Try it in Firefox and you'll see the following.

To workaround browsers' Same Origin Policy, I added a proxy servlet to send the requests. I started with Jason Edwards's ProxyServlet and modified it to fit my needs. I then registered it in both *.gwt.xml and web.xml.

<servlet path="/google/" class="org.appfuse.gwt.servlet.AlternateHostProxyServlet"/>

Now, before calling the send() method, I replace the start of the URL so the request would be routed through the servlet.

public void getToken(RequestCallback cb) {
    String url = signRequest(provider.getConsumerKey(), 
                             provider.getConsumerSecret(), 
                             "", provider.getRequestTokenURL());
    url = url.replace("https://www.google.com/", "/google/");
    send(cb, url);
}

When the request returns, I create two cookies by calling a createOAuthCookies() method with the payload returned:

public static String[] createOAuthCookies(String data) {
    String oauth_token = data.substring(data.indexOf("oauth_token=") + 12);
    oauth_token = oauth_token.substring(0, oauth_token.indexOf("&"));

    String oauth_token_secret = data.substring(data.indexOf("oauth_token_secret=") + 19);

    Cookies.setCookie("oauth_token", URL.decode(oauth_token));
    Cookies.setCookie("oauth_token_secret", URL.decode(oauth_token_secret));
    return new String[]{oauth_token, oauth_token_secret};
}

The next step is to authorize the token. This is where things got tricky with my proxy servlet and I had to add some special logic for GWT. Google was sending back a 302 with a Location header, but it wasn't hitting the onResponseReceived() method in my callback. For this reason, I had to change it to a 200 status code and add the redirect location to the body. I also discovered that sometimes they'd return an HTML page with a <meta http-equiv="refresh" ...> tag. When using Twitter, I discovered the full HTML for the allow/deny page was returned. Below is the callback I'm using. WindowUtils is a class I got from Robert Hanson and the gwt-widget project.

public void onResponseReceived(Request request, Response response) {
    String text = response.getText();
    if (response.getStatusCode() == 200 && response.getText().startsWith("http")) {
        WindowUtils.changeLocation(response.getText());
    } else {
        // look for meta-tag that refreshes and grab its URL
        if (text.contains("";
            String url = text.substring(text.indexOf(tokenToStartWith) + tokenToStartWith.length());
            url = url.substring(0, url.indexOf(tokenToEndWith) + tokenToEndWith.length());
            WindowUtils.changeLocation(url);
        } else {
            // Twitter returns a full HTML page, so redirect to the authorize URL manually
            if (provider instanceof Twitter) {
                String url = provider.getAuthorizeTokenURL();
                url = url.replace("$1", OAuthRequest.getAuthToken());
                url = url.replace("$2", DefaultRequest.getCurrentLocation());
                WindowUtils.changeLocation(url);
            } else {
                onError(request, new RequestException(text));
            }
        }
    }
}

public void onError(Request request, Throwable caught) {
    Window.alert("Calling authorize token failed. " + OAuthPage.STANDARD_ERROR + "\n\n" + caught.getMessage());
}

The 3rd step is to get an access token. The most important thing to remember when you do this is to include the "oauth_token_secret" value when signing the request.

signRequest(provider.getConsumerKey(), provider.getConsumerSecret(), 
            getAuthTokenSecret(), url);

After this completes with a 200, I create the cookies again (since oauth_token and oauth_token_secret are returned in the body), then call the API to get a list of contacts. The ContactsRequests class is responsible for making the call. The DefaultRequest class contains the send() method as well as utility methods to get the cookie values of the oauth tokens.

public class ContactsRequest extends DefaultRequest {
    private static final String GOOGLE_CONTACTS_URL = 
        "http://www.google.com/m8/feeds/contacts/default/thin?oauth_token=$1";
    private OAuthProvider provider;

    public ContactsRequest(OAuthProvider provider) {
        this.provider = provider;
    }

    public void getContacts(RequestCallback cb) {
        String url = GOOGLE_CONTACTS_URL.replace("$1", getAuthToken());
        url = signRequest(provider.getConsumerKey(), provider.getConsumerSecret(), 
                          getAuthTokenSecret(), url);

        String proxiedURLPrefix = "/contacts/";
        // allow for deploying at /gwt-oauth context
        if (WindowUtils.getLocation().getPath().contains("gwt-oauth")) {
            proxiedURLPrefix = "/gwt-oauth" + proxiedURLPrefix;
        }

        url = url.replace("http://www.google.com/", proxiedURLPrefix);

        send(cb, url);
    }
}

If all goes well, the response contains the data you requested and it's used to populate a textarea (at least in this demo application). Of course, additional processing needs to occur to parse/format this data into something useful.

This all sounds pretty useful for GWT applications, right? I believe it does - but only if it works consistently. I sent a message to the OAuth Google Group explaining the issues I've had.

I'm trying to use the JavaScript API to authenticate with OAuth from a GWT application. I've got it working with both Google and Twitter's OAuth implementations. However, it seems to fail to sign the URL at random. In other words, it works 1 out of 3 times. ... Any idea why this could be happening?

I received a response with a cleaner makeSignedRequest() function. I tried it and, unfortunately, it seems to be equally unreliable. I suspect the problem is with the OAuth JavaScript implementation, GWT's interpretation of it, or that OAuth isn't as mature as it appears to be. I'd like to think one of the first two causes the problem.

To make it easier to create a robust example of GWT and OAuth, I created a gwt-oauth project you can download or view online. Please keep in mind the demo is likely to be flakey. If you're persistent and try enough times, it's likely to work. Firefox seems to succeed moreso than Safari or Chrome. If you have any suggestions for improving this example, please let me know.

Appcelerator with Matt Quinlan

Matt Raible — Tue, 7 Oct 2008 19:08:19 -0600

This evening I attended the Denver Open Source User Group meeting where the Basic Concepts talk was on Appcelerator. Matt Quinlan (Twitter, Blog, LinkedIn) was the presenter. I arrived 10 minutes late, so I didn't hear any of the intro stuff. Below are my notes from the event.

The Appcelerator developers liked the "onclick" syntax, but found it was too limited to do everything they wanted. Rather than onclick, they use an on attribute. For example:

<div on="click then l:show.box">
Click me
<div>

"DOM Manipulation is JavaScript cruft."

Appcelerator allows you to implement the Observer pattern in the browser. In addition to allowing DOM elements to subscribe to messages, server-side objects (in any language) can subscribe as well. In Appcelerator syntax "l:" means local and "r:" means remote. The messages that are passed to the server are JSON and have payloads. JSON is more popular than XML because you can eval() it and create JavaScript objects from it. Appcelerator allows you to do Declarative Ajax. On the server-side, you can annotation Java and C# classes with @Service to subscribe to messages. In other languages (i.e. PHP), Javadoc-style comments are used.

Tagline: The seamless fusion of RIA and SOA.

Web Expression Language
Goal is to eliminate 90% of the JavaScript you write. Example syntax:

on="[condition] then [action]"

Conditions include DOM events (click, focus, blur, change, mouse events), key events (up, down, press), other (history, drag/drop, selected, resize, iPhone orient, sortXYZ), subscribe to custom message. Actions include Scriptaculous effects (show/hide, fade, move, drop, grow), set element value (static, dynamic, bind), set CSS class or attribute, execute custom JavaScript, publish custom message.

Now Matt is doing a demo on http://try.appcelerator.org. This site consists of a form that allows you to type in Appcelerator code and run it. 3 attributes can be added to any tag: draggable, droppable and resizeable.

Client-Side
Add simple tags to your HTML to inject RIA widgets. Add single property to existing HTML elements for dynamic behavior. Eclipse Plugin built on Aptana, but is generally targeted towards web developers moreso than business analysts (no drag and drop of widgets).

Server-Side
Server-side development done with your IDE of choices. Based on your server-side tehchnology platform. Easily create services using annotations.

App Command
The app command is similar to Rails' GEM command. Allows you to build scaffolding and deploy to cloud (AppEngine, Amazon S3). It also allows you to pulldown components from the main server and auto-updating.

Examples:

appTunes: widget that wraps Flex Cover Flow widget
Snapshot: photo editing application
Radio Javan: Persian music online
SkyBlox: wireless company

Appcelerator allows you to create prototypes easily by using a JavaScript file with mocks for the server-side objects. In the next version, you can "annotate" the UI and allow end-users to Ctrl+Click on elements and add feedback. For an example of this, see http://dev.appcelerator.com/pearson.

When starting with Appcelerator, you can start by crawling (including appcelerator.js for widgets) then move to walking (decouple server-side and client-side) and finally running (developing working prototypes with mocks for server-side).

"Let's face it, ASP, JSP, PHP and Ruby are just lipstick on CGI."

[OSCON 2008] Even Faster Web Sites by Steve Souders

Matt Raible — Thu, 24 Jul 2008 16:23:12 -0600

Steve works at Google on web performance and open source initiatives. To begin his talk, Steve is running YSlow in "autorun" mode. This runs YSlow Performance tests on the top 100 sites according to Alexa. Before Google, Steve was at Yahoo for 7 years. You can download Steve's slides from his site (don't ask me where).

iGoogle with an empty cache: 9% of the time is spent getting the HTML document. The % of time of what a webserver does is a pretty small percentage of the overall picture. If the cache is primed, the time goes up to 17% of the time.

80-90% of the end-user response time is spent on the frontend. Start there.

There's a greater potential of improvement on the frontend. If you improve the backend performance by 50%, chances are the end-user only sees a 5% improvement.

The 14 Rules are encapsulated in the YSlow plugin. At OSCON last year, Yahoo released YSlow. 500,000 downloads since it was released. Following the release of YSlow, Steve wrote High Performance Web Sites.

High Performance Web Sites, Vol 2. The 3 most important rules are:

Split the initial payload
Load scripts without blocking
Don't scatter inline scripts

Why focus on JavaScript? A lot of the top sites use JavaScript. For example, up until a few weeks ago, Facebook served up 1MB of JavaScript, uncompressed. Scripts block parallel downloads and page rendering. To see it in action, go to http://stevesouders.com/cuzillion/?ex=10008.

Any content below a <script> is blocked from rendering - even if it's already cached in the browser. Cuzillion is an open source project that Steve is releasing that allows you to add components to a page and test their performance.

Split your JavaScript between what's needed to render the page and everything else. Load "everything else" after the page is rendered. To do this, you can use Firebug to do it manually, or you can use Doloto from Microsoft to automate the splitting of your files.

MSN.com solves the script blocking problem by using JS DOM to allow for parallel downloading. There's 6 techniques for doing this:

XHR Eval (must have same domain as page)
XHR Injection (same domain)
Script in iFrame (same domain)
Script DOM Element (domains can differ)
Script Defer (only supported in IE, domains can differ)
document.write (not recommended, parallelization only works in IE)

How do these techniques cause "browser busy" indicators? XHR Eval and Injection don't trigger any indicators. You need to choose when you want to show busy indicators. It's good to show them when you want to show your users that something is processing (but not for lazy-loading JavaScript that's not required for load). For the different techniques, most don't ensure order of parsing.

Based on 3 factors, Steve can tell you which technique is best to use. These three factors are 1) the URL of the page and script 2) if you want busy indicators and 3) if you care about order. Steve thinks it would be awesome if web frameworks could support this to write out JavaScript appropriately for the developer's input.

Long executing inline scripts block rendering and downloads. If you know you're going to have scripts like this, you can solve it with a couple workarounds:

Initiate execution with setTimeout(>250 for Firefox)
Move JavaScript to enternal script with advanced downloading techniques
Use defer attribute for IE

In Firefox 2, stylesheets block parallel downloads just like scripts. IE doesn't. However, IE will block when you have a stylesheet followed by an inline script. To solve, it's best to move line scripts above stylesheets or below other resources. use <link>, not @import.

Takeaways: focus on the frontend, run YSlow, focus on JavaScript (split initial payload, load scripts w/o blocking, don't scatter inline scripts).

Three Announcements:

HTTPWatch for Firefox (not public yet, not free).
Firebug Light 1.2 (can be used with IE or Opera).
Mozilla is Firebuggin' (Mozilla is dedicating 3 people to work on Firebug).

[OSCON 2008] CSS for High Performance JavaScript UI by Gavin Doughtie

Matt Raible — Thu, 24 Jul 2008 15:30:32 -0600

Gavin is a front end developer on Google’s Picasa Web Albums and a contributor to the dojo toolkit. The original designer tools for Web 1.0 were the FONT tag, TABLE hacks and spacer gifs. Now we live in the future (shows a picture of the iPhone). Maybe it's time to accept that we're stuck with CSS. "I'm a coder, not a designer" is what happens at OSCON.

There are costs of JavaScript: development, download, parse time and runtime performance. It's extremely powerful and high-level, but it's slow because it's interpreted. Drawing a box with JavaScript in Firefox 3 isn't too difficult. Another way to do the same thing is with CSS. Doing the same thing in CSS is much faster and requires less code. Surrender To Win. You don't have to code it all. You can hand off part of that to your runtime environment (browser).

CSS Fundamentals
You want to how things flow in a page. Browsers were originally designed to render text. They're built to render flowing text. Other important fundamentals include float, positioning, negative margins, relative units, pseudo-selectors. Lastly, you need to know when to use tables. Gavin is now showing an example of using CSS to modify an image so it scales with the browser window. It's pretty simple:

body {
  margin: 0;
  padding: 0;
  height: 100%;
  width: 100%;
  overflow: hidden;
}

img { 
  position: relative;
  width: 100%;
  height: 100%;
}

Relatively Absolutely: "Absolute" in relative to position:relative. If an element has absolute positioning, it will only be positioned relative to it's parent element. To draw a box on an image, it's usually best to calculate the percentage position and sizes in script or on the server. The world's greatest psuedo-selector is :hover. Unfortunately, :hover doesn't work on anything but <a> in IE 6.

With floats, you can "float" elements to the top, right, bottom and left. In Firefox and Safari, you can set a border-radius to draw lines that are curved. Before Firefox 3, these lines where terrible looking.

Tables make a lot of sense when you have a grid layout. Use table-layout:fixed if you don't want table cells to be the width of their contents.

For sizing images and other elements, it's usually best to use em for the height and width and relative measurements. You can then use style.fontSize to resize the images. Using this technique is must faster than using JavaScript to set the height and width on an image.

WebKit, the CSS Wonderland. Gavin loves WebKit. It's on Safari (Windows, OS X and iPhone), Android, GNOME and KDE. With WebKit, you can build expanding lists w/o any coding. To do gradients in WebKit, you use:

background: -webkit-gradient(linear, left top, left bottom, from(#fff), to(#00abeb));
-webkit-border-radius: 0.24em;

To do animation, you can use:

-webkit-transition-property: width, height;
-webkit-transition-duration: 250ms;
-webkit-transition-timing-function: default;

Another thing you can do with WebKit is rotate images (using -webkit-transform: rotate()) and just about anything (divs, forms, etc.). WebKit also supports SVN masks, which means you can open up a hole and view an image through it.

Gecko's pretty cool too. Firefox 3 introduced a new rendering engine based on Cairo. You can do an SVG transform in Firefox 3 to create reflections of elements (divs) in your page.

"With browsers, you cut people off at the knees, but everyone's the same height." -- Alex Russell

IE 6 is not the problem, we're the problem. If you drop support for IE 6, you won't have to worry about coding towards it. It might not be possible if you work for a large company, but if you're small, you should definitely think about it hard.

It's funny to think that IE 6 is the new Netscape 4.

Gavin's slides from this talk will be available at http://xdraw.org/oscon2008.html in the next few days.

Shadowbox - a slick Lightbox that supports Flash

Matt Raible — Fri, 25 Jan 2008 21:05:16 -0700

Via Ajaxian, I learned about Shadowbox.js. From its creator, Michael Jackson:

A few weeks ago, I was looking for a Lightbox-like script that would allow me to display more than just pictures. In addition to static images, my client required the ability to display various types of movies including QuickTime and SWF. The only script that fit the bill was Lightwindow?a nice piece of work to be sure?but it required the Prototype + Scriptaculous combo and I was already using YUI.

Besides, I thought, it would be really great to have a full-featured media viewing application that was library agnostic. Then, if I need to use a different framework for some particular reason, I can easily switch.

Thus was born Shadowbox?a cross-browser, cross-platform, cleanly-coded and fully-documented media viewer application built entirely in JavaScript.

I've been using Lightbox JS on this site for almost 2 years. The next time I need lightbox functionality for an application, I'll definitely try out Shadowbox. I dig the look and feel. I agree with Ajaxian commentors that rel="lightbox[name]" would be awesome. If it's added, I could theoretically replace lightbox.js with shadowbox.js and I wouldn't have to make any other changes.

View Shadowbox Demos »

Ext JS Tag Library

Matt Raible — Tue, 22 Jan 2008 10:01:27 -0700

James Carr in Making extJS More Accessible to Java Developers:

With my recent interest in extjs, I was playing with the idea of making a Struts2/WebWork component library or a tag library to handle a lot of the boilerplate extjs code (i.e. creating layouts and such) but, luckily, discovered someone beat me to the punch!

I randomly came across ExtTLD this morning while sifting through my rss feeds, and I must say I am rather impressed. Although I consider myself a pretty good javascript developer, there seems to be a lot of java developers who aren?t that hot at javascript... which is why whenever I attend any java related conference there is always several sessions touting "javascript free ajax!" frameworks like GWT, Ajax4JSF, or IceFaces. Although I've always been skeptical of such frameworks, I do see their benefits... especially for the java developer who excels at serverside JEE development but generally sucks when it comes to adding javascript behavior to the presentation layer.

I can definitely see how Ajax-with-IDE-code-completion would appeal to many developers. However, I do have to agree with James:

So far it looks good, but I haven't had a chance to play with it yet. Basically, I'll have to see if it passes my "good javascript generator framework" test. I?m a pretty staunch advocate of unobtrusive javascript, and generally hate any presentation layer framework that seeks to dump several hundred (or thousand) lines of javascript inline in the html document.

For development shops that have UI-only developers for the front-end and Java developers for the controller/validation part of an application, frameworks that generate JavaScript usually don't make sense.

ExtTLD's license:

ExtTLD is published under GPL 3.0 license however restricts use by companies participating in animal abuse, such as animal testing laboratories etc.