From 82c7110b8e48bfcbc7d849eae986f67ce69c2fcb Mon Sep 17 00:00:00 2001 From: Andy G Date: Thu, 10 Nov 2022 13:31:07 -0700 Subject: [PATCH] Updates for 4.25 --- CHANGELOG.md | 6 ++ README.md | 170 +++++++----------------------------------- archived-examples.md | 110 +++++++++++++++++++++++++++ src/esri-loader.ts | 2 +- src/modules.ts | 2 +- src/script.test.ts | 8 +- src/script.ts | 2 +- src/utils/css.test.ts | 10 +-- src/utils/css.ts | 2 +- src/utils/index.ts | 2 +- src/utils/url.test.ts | 8 +- src/utils/url.ts | 8 +- 12 files changed, 165 insertions(+), 165 deletions(-) create mode 100644 archived-examples.md diff --git a/CHANGELOG.md b/CHANGELOG.md index bdec3fd..32e7f58 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,12 @@ This project adheres to [Semantic Versioning](http://semver.org/). ### Removed ### Breaking +## [3.7.0] - 2022-11-10 +### Added +- default to JS API 4.25; update docs w/ latest version numbers - @andygup +- raise visibility of deprecation notice for frameworks that do not support async/await at runtime, e.g. Angular +- archive framework samples and various 3.x-related sections to archived-examples.md. Most of the samples haven't been updated` in years + ## [3.6.0] - 2022-07-07 ### Added - default to JSAPI 4.24; update docs w/ latest version numbers - @gavinr diff --git a/README.md b/README.md index d120b02..dfa884d 100644 --- a/README.md +++ b/README.md @@ -8,26 +8,21 @@ A tiny library to help you use the [ArcGIS API for JavaScript](https://developer ![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) -Ready to jump in? Follow the [Install](#install) and [Usage](#usage) instructions below to get started. Then see more in depth instructions on how to [configure esri-loader](#configuring-esri-loader) and use it with [React](#react), [Vue.js](#vuejs), [Angular](#angular), [Ember](#ember), or the [ArcGIS Types](#arcgis-types). +Ready to jump in? Follow the [Install](#install) and [Usage](#usage) instructions below to get started. Then see more in depth instructions on how to [configure esri-loader](#configuring-esri-loader). Want to learn more? Learn how esri-loader can help [improve application load performance](#lazy-loading-the-arcgis-api-for-javascript) and allow you to [use the ArcGIS API in server side rendered applications](#server-side-rendering). -Want to be inspired? See the [Examples](#examples) section below for links to applications that use this library in over a dozen different frameworks. +Looking for legacy examples from a variety of frameworks, or 3.x information? Visit the [archive](archived-examples.md) page. ## Table of Contents - + d +- [Known Limitations](#known-limitations) - [Install](#install) - [Usage](#usage) - [Loading Modules from the ArcGIS API for JavaScript](#loading-modules-from-the-arcgis-api-for-javascript) - [Lazy Loading the ArcGIS API for JavaScript](#lazy-loading-the-arcgis-api-for-javascript) - [Loading Styles](#loading-styles) - [Do I need esri-loader?](#do-i-need-esri-loader) -- [Known Limitations](#known-limitations) -- [Examples](#examples) - - [Angular](#angular) - - [Ember](#ember) - - [React](#react) - - [Vue.js](#vuejs) - [Advanced Usage](#advanced-usage) - [ArcGIS Types](#arcgis-types) - [esri-loader-typings-helper Plugin](#esri-loader-typings-helper-plugin) @@ -53,6 +48,10 @@ Want to be inspired? See the [Examples](#examples) section below for links to ap - [Contributing](#contributing) - [Licensing](#licensing) +## Known Limitations + +- Compatibility with implementations that don't support [async/await](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Asynchronous/Promises#async_and_await) at runtime, within AMD modules, is deprecated at version 4.25 (November 2022) - this means the functionality will be removed in a future release. In particular, this affects Angular applications using esri-loader because of [well-known limitations in Zone.js](https://angular.io/guide/roadmap#improve-runtime-performance-and-make-zonejs-optional). Angular users will need to migrate from AMD modules to using [@arcgis/core ES modules](https://developers.arcgis.com/javascript/latest/es-modules/) in order to continue using the latest release of the API. Refer to the [APIs FAQ](https://developers.arcgis.com/javascript/latest/faq/#how-are-breaking-changes-managed) for more information on breaking changes. + ## Install ```bash @@ -67,7 +66,7 @@ yarn add esri-loader ## Usage -The code snippets below show how to load the ArcGIS API and its modules and then 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 examples that are specific to [React](#react), [Vue.js](#vuejs), [Angular](#angular), [Ember](#ember), and [example applications](#examples) written in over a dozen frameworks. +The code snippets below show how to load the ArcGIS API and its modules and then use them to create a map. Where you would place similar code in your application will depend on which application framework you are using. ### Loading Modules from the ArcGIS API for JavaScript @@ -83,13 +82,13 @@ import { loadModules } from 'esri-loader'; loadModules(['esri/views/MapView', 'esri/WebMap']) .then(([MapView, WebMap]) => { // then we load a web map from an id - var webmap = new WebMap({ + const webmap = new WebMap({ portalItem: { // autocasts as new PortalItem() id: 'f2e9b762544945f390ca4ac3671cfa72' } }); // and we show that map in a container w/ id #viewDiv - var view = new MapView({ + const view = new MapView({ map: webmap, container: 'viewDiv' }); @@ -104,18 +103,16 @@ loadModules(['esri/views/MapView', 'esri/WebMap']) By default esri-loader will load modules from the [latest 4.x release of the API from the CDN](https://developers.arcgis.com/javascript/latest/guide/get-api/#cdn), but you can [configure the default behavior](#configuring-esri-loader) by calling `setDefaultOptions()` once _before_ making any calls to `loadModules()`. -For example, the snippet below configures esri-loader to use the [latest 3.x release of the API from the CDN](https://developers.arcgis.com/javascript/3/jshelp/intro_accessapi.html#cdn) by setting the default `version` option during application start up. - ```js // app.js import { setDefaultOptions } from 'esri-loader'; -// configure esri-loader to use version 3.41 from the ArcGIS CDN +// configure esri-loader to use version 4.24 from the ArcGIS CDN // NOTE: make sure this is called once before any calls to loadModules() -setDefaultOptions({ version: '3.41' }) +setDefaultOptions({ version: '4.24' }) ``` -Then later, for example after a map component has mounted, you would use `loadModules()` as normal, except in this case you'd be using the [3.x `Map` class](https://developers.arcgis.com/javascript/3/jsapi/map-amd.html) instead of the 4.x classes. +Then later, for example after a map component has mounted, you would use `loadModules()` as normal. ```js // component.js @@ -196,10 +193,10 @@ import { loadCss } from 'esri-loader'; loadCss(); // or for a specific CDN version -loadCss('3.41'); +loadCss('4.25'); // or a from specific URL, like a locally hosted version -loadCss('http://server/path/to/esri/css/main.css'); +loadCss('http://server/version/esri/themes/light/main.css'); ``` See below for information on how to [override ArcGIS styles](#overriding-arcgis-styles) that you've lazy loaded with `loadModules()` or `loadCss()`. @@ -217,126 +214,27 @@ It is recommended to try installing [@arcgis/core](https://www.npmjs.com/package esri-loader provides a convenient way to lazy load the API in any application, and it has been the most versatile way to integrate the ArcGIS API for JavaScript with other frameworks and their tools since it works in applications that: - are built with _any_ loader/bundler, such as [webpack](https://webpack.js.org/), [rollup.js](https://rollupjs.org/), or [Parcel](https://parceljs.org) - use framework tools that discourage or prevent you from manually editing their configuration -- use either version [4.x](https://developers.arcgis.com/javascript/) _or_ [3.x](https://developers.arcgis.com/javascript/3/) of the ArcGIS API for JavaScript - make very limited use of the ArcGIS API and don't want to incur the cost of including it in their build Most developers will prefer the convenience and native interoperability of being able to `import` modules from `@arcgis/core` directly, especially if their application makes extensive use of the ArcGIS API. However, if `@arcgis/core` doesn't work in your application for whatever reason, esri-loader probably will. Learn more about [which is the right solution for your application](https://developers.arcgis.com/javascript/latest/guide/tooling-intro/). -## Known Limitations - -- Compatibility with implementations that don't support [async/await](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Asynchronous/Promises#async_and_await) at runtime, within AMD modules, will be deprecated at version 4.25. In particular, Angular applications using esri-loader will need to migrate from AMD modules to using [@arcgis/core ES modules](https://developers.arcgis.com/javascript/latest/es-modules/). Refer to the [APIs FAQ](https://developers.arcgis.com/javascript/latest/faq/#how-are-breaking-changes-managed) for more information on breaking changes. - -## Examples - -Here are some applications and framework-specific wrapper libraries that use this library. We don't guarantee that these examples are current, so check the version of esri-loader and their commit history before using them as a reference. They are presented by framework in alphabetical order - not picking any favorites here :stuck_out_tongue_winking_eye:: - -### [Angular](https://angular.io/) - -#### Reusable libraries for Angular - -- [angular-esri-components](https://github.com/TheKeithStewart/angular-esri-components) - A set of Angular components to work with ArcGIS API for JavaScript v4.3 - -#### Example Angular applications - -- [angular-cli-esri-map](https://github.com/Esri/angular-cli-esri-map) - Example of how to build a simple mapping component using Angular CLI. - -### [CanJS](https://canjs.com/) - -- [can-arcgis](https://github.com/roemhildtg/can-arcgis) - CanJS configurable mapping app (inspired by [cmv-app](https://github.com/cmv/cmv-app)) and components built for the ArcGIS JS API 4.x, bundled with [StealJS](https://stealjs.com/) - -### [Choo](https://choo.io/) - -- [esri-choo-example](https://github.com/jwasilgeo/esri-choo-example) - An example Choo application that shows how to use esri-loader to create a custom map view. - -### [Dojo 2+](https://dojo.io) - -- [dojo-esri-loader](https://github.com/odoe/dojo-esri-loader) - Dojo 5 app with esri-loader ([blog post](https://odoe.net/blog/dojo-framework-with-arcgis-api-for-javascript/)) - -- [esri-dojo](https://github.com/jamesmilneruk/esri-dojo) - An example of how to use Esri Loader with Dojo 2+. This example is a simple map that allows you to place markers on it. - -### [Electron](https://electron.atom.io/) - -- [ng-cli-electron-esri](https://github.com/TheKeithStewart/ng-cli-electron-esri) - This project is meant to demonstrate how to run a mapping application using the ArcGIS API for JavaScript inside of Electron - -#### Reusable libraries for Ember - -- [ember-esri-loader](https://github.com/Esri/ember-esri-loader) - An Ember addon that wraps this library - -#### Example Ember applications - -See the [examples over at ember-esri-loader](https://github.com/Esri/ember-esri-loader/#examples) - -### [Glimmer.js](https://glimmerjs.com/) - -- [esri-glimmer-example](https://github.com/tomwayson/esri-glimmer-example) - An example of how to use the ArcGIS API for JavaScript in a https://glimmerjs.com/ application - -### [Hyperapp](https://hyperapp.js.org/) - -- [esri-hyperapp-example](https://github.com/jwasilgeo/esri-hyperapp-example) - An example Hyperapp application that shows how to use esri-loader to create a custom map view and component. - -### [Preact](https://github.com/developit/preact) - -- [esri-preact-pwa](https://github.com/tomwayson/esri-preact-pwa) - An example progressive web app (PWA) using the ArcGIS API for JavaScript built with Preact - -#### Reusable libraries for React - -- [esri-loader-hooks](https://github.com/tomwayson/esri-loader-hooks) - Custom React hooks for using the ArcGIS API for JavaScript with esri-loader -- [react-arcgis](https://github.com/Esri/react-arcgis) - A few components to help you get started using esri-loader with React -- [esri-loader-react](https://github.com/davetimmins/esri-loader-react) - A React component wrapper around esri-loader ([blog post](https://davetimmins.github.io/2017/07/19/esri-loader-react/)) -- [arcgis-react-redux-legend](https://github.com/davetimmins/arcgis-react-redux-legend) - Legend control for ArcGIS JS v4 using React and Redux - -#### Example React applications -- [create-arcgis-app](https://github.com/tomwayson/create-arcgis-app/) - An example of how to use the ArcGIS platform in an application created with Create React App and React Router. -- [next-arcgis-app](https://github.com/tomwayson/next-arcgis-app/) - An example of how to use the ArcGIS platform in an application built with Next.js -- [esri-loader-react-starter-kit](https://github.com/tomwayson/esri-loader-react-starter-kit) - A fork of the [react-starter-kit](https://github.com/kriasoft/react-starter-kit) showing how to use esri-loader in an isomorphic/universal React application -- [create-react-app-esri-loader](https://github.com/davetimmins/create-react-app-esri-loader/) - An example create-react-app application that uses [esri-loader-react](https://github.com/davetimmins/esri-loader-react) to load the ArcGIS API -- [React-Typescript-App-with-ArcGIS-JSAPI](https://github.com/guzhongren/React-Typescript-App-with-ArcGIS-JSAPI) - An example create-react-app application that uses [esri-loader](https://github.com/Esri/esri-loader), [esri-loader-react](https://github.com/davetimmins/esri-loader-react), [Typescript](https://www.typescriptlang.org/), [Webpack3](https://webpack.js.org/) to create MapView - -### [Riot](https://riot.js.org/) - -- [esri-riot-example](https://github.com/jwasilgeo/esri-riot-example) - An example Riot application that shows how to use esri-loader to create a custom `` component. - -### [Stencil](https://stenciljs.com/) - -- [esri-stencil-example](https://github.com/Dzeneralen/esri-stencil-example) - An example Stencil application that shows how to use esri-loader to create a custom map view component and implement some basic routing controlling the map state - -### [Svelte](https://svelte.dev/) - -- [esri-svelte-example](https://github.com/gavinr/esri-svelte-example) - An example Svelte application that shows how to use esri-loader to load a map. -- [esri-svelte-basemaps-example](https://github.com/jwasilgeo/esri-svelte-basemaps-example) - An example Svelte application that shows how to use esri-loader to create a custom `` component and explore various basemaps. - -### [Vue.js](https://vuejs.org/) - -- [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 -- [vue-jsapi4](https://github.com/odoe/vue-jsapi4) - An example of how to use the [ArcGIS API for Javascript](https://developers.arcgis.com/javascript/) in a [NUXT](https://nuxtjs.org/) application ([blog post](https://odoe.net/blog/arcgis-api-4-for-js-with-vue-cli-and-nuxt/), [video](https://youtu.be/hqJzzgM8seo)) -- [esri-vue-cli-example](https://github.com/tomwayson/esri-vue-cli-example) - An example of how to use the [ArcGIS API for JavaScript 3.x](https://developers.arcgis.com/javascript/3/) in a [vue-cli](https://github.com/vuejs/vue-cli) application - ## Advanced Usage ### ArcGIS TypeScript Types This library doesn't make any assumptions about which version of the ArcGIS API for JavaScript you are using, so you will have to install the appropriate types. Furthermore, because you don't `import` esri modules directly with esri-loader, you'll have to follow the instructions below to use the types in your application. -#### 4.x Types - Follow [these instructions](https://github.com/Esri/jsapi-resources/tree/master/4.x/typescript) to install the 4.x types. After installing the 4.x types, you can use the `__esri` namespace for the types as seen in [this example](https://github.com/kgs916/angular2-esri4-components/blob/68861b286fd3a4814c495c2bd723e336e917ced2/src/lib/esri4-map/esri4-map.component.ts#L20-L26). -#### 3.x Types - -You can use [these instructions](https://github.com/Esri/jsapi-resources/tree/master/3.x/typescript) to install the 3.x types. - -Use `import * as esri from 'esri';` to implement the types [as shown here](https://github.com/Esri/angular-cli-esri-map/issues/17#issue-360490589). - #### TypeScript import() -TypeScript 2.9 added a way to `import()` types which allows types to be imported without importing the module. For more information on import types see [this post](https://davidea.st/articles/typescript-2-9-import-types). You can use this as an alternative to the 4.x `_esri` namespace or `import * as esri from 'esri'` for 3.x. +TypeScript 2.9 added a way to `import()` types which allows types to be imported without importing the module. For more information on import types see [this post](https://davidea.st/articles/typescript-2-9-import-types). You can use this as an alternative to the 4.x `_esri` namespace. -After you've installed the [4.x](#4x-types) or [3.x](#3x-types) types as described above, you can then use TypeScript's `import()` like: +After you've installed the [4.x](#4x-types) as described above, you can then use TypeScript's `import()` like: ```ts // define a type that is an array of the 4.x types you are using @@ -347,20 +245,6 @@ const [WebMap, MapView] = await (loadModules(["esri/WebMap", "esri/views/MapView const webmap = new WebMap({portalItem: {id: this.webmapid}}); ``` -A more complete 4.x sample can be [seen here](https://codesandbox.io/s/xv8mw2890w?fontsize=14&module=%2Fsrc%2Fmapping.ts). - -This also works with the 3.x types: - -```ts -// define a type that is an array of the 3.x types you are using -// and indicate that loadModules() will resolve with that type -type MapModules = [typeof import("esri/map"), typeof import("esri/geometry/Extent")]; -const [Map, Extent] = await (loadModules(["esri/map", "esri/geometry/Extent"]) as Promise); -// the returned objects now have type -let map = new Map("viewDiv"... -``` -A more complete 3.x sample can be [seen here](https://codesandbox.io/s/rj6jloy4nm?fontsize=14&module=%2Fsrc%2Fmapping.ts). - #### Types in Angular CLI Applications For Angular CLI applications, you will also need to add "arcgis-js-api" to `compilerOptions.types` in src/tsconfig.app.json and src/tsconfig.spec.json [as shown here](https://gist.github.com/tomwayson/e6260adfd56c2529313936528b8adacd#adding-the-arcgis-api-for-javascript-types). @@ -385,7 +269,7 @@ As mentioned above, you can call `setDefaultOptions()` to configure [how esri-lo | Name | Type | Default Value | Description | | ----------------- | --------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `version` | `string` | `'4.24'` | The version of the ArcGIS API hosted on Esri's CDN to use. | +| `version` | `string` | `'4.25'` | The version of the ArcGIS API hosted on Esri's CDN to use. | | `url` | `string` | `undefined` | The URL to a hosted build of the ArcGIS API to use. If both `version` and `url` are passed, `url` will be used. | | `css` | `string` or `boolean` | `undefined` | If a `string` is passed it is assumed to be the URL of a CSS file to load. Use `css: true` to load the `version`'s CSS from the CDN. | | `insertCssBefore` | `string` | `undefined` | When using `css`, the `` to the stylesheet will be inserted before the first element that matches this [CSS Selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors). See [Overriding ArcGIS Styles](#overriding-arcgis-styles). | @@ -399,14 +283,14 @@ If your application only has a single call to `loadModules()`, you do not need ` ```js import { loadModules } from 'esri-loader'; -// configure esri-loader to use version 3.41 +// configure esri-loader to use version 4.25 // and the CSS for that version from the ArcGIS CDN -const options = { version: '3.41', css: true }; +const options = { version: '4.25', css: true }; loadModules(['esri/map'], options) .then(([Map]) => { // create map with the given options at a DOM node w/ id 'mapNode' - let map = new Map('mapNode', { + const map = new Map('mapNode', { center: [-118, 34.5], zoom: 8, basemap: 'dark-gray' @@ -462,7 +346,7 @@ const options = { }; // before loading the modules, this will call: -// loadCss('https://js.arcgis.com/4.12/themes/light/main.css', 'style') +// loadCss('https://js.arcgis.com/4.25/themes/light/main.css', 'style') loadModules(['esri/views/MapView', 'esri/WebMap'], options); ``` @@ -496,7 +380,7 @@ It is possible to use this library only to load modules (i.e. not to lazy load o ```html - + ``` ### Without a module bundler @@ -625,13 +509,13 @@ The angular-esri-loader wrapper library is no longer needed and has been depreca ### Browsers -This library doesn't have any external dependencies, but the functions it exposes to load the ArcGIS API and its modules expect to be run in a browser. This library officially supports [the same browsers that are supported by the latest version of the ArcGIS API for JavaScript](https://developers.arcgis.com/javascript/latest/guide/system-requirements/index.html#supported-browsers). Since this library also works with [v3.x of the ArcGIS API](https://developers.arcgis.com/javascript/3/), the community [has made some effort](https://github.com/Esri/esri-loader/pull/67) to get it to work with [some of the older browsers supported by 3.x](https://developers.arcgis.com/javascript/3/jshelp/supported_browsers.html) like IE < 11. +This library doesn't have any external dependencies, but the functions it exposes to load the ArcGIS API and its modules expect to be run in a browser. This library officially supports [the same browsers that are supported by the latest version of the ArcGIS API for JavaScript](https://developers.arcgis.com/javascript/latest/guide/system-requirements/index.html#supported-browsers). -You cannot run the ArcGIS API for JavaScript in [Node.js](https://nodejs.org/), but you _can_ use this library in [server side rendered applications](#server-side-rendering) as well as [Electron](#electron). If you need to execute requests to ArcGIS REST services from something like a Node.js CLI application, see [arcgis-rest-js](https://github.com/Esri/arcgis-rest-js). +You cannot use this helper library in [Node.js](https://nodejs.org/), but you _can_ use this library in [server side rendered applications](#server-side-rendering) as well as [Electron](#electron). If you need to execute requests to ArcGIS REST services from something like a Node.js CLI application, see [ArcGIS Rest JS](https://developers.arcgis.com/arcgis-rest-js/). ### Promises -Since v1.5 asynchronous functions like `loadModules()` and `loadScript()` return [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)s, so if your application has to support [browsers that don't support Promise (i.e. IE)](https://caniuse.com/#search=promise) you have a few options. +The asynchronous functions like `loadModules()` and `loadScript()` return [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)s, so if your application has to support [browsers 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. diff --git a/archived-examples.md b/archived-examples.md new file mode 100644 index 0000000..46e12b1 --- /dev/null +++ b/archived-examples.md @@ -0,0 +1,110 @@ +### 3.x Types + +You can use these instructions in the [Legacy samples for ArcGIS JSAPI Resources](https://github.com/Esri/jsapi-resources/releases/tag/legacy) to install the 3.x types. Follow the instructions outlined in the `/3.x/typescript` directory. + +Use `import * as esri from 'esri';` to implement the types [as shown here](https://github.com/Esri/angular-cli-esri-map/issues/17#issue-360490589). + +```ts +// define a type that is an array of the 3.x types you are using +// and indicate that loadModules() will resolve with that type +type MapModules = [typeof import("esri/map"), typeof import("esri/geometry/Extent")]; +const [Map, Extent] = await (loadModules(["esri/map", "esri/geometry/Extent"]) as Promise); +// the returned objects now have type +let map = new Map("viewDiv"... +``` + +A more complete 3.x sample can be [seen here](https://codesandbox.io/s/rj6jloy4nm?fontsize=14&module=%2Fsrc%2Fmapping.ts). + +### 4.x Types + +A more complete 4.x sample can be [seen here](https://codesandbox.io/s/xv8mw2890w?fontsize=14&module=%2Fsrc%2Fmapping.ts). + +### Legacy browsers + +Since this library also works with [v3.x of the ArcGIS API](https://developers.arcgis.com/javascript/3/), the community [has made some effort](https://github.com/Esri/esri-loader/pull/67) to get it to work with [some of the older browsers supported by 3.x](https://developers.arcgis.com/javascript/3/jshelp/supported_browsers.html) like IE < 11. + +### Legacy examples + +Here is an archive of some applications and framework-specific wrapper libraries that use this library. Most of these examples haven't been updated in a long time, so check the version of esri-loader and their commit history before using them as a reference. They are presented by framework in alphabetical order - not picking any favorites here :stuck_out_tongue_winking_eye:: + +### [Angular](https://angular.io/) + +#### Reusable libraries for Angular + +- [angular-esri-components](https://github.com/TheKeithStewart/angular-esri-components) - A set of Angular components to work with ArcGIS API for JavaScript v4.3 + +#### Example Angular applications + +- [angular-cli-esri-map](https://github.com/Esri/angular-cli-esri-map) - Example of how to build a simple mapping component using Angular CLI. + +### [CanJS](https://canjs.com/) + +- [can-arcgis](https://github.com/roemhildtg/can-arcgis) - CanJS configurable mapping app (inspired by [cmv-app](https://github.com/cmv/cmv-app)) and components built for the ArcGIS JS API 4.x, bundled with [StealJS](https://stealjs.com/) + +### [Choo](https://choo.io/) + +- [esri-choo-example](https://github.com/jwasilgeo/esri-choo-example) - An example Choo application that shows how to use esri-loader to create a custom map view. + +### [Dojo 2+](https://dojo.io) + +- [dojo-esri-loader](https://github.com/odoe/dojo-esri-loader) - Dojo 5 app with esri-loader ([blog post](https://odoe.net/blog/dojo-framework-with-arcgis-api-for-javascript/)) + +- [esri-dojo](https://github.com/jamesmilneruk/esri-dojo) - An example of how to use Esri Loader with Dojo 2+. This example is a simple map that allows you to place markers on it. + +### [Electron](https://electron.atom.io/) + +- [ng-cli-electron-esri](https://github.com/TheKeithStewart/ng-cli-electron-esri) - This project is meant to demonstrate how to run a mapping application using the ArcGIS API for JavaScript inside of Electron + +#### Reusable libraries for Ember + +- [ember-esri-loader](https://github.com/Esri/ember-esri-loader) - An Ember addon that wraps this library + +#### Example Ember applications + +See the [examples over at ember-esri-loader](https://github.com/Esri/ember-esri-loader/#examples) + +### [Glimmer.js](https://glimmerjs.com/) + +- [esri-glimmer-example](https://github.com/tomwayson/esri-glimmer-example) - An example of how to use the ArcGIS API for JavaScript in a https://glimmerjs.com/ application + +### [Hyperapp](https://hyperapp.js.org/) + +- [esri-hyperapp-example](https://github.com/jwasilgeo/esri-hyperapp-example) - An example Hyperapp application that shows how to use esri-loader to create a custom map view and component. + +### [Preact](https://github.com/developit/preact) + +- [esri-preact-pwa](https://github.com/tomwayson/esri-preact-pwa) - An example progressive web app (PWA) using the ArcGIS API for JavaScript built with Preact + +#### Reusable libraries for React + +- [esri-loader-hooks](https://github.com/tomwayson/esri-loader-hooks) - Custom React hooks for using the ArcGIS API for JavaScript with esri-loader +- [react-arcgis](https://github.com/Esri/react-arcgis) - A few components to help you get started using esri-loader with React +- [esri-loader-react](https://github.com/davetimmins/esri-loader-react) - A React component wrapper around esri-loader ([blog post](https://davetimmins.github.io/2017/07/19/esri-loader-react/)) +- [arcgis-react-redux-legend](https://github.com/davetimmins/arcgis-react-redux-legend) - Legend control for ArcGIS JS v4 using React and Redux + +#### Example React applications +- [create-arcgis-app](https://github.com/tomwayson/create-arcgis-app/) - An example of how to use the ArcGIS platform in an application created with Create React App and React Router. +- [next-arcgis-app](https://github.com/tomwayson/next-arcgis-app/) - An example of how to use the ArcGIS platform in an application built with Next.js +- [esri-loader-react-starter-kit](https://github.com/tomwayson/esri-loader-react-starter-kit) - A fork of the [react-starter-kit](https://github.com/kriasoft/react-starter-kit) showing how to use esri-loader in an isomorphic/universal React application +- [create-react-app-esri-loader](https://github.com/davetimmins/create-react-app-esri-loader/) - An example create-react-app application that uses [esri-loader-react](https://github.com/davetimmins/esri-loader-react) to load the ArcGIS API +- [React-Typescript-App-with-ArcGIS-JSAPI](https://github.com/guzhongren/React-Typescript-App-with-ArcGIS-JSAPI) - An example create-react-app application that uses [esri-loader](https://github.com/Esri/esri-loader), [esri-loader-react](https://github.com/davetimmins/esri-loader-react), [Typescript](https://www.typescriptlang.org/), [Webpack3](https://webpack.js.org/) to create MapView + +### [Riot](https://riot.js.org/) + +- [esri-riot-example](https://github.com/jwasilgeo/esri-riot-example) - An example Riot application that shows how to use esri-loader to create a custom `` component. + +### [Stencil](https://stenciljs.com/) + +- [esri-stencil-example](https://github.com/Dzeneralen/esri-stencil-example) - An example Stencil application that shows how to use esri-loader to create a custom map view component and implement some basic routing controlling the map state + +### [Svelte](https://svelte.dev/) + +- [esri-svelte-example](https://github.com/gavinr/esri-svelte-example) - An example Svelte application that shows how to use esri-loader to load a map. +- [esri-svelte-basemaps-example](https://github.com/jwasilgeo/esri-svelte-basemaps-example) - An example Svelte application that shows how to use esri-loader to create a custom `` component and explore various basemaps. + +### [Vue.js](https://vuejs.org/) + +- [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 +- [vue-jsapi4](https://github.com/odoe/vue-jsapi4) - An example of how to use the [ArcGIS API for Javascript](https://developers.arcgis.com/javascript/) in a [NUXT](https://nuxtjs.org/) application ([blog post](https://odoe.net/blog/arcgis-api-4-for-js-with-vue-cli-and-nuxt/), [video](https://youtu.be/hqJzzgM8seo)) +- [esri-vue-cli-example](https://github.com/tomwayson/esri-vue-cli-example) - An example of how to use the [ArcGIS API for JavaScript 3.x](https://developers.arcgis.com/javascript/3/) in a [vue-cli](https://github.com/vuejs/vue-cli) application \ No newline at end of file diff --git a/src/esri-loader.ts b/src/esri-loader.ts index 5c3f5af..33a3d14 100644 --- a/src/esri-loader.ts +++ b/src/esri-loader.ts @@ -1,5 +1,5 @@ /* - Copyright (c) 2017 Esri + Copyright (c) 2022 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 diff --git a/src/modules.ts b/src/modules.ts index 7394cd6..de9307f 100644 --- a/src/modules.ts +++ b/src/modules.ts @@ -1,4 +1,4 @@ -/* Copyright (c) 2017 Environmental Systems Research Institute, Inc. +/* Copyright (c) 2022 Environmental Systems Research Institute, Inc. * Apache-2.0 */ import { getScript, ILoadScriptOptions, isLoaded, loadScript } from './script'; diff --git a/src/script.test.ts b/src/script.test.ts index 442e98c..1b38645 100644 --- a/src/script.test.ts +++ b/src/script.test.ts @@ -57,7 +57,7 @@ describe('when loading the script', function() { }); }); it('should default to latest version', function() { - expect(scriptEl.src).toEqual('https://js.arcgis.com/4.24/'); + expect(scriptEl.src).toEqual('https://js.arcgis.com/4.25/'); }); it('should not have called loadCss', function() { expect((cssUtils.loadCss as jasmine.Spy).calls.any()).toBeFalsy(); @@ -94,12 +94,12 @@ describe('when loading the script', function() { }); }); describe('with a specific version from the CDN', function() { - const expected = 'https://js.arcgis.com/3.41/'; + const expected = 'https://js.arcgis.com/3.42/'; let scriptEl; beforeAll(function(done) { fakeLoading(); loadScript({ - version: '3.41' + version: '3.42' }) .then((script) => { // hold onto script element for assertions below @@ -145,7 +145,7 @@ describe('when loading the script', function() { }); }); describe('with a specific version from the CDN', () => { - const version = '3.41'; + const version = '3.42'; beforeAll(function(done) { fakeLoading(); loadScript({ diff --git a/src/script.ts b/src/script.ts index bb6f826..88ac418 100644 --- a/src/script.ts +++ b/src/script.ts @@ -1,4 +1,4 @@ -/* Copyright (c) 2017 Environmental Systems Research Institute, Inc. +/* Copyright (c) 2022 Environmental Systems Research Institute, Inc. * Apache-2.0 */ import { loadCss } from './utils/css'; diff --git a/src/utils/css.test.ts b/src/utils/css.test.ts index f7d1e2a..d943ddd 100644 --- a/src/utils/css.test.ts +++ b/src/utils/css.test.ts @@ -2,7 +2,7 @@ import { loadCss } from './css'; describe('when loading the css', () => { describe('with no arguments', () => { - const url = 'https://js.arcgis.com/4.24/esri/themes/light/main.css'; + const url = 'https://js.arcgis.com/4.25/esri/themes/light/main.css'; let link; beforeAll(() => { spyOn(document.head, 'appendChild').and.stub(); @@ -20,12 +20,12 @@ describe('when loading the css', () => { }); }); describe('with a version', () => { - const url = 'https://js.arcgis.com/4.8/esri/themes/light/main.css'; + const url = 'https://js.arcgis.com/4.25/esri/themes/light/main.css'; let link; beforeAll(() => { spyOn(document.head, 'appendChild').and.stub(); spyOn(document, 'querySelector'); - link = loadCss('4.8'); + link = loadCss('4.25'); }); it('should have checked if the link was already appended', () => { expect((document.querySelector as jasmine.Spy).calls.argsFor(0)[0]).toEqual(`link[href*="${url}"]`); @@ -75,7 +75,7 @@ describe('when loading the css', () => { }); describe('when called twice', () => { describe('when loading the same url', () => { - const url = 'https://js.arcgis.com/4.24/esri/themes/light/main.css'; + const url = 'https://js.arcgis.com/4.25/esri/themes/light/main.css'; let link; let link2; beforeAll(() => { @@ -93,7 +93,7 @@ describe('when loading the css', () => { }); }); describe('when inserting before an existing node', () => { - const url = 'https://js.arcgis.com/4.24/esri/themes/light/main.css'; + const url = 'https://js.arcgis.com/4.25/esri/themes/light/main.css'; // insert before the first