Merge pull request usablica#1621 from usablica/dontShowAgain

feat: "Don't show again" feature

Author: afshinm

src/core/dontShowAgain.js

@@ -0,0 +1,33 @@
+import { deleteCookie, getCookie, setCookie } from "../util/cookie";
+
+const dontShowAgainCookieValue = "true";
+
+/**
+ * Set the "Don't show again" state
+ *
+ * @api private
+ * @param {Boolean} dontShowAgain
+ * @method setDontShowAgain
+ */
+export function setDontShowAgain(dontShowAgain) {
+  if (dontShowAgain) {
+    setCookie(
+      this._options.dontShowAgainCookie,
+      dontShowAgainCookieValue,
+      this._options.dontShowAgainCookieDays
+    );
+  } else {
+    deleteCookie(this._options.dontShowAgainCookie);
+  }
+}
+
+/**
+ * Get the "Don't show again" state from cookies
+ *
+ * @api private
+ * @method getDontShowAgain
+ */
+export function getDontShowAgain() {
+  const dontShowCookie = getCookie(this._options.dontShowAgainCookie);
+  return dontShowCookie && dontShowCookie === dontShowAgainCookieValue;
+}

src/core/introForElement.js

@@ -14,6 +14,9 @@ import fetchIntroSteps from "./fetchIntroSteps";
  * @returns {Boolean} Success or not?
  */
 export default function introForElement(targetElm) {
+  // don't start the tour if the instance is not active
+  if (!this.isActive()) return;
+
   if (this._introStartCallback !== undefined) {
     this._introStartCallback.call(this, targetElm);
   }
@@ -38,5 +41,6 @@ export default function introForElement(targetElm) {
     //for window resize
     DOMEvent.on(window, "resize", onResize, this, true);
   }
+
   return false;
 }

src/core/showElement.js

