ESRI Javascript API 4 with Angular 2 - Transition to Webpack

Sun, 08 Jan 2017 14:21:52 -0500

Since my first post on Angular 2 and the ESRI API, I’ve transitioned from SystemJS to Webpack which I’m enjoying thoroughly.

Sample App w/ Webpack setup:
Demo
Repo

IMO, Webpack has a few major advantages over SystemJS:

Development build step is much faster and lite-server does not bog down with memory leaks (not sure why that happened with the SystemJS setup but lite-server got slower and slower until restarted).
Webpack takes care of bundling code for you (everything expect the ESRI requires).
- This setup also bundles each components’ html and css in the main bundle.
Feels like less of a hack to use with esri - simply require in each module and that’s it. Setup is simply specifying ESRI as an “external”. Nothing really special there and it just works.
No need for a grunt/gulp step to minimize, etc. Webpack is pretty comprehensive.

This app is just a map with a custom coordinate display component (bottom left):

I’ve used a similar webpack configuration to this in a couple production apps over the last several months. Unit testing w/ this setup and Typescript is finally starting to feel natural (instead of a large very verbose burden w/ es5). I’ve found it fairly straightfoward to test domain classes and models w/ business logic where I feel you get the most bang for your buck from testing. What I haven’t quite figured out yet is how to test components (and when it’s actually worth the effort). This project contains a working test for the coordinate component… It works, but I’m not yet convinced it’s the best way to go about it. Please comment if you have experience here!

Coordinate Component test:

import { TestBed, ComponentFixture } from '@angular/core/testing';
import { DebugElement } from '@angular/core';

import { CoordinateComponent } from './coordinate.component';

let fixture: ComponentFixture<CoordinateComponent>;
let component: CoordinateComponent;
let de: DebugElement;
let el: HTMLElement;
let $mapDiv;
let mapDivEl: Element;
beforeEach(() => {
  // refine the test module by declaring the test component
  TestBed.configureTestingModule({
    declarations: [CoordinateComponent]
  });

  // create component and test fixture
  fixture = TestBed.createComponent(CoordinateComponent);
  el = fixture.nativeElement;

  // get test component from the fixture
  component = fixture.componentInstance;

  // add a div to the body
  $mapDiv = $('<div>', { id: 'mapDiv' }).appendTo('body');
  mapDivEl = $mapDiv[0];

  // mock required MapView props/functions
  component.mapView = <any>{
    container: mapDivEl,
    toMap: (point) => {
      return {
        longitude: 5,
        latitude: 10
      };
    },
    zoom: 7,
    scale: 500
  };

  // runs ngOnInit
  fixture.detectChanges();
});

describe('Coordinate', () => {
  it('should update lat/long on mousemove', () => {
    mapDivEl.dispatchEvent(new Event('mousemove', {
      bubbles: true,
      cancelable: true
    }));
    // pageX, pageY
    fixture.detectChanges();
    expect(el.querySelector('#longitude').innerHTML).toBe('5.000000');
    expect(el.querySelector('#latitude').innerHTML).toBe('10.000000');
    expect(el.querySelector('#zoom').innerHTML).toBe('7');
    expect(el.querySelector('#scale').innerHTML).toBe('500');
  });
});

ESRI Javascript API 4 with Angular 2 and Typescript

Tue, 17 May 2016 20:23:08 -0400

Update 1/8/2017: I’ve transitioned to Webpack since this post: link

This could really be a post about many things.

First, I’m a believer in client-side MV*. Second, I’m trying to incorporate better testing into my front-end JS code. Angular seemed like a natural fit given these 2 primary objectives. I’ve done a fair amount of work now with Angular 1 and the ESRI JSAPI 3.x library. There have been some solid success here, but Dojo require throughout the app and especially in unit tests have been a major headache. You could perhaps mock all dependencies from ESRI in the unit tests or try to keep ESRI in it’s own untested sandbox, but both of these strategies seems better in theory than practice.

Aside: ESRI does not make any of this easy. Sure, you can get it to work… kind of…. with a lot of headaches along the way. It all boils down to Dojo. Don’t get me wrong, the ESRI API does some amazing things and some of the new 4.0 features look incredibly promising (.watch() is brilliant), but there’s really no solid reason why we’re still forced to use Dojo.

Anyway, getting to what this post is really about….

The App

Live Demo

From a high level view, the app simply adds points to the map and shows a list of those points with their geometry and “index” attribute. Nothing too special - just there to test some concepts. As an added bonus, the app is served through lite-server and constantly updates as you code. Similarly, the unit tests run continuously.

Building upon experimental work by Rene Rubalcava and Tom Wayson, I was able to get an Angular 2 app properly loading dojo dependencies both in the browser and in Karma tests.

