{"id":18223066,"url":"https://github.com/esri/ember-esri-loader","last_synced_at":"2025-04-03T04:30:33.384Z","repository":{"id":19162709,"uuid":"84780928","full_name":"Esri/ember-esri-loader","owner":"Esri","description":"An Ember addon to allow lazy loading the ArcGIS API for JavaScript in Ember applications","archived":false,"fork":false,"pushed_at":"2023-07-19T06:48:04.000Z","size":2355,"stargazers_count":11,"open_issues_count":21,"forks_count":6,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-03-18T09:04:51.448Z","etag":null,"topics":["arcgis-api","ember","ember-addon","ember-cli","esri-loader","javascript","module-loader","web-development"],"latest_commit_sha":null,"homepage":"http://ember-esri-loader.surge.sh/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Esri.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-03-13T03:38:39.000Z","updated_at":"2024-05-30T03:15:05.000Z","dependencies_parsed_at":"2022-09-04T07:40:41.727Z","dependency_job_id":null,"html_url":"https://github.com/Esri/ember-esri-loader","commit_stats":null,"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Esri%2Fember-esri-loader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Esri%2Fember-esri-loader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Esri%2Fember-esri-loader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Esri%2Fember-esri-loader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Esri","download_url":"https://codeload.github.com/Esri/ember-esri-loader/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246938914,"owners_count":20857916,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arcgis-api","ember","ember-addon","ember-cli","esri-loader","javascript","module-loader","web-development"],"created_at":"2024-11-04T00:03:57.692Z","updated_at":"2025-04-03T04:30:33.027Z","avatar_url":"https://github.com/Esri.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# ember-esri-loader\n\nAn [Ember addon](https://ember-cli.com/extending/) that wraps the [esri-loader](https://github.com/Esri/esri-loader) library to allow lazy loading and preloading the [ArcGIS API for JavaScript](https://developers.arcgis.com/javascript/) in Ember applications.\n\n![An example of preloading the ArcGIS API](/preload-jsapi-in-ember.gif)\n\n[View it live](http://ember-esri-loader.surge.sh/).\n\nSee the [esri-loader README](https://github.com/Esri/esri-loader#why-is-this-needed) for more information on why this is needed.\n\n\nCompatibility\n------------------------------------------------------------------------------\n\n* Ember.js v3.20 or above\n* Ember CLI v3.20 or above\n* Node.js v12 or above\n\n\nInstallation\n------------------------------------------------------------------------------\n\n\nIn your app's root folder run:\n\n```shell\nnpm install esri-loader\nember install ember-esri-loader\n```\n\n## Usage\n\n### Loading Modules from the ArcGIS API for JavaScript\n\nHere's an example of how you could load and use the latest 4.x `MapView` and `WebMap` classes in a component to create a map:\n\n```js\n// app/components/esri-map.js\nexport default Ember.Component.extend({\n  layout,\n  esriLoader: Ember.inject.service('esri-loader'),\n\n  // once we have a DOM node to attach the map to...\n  didInsertElement () {\n    this._super(...arguments);\n    // load the map modules\n    this.get('esriLoader').loadModules(['esri/views/MapView', 'esri/WebMap']).then(modules =\u003e {\n      if (this.get('isDestroyed') || this.get('isDestroying')) {\n        return;\n      }\n      const [MapView, WebMap] = modules;\n      // load the webmap from a portal item\n      const webmap = new WebMap({\n        portalItem: { // autocasts as new PortalItem()\n          id: this.itemId\n        }\n      });\n      // Set the WebMap instance to the map property in a MapView.\n      this._view = new MapView({\n        map: webmap,\n        container: this.elementId\n      });\n    });\n  },\n\n  // destroy the map view before this component is removed from the DOM\n  willDestroyElement () {\n    if (this._view) {\n      this._view.container = null;\n      delete this._view;\n    }\n  }\n});\n```\n\nSee the [esri-loader documentation on loading modules](https://github.com/Esri/esri-loader#loading-modules-from-the-arcgis-api-for-javascript) for more details.\n\n### Loading Styles\n\nBefore you can use the ArcGIS API in your app, you'll need to load the styles. See the [esri-loader documentation on loading styles](https://github.com/Esri/esri-loader#loading-styles) for more details.\n\n#### Lazy Loading the ArcGIS API for JavaScript\n\nThe above code will lazy load the ArcGIS API for JavaScript the first time `loadModules()` is called. This means users of your application won't need to wait for the ArcGIS API to download until it is need.\n\n### Pre-loading the ArcGIS API for JavaScript\n\nAlternatively, 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 template rendering. You can add the following to the application route:\n\n```js\nimport { inject as service } from '@ember/service';\nimport Route from '@ember/routing/route';\n\nexport default class ApplicationRoute extends Route {\n  @service esriLoader\n\n  beforeModel() {\n    // Preload the JS \u0026 CSS for the latest (4.x) version of the JSAPI\n    this.esriLoader.loadScript({ css: true })\n      .catch(err =\u003e {\n        // TODO: better way of showing error\n        window.alert(err.message || err);\n      });\n  }\n\n}\n```\n\nNow you can use `loadModules()` in components to [create maps](https://github.com/Esri/ember-esri-loader/blob/master/tests/dummy/app/components/web-map.js) or [3D scenes](https://github.com/Esri/ember-esri-loader/blob/master/tests/dummy/app/components/scene-view.js). Also, if you need to, you can [use `isLoaded()` anywhere in your application to find out whether or not the ArcGIS API has finished loading](https://github.com/Esri/ember-esri-loader/blob/master/tests/dummy/app/controllers/application.js).\n\n### esri-module-cache mixin\n\nThis addon also includes a mixin that can be help mitigate one of the primary pain points of using esri-loader: accessing modules is always asynchronous. That's fine for modules like `esri/map` where you expect to be using them in an asynchronous operation (like creating a map). However, it can be cumbersome when you just need something like a `new Graphic()` to add to that map.\n\nServices or components that implement the `esri-module-cache` mixin can load all the modules they may need up front during an async operation (such as creating a map), and then use the mixin's `cacheModules()` function to store references to any of those modules so they don't have to be loaded again. Later the `getCachedModule()` and `newClassInstance()` functions can be used to synchronously access and use the modules that have already been loaded. For example:\n\n```js\n// map-service.js\nimport Service, { inject as service } from '@ember/service';\nimport EsriModuleCacheMixin from 'ember-esri-loader/mixins/esri-module-cache';\n\nexport default Service.extend(EsriModuleCacheMixin, {\n  esriLoader: service('esri-loader'),\n  loadMap (elemendId, options) {\n    return thigs.get('esriLoader').loadModules([\n      'esri/map',\n      'esri/Graphic'\n    ]).then(([Map, Graphic]) =\u003e {\n      // cache graphic module later for synchronous use\n      this.cacheModules({ Graphic });\n      // create and return the map instance\n      return new Map(elementId, options);\n    });\n  },\n  // NOTE: this will throw an error if it is called before loadMap()\n  newGraphic (...args) {\n    return this.newClassInstance('Graphic', ...args);\n  }\n});\n```\n\n```js\n// my-map/component.js\nexport default Component.extend({\n  layout,\n  mapService: service(),\n\n  // once we have a DOM node to attach the map to...\n  didInsertElement () {\n    this._super(...arguments);\n    // load the map\n    this.get('mapService').loadMap(this.elementId, { basemap: 'gray' })\n    .then(map =\u003e {\n      this.map = map;\n    })\n  },\n  actions: {\n    addGraphic (x, y) {\n      if (!this.map) {\n        // can't call newGraphic() unles map has loaded\n        // also no point in creating a gaphic if there's no map to add it to\n        return;\n      }\n      const graphicJson = {\n        geometry: {\n          x,\n          y,\n          spatialReference: {\n            wkid: 4326\n          }\n        },\n        symbol: {\n          color: [255, 0, 0, 128],\n          size: 12,\n          angle: 0,\n          xoffset: 0,\n          yoffset: 0,\n          type: 'esriSMS',\n          style: 'esriSMSSquare',\n          outline: {\n            color: [0, 0, 0, 255],\n            width: 1,\n            type: 'esriSLS',\n            style: 'esriSLSSolid'\n          }\n        }\n      };\n      const graphic =\n      this.get('mapService').newGraphic(graphicJson);\n      this.map.graphics.add(graphic);\n    }\n  }\n```\n\n### Configuration\n\n#### Options\n\n* additionalFiles: _list of strings or RegExp objects, defaults to []_.  Identifies additional files in which we should replace `require` and `define`.  This can be particularly helpful if also using ember-auto-import 2.x, which places its modules in separate js files and attempts to capture the `require` and `define` the app is using.  The configuration example above shows how to support ember-auto-import 2.x with the default webpack configuration, but you can add additional globs as necessary.\n\n#### Using with ember-auto-import\n\nIf you are using [ember-auto-import](https://github.com/ef4/ember-auto-import) you will have to [configure ember-auto-import](https://github.com/ef4/ember-auto-import#customizing-build-behavior) to `exclude` any imports from esri-loader. Furthermore, if you are using ember-auto-import v2.x you will need to [configure ember-esri-loader](#options) to process the ember-auto-import output using `additionalFiles`. To do so, add the following options in your ember-cli-build.js file:\n\n```\n// ember-cli-build.js\n\nlet app = new EmberApp(defaults, {\n  autoImport: {\n    // ember-esri-loader loads esri-loader with a script tag to prevent it from being rewritten to replace \"require\"\n    // and \"define\" in the build pipeline.  We need to exclude it from ember-auto-import so that we don't pull it\n    // back into the build pipeline when we import it ourselves.\n    exclude: [ 'esri-loader' ],\n  }\n  'ember-esri-loader': {\n    // this is only needed for ember-auto-import 2.x\n    additionalFiles: [ /chunk\\.app\\..*\\.js/ ],\n  }\n}\n```\n\n## How It Works\n\nThis addon is an implementation of the [\"Dedicated Loader Module\" pattern](http://tomwayson.com/2016/11/27/using-the-arcgis-api-for-javascript-in-applications-built-with-webpack/) for [Ember](http://emberjs.com/). It is a mashup of the ideas from [angular2-esri-loader](https://github.com/tomwayson/angular2-esri-loader) and [ember-cli-amd](https://github.com/Esri/ember-cli-amd). Like angular2-esri-loader, it creates a service that exposes functions that wrap calls to the [esri-loader](https://github.com/tomwayson/esri-loader) library to load the ArcGIS API and it's modules in promises. However, in order to avoid global namespace collisions with [loader.js](https://github.com/ember-cli/loader.js)'s `require()` and `define()` this addon also has to \u003cdel\u003esteal\u003c/del\u003e borrow from ember-cli-amd the code that finds and replaces those terms with their pig-latin counterparts in the build output. However unlike ember-cli-amd, it does **not** inject the ArcGIS for JavaScript in the page, nor does it use the ArcGIS API's Dojo loader to load the entire app.\n\n### Limitations\n\nYou cannot use ES2015 module syntax for ArcGIS API modules (i.e. `import Map from 'esri/map';`) with this addon. If you do not feel that your application would benefit from lazy-loading\nthe ArcGIS API, and you'd prefer the cleaner abstraction of being able to use\n`import` statements, you can use [ember-cli-amd](https://emberobserver.com/addons/ember-cli-amd).\n\nUsing this addon to load ArcGIS API for JavaScript v4.x modules in tests run in PhantomJS [may cause global errors](https://github.com/Esri/ember-esri-loader/pull/28#issue-253837905). Those errors did not happen when running the same tests in Chrome or FireFox.\n\nAlso, this addon cannot be used in an [Ember twiddle](https://ember-twiddle.com/).\n\n## Examples\n\nIn addition to ArcGIS Online applications such as [ArcGIS Hub](https://hub.arcgis.com/), the following open source applications use this addon:\n\n[MyStreet](https://github.com/Esri/MyStreet) - A municipality viewer that allows users to input an address and receive information based on that location uses this addon to lazy load v3.x of the ArcGIS API only when an app uses a map.\n\nThe [dummy application for this addon](http://ember-esri-loader.surge.sh/) demonstrates how to pre-load v4.x of the ArcGIS API.\n\n## Development Instructions\n\n### Fork, Clone, and Install\n\n* fork and clone the repository\n* `cd ember-esri-loader`\n* `npm install`\n\n\n### Linting\n\n* `npm run lint:hbs`\n* `npm run lint:js`\n* `npm run lint:js -- --fix`\n\n\n### Running Tests\n\n* `ember test` – Runs the test suite on the current Ember version\n* `ember test --server` – Runs the test suite in \"watch mode\"\n* `ember try:each` – Runs the test suite against multiple Ember versions\n\n### Building\n\n* `ember serve`\n* Visit the dummy application at [http://localhost:4200](http://localhost:4200).\n\n\n## Issues\n\nFind a bug or want to request a new feature?  Please let us know by [submitting an issue](https://github.com/Esri/ember-esri-loader/issues/).\n\n## Contributing\n\nEsri welcomes contributions from anyone and everyone. Please see our [guidelines for contributing](https://github.com/esri/contributing).\n\n## Licensing\nCopyright 2017 Esri\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n   http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n\nA copy of the license is available in the repository's [license.txt]( ./license.txt) file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fesri%2Fember-esri-loader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fesri%2Fember-esri-loader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fesri%2Fember-esri-loader/lists"}