@@ -253,7 +253,7 @@ export default function _showElement(targetElement) {
     self._lastShowElementTimer = window.setTimeout(() => {
       // set current step to the label
       if (oldHelperNumberLayer !== null) {
-        oldHelperNumberLayer.innerHTML = `${targetElement.step} of ${this._introItems.length}`;
+        oldHelperNumberLayer.innerHTML = `${targetElement.step} ${this._options.stepNumbersOfLabel} ${this._introItems.length}`;
       }
 
       // set current tooltip text
@@ -356,6 +356,30 @@ export default function _showElement(targetElement) {
     tooltipHeaderLayer.appendChild(tooltipTitleLayer);
     tooltipLayer.appendChild(tooltipHeaderLayer);
     tooltipLayer.appendChild(tooltipTextLayer);
+
+    // "Do not show again" checkbox
+    if (this._options.dontShowAgain) {
+      const dontShowAgainWrapper = createElement("div", {
+        className: "introjs-dontShowAgain",
+      });
+      const dontShowAgainCheckbox = createElement("input", {
+        type: "checkbox",
+        id: "introjs-dontShowAgain",
+        name: "introjs-dontShowAgain",
+      });
+      dontShowAgainCheckbox.onchange = (e) => {
+        this.setDontShowAgain(e.target.checked);
+      };
+      const dontShowAgainCheckboxLabel = createElement("label", {
+        htmlFor: "introjs-dontShowAgain",
+      });
+      dontShowAgainCheckboxLabel.innerText = this._options.dontShowAgainLabel;
+      dontShowAgainWrapper.appendChild(dontShowAgainCheckbox);
+      dontShowAgainWrapper.appendChild(dontShowAgainCheckboxLabel);
+
+      tooltipLayer.appendChild(dontShowAgainWrapper);
+    }
+
     tooltipLayer.appendChild(_createBullets.call(this, targetElement));
     tooltipLayer.appendChild(_createProgressBar.call(this));
 
@@ -364,7 +388,7 @@ export default function _showElement(targetElement) {
 
     if (this._options.showStepNumbers === true) {
       helperNumberLayer.className = "introjs-helperNumberLayer";
-      helperNumberLayer.innerHTML = `${targetElement.step} of ${this._introItems.length}`;
+      helperNumberLayer.innerHTML = `${targetElement.step} ${this._options.stepNumbersOfLabel} ${this._introItems.length}`;
       tooltipLayer.appendChild(helperNumberLayer);
     }
 

src/index.js

@@ -3,6 +3,7 @@ import stamp from "./util/stamp";
 import exitIntro from "./core/exitIntro";
 import refresh from "./core/refresh";
 import introForElement from "./core/introForElement";
+import { getDontShowAgain, setDontShowAgain } from "./core/dontShowAgain";
 import { version } from "../package.json";
 import {
   populateHints,
@@ -32,6 +33,8 @@ function IntroJs(obj) {
   this._introItems = [];
 
   this._options = {
+    /* Is this tour instance active? Don't show the tour again if this flag is set to false */
+    isActive: true,
     /* Next button label in tooltip box */
     nextLabel: "Next",
     /* Previous button label in tooltip box */
@@ -58,8 +61,10 @@ function IntroJs(obj) {
     exitOnEsc: true,
     /* Close introduction when clicking on overlay layer? */
     exitOnOverlayClick: true,
-    /* Show step numbers in introduction? */
+    /* Display the pagination detail */
     showStepNumbers: false,
+    /* Pagination "of" label */
+    stepNumbersOfLabel: "of",
     /* Let user use keyboard to navigate the tour? */
     keyboardNavigation: true,
     /* Show tour control buttons? */
@@ -86,6 +91,12 @@ function IntroJs(obj) {
     positionPrecedence: ["bottom", "top", "right", "left"],
     /* Disable an interaction with element? */
     disableInteraction: false,
+    /* To display the "Don't show again" checkbox in the tour */
+    dontShowAgain: false,
+    dontShowAgainLabel: "Don't show this again",
+    /* "Don't show again" cookie name and expiry (in days) */
+    dontShowAgainCookie: "introjs-dontShowAgain",
+    dontShowAgainCookieDays: 365,
     /* Set how much padding to be used around helper element */
     helperElementPadding: 10,
     /* Default hint position */
@@ -149,6 +160,13 @@ introJs.instances = {};
 
 //Prototype
 introJs.fn = IntroJs.prototype = {
+  isActive() {
+    if (this._options.dontShowAgain && getDontShowAgain.call(this)) {
+      return false;
+    }
+
+    return this._options.isActive;
+  },
   clone() {
     return new IntroJs(this);
   },
@@ -210,6 +228,10 @@ introJs.fn = IntroJs.prototype = {
     refresh.call(this, refreshSteps);
     return this;
   },
+  setDontShowAgain(dontShowAgain) {
+    setDontShowAgain.call(this, dontShowAgain);
+    return this;
+  },
   onbeforechange(providedCallback) {
     if (typeof providedCallback === "function") {
       this._introBeforeChangeCallback = providedCallback;

src/styles/introjs.scss

@@ -175,6 +175,32 @@ tr.introjs-showElement {
   padding: 20px;
 }
 
+.introjs-dontShowAgain {
+  padding-left: 20px;
+  padding-right: 20px;
+}
+
+.introjs-dontShowAgain input {
+  padding: 0;
+  margin: 0;
+  margin-bottom: 2px;
+  display: inline;
+  width: 10px;
+  height: 10px;
+}
+
+.introjs-dontShowAgain label {
+  font-size: 14px;
+  display: inline-block;
+  font-weight: normal;
+  display: inline-block;
+  margin: 0 0 0 5px;
+  padding: 0;
+  background-color: $white;
+  color: $black600;
+  user-select: none;
+}
+
 .introjs-tooltip-title {
   font-size: 18px;
   margin: 0;

src/util/cookie.js

@@ -0,0 +1,37 @@
+export function setCookie(name, value, days) {
+  const cookie = { [name]: value, path: "/" };
+
+  if (days) {
+    let date = new Date();
+    date.setTime(date.getTime() + days * 24 * 60 * 60 * 1000);
+    cookie.expires = date.toUTCString();
+  }
+
+  let arr = [];
+  for (let key in cookie) {
+    arr.push(`${key}=${cookie[key]}`);
+  }
+
+  document.cookie = arr.join("; ");
+
+  return getCookie(name);
+}
+
+export function getAllCookies() {
+  let cookie = {};
+
+  document.cookie.split(";").forEach((el) => {
+    let [k, v] = el.split("=");
+    cookie[k.trim()] = v;
+  });
+
+  return cookie;
+}
+
+export function getCookie(name) {
+  return getAllCookies()[name];
+}
+
+export function deleteCookie(name) {
+  setCookie(name, "", -1);
+}

tests/core/dontShowAgain.test.js

@@ -0,0 +1,69 @@
+import * as cookie from "../../src/util/cookie";
+import {
+  setDontShowAgain,
+  getDontShowAgain,
+} from "../../src/core/dontShowAgain";
+
+describe("dontShowAgain", () => {
+  test("should call set cookie", () => {
+    const setCookieMock = jest.spyOn(cookie, "setCookie");
+
+    setDontShowAgain.call(
+      {
+        _options: {
+          dontShowAgainCookie: "cookie-name",
+          dontShowAgainCookieDays: 7,
+        },
+      },
+      true
+    );
+
+    expect(setCookieMock).toBeCalledTimes(1);
+    expect(setCookieMock).toBeCalledWith("cookie-name", "true", 7);
+  });
+
+  test("should call delete cookie", () => {
+    const setCookieMock = jest.spyOn(cookie, "setCookie");
+    const deleteCookieMock = jest.spyOn(cookie, "deleteCookie");
+
+    setDontShowAgain.call(
+      {
+        _options: {
+          dontShowAgainCookie: "cookie-name",
+          dontShowAgainCookieDays: 7,
+        },
+      },
+      false
+    );
+
+    expect(setCookieMock).toBeCalledTimes(0);
+    expect(deleteCookieMock).toBeCalledTimes(1);
+    expect(deleteCookieMock).toBeCalledWith("cookie-name");
+  });
+
+  test("should return true when cookie is valid", () => {
+    jest.spyOn(cookie, "getCookie").mockReturnValue("true");
+
+    expect(
+      getDontShowAgain.call({
+        _options: {
+          dontShowAgainCookie: "cookie-name",
+          dontShowAgainCookieDays: 7,
+        },
+      })
+    ).toBe(true);
+  });
+
+  test("should return false when cookie is invalid", () => {
+    jest.spyOn(cookie, "getCookie").mockReturnValue("invalid-state");
+
+    expect(
+      getDontShowAgain.call({
+        _options: {
+          dontShowAgainCookie: "cookie-name",
+          dontShowAgainCookieDays: 7,
+        },
+      })
+    ).toBe(false);
+  });
+});

tests/core/introForElement.test.js

@@ -2,6 +2,7 @@ import introForElement from "../../src/core/introForElement";
 import * as fetchIntroSteps from "../../src/core/fetchIntroSteps";
 import * as addOverlayLayer from "../../src/core/addOverlayLayer";
 import * as nextStep from "../../src/core/steps";
+import introJs from "../../src";
 
 describe("introForElement", () => {
   test("should call the onstart callback", () => {
@@ -11,14 +12,31 @@ describe("introForElement", () => {
 
     const onstartCallback = jest.fn();
 
-    const self = {
-      _options: {},
-      _introStartCallback: onstartCallback,
-    };
+    const context = introJs().setOptions({
+      isActive: true,
+    });
 
-    introForElement.call(self, document.body);
+    context._introStartCallback = onstartCallback;
+
+    introForElement.call(context, document.body);
 
     expect(onstartCallback).toBeCalledTimes(1);
     expect(onstartCallback).toBeCalledWith(document.body);
   });
+
+  test("should not start the tour if isActive is false", () => {
+    const fetchIntroStepsMock = jest.spyOn(fetchIntroSteps, "default");
+    const addOverlayLayerMock = jest.spyOn(addOverlayLayer, "default");
+    const nextStepMock = jest.spyOn(nextStep, "nextStep");
+
+    const context = introJs().setOptions({
+      isActive: false,
+    });
+
+    introForElement.call(context, document.body);
+
+    expect(fetchIntroStepsMock).toBeCalledTimes(0);
+    expect(addOverlayLayerMock).toBeCalledTimes(0);
+    expect(nextStepMock).toBeCalledTimes(0);
+  });
 });