Merge pull request #737 from usablica/afshinm-onbeforexit

afshinm · web-flow · commit f5a3fa40ecd5 · 2017-08-18T11:59:19.000+01:00
Adding onbeforexit and force option
diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-# Intro.js v2.6.0
+# Intro.js v2.7.0
 
 > Better introductions for websites and features with a step-by-step guide for your projects.
 
diff --git a/changelog.md b/changelog.md
@@ -1,5 +1,10 @@
 ## Release History
 
+ * **v2.7.0** - 2017-08-17
+   - Added `onbeforeexit` callback
+   - Added `force` parameter to `exit()`
+   - Added Code of Conduct and Contributing guide files
+
  * **v2.6.0** - 2017-07-29
    - Per step disable interaction
    - Adding `scrollTo` option 
diff --git a/component.json b/component.json
@@ -2,7 +2,7 @@
   "name": "intro.js",
   "repo": "usablica/intro.js",
   "description": "Better introductions for websites and features with a step-by-step guide for your projects",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "main": "intro.js",
   "scripts": [
     "intro.js"
diff --git a/docs/docs/getting-started/examples.md b/docs/docs/getting-started/examples.md
@@ -14,6 +14,7 @@ We have prepared a list of common examples using Introjs for both hints and intr
 *   [Basic usage with buttons](http://introjs.com/example/hello-world/withoutBullets.html "Basic usage with buttons")
 *   [Basic usage with bullets](http://introjs.com/example/hello-world/withoutButtons.html "Basic usage with bullets")
 *   [Basic usage with progress-bar](http://introjs.com/example/hello-world/withProgress.html "Basic usage with progress-bar")
+*   [Confirm before exit](http://introjs.com/example/hello-world/exit-confirm.html "Shows a confirm before exit")
 *   [Programmatic defining using JSON](http://introjs.com/example/programmatic/index.html "Programmatic defining using JSON")
 *   [Multi-Page introduction](http://introjs.com/example/multi-page/index.html "Multi-Page introduction")
 *   [Disabling interaction with elements](http://introjs.com/example/disable-interaction/index.html "Disabling interaction with elements")
diff --git a/docs/docs/intro/api.md b/docs/docs/intro/api.md
@@ -67,7 +67,7 @@ introJs().goToStep(2).start(); //starts introduction from step 2
 
 -----
 
-###introJs.goToStepNumber(step)
+##### introJs.goToStepNumber(step)
 
 Go to specific step of introduction with the concrete step.
 This differs from `goToStep` in the way that `data-step`
@@ -165,12 +165,16 @@ introJs().goToStep(3).start().previousStep(); //starts introduction from step 2
 
 -----
 
-##### introJs.exit()
+##### introJs.exit([force])
 
 Exit the introduction.
 
 **Available since**: v0.3.0
 
+**Parameters:**
+
+ - force : Boolean (optional) - Exit the tour even if `introJs.onbeforeexit` returns `false` (Available since 2.7.0)
+
 **Returns:**
 
  - introJs object.
@@ -296,6 +300,33 @@ introJs().onexit(function() {
 
 -----
 
+##### introJs.onbeforeexit(providedCallback)
+
+Works exactly same as `onexit` but calls before closing the tour. Also, returning `false` would prevent the tour from closing.
+
+**Available since:** v0.2.7
+
+**Parameters:**
+
+ - providedCallback : Function
+
+**Returns:**
+
+ - introJs object.
+
+**Example:**
+
+```javascript
+introJs().onbeforeexit(function() {
+  console.log("on before exit")
+
+  // returning false means don't exit the intro
+  return false;
+});
+````
+
+-----
+
 ##### introJs.onchange(providedCallback)
 
 Set callback to change of each step of introduction. Given callback function will be called after completing each step.
diff --git a/example/hello-world/exit-confirm.html b/example/hello-world/exit-confirm.html
@@ -0,0 +1,80 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <title>Basic usage</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="description" content="Intro.js - Better introductions for websites and features with a step-by-step guide for your projects.">
+    <meta name="author" content="Afshin Mehrabani (@afshinmeh) in usabli.ca group">
+
+    <!-- styles -->
+    <link href="../assets/css/bootstrap.min.css" rel="stylesheet">
+    <link href="../assets/css/demo.css" rel="stylesheet">
+
+    <!-- Add IntroJs styles -->
+    <link href="../../introjs.css" rel="stylesheet">
+
+    <link href="../assets/css/bootstrap-responsive.min.css" rel="stylesheet">
+  </head>
+
+  <body>
+
+    <div class="container-narrow">
+
+      <div class="masthead">
+        <ul class="nav nav-pills pull-right" data-step="5" data-intro="Get it, use it.">
+          <li><a href="https://github.com/usablica/intro.js/tags"><i class='icon-black icon-download-alt'></i> Download</a></li>
+          <li><a href="https://github.com/usablica/intro.js">Github</a></li>
+          <li><a href="https://twitter.com/usablica">@usablica</a></li>
+        </ul>
+        <h3 class="muted">Intro.js</h3>
+      </div>
+
+      <hr>
+
+      <div class="jumbotron">
+        <h1 data-step="1" data-intro="This is a tooltip!">Confirm before exit</h1>
+        <p class="lead" data-step="4" data-intro="Another step.">Shows a confirmation box before existing the tour using <code>onbeforeexit</code> callback.</p>
+        <a class="btn btn-large btn-success" href="javascript:void(0);" onclick="javascript:startTour();">Show me how</a>
+      </div>
+
+      <hr>
+
+      <div class="row-fluid marketing">
+        <div class="span6" data-step="2" data-intro="Ok, wasn't that fun?" data-position='right' data-scrollTo='tooltip'>
+          <h4>Section One</h4>
+          <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis mollis augue a neque cursus ac blandit orci faucibus. Phasellus nec metus purus.</p>
+
+          <h4>Section Two</h4>
+          <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis mollis augue a neque cursus ac blandit orci faucibus. Phasellus nec metus purus.</p>
+
+          <h4>Section Three</h4>
+          <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis mollis augue a neque cursus ac blandit orci faucibus. Phasellus nec metus purus.</p>
+          </div>
+
+        <div class="span6" data-step="3" data-intro="More features, more fun."  data-position='left'>
+          <h4>Section Four</h4>
+          <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis mollis augue a neque cursus ac blandit orci faucibus. Phasellus nec metus purus.</p>
+
+          <h4>Section Five</h4>
+          <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis mollis augue a neque cursus ac blandit orci faucibus. Phasellus nec metus purus.</p>
+
+          <h4>Section Six</h4>
+          <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis mollis augue a neque cursus ac blandit orci faucibus. Phasellus nec metus purus.</p>
+
+        </div>
+      </div>
+
+      <hr>
+    </div>
+    <script type="text/javascript" src="../../intro.js"></script>
+
+    <script type="text/javascript">
+      function startTour() {
+        introJs().start().onbeforeexit(function () {
+          return confirm("Are you sure?");
+        });
+      }
+    </script>
+  </body>
+</html>
diff --git a/intro.js b/intro.js
@@ -1,5 +1,5 @@
 /**
- * Intro.js v2.6.0
+ * Intro.js v2.7.0
  * https://github.com/usablica/intro.js
  *
  * Copyright (C) 2017 Afshin Mehrabani (@afshinmeh)
@@ -18,7 +18,7 @@
   }
 } (this, function (exports) {
   //Default config/variables
-  var VERSION = '2.6.0';
+  var VERSION = '2.7.0';
 
   /**
    * IntroJs main class
@@ -435,8 +435,22 @@
    * @api private
    * @method _exitIntro
    * @param {Object} targetElement
+   * @param {Boolean} force - Setting to `true` will skip the result of beforeExit callback
    */
-  function _exitIntro(targetElement) {
+  function _exitIntro(targetElement, force) {
+    var continueExit = true;
+
+    // calling onbeforeexit callback
+    // 
+    // If this callback return `false`, it would halt the process
+    if (this._introBeforeExitCallback != undefined) {
+      continueExit = this._introBeforeExitCallback.call(self);
+    }
+
+    // skip this check if `force` parameter is `true`
+    // otherwise, if `onbeforeexit` returned `false`, don't exit the intro
+    if (!force && continueExit === false) return;
+
     //remove overlay layers from the page
     var overlayLayers = targetElement.querySelectorAll('.introjs-overlay');
 
@@ -2006,8 +2020,8 @@
       _previousStep.call(this);
       return this;
     },
-    exit: function() {
-      _exitIntro.call(this, this._targetElement);
+    exit: function(force) {
+      _exitIntro.call(this, this._targetElement, force);
       return this;
     },
     refresh: function() {
@@ -2078,6 +2092,14 @@
       }
       return this;
     },
+    onbeforeexit: function(providedCallback) {
+      if (typeof (providedCallback) === 'function') {
+        this._introBeforeExitCallback = providedCallback;
+      } else {
+        throw new Error('Provided callback for onbeforeexit was not a function.');
+      }
+      return this;
+    },
     addHints: function() {
       _populateHints.call(this, this._targetElement);
       return this;
diff --git a/package.json b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "intro.js",
   "description": "Better introductions for websites and features with a step-by-step guide for your projects",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "author": "Afshin Mehrabani <afshin.meh@gmail.com>",
   "homepage": "http://introjs.com",
   "repository": {

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Intro.js v2.6.0`
	`1`	`+# Intro.js v2.7.0`
`2`	`2`
`3`	`3`	`> Better introductions for websites and features with a step-by-step guide for your projects.`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "intro.js",`
`3`	`3`	`"description": "Better introductions for websites and features with a step-by-step guide for your projects",`
`4`		`- "version": "2.6.0",`
	`4`	`+ "version": "2.7.0",`
`5`	`5`	`"author": "Afshin Mehrabani <[email protected]>",`
`6`	`6`	`"homepage": "http://introjs.com",`
`7`	`7`	`"repository": {`