Added tour functionality to tutorial (#204)

Author: adamcarheden

build/cwc/tutorials.js

@@ -63,14 +63,26 @@ let replacePlaceholders = function(obj, pwd) {
   if (obj === null || typeof obj !== 'object') {
     return;
   }
-  let templateRE = /^___TEMPLATE___:(binary:)?/;
+  let templateRE = /^___TEMPLATE___:((json|binary):)?/;
   for (let k in obj) {
     if (!Object.prototype.hasOwnProperty.call(obj, k)) continue;
     const matches = k.match(templateRE);
     if (matches) {
-      const data = matches[1] ?
-        fs.readFileSync(pwd+'/'+obj[k]).toString('base64') :
-        fs.readFileSync(pwd+'/'+obj[k], 'utf8');
+      let data = '';
+      switch (matches[2]) {
+        case 'binary':
+          data = fs.readFileSync(pwd+'/'+obj[k]).toString('base64');
+          break;
+        case 'json':
+          data = JSON.parse(fs.readFileSync(pwd+'/'+obj[k], 'utf8'));
+          break;
+        case undefined:
+          data = fs.readFileSync(pwd+'/'+obj[k], 'utf8');
+          break;
+        default:
+          throw new Error('Unknown file type "' + matches[2] +
+            '" for template "'+k+'"');
+      }
       obj[k.replace(matches[0], '')] = data;
       delete obj[k];
     } else {
@@ -95,7 +107,8 @@ procTemplates(inDir, function(template) {
         if (err) {
           throw err;
         }
-        console.log(template.replace(base, ''), '->', target.replace(base, ''));
+        console.log('\t'+template.replace(base, ''), '->',
+          target.replace(base, ''));
       });
     });
   });

src/ui/select_screen/normal/basic/basic.soy

@@ -118,6 +118,15 @@
       {/call}
 
       <div class="mdl-grid cwc-tutorial-list">
+        {call cwc.soy.SelectScreenTemplate.fileCard data="all"}
+          {param title: 'Introduction to Coding with Chrome' /}
+          {param text: 'Everything you need to know to get started.' /}
+          {param opt_link_text: 'Learn CwC' /}
+          {param tutorial: 'cwc.cwct' /}
+          {param opt_color_class: 'bg-light-blue' /}
+          {param opt_icon: 'school' /}
+        {/call}
+
         {call cwc.soy.SelectScreenTemplate.fileCard data="all"}
           {param title: 'Blockly Basics' /}
           {param text: 'Learn drag-and-drop programming' /}

src/ui/tour/tour.js

@@ -75,12 +75,6 @@ cwc.ui.Tour.prototype.setTour = function(tour) {
       'showCancelLink': true,
     },
   });
