Merge pull request #83 from Esri/feat/load-css

Feat/load css

Author: tomwayson

CHANGELOG.md

@@ -4,6 +4,7 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 ### Added
+- added loadCss(url) to inject a stylesheet link
 ### Changed
 - added GitHub issue and pull request templates
 - added badges to README

README.md

@@ -31,17 +31,25 @@ The code snippets below show how to load the ArcGIS API and its modules and then
 
 ### Loading Styles
 
-Before you can use the ArcGIS API in your app, you'll need to load the styles. For example, if you're using the latest 4.x version (the default):
+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:
 
-```css
-/* esri styles */
+```js
+// load esri styles for version 4.6 using loadCss
+esriLoader.loadCss('https://js.arcgis.com/4.6/esri/css/main.css');
+```
+
+Alternatively, 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:
+
+```html
+<!-- load esri styles for version 4.6 via a link tag -->
+<link rel="stylesheet" href="https://js.arcgis.com/4.6/esri/css/main.css">
 @import url('https://js.arcgis.com/4.6/esri/css/main.css');
 ```
 
-If you're using a specific version other than the latest 4.x:
+or:
 
 ```css
-/* esri styles */
+/* load esri styles for version 3.23 via import */
 @import url('https://js.arcgis.com/3.23/esri/css/esri.css');
 ```
 

src/esri-loader.ts

@@ -12,7 +12,6 @@
 */
 const isBrowser = typeof window !== 'undefined';
 const DEFAULT_URL = 'https://js.arcgis.com/4.6/';
-
 // this is the url that is currently being, or already has loaded
 let _currentUrl;
 
@@ -24,6 +23,13 @@ function createScript(url) {
   return script;
 }
 
+function createStylesheetLink(url) {
+  const link = document.createElement('link');
+  link.rel = 'stylesheet';
+  link.href = url;
+  return link;
+}
+
 // add a one-time load handler to script
 // and optionally add a one time error handler as well
 function handleScriptLoad(script, callback, errback?) {
@@ -60,6 +66,7 @@ function handleScriptError(script, callback) {
 // interfaces
 export interface ILoadScriptOptions {
   url?: string;
+  // TODO: css?: string;
   dojoConfig?: { [propName: string]: any };
 }
 
@@ -72,6 +79,11 @@ export const utils = {
 export function getScript() {
   return document.querySelector('script[data-esri-loader]') as HTMLScriptElement;
 }
+// TODO: export this function?
+// check if the css url has been injected or added manually
+function getCss(url) {
+  return document.querySelector(`link[href*="${url}"]`) as HTMLLinkElement;
+}
 
 // has ArcGIS API been loaded on the page yet?
 export function isLoaded() {
@@ -80,6 +92,17 @@ export function isLoaded() {
   return globalRequire && globalRequire.on;
 }
 
+// lazy load the CSS needed for the ArcGIS API
+export function loadCss(url) {
+  let link = getCss(url);
+  if (!link) {
+    // create & load the css library
+    link = createStylesheetLink(url);
+    document.head.appendChild(link);
+  }
+  return link;
+}
+
 // load the ArcGIS API on the page
 export function loadScript(options: ILoadScriptOptions = {}): Promise<HTMLScriptElement> {
   // default options
@@ -95,7 +118,7 @@ export function loadScript(options: ILoadScriptOptions = {}): Promise<HTMLScript
       // b/c the latter will return the full url for relative paths
       const src = script.getAttribute('src');
       if (src !== options.url) {
-        // potentailly trying to load a different version of the API
+        // potentially trying to load a different version of the API
         reject(new Error(`The ArcGIS API for JavaScript is already loaded (${src}).`));
       } else {
         if (isLoaded()) {
@@ -109,7 +132,7 @@ export function loadScript(options: ILoadScriptOptions = {}): Promise<HTMLScript
     } else {
       if (isLoaded()) {
         // the API has been loaded by some other means
-        // potentailly trying to load a different version of the API
+        // potentially trying to load a different version of the API
         reject(new Error(`The ArcGIS API for JavaScript is already loaded.`));
       } else {
         // this is the first time attempting to load the API

test/esri-loader.spec.js

@@ -37,6 +37,45 @@ describe('esri-loader', function () {
     });
   });
 
+  describe('when loading the css', function () {
+    describe('with a url', function () {
+      var url = 'https://js.arcgis.com/4.6/esri/css/main.css';
+      var link;
+      beforeAll(function () {
+        spyOn(document.head, 'appendChild').and.stub();
+        spyOn(document, 'querySelector');
+        link = esriLoader.loadCss(url);
+      });
+      it('should have checked if the link was already appended', function() {
+        expect(document.querySelector.calls.argsFor(0)[0]).toEqual(`link[href*="${url}"]`);
+      });
+      it('should have set the href', function () {
+        expect(link.href).toEqual(url);
+      });
+      it('should not have set the rel', function () {
+        expect(link.rel).toEqual('stylesheet');
+      });
+    });
+    describe('when called twice', function () {
+      describe('when loading the same url', function () {
+        var url = 'https://js.arcgis.com/4.6/esri/css/main.css';
+        var link, link2;
+        beforeAll(function () {
+          spyOn(document.head, 'appendChild').and.stub();
+          link = esriLoader.loadCss(url);
+          spyOn(document, 'querySelector').and.returnValue(link);
+          link2 = esriLoader.loadCss(url);
+        });
+        it('should return the link if it is already loaded', function () {
+          expect(link2).toEqual(link);
+        });
+        it('should not have tried to append the link a second time', function () {
+          expect(document.head.appendChild.calls.count()).toEqual(1);
+        });
+      });
+    });
+  });
+
   describe('when loading the script', function () {
     describe('with defaults', function () {
       var scriptEl;