esri-system-js

Load ArcGIS API for JavaScript modules using SystemJS

NOTE: this library has been deprecated in favor of systemjs-plugin-dojo - which is a SystemJS plugin for loading Dojo modules that works with the ArcGIS API for JavaScript. ng2-esri-demo shows how to use that plugin to load ArcGIS modules in an Angular application.

Provides a wrapper around SystemJS's register() function that will first use Dojo's AMD loader to load Esri modules, and then register a SystemJS module that will expose them.

NOTE: many users have experienced trouble using this library in Visual Studio. For all intents and purposes you should consider Visual Studio to be unsupported by this library. None of the maintainers have access to it. We recommend Visual Studio Code.

SystemJS Plugin

systemjs-plugin-dojo is a SystemJS plugin for loading Dojo modules that works with the ArcGIS API for JavaScript. ng2-esri-demo shows how to use that plugin to load ArcGIS modules in an Angular application.

This library (esri-system-js) predates the above SystemJS plugin, but is not a SystemJS plugin, and therefore requires you to perform the additional configuration steps shown below.

Quick Start

For example, if you wanted to use ArcGIS API for JavaScript modules in your TypeScript code in an Angular 2 application.

1. Install:

npm install esri-system-js@beta --save

2. Include (in index.html):

<!-- load SystemJS library -->
<script src="node_modules/systemjs/dist/system.src.js"></script>

<!-- load Esri library -->
<link rel="stylesheet" href="//js.arcgis.com/4.0/esri/css/main.css">
<script src="//js.arcgis.com/4.0/"></script>

<!-- load esri-system-js library -->
<script src="node_modules/esri-system-js/dist/esriSystem.js"></script>

3. Configure (in index.html):

<script>
// configure system.js
System.config({
  packages: {
    app: {
      defaultExtension: 'js'
    }
  }
});

// load esri modules needed by this application
// and then regsiter each as it's own SystemJS module
esriSystem.register(
  // array of Esri module names to load and then register with SystemJS
  [
    'esri/Map',
    'esri/views/MapView',
    'esri/widgets/Home/HomeViewModel',
    'esri/request'
  ],

  // optional callback function
  function() {
    // then bootstrap application
    System.import('app/boot')
      .then(null, console.error.bind(console));
  });
</script>

4. Import modules (in app/boot.ts or any other application module):

import Map from 'esri/Map';
import MapView from 'esri/views/MapView';
import esriRequest from 'esri/request';

If your project requires you to configure SystemJS with defaultJSExtensions: true, see this issue for additional configuration steps.

Using esri-system-js in TypeScript Applications

If you're writing your application code in TypeScript, you can now get type checking and intellisense for the above modules by downloading and using the ArcGIS API for JavaScript type definitions. Note that you will need to configure the TypeScript compiler to use "allowSyntheticDefaultImports": true.

Registering as a Single Module

You can supply a third, optional argument to esriSystem.register() with options to register all the required Esri modules to a single new module. Note that registering all modules as a single SystemJS module will not work with the ArcGIS API for JavaScript type definitions).

// load esri modules needed by this application
// and then regsiter a new SystemJS module that exposes them
esriSystem.register(
  // array of Esri module names to load and then register with SystemJS
  [
    'esri/Map',
    'esri/views/MapView',
    'esri/widgets/Home/HomeViewModel',
    'esri/request'
  ],

  // optional callback function
  function() {
    // then bootstrap application
    System.import('app/boot')
      .then(null, console.error.bind(console));
  },
  // options to register a new, single SystemJS module
  {
    // name of SystemJS module that you will import from
    outModuleName: 'esri-mods',
    // by default each module will use everything after the last '/' in their name
    // however you can override that for specific modules here
    moduleNameOverrides: {
      'esri/request': 'esriRequest'
    }
  });
</script>

Now you can import these modules as follows:

import { Map, MapView, esriRequest } from 'esri-mods';

Why?

The ArcGIS API for JavaScript is based on Dojo, which uses AMD modules, and SystemJS can load AMD modules, so why is this needed? We've not been able to figure out a way to have SystemJS load Esri's modules directly. As with other loaders that support AMD, the issue is around plugins. You can see a summary of the issue here.

Example Applications

See these applications for examples of how to use this library:

• jwasilgeo/angular2-esri-playground - Angular 2 & Esri 4 View it live
• Josh Wert's blog post on ESRI Javascript API 4 with Angular 2 and Typescript - includes Jasmine/Karma test configuration View it live
• "Angular 2 + Esri 3 + Dojo Plugin" - Angular 2 with Esri JSAPI v3, demonstrating how to incorporate an external Dojo package/plugin for point layer clustering with esri-system-js. View it live on plnkr. (This demo originated from issue #9.)
• Angular and Esri JavaScript API - Startup project for ArcGIS API for JavaScript V3, Angular and Material Design

Have you built an application using esri-system-js? Let us know and we'll add it here.

Development Instructions

Make sure you have Node installed.

1. Fork and clone this repo
2. cd into the esri-system-js folder
3. Install the dependencies with npm install
4. run npm start from the command line. This will run the TypeScript compiler then start a local web server hosting the application under the docs folder
5. Modify the source files (under src)
6. Make a pull request to contribute your changes

Credit

This pattern was established by @odoe in the load.js file of his example of using ErsiJS 4.0 view models with Angular 2.

Later, @nickcam came up with the idea to register one SystemJS module for each Esri module required and maintain the exact same module names, which makes it possible to use the ArcGIS API for JavaScript type definitions for the modules you import.

Resources

• ArcGIS API for JavaScript
• SystemJS
• TypeScript
• Angular 2

Issues

Find a bug or want to request a new feature? Please let us know by submitting an issue. Thank you!

Contributing

Anyone and everyone is welcome to contribute. Please see our guidelines for contributing.

Licensing

Copyright 2016 Esri

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

A copy of the license is available in the repository's license.txt file.

[](Esri Tags: ArcGIS Esri SystemJS TypeScript) [](Esri Language: JavsScript)