Merge pull request #163 from Esri/feat/version

Feat/version

CHANGELOG.md

@@ -4,7 +4,14 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 ### Added
-### Changed
+- `loadScript()` takes a new `version` option to load a specific version from the CDN
+- passing `css: true` to `loadScript()` will load the styles for the CDN version
+- `loadCss()` defaults to loading the latest 4.x styles if no arguments are passed
+- `loadCss()` can take a version as a string to load a version's styles from the CDN
+### Changed
+- split source code into modules
+- tests are now written in TypeScript and loaded via karma-typescript
+- updated to recent versions of TypeScript, Karma, & Jasmine
 ### Fixed
 ### Removed
 ### Breaking

README.md

@@ -4,9 +4,9 @@
 
 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.
 
-![ArcGIS logo, mended broken heart, Angular logo, Ember logo, Rreact logo, Vue logo](https://docs.google.com/drawings/d/e/2PACX-1vSUEfgaupMLz6FXBX65X-nm7cqA0r9ed3rJ_KNISeqzwDDkd8LsubLhQ_hCWwO3zjS41cD5eG7QUBHl/pub?w=888&h=222)
+![ArcGIS logo, mended broken heart, Angular logo, Ember logo, React logo, Vue logo](https://docs.google.com/drawings/d/e/2PACX-1vSUEfgaupMLz6FXBX65X-nm7cqA0r9ed3rJ_KNISeqzwDDkd8LsubLhQ_hCWwO3zjS41cD5eG7QUBHl/pub?w=888&h=222)
 
-See below for more information on [why this library is needed](#why-is-this-needed) and how it can help improve application load performance and allow using the ArcGIS API in isomorphic/universal 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 and allow [using the ArcGIS API in isomorphic/universal applications](#isomorphicuniversal-applications).
 
 **NOTE**: If you want to use the ArcGIS API in an [Ember](#ember) or [AngularJS](https://angularjs.org/) (1.x) application, you should use one of these libraries instead:
 
@@ -29,8 +29,8 @@ See the [Examples](#examples) section below for links to applications that use t
 - [Why is this needed?](#why-is-this-needed)
 - [Examples](#examples)
 - [Advanced Usage](#advanced-usage)
-  - [Overriding ArcGIS Styles](#overriding-arcgis-styles)
   - [Configuring Dojo](#configuring-dojo)
+  - [Overriding ArcGIS Styles](#overriding-arcgis-styles)
   - [Pre-loading the ArcGIS API for JavaScript](#pre-loading-the-arcgis-api-for-javascript)
   - [Isomorphic/universal applications](#isomorphicuniversal-applications)
   - [Using your own script tag](#using-your-own-script-tag)
@@ -66,7 +66,7 @@ The code snippets below show how to load the ArcGIS API and its modules and then
 
 #### From the Latest Version
 
-Here's an example of how you could load and use the latest 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)):
+Here's an example of how you could load and use the latest 4.x `WebMap` 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 { loadModules } from 'esri-loader';
@@ -102,9 +102,7 @@ import { loadModules } from 'esri-loader';
 // 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.27/'
-};
+const options = { version: '3.27' };
 
 loadModules(['esri/map'], options)
   .then(([Map]) => {
@@ -121,53 +119,68 @@ loadModules(['esri/map'], options)
   });
 ```
 
+### From a Specific URL
+
+You can also load the modules from a specific URL, for example from a version of the SDK that you host on your own server. In this case, instead of passing the `version` option, you would pass the URL as a string like:
+
+```js
+const options = { url: `http://server/path/to/esri` };
+```
+
 ### Lazy Loading the ArcGIS API for JavaScript
 
 Lazy loading the ArcGIS API can dramatically improve the initial load performance of your application, especially if your users may never end up visiting any routes that need to show a map or 3D scene. That is why it is the default behavior of esri-loader. In the above snippets, the first time `loadModules()` is called, it will attempt lazy load the ArcGIS API by calling `loadScript()` for you. Subsequent calls to `loadModules()` will not attempt to load the script once `loadScript()` has been called.
 
-See below for information on how you can precisely control when the ArcGIS API is loaded by [pre-loading the ArcGIS API](#pre-loading-the-arcgis-api-for-javascript).
+See below for information on how you can [pre-load the ArcGIS API](#pre-loading-the-arcgis-api-for-javascript) after initial render but before a user visits a route that needs it.
 
 ### Loading Styles
 
-Before you can use the ArcGIS API in your app, you'll need to load the styles that correspond to the version you are using. Just like the ArcGIS API modules, you'll probably want to [lazy load](#lazy-loading-the-arcgis-api-for-javascript) the styles only once they are needed by the application. The easiest way to do that is to pass the `css` option to `loadModules()`:
+Before you can use the ArcGIS API in your app, you'll need to load the styles that correspond to the version you are using. Just like the ArcGIS API modules, you'll probably want to [lazy load](#lazy-loading-the-arcgis-api-for-javascript) the styles only once they are needed by the application.
+
+#### When you load the script
+
+The easiest way to do that is to pass the `css` option to `loadModules()` or `loadScript()`:
 
 ```js
 import { loadModules } from 'esri-loader';
 
-// lazy load the CSS before loading the modules
-const options = {
-  css: 'https://js.arcgis.com/4.10/esri/css/main.css'
-};
+// before loading the modules for the first time, 
+// also lazy load the CSS for the version of 
+// the script that you're loading from the CDN 
+const options = { css: true };
 
 loadModules(['esri/views/MapView', 'esri/WebMap'], options)
   .then(([MapView, WebMap]) => {
-    // you can safely create a map now that the styles are loaded
+    // the styles, script, and modules have all been loaded (in that order)
   });
 ```
 
-Alternatively, you can use the provided `loadCss(url)` function to control when the ArcGIS styles are loaded. For example:
+Passing `css: true` does not work when loading the script using the `url` option. In that case you'll need to pass the URL to the styles like: `css: 'http://server/path/to/esri/css/main.css'`.
+
+When passing the `css` option to `loadModules()` it actually passes it to `loadScript()`, So you can also use the same values (either `true` or stylesheet URL) when you call `loadScript()` directly.
+
+#### Using loadCss()
+
+Alternatively, you can use the provided `loadCss()` function to load the ArcGIS styles at any point in your application's life cycle. For example:
 
 ```js
-// load esri styles for version 4.x using loadCss
 import { loadCss } from 'esri-loader';
-loadCss('https://js.arcgis.com/4.10/esri/css/main.css');
-```
 
-See below for information on how to [override ArcGIS styles](#overriding-arcgis-styles) that you've lazy loaded with `loadModules()` or `loadCss()`.
+// by default loadCss() loads styles for the latest 4.x version
+loadCss();
 
-Finally, you can manually load them by more traditional means such as adding `<link>` tags to your HTML, or `@import` statements to your CSS. For example:
+// or for a specific CDN version
+loadCss('3.27');
 
-```html
-<!-- load esri styles for version 4.x via an html link tag -->
-<link rel="stylesheet" href="https://js.arcgis.com/4.10/esri/css/main.css">
+// or a from specific URL, like a locally hosted version
+loadCss('http://server/path/to/esri/css/main.css');
 ```
 
-or:
+See below for information on how to [override ArcGIS styles](#overriding-arcgis-styles) that you've lazy loaded with `loadModules()` or `loadCss()`.
 
-```css
-/* load esri styles for version 3.x via css import */
-@import url('https://js.arcgis.com/3.27/esri/css/esri.css');
-```
+#### Using traditional means
+
+Of course, you don't need to use esri-loader to load the styles. See the [ArcGIS API for JavaScript documentation](https://developers.arcgis.com/javascript/latest/guide/get-api/index.html) for more information on how to load the ArcGIS styles by more traditional means such as adding `<link>` tags to your HTML, or `@import` statements to your CSS.
 
 ## Why is this needed?
 
@@ -313,7 +326,7 @@ import { loadModules } from 'esri-loader';
 
 // lazy load the CSS before loading the modules
 const options = {
-  css: 'https://js.arcgis.com/4.10/esri/css/main.css',
+  css: true,
   // insert the stylesheet link above the first <style> tag on the page
   insertCssBefore: 'style'
 };
@@ -372,7 +385,7 @@ It is possible to use this library only to load modules (i.e. not to lazy load o
 
 ```html
 <!-- index.html -->
-<script src="https://js.arcgis.com/3.27/" data-esri-loader="loaded"></script>
+<script src="https://js.arcgis.com/4.10/" data-esri-loader="loaded"></script>
 ```
 
 ### ArcGIS Types

karma.conf.js

@@ -2,8 +2,6 @@
 // Generated on Wed Mar 08 2017 13:05:58 GMT-0800 (PST)
 
 var isTravis = !!process.env.TRAVIS;
-// for now testing on the build output
-var builtFile = isTravis ? 'dist/umd/esri-loader.min.js' : 'dist/umd/esri-loader.js';
 
 module.exports = function(config) {
   var configuration = {
@@ -14,13 +12,16 @@ module.exports = function(config) {
 
     // frameworks to use
     // available frameworks: https://npmjs.org/browse/keyword/karma-adapter
-    frameworks: ['jasmine'],
+    frameworks: ['jasmine', 'karma-typescript'],
 
 
     // list of files / patterns to load in the browser
     files: [
-      builtFile,
-      'test/*.js',
+      // source code and tests
+      'src/**/*.ts',
+      // test helpers
+      'test/**/*.ts',
+      // serve mock scripts
       { pattern: 'test/mocks/*.js', included: false }
     ],
 
@@ -33,13 +34,15 @@ module.exports = function(config) {
     // preprocess matching files before serving them to the browser
     // available preprocessors: https://npmjs.org/browse/keyword/karma-preprocessor
     preprocessors: {
+      '**/*.ts': 'karma-typescript',
+      'src/**/!(*test).ts': 'coverage'
     },
 
 
     // test results reporter to use
     // possible values: 'dots', 'progress'
     // available reporters: https://npmjs.org/browse/keyword/karma-reporter
-    reporters: ['mocha'],
+    reporters: ['mocha', 'karma-typescript'],
 
     // web server port
     port: 9876,
@@ -79,7 +82,6 @@ module.exports = function(config) {
 
   // run code coverage locally
   if (!isTravis) {
-    configuration.preprocessors[builtFile] = ['coverage'];
     configuration.reporters.push('coverage');
   }
 

package.json

@@ -21,8 +21,8 @@
     "precompile": "npm run lint",
     "prepublish": "npm run build:release",
     "preversion": "npm run test && git add README.md CHANGELOG.md",
-    "start": "npm run clean && npm run build && concurrently \"onchange 'src/**/*.ts' -- npm run build\" \"karma start\"",
-    "test": "npm run build:release && karma start --single-run=true --browsers Firefox"
+    "start": "karma start",
+    "test": "karma start --single-run=true --browsers Firefox"
   },
   "repository": {
     "type": "git",
@@ -43,20 +43,22 @@
   },
   "homepage": "https://github.com/Esri/esri-loader",
   "devDependencies": {
+    "@types/jasmine": "^2.8.11",
     "concurrently": "^3.4.0",
-    "jasmine-core": "^2.5.2",
-    "karma": "^3.1.3",
+    "jasmine-core": "^2.8.0",
+    "karma": "^4.0.1",
     "karma-chrome-launcher": "^2.0.0",
     "karma-coverage": "^1.1.2",
     "karma-firefox-launcher": "^1.1.0",
     "karma-jasmine": "^1.1.0",
     "karma-mocha-reporter": "^2.2.3",
+    "karma-typescript": "^4.0.0",
     "mkdirp": "^0.5.1",
     "onchange": "^3.2.1",
     "rimraf": "^2.6.2",
     "rollup": "^0.41.6",
     "rollup-plugin-uglify": "^2.0.1",
     "tslint": "^5.7.0",
-    "typescript": "^2.0.10"
+    "typescript": "^3.3.4000"
   }
 }