Merge pull request #1 from DriveWorks/1.1.0

1.1.0 - Implement warning when leaving "run" view (beforeunload).

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (C) 2020 DriveWorks Ltd
+Copyright (C) 2021 DriveWorks Ltd
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this example and associated documentation files (the "Example"), to deal in the Example without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Example, and to permit persons to whom the Example is furnished to do so, subject to the following conditions:
 

README.md

@@ -1,5 +1,5 @@
 # DriveWorks Live - Integration Theme Example - Simple Login (DriveApps)
-### Release: 1.0.0
+### Release: 1.1.0
 #### Minimum DriveWorks Version: 18.1
 
 A simple distributable template that renders a predefined DriveApp after a valid login.

config.js

@@ -10,4 +10,8 @@ const config = {
     // This function prevents a DriveApp timing out as long as the page is in view.
     // Disable the ping by changing the setting to 0
     driveAppPingInterval: 0,
+    // (Optional) Configure 'Run' view
+    run: {
+        showWarningOnExit: true, // Toggle warning dialog when exiting "Run" view with potentially unsaved changes (where supported)
+    },
 };

css/run.css

@@ -9,9 +9,7 @@ body {
   position: relative;
 }
 
-
 /* Simple Header */
-
 header,
 header * {
   box-sizing: border-box;
@@ -53,7 +51,7 @@ header .header-user {
 }
 
 @media screen and (min-width: 640px) {
-  
+
   header .header-user.is-shown {
     display: flex;
     align-items: center;
@@ -63,6 +61,7 @@ header .header-user {
 }
 
 header button {
+  position: relative;
   display: block;
   padding: .75em 2em;
   margin: 0;
@@ -79,10 +78,29 @@ header button {
 header button:hover {
   background-color: rgba(0,0,0,.2);
 }
+header button.is-loading {
+  opacity: .75;
+  color: transparent;
+  pointer-events: none;
+}
 
+header button svg.loading {
+  display: none;
+  font-size: 1.5em;
+  width: 1em;
+  height: 1em;
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  margin: -0.5em 0 0 -0.5em;
+  color: #fff;
+  animation: spin .75s linear infinite;
+}
+header button.is-loading svg.loading {
+  display: block;
+}
 
 /* Form Output */
-
 .output {
   position: absolute;
   bottom: 0;

js/login.js

@@ -5,13 +5,23 @@ const GROUP_ALIAS = config.groupAlias;
 // Elements
 const loginButton = document.getElementById("login-button");
 const loginForm = document.getElementById("login-form");
-loginForm.addEventListener("submit", handleLogin);
 
-// Display any notice passed e.g. "You have been logged out."
-showLoginNotice();
-
-// Construct DriveWorks Live client
+// Global client
 let DW_CLIENT;
+
+/**
+ * On page load.
+ */
+(() => {
+    loginForm.addEventListener("submit", handleLogin);
+
+    // Display any notice passed e.g. "You have been logged out."
+    showLoginNotice();
+})();
+
+/**
+ * DriveWorks Live client loaded.
+ */
 function dwClientLoaded() {
     try {
         DW_CLIENT = new window.DriveWorksLiveClient(SERVER_URL);
@@ -22,13 +32,14 @@ function dwClientLoaded() {
 }
 
 /**
- * Handle login
+ * Handle DriveWorks Group login.
  *
- * @param evt Form submit event
+ * @param {Object} event - Form submit event.
  */
-async function handleLogin(evt) {
+async function handleLogin(event) {
+
     // Prevent browser handling submission
-    evt.preventDefault();
+    event.preventDefault();
 
     // Show error if cannot connect to client
     if (!DW_CLIENT) {
@@ -69,12 +80,13 @@ async function handleLogin(evt) {
 }
 
 /**
- * Show login error
+ * Show login error.
  *
- * @param {Object} [text] The originating error
- * @param {string} [text] The text displayed to the user on the login screen
+ * @param {Object} error - The originating error object.
+ * @param {string} text - The text displayed to the user on the login screen.
  */
 function loginError(error, text) {
+
     // Log error to console
     if (error) {
         console.log(error);
@@ -95,7 +107,7 @@ function loginError(error, text) {
 }
 
 /**
- * Show login notice
+ * Show login notice.
  */
 function showLoginNotice() {
     const loginNotice = document.getElementById("login-notice");

js/run.js

@@ -5,10 +5,34 @@ const DRIVEAPP_ALIAS = config.driveAppAlias;
 
 // Get session
 const CURRENT_SESSION = localStorage.getItem("sessionId");
-checkSession();
 
-// Construct DriveWorks Live client
+// Elements
+const logoutButton = document.getElementById("logout-button");
+
+// Global client
 let DW_CLIENT;
+
+/**
+ * On page load.
+ */
+(() => {
+
+    // Check if Session Id exists
+    checkSession();
+
+    // Attach logout function to button click
+    logoutButton.onclick = () => handleLogout();
+
+    // Quick Logout (?bye URL query)
+    const urlQuery = new URLSearchParams(window.location.search);
+    if (urlQuery.has("bye")) {
+        handleLogout();
+    }
+})();
+
+/**
+ * DriveWorks Live client loaded.
+ */
 function dwClientLoaded() {
     try {
         DW_CLIENT = new window.DriveWorksLiveClient(SERVER_URL);
@@ -22,7 +46,9 @@ function dwClientLoaded() {
     run();
 }
 
-// Run on load
+/**
+ * Setup page and run Specification, attach event handling.
+ */
 async function run() {
     showUsername();
 
@@ -45,6 +71,8 @@ async function run() {
         // (Optional) Prevent Specification timeout
         pingDriveApp(driveApp);
 
+        // (Optional) Show warning dialog when exiting page after Form renders
+        attachPageUnloadEvent();
     } catch (error) {
         console.log(error);
 
@@ -57,7 +85,7 @@ async function run() {
 }
 
 /**
- * Check for stored session
+ * Check for stored session id. Redirect to login if not found.
  */
 function checkSession() {
     // If no session is stored (e.g. not logged in), redirect to login
@@ -72,7 +100,7 @@ function checkSession() {
  * A DriveApp will timeout after a configured period of inactivity (see DriveWorksConfigUser.xml).
  * This function prevents a DriveApp timing out as long as the page is in view.
  *
- * @param driveApp The DriveApp object.
+ * @param {object} driveApp - The DriveApp object.
  */
  function pingDriveApp(driveApp) {
     // Disable ping if interval is 0
@@ -88,31 +116,32 @@ function checkSession() {
 }
 
 /**
- * Handle logout
+ * Handle Group logout.
+ * 
+ * @param {string} [text] - The message to display when directed to the login screen.
+ * @param {string} [state] - The type of message state (error/success).
  */
 async function handleLogout(text = "You have been logged out.", state = "success") {
     try {
+        logoutButton.classList.add("is-loading");
+
+        // Remove warning on unload - intentional navigation
+        window.removeEventListener("beforeunload", beforeUnloadHandler);
+
         // Logout of Group
         await DW_CLIENT.logoutGroup(GROUP_ALIAS);
+
         redirectToLogin(text, state);
     } catch (error) {
         console.log(error);
     }
 }
 
-// Attach logout function to button click
-document.getElementById("logout-button").onclick = function() {
-    handleLogout();
-};
-
-// Quick Logout (?bye URL query)
-const urlQuery = new URLSearchParams(window.location.search);
-if (urlQuery.has("bye")) {
-    handleLogout();
-}
-
 /**
- * Set login screen message
+ * Redirect to login screen.
+ * 
+ * @param {string} text - The message to display when directed to the login screen.
+ * @param {string} state - The type of message state (error/success).
  */
 function redirectToLogin(text, state) {
     // Clear all stored credentials
@@ -126,7 +155,10 @@ function redirectToLogin(text, state) {
 }
 
 /**
- * Set login screen message
+ * Set login screen message.
+ * 
+ * @param {string} text - The message to display when directed to the login screen.
+ * @param {string} state - The type of message state (error/success).
  */
 function setLoginMessage(text, state) {
     message = {
@@ -137,7 +169,7 @@ function setLoginMessage(text, state) {
 }
 
 /**
- * Show username in header
+ * Display username onscreen.
  */
 function showUsername() {
     const username = localStorage.getItem("sessionUser");
@@ -146,3 +178,22 @@ function showUsername() {
         document.getElementById("header-user").classList.add("is-shown");
     }
 }
+
+/**
+ * On page unload, show dialog to confirm navigation.
+ */
+ function attachPageUnloadEvent() {
+    if (config.run.showWarningOnExit) {
+        window.addEventListener("beforeunload", beforeUnloadHandler);
+    }
+}
+
+/**
+ * Handle beforeunload event.
+ * 
+ * @param {Object} event - The beforeunload event object
+ */
+function beforeUnloadHandler(event) {
+    event.preventDefault();
+    event.returnValue = "Are you sure you want to leave this page?";
+}

run.html

@@ -29,7 +29,12 @@
             <div id="username"></div>
         </div>
 
-        <button id="logout-button">Logout</button>
+        <button id="logout-button">
+            Logout
+            <svg viewBox="0 0 512 512" class="loading">
+                <path fill="#fff" d="M255.43 0v102.4h.57c84.76 0 153.6 68.84 153.6 153.6S340.76 409.6 256 409.6 102.4 340.76 102.4 256c0-15.93 2.28-31.86 7.4-47.22L12.52 177.5C3.98 202.52 0 229.26 0 256c0 141.08 114.92 256 256 256s256-114.92 256-256S397.08 0 255.43 0z"></path>
+            </svg>
+        </button>
 
     </header>