-  this.tour_['once']('cancel', () => {
-    let sidebarInstance = this.helper.getInstance('sidebar');
-    if (sidebarInstance) {
-      sidebarInstance.setActive('tour', false);
-    }
-  });
   this.tourLength_ = tour['data'].length;
   for (let i in tour['data']) {
     if (!Object.prototype.hasOwnProperty.call(tour['data'], i)) continue;
@@ -128,13 +122,25 @@ cwc.ui.Tour.prototype.getTourDescription = function() {
   return this.tourDescription_ || '';
 };
 
+/**
+ * @return {Shepherd.Tour|boolean}
+ */
+cwc.ui.Tour.prototype.getTour = function() {
+  return this.tour_ || false;
+};
 
 cwc.ui.Tour.prototype.startTour = function() {
   if (!this.tour_) {
     return;
   }
   this.tour_.cancel();
   this.log_.info('Starting tour with', this.tourLength_, 'steps...');
+  this.tour_['once']('cancel', () => {
+    let sidebarInstance = this.helper.getInstance('sidebar');
+    if (sidebarInstance) {
+      sidebarInstance.setActive('tour', false);
+    }
+  });
   let sidebarInstance = this.helper.getInstance('sidebar');
   if (sidebarInstance) {
     sidebarInstance.showContent('tour', 'Tour', this.tourDescription_);
@@ -160,47 +166,65 @@ cwc.ui.Tour.prototype.clear = function() {
   this.tourLength_ = 0;
 };
 
-
 /**
- * @param {number} step
+ * @param {number} stepNumber
+ * @param {number} tourLength
+ * @param {function} cancel
  * @return {!array}
  * @private
  */
-cwc.ui.Tour.prototype.processButtons_ = function(step) {
+cwc.ui.Tour.prototype.getStepButtons = function(stepNumber, tourLength,
+  cancel) {
   let tourButtons = [];
   // Back button
-  if (step > 0) {
+  if (stepNumber > 0) {
     tourButtons.push({
       'text': i18t('@@GENERAL__BACK'),
-      'action': this.tour_['back'],
+      // The inline func lets us call getStepButtons before this.tour_ is set
+      'action': () => {
+        this.tour_['back']();
+      },
       'classes': 'shepherd-button-secondary',
     });
   }
 
   // Exit
-  if (step == 0) {
+  if (stepNumber == 0) {
     tourButtons.push({
       'text': i18t('@@GENERAL__EXIT'),
-      'action': this.cancelTour.bind(this),
+      'action': cancel,
       'classes': 'shepherd-button-secondary',
     });
   }
 
   // Done
-  if (step == this.tourLength_ - 1) {
+  if (stepNumber == tourLength - 1) {
     tourButtons.push({
       'text': i18t('@@GENERAL__DONE'),
-      'action': this.cancelTour.bind(this),
+      'action': cancel,
       'classes': 'shepherd-button-example-primary',
     });
   }
   // Next button
-  if (step < this.tourLength_ - 1) {
+  if (stepNumber < tourLength - 1) {
     tourButtons.push({
       'text': i18t('@@GENERAL__NEXT'),
-      'action': this.tour_['next'],
+      // The inline func lets us call getStepButtons before this.tour_ is set
+      'action': () => {
+        this.tour_['next']();
+      },
       'classes': 'shepherd-button-example-primary',
     });
   }
   return tourButtons;
 };
+
+/**
+ * @param {number} stepNumber
+ * @return {!array}
+ * @private
+ */
+cwc.ui.Tour.prototype.processButtons_ = function(stepNumber) {
+  return this.getStepButtons(stepNumber, this.tourLength_,
+    this.cancelTour.bind(this));
+};

src/ui/tutorial/tutorial.js

@@ -116,6 +116,9 @@ cwc.ui.Tutorial = function(helper) {
 
   /** @private {Element} */
   this.rootNode_ = null;
+
+  /** @private {cwc.ui.Tour} */
+  this.tour_ = this.helper.getInstance('tour');
 };
 
 
@@ -229,6 +232,24 @@ cwc.ui.Tutorial.prototype.addStep_ = async function(stepTemplate, id) {
     await this.appendBinaries_(stepTemplate['images'], images, 'image');
   }
 
+  let tour = false;
+  if (stepTemplate['tour']) {
+    if (Array.isArray(stepTemplate['tour'])) {
+      tour = stepTemplate['tour'];
+      tour.forEach((step, stepNumber) => {
+        if (!('buttons' in step)) {
+          step['buttons'] = this.tour_.getStepButtons(stepNumber, tour.length,
+            () => {
+            this.cancelTour_();
+          });
+        }
+      });
+    } else {
+      this.log_.warn('Skipping tour for step', id, 'because it is not an array',
+        stepTemplate['tour']);
+    }
+  }
+
   this.steps_[id] = {
     code: code,
     description: description,
@@ -237,6 +258,7 @@ cwc.ui.Tutorial.prototype.addStep_ = async function(stepTemplate, id) {
     title: stepTemplate['title'] || '',
     validate: stepTemplate['validate'] || false,
     videos: stepTemplate['videos'] || [],
+    tour: tour,
   };
 };
 
@@ -444,6 +466,7 @@ cwc.ui.Tutorial.prototype.startTutorial = function() {
             video['youtube_id']
           ),
           hasCode: step.code && step.code.trim().length > 0,
+          hasTour: !!step.tour,
         })),
       }
     );
@@ -533,6 +556,7 @@ cwc.ui.Tutorial.prototype.initSteps_ = function() {
     step.node = stepNode;
     step.nodeContinue = stepNode.querySelector(classPrefix + 'continue');
     step.nodeLoadCode = stepNode.querySelector(classPrefix + 'load-code');
+    step.nodeLoadTour = stepNode.querySelector(classPrefix + 'load-tour');
     step.nodeHeader = stepNode.querySelector(classPrefix + 'header');
     step.nodeListMediaExpand = stepNode.querySelectorAll(classPrefix +
       'media-expand');
@@ -557,6 +581,10 @@ cwc.ui.Tutorial.prototype.initStepButtons_ = function() {
       goog.events.listen(step.nodeLoadCode, goog.events.EventType.CLICK,
         this.loadCodeWithPrompt_.bind(this));
     }
+    if (step.nodeLoadTour) {
+      goog.events.listen(step.nodeLoadTour, goog.events.EventType.CLICK,
+        this.loadTour.bind(this));
+    }
     goog.events.listen(step.nodeHeader, goog.events.EventType.CLICK,
       this.jumpToStep_.bind(this, step.id));
 
@@ -602,8 +630,18 @@ cwc.ui.Tutorial.prototype.jumpToStep_ = function(stepID) {
       activeStepID: stepID,
     });
   }
+  this.cancelTour_();
 };
 
+/**
+ * @private
+ */
+cwc.ui.Tutorial.prototype.cancelTour_ = function() {
+  let tour = this.tour_.getTour();
+  if (tour) {
+    tour.cancel();
+  }
+};
 
 /**
  * Scrolls the tutorial to the top of the given step.
@@ -747,10 +785,14 @@ cwc.ui.Tutorial.prototype.showMedia_ = function(media) {
  * @private
  */
 cwc.ui.Tutorial.prototype.setState_ = function(change) {
+  let previousActiveStepID = this.state_.activeStepID;
   let isEditorDirty = this.isEditorDirty_();
   Object.keys(change).forEach((key) => {
     this.state_[key] = change[key];
   });
+  if (previousActiveStepID != this.state_.activeStepID) {
+    this.cancelTour_();
+  }
   this.updateView_();
   if (!isEditorDirty) {
     this.loadCode_();
@@ -807,6 +849,7 @@ cwc.ui.Tutorial.prototype.loadCodeWithPrompt_ = function() {
   });
 };
 
+
 /**
  * Loads example code into editor
  * @private
@@ -825,6 +868,28 @@ cwc.ui.Tutorial.prototype.loadCode_ = function() {
   this.restartValidate_();
 };
 
+/**
+ * Starts a per-step tour
+ * @private
+ */
+cwc.ui.Tutorial.prototype.loadTour = function() {
+  let step = this.getActiveStep_();
+  if (!step.tour) {
+    this.log_.warn('loadTour called for step with no tour');
+    return;
+  }
+  if (!this.tour_) {
+    this.log_.error('No tour instnace, can\'t load tour');
+    return;
+  }
+  this.tour_.setTour({
+    'description': 'Tutorial Tour', // TODO(carheden): Merge tutorial/tour
+    'data': step.tour,
+  });
+  this.cancelTour_();
+  this.tour_.getTour().start();
+};
+
 /**
  * Updates the view to reflect the current state
  * @private

src/ui/tutorial/tutorial.soy

@@ -77,6 +77,7 @@
   {@param images: list<string>}
   {@param isLastStep: bool}
   {@param hasCode: bool}
+  {@param hasTour: bool}
   {@param number: number}
   {@param online: bool}
   {@param prefix: string}
@@ -124,11 +125,16 @@
         <div class="{$prefix}actions">
           {if $hasCode}
             <button type="button" class="mdl-button mdl-js-button mdl-button--colored mdl-button--raised {$prefix}load-code">
-              <i class='material-icons'>chevron_left</i><label>Load Example Code</label>
+              <i class='material-icons'>chevron_left</i><label>{msg desc="Overwrite the content of the editor with the example code for the current step"}Load Example Code{/msg}</label>
+            </button>
+          {/if}
+          {if $hasTour}
+            <button type="button" class="mdl-button mdl-js-button mdl-button--colored mdl-button--raised {$prefix}load-tour">
+              <label>{msg desc="Shows the user what to do by opening a set of modal dialogs that point to areas of the scren"}Show Me{/msg}</label>
             </button>
           {/if}
           {if not $isLastStep}
-            <button type="button" class="mdl-button mdl-js-button mdl-button--colored mdl-button--raised {$prefix}continue">Continue</button>
+            <button type="button" class="mdl-button mdl-js-button mdl-button--colored mdl-button--raised {$prefix}continue">{msg desc="Continue to the next step"}Continue{/msg}</button>
           {/if}
         </div>
     </div>

static_files/resources/tour/basic/blocks/cwc.cwct

@@ -61,7 +61,7 @@
         }, {
           "title": "Tooltips",
           "attachTo": {
-            "element": "#cwc-status-button-body",
+            "element": "#cwc-preview-status-button-body",
             "on": "right"
           },
           "text": "Coding with Chrome has lots of buttons. Hover your mouse over one to see what it does."
@@ -94,4 +94,4 @@
   },
   "mode": "basic_blockly",
   "ui": "blockly"
-}
+}

static_files/tutorials/basic/blocks/blockly.cwct/cwct.template

@@ -43,7 +43,8 @@
             "validate": {
 							"type": "function",
 							"___TEMPLATE___:value": "eng/step1/validate.js"
-						}
+						},
+            "___TEMPLATE___:json:tour": "eng/step1/tour.json"
           },
           {
             "title": "Fill it with blue",

static_files/tutorials/basic/blocks/blockly.cwct/eng/step1/tour.json

@@ -0,0 +1,10 @@
+[
+  {
+    "title": "Add a circle",
+    "attachTo": {
+      "element": ".blocklyTreeRowItem_draw",
+      "on": "right"
+    },
+    "text": "Drag a 'Circle' block into the editor"
+  }
+]