diff --git a/CHANGELOG.md b/CHANGELOG.md index 4899bb2..afd5f8c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,7 @@ This project adheres to [Semantic Versioning](http://semver.org/). ## [Unreleased] ### Added -- option to insert CSS link before an existing link tag +- `insertCssBefore` option to insert CSS link before an existing element ### Changed ### Fixed ### Removed diff --git a/README.md b/README.md index b93e75c..fdf7a57 100644 --- a/README.md +++ b/README.md @@ -23,15 +23,16 @@ See the [Examples](#examples) section below for links to applications that use t - [Table of contents](#table-of-contents) - [Install](#install) - [Usage](#usage) - - [Loading Styles](#loading-styles) - [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) - [Why is this needed?](#why-is-this-needed) - [Examples](#examples) - [Advanced Usage](#advanced-usage) + - [Overriding ArcGIS Styles](#overriding-arcgis-styles) + - [Configuring Dojo](#configuring-dojo) - [Pre-loading the ArcGIS API for JavaScript](#pre-loading-the-arcgis-api-for-javascript) - [Isomorphic/universal applications](#isomorphicuniversal-applications) - - [Configuring Dojo](#configuring-dojo) - [Using your own script tag](#using-your-own-script-tag) - [ArcGIS Types](#arcgis-types) - [Using the esriLoader Global](#using-the-esriloader-global) @@ -61,30 +62,6 @@ yarn add esri-loader 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 [example applications](#examples). -### 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. You can use the provided `loadCss(url)` function. 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'); -``` - -Alternatively, you can manually load them by more traditional means such as adding `` tags to your HTML, or `@import` statements to your CSS. For example: - -```html - - -``` - -or: - -```css -/* load esri styles for version 3.x via css import */ -@import url('https://js.arcgis.com/3.27/esri/css/esri.css'); -``` - ### Loading Modules from the ArcGIS API for JavaScript #### From the Latest Version @@ -150,6 +127,48 @@ Lazy loading the ArcGIS API can dramatically improve the initial load performanc See the [Advanced Usage](#advanced-usage) section below for more advanced techniques such as [pre-loading the ArcGIS API](#pre-loading-the-arcgis-api-for-javascript), [using in isomorphic/universal applications](#isomorphicuniversal-applications), [configuring Dojo](#configuring-dojo), and more. +### 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()`: + +```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' +}; + +loadModules(['esri/views/MapView', 'esri/WebMap'], options) + .then(([MapView, WebMap]) => { + // you can safely create a map now that the styles are loaded + }); +``` + +Alternatively, you can use the provided `loadCss(url)` function to control when the ArcGIS styles are loaded. 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](#override-arcgis-styles) that you've lazy-loaded with `loadModules()` or `loadCss()`. + +Finally, you can manually load them by more traditional means such as adding `` tags to your HTML, or `@import` statements to your CSS. For example: + +```html + + +``` + +or: + +```css +/* load esri styles for version 3.x via css import */ +@import url('https://js.arcgis.com/3.27/esri/css/esri.css'); +``` + ## Why is this needed? Unfortunately, you can't simply `npm install` the ArcGIS API and then `import` ArcGIS modules directly from other modules in a non-Dojo application. The only reliable way to load ArcGIS API for JavaScript modules is using Dojo's AMD loader. However, when using the ArcGIS API in an application built with another framework, you typically want to use the tooling and conventions of that framework rather than the Dojo build system. This library lets you do that by providing an ES 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. @@ -247,6 +266,58 @@ See the [examples over at ember-esri-loader](https://github.com/Esri/ember-esri- ## Advanced Usage +### Configuring Dojo + +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 +import { loadModules } from 'esri-loader'; + +// 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/fcl', + name: 'fcl' + } + ] + } +}; + +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); + }); +``` + +### Overriding ArcGIS Styles + +If you want to override ArcGIS styles that you have lazy-loaded using `loadModules()` or `loadCss()`, you may need to insert the ArcGIS styles into the document _above_ your custom styles in order to ensure the [rules of CSS precedence](https://css-tricks.com/precedence-css-order-css-matters/) are applied correctly. For this reason, `loadCss()` accepts a [selector](https://developer.mozilla.org/en-US/docs/Web/API/Document_object_model/Locating_DOM_elements_using_selectors#Selectors) (string) as optional second argument that will be used to query the DOM node (i.e. `` or `