Merge pull request #48 from Esri/feat/promise-api

Feat/promise api
Esri · Nov 10, 2017 · b0fbd12 · b0fbd12
2 parents cdf4846 + a62b40b
commit b0fbd12
Show file tree

Hide file tree

Showing 9 changed files with 578 additions and 103 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,7 +4,9 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 ### Added
+- add promise-based functions to load the script and modules
 ### Changed
+- deprecate `bootstrap()` and `dojoRequire()`
 - add code coverage
 - add release script
 ### Fixed

diff --git a/README.md b/README.md
@@ -1,5 +1,5 @@
 # esri-loader
-A tiny library to help load [ArcGIS API for JavaScript](https://developers.arcgis.com/javascript/) modules in non-Dojo applications.
+A tiny library to help load modules from either the [4.x](https://developers.arcgis.com/javascript/) or [3.x](https://developers.arcgis.com/javascript/3/) versions of the [ArcGIS API for JavaScript](https://developers.arcgis.com/javascript/) in non-Dojo applications.
 
 See below for more information on [why this library is needed](#why-is-this-needed) and how it can help improve application load performance.
 
@@ -20,7 +20,7 @@ npm install esri-loader
 ```
 
 ## Usage
-The code below shows how you can load the ArcGIS API for JavaScript and then create a map. Where you place this code in your application will depend on what framework you are using. See below for [example applications](#examples).
+The code snippets below show how to load ArcGIS API for JavaScript modules use them to create a map. Where you would place similar code in your application will depend on which application framework you are using. See below for [example applications](#examples).
 
 ### Loading Styles
 
@@ -38,103 +38,119 @@ If you're using a specific version other than the latest 4.x:
 @import url('https://js.arcgis.com/3.22/esri/css/esri.css');
 ```
 
-### Pre-loading the ArcGIS API for JavaScript
-
-If you have good reason to believe that the user is going to transition to a map route, you may want to start pre-loading the ArcGIS API as soon as possible w/o blocking rendering, for example:
-
-```js
-import * as esriLoader from 'esri-loader';
-
-// preload the ArcGIS API
-esriLoader.bootstrap((err) => {
-  if (err) {
-    // handle any loading errors
-    console.error(err);
-  } else {
-    // optional execute any code once it's preloaded
-    createMap();
-  }
-}, {
-  // use a specific version instead of latest 4.x
-  url: 'https://js.arcgis.com/3.22/'
-});
-```
-
-### Lazy Loading the ArcGIS API for JavaScript
+### Loading Modules from the ArcGIS API for JavaScript
 
-Alternatively, if users may never end up visiting any map routes, you can lazy load the ArcGIS API for JavaScript the first time a user visits a route with a map, for example:
+Here's an example of how you could load and use the 4.x `Map` and `MapView` classes in a component to create a map (based on [this sample](https://developers.arcgis.com/javascript/latest/sample-code/sandbox/index.html?sample=webmap-basic)):
 
 ```js
-// import the esri-loader library
-import * as esriLoader from 'esri-loader';
-
-// has the ArcGIS API been added to the page?
-if (!esriLoader.isLoaded()) {
-  // no, lazy load it the ArcGIS API before using its classes
-  esriLoader.bootstrap((err) => {
-    if (err) {
-      console.error(err);
-    } else {
-      // once it's loaded, create the map
-      createMap();
+// first, we use Dojo's loader to require the map class
+esriLoader.loadModules(['esri/views/MapView', 'esri/WebMap'])
+.then(([MapView, WebMap]) => {
+  // then we load a web map from an id
+  var webmap = new WebMap({
+    portalItem: { // autocasts as new PortalItem()
+      id: 'f2e9b762544945f390ca4ac3671cfa72'
     }
-  }, {
-    // use a specific version instead of latest 4.x
-    url: 'https://js.arcgis.com/3.22/'
   });
-} else {
-  // ArcGIS API is already loaded, just create the map
-  createMap();
-}
+  // and we show that map in a container w/ id #viewDiv
+  var view = new MapView({
+    map: webmap,
+    container: 'viewDiv'
+  });
+})
+.catch(err => {
+  // handle any errors
+  console.error(err);
+});
 ```
 
-### Loading Modules from the ArcGIS API for JavaScript
+#### Lazy Loading the ArcGIS API for JavaScript
+
+If users may never end up visiting any map routes, you can lazy load the ArcGIS API for JavaScript the first time a user visits a route with a map. 
 
-Once you've loaded the API using one of the above methods, you can then load modules. Here's an example of how you could load and use the 3.x `Map` and `VectorTileLayer` classes in a component to create a map:
+In the above snippet, the first time `loadModules()` is called, it will attempt to lazy load the most recent 4.x version of the ArcGIS API by calling `loadScript()` for you if the API has not already been loaded. The snippet below uses version 3.x of the ArcGIS API to create a map.
 
 ```js
-// create a map on the page
-function createMap() {
-  // first, we use Dojo's loader to require the map class
-  esriLoader.dojoRequire(['esri/map'], (Map) => {
-    // create map with the given options at a DOM node w/ id 'mapNode'
-    let map = new Map('mapNode', {
-      center: [-118, 34.5],
-      zoom: 8,
-      basemap: 'dark-gray'
-    });
+// if the API hasn't already been loaded (i.e. the frist time this is run)
+// loadModules() will call loadScript() and pass these options, which, 
+// in this case are only needed b/c we're using v3.x instead of the latest 4.x
+const options = {
+  url: 'https://js.arcgis.com/3.22/'
+};
+esriLoader.loadModules(['esri/map'], options)
+.then(([Map]) => {
+  // create map with the given options at a DOM node w/ id 'mapNode'
+  let map = new Map('mapNode', {
+    center: [-118, 34.5],
+    zoom: 8,
+    basemap: 'dark-gray'
   });
-}
+})
+.catch(err => {
+  // handle any script or module loading errors
+  console.error(err);
+});
 ```
 
-### Using your own script tag
+### Pre-loading the ArcGIS API for JavaScript
 
-It is possible to use this library only to load modules (i.e. not to pre-load or lazy load the ArcGIS API), then you will need to add a `data-esri-loader` attribute to the script tag you use to load the ArcGIS API for JavaScript. Example:
+If you have good reason to believe that the user is going to transition to a map route, you may want to start pre-loading the ArcGIS API as soon as possible w/o blocking rendering, for example:
 
-```html
-<!-- index.html -->
-<script src="https://js.arcgis.com/3.22/" data-esri-loader="loaded"></script>
+```js
+// preload the ArcGIS API
+// NOTE: in this case, we're not passing any options to loadScript()
+// so it will default to loading the latest 4.x version of the API from the CDN
+this.loadScriptPromise = esriLoader.loadScript();
+
+// later, for example once a component has been rendered,
+// you can wait for the above promise to resolve (if it hasn't already)
+this.loadScriptPromise
+.then(() => {
+  // you can now load the map modules and create the map
+})
+.catch(err => {
+  // handle any script loading errors
+  console.error(err);
+});
 ```
 
 ### Configuring Dojo
 
-You can pass a [`dojoConfig`](https://dojotoolkit.org/documentation/tutorials/1.10/dojo_config/) option to `bootstrap()` to configure Dojo before the script tag is loaded. This is useful if you want to use esri-loader to load Dojo packages that are not included in the ArcGIS API for JavaScript such as [FlareClusterLayer](https://github.com/nickcam/FlareClusterLayer).
+You can pass a [`dojoConfig`](https://dojotoolkit.org/documentation/tutorials/1.10/dojo_config/) option to `loadScript()` or `loadModules()` to configure Dojo before the script tag is loaded. This is useful if you want to use esri-loader to load Dojo packages that are not included in the ArcGIS API for JavaScript such as [FlareClusterLayer](https://github.com/nickcam/FlareClusterLayer).
 
 ```js
-esriLoader.bootstrap(callbackFn, {
+// in this case options are only needed so we can configure dojo before loading the API
+const options = {
   // tell Dojo where to load other packages
   dojoConfig: {
     async: true,
     packages: [
       {
-        location: 'path/to/somelib',
-        name: 'somelib'
+        location: '/path/to/fcl',
+        name: 'fcl'
       }
     ]
   }
+};
+esriLoader.loadModules(['esri/map', 'fcl/FlareClusterLayer_v3'], options)
+.then(([Map, FlareClusterLayer]) => {
+  // you can now create a new FlareClusterLayer and add it to a new Map
+})
+.catch(err => {
+  // handle any errors
+  console.error(err);
 });
 ```
 
+### Using your own script tag
+
+It is possible to use this library only to load modules (i.e. not to pre-load or lazy load the ArcGIS API), then you will need to add a `data-esri-loader` attribute to the script tag you use to load the ArcGIS API for JavaScript. Example:
+
+```html
+<!-- index.html -->
+<script src="https://js.arcgis.com/3.22/" data-esri-loader="loaded"></script>
+```
+
 ## Why is this needed?
 
 Unfortunately, you can't simply `npm install` the ArcGIS API and then `import` ArcGIS modules directly from the modules in a non-Dojo application. The only reliable way to load ArcGIS API for JavaScript modules is using Dojo's AMD loader. When using the ArcGIS API in an application built with another framework, you typically want to use the tooling and conventions of that framework instead of the Dojo build system. This library lets you do that by providing a module that you can `import` and use to dynamically inject an ArcGIS API script tag in the page and then use its Dojo loader to load only the ArcGIS API modules as needed.
@@ -172,6 +188,24 @@ Here are some applications that use this library (presented by framework in alph
 - [CreateMap](https://github.com/oppoudel/CreateMap) - Create Map: City of Baltimore - https://gis.baltimorecity.gov/createmap/#/
 - [City of Baltimore: Map Gallery](https://github.com/oppoudel/MapGallery_Vue) - Map Gallery built with Vue.js that uses this library to load the ArcGIS API
 
+## Dependencies
+
+This library doesn't have any external dependencies, but it expects to be run in a browser (i.e. not Node.js). Since v1.5 asynchronous functions like `loadScript()` and `loadModules()` return [`Promise`s](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), so if your application has to support [browers that don't support Promise (i.e. IE)](https://caniuse.com/#search=promise) you have a few options.
+
+If there's already a Promise implementation loaded on the page you can configure esri-loader to use that implementation. For example, in [ember-esri-loader](https://github.com/Esri/ember-esri-loader), we configure esri-loader to use the RSVP Promise implementation included with Ember.js.
+
+```js
+  init () {
+    this._super(...arguments);
+    // have esriLoader use Ember's RSVP promise
+    esriLoader.utils.Promise = Ember.RSVP.Promise;
+  },
+```
+
+Otherwise, you should consider using a [Promise polyfill](https://www.google.com/search?q=promise+polyfill), ideally [only when needed](https://philipwalton.com/articles/loading-polyfills-only-when-needed/).
+
+Finally, for now you can still use `bootstrap()` and `dojoRequire()` which are the callback-based equivalents of the above functions. See the [v1.4.0 documentation](https://github.com/Esri/esri-loader/blob/v1.4.0/README.md#usage) for how to use the callback-based API, but _keep in mind that these functions have been deprecated and will be removed at the next major release_.
+
 ## Issues
 
 Find a bug or want to request a new feature?  Please let us know by [submitting an issue](https://github.com/Esri/esri-loader/issues/).

diff --git a/karma.conf.js b/karma.conf.js
@@ -20,7 +20,8 @@ module.exports = function(config) {
     // list of files / patterns to load in the browser
     files: [
       builtFile,
-      'test/**/*.js'
+      'test/*.js',
+      { pattern: 'test/mocks/*.js', included: false }
     ],