From 567041da05d5c2eda1ddaa1c652a52e97d375691 Mon Sep 17 00:00:00 2001
From: Jake Marsh <jakemmarsh@gmail.com>
Date: Sun, 8 Mar 2015 16:15:14 -0400
Subject: [PATCH] Add a `getUserTourProgress` method and logic, to allow for
 retrieval/saving of the user's current progress through the tour

---
 README.md        | 20 ++++++++++++++++++++
 dist/js/Mixin.js | 11 ++++++++++-
 lib/js/Mixin.js  | 11 ++++++++++-
 3 files changed, 40 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index d85728f..4475825 100644
--- a/README.md
+++ b/README.md
@@ -46,6 +46,7 @@ var App = React.createClass({
 
 A Javascript object is passed to the `TourGuideMixin` to specify options, as well as the steps of your tour as an array. The options are:
 
+- `startIndex` (int): the index from which to begin the steps of the tour. This can be retrieved and saved via `getUserTourProgress` (discussed below), in order to be specified when a user returns. Defaults to `0`.
 - `scrollToSteps` (bool): if true, the page will be automatically scrolled to the next indicator (if one exists) after a tooltip is dismissed. Defaults to `true`.
 
 Each "step" in the array represents one indicator and tooltip that a user must click through in the guided tour. A step has the following structure:
@@ -68,6 +69,25 @@ An optional callback may be passed as the second parameter to `TourGuideMixin`,
 
 ---
 
+### Getting the User's Current Progress
+
+Upon including the mixin, the function `getUserTourProgress` will be available to your component. At any point, this method can be called to retrieve information about the current user's progress through the guided tour. The object returned looks like this:
+
+```json
+{
+  "index": 2,
+  "percentageComplete": 50,
+  "step": {
+    "text": "...",
+    "element": "...",
+    "position": "..."
+  }
+}
+```
+This information can be used to save a user's progress upon navigation from the page or application, allowing you to return them back to their correct spot when they visit next using the `startIndex` option (discussed above).
+
+---
+
 ### Styling
 
 Some basic styling is provided in `/dist/css/tour-guide.css`. This can either be included directly in your project, or used as a base for your own custom styles. Below, the HTML structure of the tour is also outlined for custom styling.
diff --git a/dist/js/Mixin.js b/dist/js/Mixin.js
index 9f9cf51..e993c1b 100644
--- a/dist/js/Mixin.js
+++ b/dist/js/Mixin.js
@@ -14,6 +14,7 @@ module.exports = function(settings, done) {
   var mixin = {
 
     settings: $.extend({
+      startIndex: 0,
       scrollToSteps: true,
       steps: []
     }, settings),
@@ -22,7 +23,7 @@ module.exports = function(settings, done) {
 
     getInitialState: function() {
       return {
-        currentIndex: 0,
+        currentIndex: this.settings.startIndex,
         showTooltip: false,
         xPos: -1000,
         yPos: -1000
@@ -75,6 +76,14 @@ module.exports = function(settings, done) {
       $(window).off('resize', this.calculatePlacement);
     },
 
+    getUserTourProgress: function() {
+      return {
+        index: this.state.currentIndex,
+        percentageComplete: (this.state.currentIndex/this.settings.steps.length)*100,
+        step: this.settings.steps[this.state.currentIndex]
+      };
+    },
+
     preventWindowOverflow: function(value, axis, elWidth, elHeight) {
       var winWidth = parseInt($(window).width());
       var docHeight = parseInt($(document).height());
diff --git a/lib/js/Mixin.js b/lib/js/Mixin.js
index 9e0f94b..4ceb558 100644
--- a/lib/js/Mixin.js
+++ b/lib/js/Mixin.js
@@ -14,6 +14,7 @@ module.exports = function(settings, done) {
   var mixin = {
 
     settings: $.extend({
+      startIndex: 0,
       scrollToSteps: true,
       steps: []
     }, settings),
@@ -22,7 +23,7 @@ module.exports = function(settings, done) {
 
     getInitialState: function() {
       return {
-        currentIndex: 0,
+        currentIndex: this.settings.startIndex,
         showTooltip: false,
         xPos: -1000,
         yPos: -1000
@@ -75,6 +76,14 @@ module.exports = function(settings, done) {
       $(window).off('resize', this.calculatePlacement);
     },
 
+    getUserTourProgress: function() {
+      return {
+        index: this.state.currentIndex,
+        percentageComplete: (this.state.currentIndex/this.settings.steps.length)*100,
+        step: this.settings.steps[this.state.currentIndex]
+      };
+    },
+
     preventWindowOverflow: function(value, axis, elWidth, elHeight) {
       var winWidth = parseInt($(window).width());
       var docHeight = parseInt($(document).height());