💥 add 'root' option for users to select the DOM element to attach MDE to

francisashley · Dec 16, 2019 · 8ae9153 · 8ae9153
1 parent 50f2f3e
commit 8ae9153
Show file tree

Hide file tree

Showing 4 changed files with 80 additions and 28 deletions.
diff --git a/README.md b/README.md
@@ -48,9 +48,12 @@ With [unpkg.com](https://unpkg.com/browse/@fa-repo/mobile-dev-environment@latest
 import mobileDevEnvironment from '@fa-repo/mobile-dev-environment';
 import '@fa-repo/mobile-dev-environment/mobile-dev-environment.css';
 
-new mobileDevEnvironment({
-  stateId : 'my-multi-page-app',
-  actionsCorner : 'tl'
+window.addEventListener("DOMContentLoaded", event => {
+  new mobileDevEnvironment({
+    root: document.getElementById('mde'),
+    stateId : 'my-multi-page-app',
+    actionsCorner : 'tl'
+  });
 });
 
 // app.html
@@ -74,15 +77,16 @@ new mobileDevEnvironment({
   <head>
   <link href="https://unpkg.com/@fa-repo/mobile-dev-environment@latest/dist/mde.min.css" rel="stylesheet" type="text/css">
   <script src="https://unpkg.com/@fa-repo/mobile-dev-environment@latest/dist/mde.min.js" defer></script>
-  <script defer>  
+</head>
+<body>
+  <div id="mde"></div>
+  <script>
     new mobileDevEnvironment({
+      root: document.getElementById('mde'),
       stateId : 'my-multi-page-app',
       actionsCorner : 'tl'
     });
   </script>
-</head>
-<body>
-  <div id="mde"></div>
 </body>
 </html>
 ```
@@ -91,52 +95,64 @@ new mobileDevEnvironment({
 
 <table>
   <tr>
-    <th colspan="4" align="left" valign="top"><a href="#options" name="options">Options</a></th>
+    <th colspan="5" align="left" valign="top"><a href="#options" name="options">Options</a></th>
   </tr>
   <tr>
     <th align="left" valign="top">Option</th>
     <th align="left" valign="top">Description</th>
     <th align="left" valign="top">Type</th>
     <th align="left" valign="top">Default</th>
+    <th align="left" valign="top">Required</th>
   </tr>
   <tr>
     <td valign="top"><code>actions</code></td>
     <td valign="top">An array of <a href="#modules" name="modules">actions</a> to load</td>
     <td valign="top"><code>array</code></td>
     <td valign="top"><code>['reload','tray']</code></td>
+    <td valign="top"></td>
   </tr>
   <tr>
     <td valign="top"><code>actionsCorner</code></td>
     <td valign="top">The actions bar position, top left <code>'tl'</code> or right <code>'tr'</code></td>
     <td valign="top"><code>string</code></td>
     <td valign="top"><code>'tr'</code></td>
+    <td valign="top"></td>
   </tr>
   <tr>
     <td valign="top"><code>hardReload</code></td>
     <td valign="top">Refresh browser cache</td>
     <td valign="top"><code>string</code></td>
     <td valign="top"><code>true</code></td>
+    <td valign="top"></td>
+  </tr>
+  <tr>
+    <td valign="top"><code>root</code></td>
+    <td valign="top">Provide a DOM element for MDE to hook on too.</td>
+    <td valign="top"><code>DOM element</code></td>
+    <td valign="top"></td>
+    <td valign="top">Required</td>
   </tr>
   <tr>
     <td valign="top"><code>stateId</code></td>
     <td valign="top">Share state information like open/close, height etc across instances of MDE on other pages</td>
     <td valign="top"><code>string</code></td>
     <td valign="top"><code>'global'</code></td>
+    <td valign="top"></td>
   </tr>
   <tr>
-    <th colspan="4" align="left" valign="top"><a href="#modules" name="modules">Modules</a></th>
+    <th colspan="5" align="left" valign="top"><a href="#modules" name="modules">Modules</a></th>
   </tr>
   <tr>
     <th colspan="1" align="left" valign="top">Module</th>
-    <th colspan="3" align="left" valign="top">Description</th>
+    <th colspan="4" align="left" valign="top">Description</th>
   </tr>
   <tr>
     <td colspan="1" valign="top"><code>reload</code></td>
-    <td colspan="3" valign="top">An easily accessible button for reloading the page</td>
+    <td colspan="4" valign="top">An easily accessible button for reloading the page</td>
   </tr>
   <tr>
     <td colspan="1" valign="top"><code>tray</code></td>
-    <td colspan="3" valign="top">A toggleable, color coded, resizable tray for displaying log messages</td>
+    <td colspan="4" valign="top">A toggleable, color coded, resizable tray for displaying log messages</td>
   </tr>
 </table>
 

diff --git a/example/index.html b/example/index.html
@@ -20,7 +20,10 @@
     <img src="http://placekitten.com/g/740/420" alt="cute cat placeholder" />
     <div id="mde"></div>
     <script>
-      mobileDevEnvironment({ actionsCorner: "tr" });
+      mobileDevEnvironment({
+        root: document.getElementById("mde"),
+        actionsCorner: "tr"
+      });
 
       intentional_error;
     </script>

diff --git a/src/mde.js b/src/mde.js
@@ -1,29 +1,34 @@
+import { defaults, isElement } from "lodash";
+
 import ActionBar from "./features/action-bar/action-bar";
 import Tray from "./features/tray/tray";
 import crel from "crel";
-import { defaults } from "lodash";
 import stately from "./utils/state";
 import tracer from "./utils/tracer.js";
 
 (function() {
   "use strict";
 
   function mobileDevEnvironment(options = {}) {
+    if (!isElement(options.root)) {
+      throw "Could not start MDE because MDE requires a `root` element to attach to the DOM.";
+    }
+
     /**
      * STATE
      */
 
-    defaults(options, {
+    const { root, stateId, actions, hardReload, actionsCorner } = defaults(options, {
       stateId: "global",
       actions: ["reload", "toggle-tray"],
       hardReload: true,
       actionsCorner: "tr"
     });
 
-    const state = stately(options.stateId);
-    state.set("action-bar", options.actions);
-    state.set("action-bar.corner", options.actionsCorner);
-    state.set("reload.refreshCache", options.hardReload);
+    const state = stately(stateId);
+    state.set("action-bar", actions);
+    state.set("action-bar.corner", actionsCorner);
+    state.set("reload.refreshCache", hardReload);
     state.setCache("tray.open", state.getCache("tray.open", true));
     state.setCache(
       "tray.height",
@@ -112,7 +117,6 @@ import tracer from "./utils/tracer.js";
     // render
 
     function render() {
-      const root = document.getElementById("mde");
       root.innerHTML = "";
 
       // render action bar

diff --git a/src/mde.test.js b/src/mde.test.js
@@ -11,14 +11,29 @@ afterEach(() => {
 });
 
 test("MDE renders to dom without crashing", () => {
-  mobileDevEnvironment();
+  mobileDevEnvironment({
+    root: document.getElementById("mde")
+  });
 
   expect(!!document.getElementById("mde-action-bar")).toBe(true);
   expect(!!document.getElementById("mde-tray")).toBe(true);
 });
 
+test("MDE throws an error if `root` option does not contain a DOM element", () => {
+  try {
+    mobileDevEnvironment();
+    expect(false).toBe(true);
+  } catch (error) {
+    expect(error).toBe(
+      "Could not start MDE because MDE requires a `root` element to attach to the DOM."
+    );
+  }
+});
+
 test("MDE console.log()'s to tray", () => {
-  mobileDevEnvironment();
+  mobileDevEnvironment({
+    root: document.getElementById("mde")
+  });
 
   console.log("works");
 
@@ -31,7 +46,9 @@ test("MDE console.log()'s to tray", () => {
 });
 
 test("MDE console.error()'s to tray", () => {
-  mobileDevEnvironment();
+  mobileDevEnvironment({
+    root: document.getElementById("mde")
+  });
 
   console.error("works");
 
@@ -44,7 +61,9 @@ test("MDE console.error()'s to tray", () => {
 });
 
 test("MDE console.assert()'s to tray", () => {
-  mobileDevEnvironment();
+  mobileDevEnvironment({
+    root: document.getElementById("mde")
+  });
 
   console.assert(false, "works");
 
@@ -70,6 +89,7 @@ test("MDE console.assert()'s to tray", () => {
 
 test("MDE shows correct actions", () => {
   mobileDevEnvironment({
+    root: document.getElementById("mde"),
     actions: ["reload", "toggle-tray"]
   });
 
@@ -78,16 +98,25 @@ test("MDE shows correct actions", () => {
 });
 
 test("MDE shows actions tray on top right by default", () => {
-  mobileDevEnvironment();
+  mobileDevEnvironment({
+    root: document.getElementById("mde")
+  });
 
   expect(document.querySelector("#mde-action-bar[data-corner=tr]")).toBeTruthy();
 });
+
 test("MDE shows actions tray on top left", () => {
-  mobileDevEnvironment({ actionsCorner: "tl" });
+  mobileDevEnvironment({
+    root: document.getElementById("mde"),
+    actionsCorner: "tl"
+  });
   expect(document.querySelector("#mde-action-bar[data-corner=tl]")).toBeTruthy();
 });
-test("MDE shows actions tray on top right", () => {
-  mobileDevEnvironment({ actionsCorner: "tr" });
 
+test("MDE shows actions tray on top right", () => {
+  mobileDevEnvironment({
+    root: document.getElementById("mde"),
+    actionsCorner: "tr"
+  });
   expect(document.querySelector("#mde-action-bar[data-corner=tr]")).toBeTruthy();
 });