The app consists of a “model” (Angular service) to hold the points (or domain object of your choosing) - the thought being that business logic in this model would be testable without being concerned about the objects’ relation to the map. Ideally, this model wouldn’t contain ESRI dependencies, but with the JSAPI 4’s watch capabilities, it seems to make sense to use an esri/core/Collection as the underlying data structure in the model. Also ideally, we’d just have the collection in the model, but it seems the only way to achieve the map automagically updating is if we use the points from a GraphicsLayer (passing in our Collection as the graphics property to the GraphicsLayer constructor worked in 4.0beta3, but not in 4.0 final for some reason).

PointsModel (points.model.ts)

So here’s our PointsModel (in Typescript). We’ve simply wrapped a few Collection methods and then we can add some additional business logic like getIndexSum(). index is just a made up attribute for sake of testing.

import { Injectable } from '@angular/core';

import Graphic from 'esri/Graphic';
import GraphicsLayer from 'esri/layers/GraphicsLayer';
import Collection from 'esri/core/Collection';

@Injectable()
export class PointsModel {
  private points: Collection = new Collection();
  pointsLayer: GraphicsLayer;
  constructor() {
    this.pointsLayer = new GraphicsLayer();
    this.points = this.pointsLayer.graphics;
  }
  addPoint(pointGraphic: Graphic) {
    this.points.add(pointGraphic);
  }
  addPoints(pointsGraphics: Graphic[]) {
    this.points.addMany(pointsGraphics);
  }
  getPointGraphics() {
    return this.points;
  }
  clear() {
    this.points.removeAll();
  }
  getIndexSum() {
    let sum = 0;
    if (this.points !== null) {
      this.points.forEach(p => sum += p.attributes.index);
    }
    return sum;
  }
}

AttributeComponent (attribute.component.html)

When we add a point to the model, it not only shows up in the map, but also in the attribute list which is wired up through databinding:

<div>
  <h2>Points!</h2>
  <p>Index Sum: {{pointsModel.getIndexSum()}}
  <ul>
    <li *ngFor="let point of points.toArray()">
      <span>{{point.attributes.index}} ({{point.geometry.x | number:'.5-5'}},{{point.geometry.y | number:'.5-5'}})</span>
    </li>
  </ul>
</div>

MapService (map.service.ts)

Our map binding to our PointsModel (which is just a matter of adding pointsModel.pointsLayer (our GraphicsLayer) to the map):

import { Injectable } from '@angular/core';

import Map from 'esri/Map';
import GraphicsLayer from 'esri/layers/GraphicsLayer';

import { PointsModel } from './points.model';

@Injectable()
export class MapService {
  map: Map;
  pointGraphicsLayer: GraphicsLayer;
  constructor(pointsModel: PointsModel) {
    this.map = new Map({
      basemap: 'topo'
    });
    this.map.add(pointsModel.pointsLayer);
  }
}

PointsModel Tests (points.model.spec.ts)

import { PointsModel } from './points.model';

import Graphic from 'esri/Graphic';
import Point from 'esri/geometry/Point';

describe('PointsModel tests', () => {
  let mockPointGraphic = new Graphic({
    attributes: {
      index: 1
    },
    geometry: new Point({
      x: 1,
      y: 2,
      spatialReference: {
        wkid: 4326
      }
    })
  });

  let pointsModel;
  beforeEach(() => {
    pointsModel = new PointsModel();
  });

  it('should contstruct it', () => {
    expect(pointsModel).toBeDefined();
    expect(pointsModel.getPointGraphics()).toBeDefined();
  });

  describe('adding and removing points', () => {
    it('should add a point to collection', () => {
       pointsModel.addPoint(mockPointGraphic);
       pointsModel.addPoint(mockPointGraphic);
       expect(pointsModel.getPointGraphics().length).toEqual(2);
    });

    it('should add points to collection', () => {
      pointsModel.addPoints([mockPointGraphic, mockPointGraphic]);
      expect(pointsModel.getPointGraphics().length).toEqual(2);
    });

    it('should clear points', () => {
      pointsModel.addPoint(mockPointGraphic);
      pointsModel.addPoint(mockPointGraphic);
      pointsModel.clear();
      expect(pointsModel.getPointGraphics().length).toEqual(0);
    });
  });

  describe('calculations', () => {
    it('should calculate the sum of the index attributes', () => {
      pointsModel.addPoints([mockPointGraphic, mockPointGraphic]);
      let sum = pointsModel.getIndexSum();
      expect(sum).toEqual(2);
    });
  });

});

The nice thing here is that the tests didn’t balk at using the esri Collection that must be imported into the PointsModel (this has been an incredibly difficult thing to do w/ Angular 1 / Dojo).

Setup

Setup for this is non-trivial and is based heavily on esri/esri-system-js along with custom configuration in the Karma configuration and loading of dependencies locally using the esri bower jsapi repo. In short, the esri-system-js loader loads ALL esri dependencies at the start of the application so they’re available through import statements in Typescript files. This was already figured out for the browser portion by Tom and Rene as referenced previously, so check out their repo’s for more information there.

Getting it wired up for testing was a little more difficult but here are the key highlights. Note that I’ve broken out some different configs for browser vs tests.

dojoConfigTest.js

Fairly standard setup for loading from a local bower setup.

(function(window) {
  // set up your dojoConfig
  window.dojoConfig = {
    baseUrl: 'app/node_modules/',
    deps: ['app/main'],
    packages: [
      'app',
      'dijit',
      'dojo',
      'dojox',
      'dstore',
      'dgrid',
      'esri', {
        name: 'moment',
        location: 'moment',
        main: 'moment'
      }
    ]
  };
});

karma.conf.js

These are the changes that were added to the karma.conf.js configuration included in the angular2 quick start repo:

  ...

  files: [
    ... angular files, etc.
    // ********* esri load ***********
    // must be able to serve these files for dojo require
    // NOTE: karma gives a cryptic error when 
    // files can't be found  (msg || "").replace is not a function
    { pattern: 'bower_components/dojo/**/*.*', included: false, watched: false },
    { pattern: 'bower_components/dojox/**/*.*', included: false, watched: false },
    { pattern: 'bower_components/dstore/**/*.*', included: false, watched: false },     
    { pattern: 'bower_components/dgrid/**/*.*', included: false, watched: false },
    
    { pattern: 'bower_components/dijit/**/*.*', included: false, watched: false },
    { pattern: 'bower_components/esri/**/*.*', included: false, watched: false },    
    { pattern: 'bower_components/moment/**/*.js', included: false, watched: false },   

    // load dojoConfig so dojo knows where to "require" modules from
    'dojoConfigTest.js',
    
    // we need the actual dojo startup file for "requrire" to be defined
    'bower_components/dojo/dojo.js',
    
    // load in esri's systemJs util
    'node_modules/esri-system-js/dist/esriSystem.js',
    
    // load in our array of esri dependencies
    'esriLoadConfig.js',
    
    // bootstrap in the modules using esri-system-js
    'esriSystemLoadTest.js', 

    ... more angular files
]

esriLoadConfig.js

Contains ALL esri modules required by the application:

(function(window) {
  window.esriLoadConfig = {
      modules: [
      'esri/Map',
      'esri/views/MapView',
      'esri/core/Collection',
      'esri/layers/GraphicsLayer',
      'esri/Graphic',
      'esri/geometry/Point',
      'esri/geometry/SpatialReference',
      'esri/symbols/SimpleMarkerSymbol',
      'esri/Color'
    ]
  };
}(window))

esriSystemLoadTest.js

Called by Karma to pre-load the esri modules before the tests run.

// load esri modules needed by this application
// into a System.js module called esri
start = performance.now();
esriSystem.register(esriLoadConfig.modules, function () {
  end = performance.now();
  time = end - start;
  console.log('Loaded esri modules', time / 1000.0);
});

esriSystemLoadBrowser.js

Used in the browser code (called from index.html) to load in the esri modules AND bootstrap the application once those modules are available.

// load esri modules needed by this application
// into a System.js module called esri
console.log("Loading esri modules: ", esriLoadConfig.modules);
start = performance.now();
esriSystem.register(esriLoadConfig.modules, function () {
  // then bootstrap application
  end = performance.now();
  time = end - start;
  console.log('Loaded esri modules', time / 1000.0);
  System.import('app/main').then(function () {
    console.log('app/main imported');
  }, function (error) {
    console.log("System import error:", error);
  });
});

Conclusion

~~This is highly experimental and there’s a lot of moving parts, but it’s nice to know this is possible.~~ This is getting closer to production quality. I’ve left out a lot but the full repo’s here:

https://github.com/jwerts/jsapi4-angular2

There will likely be updates to the repo as I continue to explore this concept (and learn Angular 2… and learn Typescript).

It could really benefit from a final build process. Note that I’ve used CDN for most dependencies in index.html for the gh-pages demo to avoid loading local bower and node dependencies to Github.

Edit 2016-06-16: Updated Angular to 2.0.0.RC2
Edit 2016-06-24: Updated Angular to 2.0.0.RC3
Edit 2016-07-05: Updated Angular to 2.0.0.RC4
Edit 2016-07-07: Updated to use esri-system-js 1.0 beta which now preserves esri module names and works correctly with Typescript arcgis-js-api typings.
Edit 2016-09-22: Updated Angular to 2.0.0 final

Typescript on Josh Werts