Merge pull request #465 from musicEnfanthen/tutorials-back-button

feat(tutorials): add a back button for the tutorial steps
music-encoding · Jan 26, 2024 · 49073ee · 49073ee
2 parents 791bd34 + 5d131a8
commit 49073ee
Show file tree

Hide file tree

Showing 3 changed files with 77 additions and 26 deletions.
diff --git a/_layouts/tutorials-ES.html b/_layouts/tutorials-ES.html
@@ -42,15 +42,19 @@ <h3>Renderización</h3>
                     <!-- verovio rendering goes in here -->
                 </div>
             </div>
-            <button id="nextStepButton" class="btn btn-primary btn-sm float-right">Continúa <i class="icon icon-forward"></i></button>
-
+
             <div id="acknowledgments" style="display: none;">
                 <h3>Agradecimientos</h3>
                 <p>Este tutorial ha sido creado por:</p>
                 <ul id="ackList"></ul>
                 <p>y traducido en la Universida de Alicante por Alba Bedbar y David Rizo</p>
             </div>
 
+            <div id="navigationButtons" style="width: 100%;">
+                <button id="previousStepButton" style="display: none;" class="btn btn-primary btn-sm float-left" ><i class="icon icon-back"></i> Atrás</button>
+                <button id="nextStepButton" style="display: none;" class="btn btn-primary btn-sm float-right">Continúa <i class="icon icon-forward"></i></button>
+            </div>  
+
             <ul id="stepBox" class="step">
                 <!-- tutorial step list goes in here -->
             </ul>

diff --git a/_layouts/tutorials.html b/_layouts/tutorials.html
@@ -42,14 +42,18 @@ <h3>Rendition</h3>
                     <!-- verovio rendering goes in here -->
                 </div>
             </div>
-            <button id="nextStepButton" class="btn btn-primary btn-sm float-right">Continue <i class="icon icon-forward"></i></button>
-
+
             <div id="acknowledgments" style="display: none;">
                 <h3>Acknowledgments</h3>
                 <p>This tutorial was brought to you by:</p>
                 <ul id="ackList"></ul>
             </div>
-
+
+            <div id="navigationButtons" style="width: 100%;">
+                <button id="previousStepButton" style="display: none;" class="btn btn-primary btn-sm float-left" ><i class="icon icon-back"></i> Back</button>
+                <button id="nextStepButton" style="display: none;" class="btn btn-primary btn-sm float-right">Continue <i class="icon icon-forward"></i></button>
+            </div>  
+
             <ul id="stepBox" class="step">
                 <!-- tutorial step list goes in here -->
             </ul>

diff --git a/js/mei-tutorials.js b/js/mei-tutorials.js
@@ -144,18 +144,13 @@ function setupTutorial(data, language) {
     loadTutorialStep(data, stepNum);
 
     //add listener to allow going to the next step
-    document.getElementById('nextStepButton').addEventListener('click',(e) => {
-        stepNum = parseInt(e.target.getAttribute('data-next-stepnum'), 10);
+    addStepListener(data, 'next');
+
+    //add listener to allow going to the previous step
+    addStepListener(data, 'previous');
+}
 
-        //catch any non numbers
-        if (isNaN(stepNum)) {
-            console.log('error getting next step number: ', stepNum, 'for event: ', e);
-        }
 
-        //load next step
-        loadTutorialStep(data, stepNum);
-    });        
-}
 
 /* 
  * function loadTutorialStep
@@ -166,20 +161,33 @@ function loadTutorialStep(data, stepNum) {
 
     console.log('\nloading step ' + stepNum + ', maximum step is ' + data.steps.length);
 
+    //get relevant elements on page
+    var editorContainer = document.getElementById('editorContainer');
+    var nextStepButton = document.getElementById('nextStepButton')
+    var previousStepButton = document.getElementById('previousStepButton');
+
     //if all steps are passed, move on to the final page, and skip rest of function
     if(stepNum >= data.steps.length) {
         showFinalPage(data);
+        previousStepButton.setAttribute('data-previous-stepnum',stepNum - 1);
         return true;
     }
 
-    // do not allow download or continuation before tutorial is set up
-    disallowDownload();
-    blockNextStep();
-    
+    //update navigation buttons to allow proceeding. listeners are set in setupTutorial() 
+    nextStepButton.setAttribute('data-next-stepnum',stepNum + 1);
+    previousStepButton.setAttribute('data-previous-stepnum',stepNum - 1);
+
     //retrieve step object from data
     var step = data.steps[stepNum];
     currentStep = step;
 
+    //do not allow going back if it is the first step
+    currentStep === data.steps[0] ? blockPreviousStep() : allowPreviousStep();
+
+    //do not allow download or continuation before tutorial is set up
+    disallowDownload();
+    blockNextStep();
+
     //adds heading as provided, falls back to plain step numbers
     document.getElementById('stepLabel').innerHTML = (typeof currentStep.label !== 'undefined' && currentStep.label !== '') ? currentStep.label : 'Step ' + (stepNum + 1);
     document.getElementById('fullFileTitle').innerHTML = currentStep.xmlFile;
@@ -191,13 +199,6 @@ function loadTutorialStep(data, stepNum) {
     var requiresEditor = (typeof currentStep.xmlFile !== 'undefined' && currentStep.xmlFile !== '') && typeof currentStep.xpaths !== 'undefined' && currentStep.xpaths.length > 0;
     var requiresPrefill = (typeof currentStep.prefillFile !== 'undefined' && currentStep.prefillFile !== '');
 
-    //get relevant elements on page
-    var editorContainer = document.getElementById('editorContainer');
-    var nextStepButton = document.getElementById('nextStepButton');
-
-    //update nextStepButton to allow proceeding. listener is set in setupTutorial() 
-    nextStepButton.setAttribute('data-next-stepnum',stepNum + 1);
-
     //show editor only when needed, allow to proceed without interaction
     if(!requiresEditor) {
         editorContainer.style.display = 'none';
@@ -236,6 +237,9 @@ function loadTutorialStep(data, stepNum) {
         .then(function(descriptionFile) {
             // update instruction section
             document.getElementById('instruction').innerHTML = descriptionFile;
+            nextStepButton.style.display = 'inline-block';
+            previousStepButton.style.display = 'inline-block';
+            document.getElementById('acknowledgments').style.display = 'none';
         })
         .catch(function(error) {
             console.error(tutorialStrings[LANG]['fetchOperationProblem'], currentStep.descFile, error.message);
@@ -477,6 +481,14 @@ function allowNextStep() {
     disallowHint();
 }
 
+/* 
+ * function allowPreviousStep
+ * This function enables the previousStepButton
+ */
+function allowPreviousStep() {
+    document.getElementById('previousStepButton').classList.remove('disabled');
+}
+
 /* 
  * function blockNextStep
  * This function disables the nextStepButton
@@ -486,6 +498,14 @@ function blockNextStep() {
     document.querySelector('.tutorialBox #editorBox').style.borderColor = 'orangered';
 }
 
+/*
+ * function blockPreviousStep
+ * This function disables the previousStepButton
+ */
+function blockPreviousStep() {
+    document.getElementById('previousStepButton').classList.add('disabled');
+}
+
 /* 
  * function allowDownload
  * This function enables the btn-openFullFileModal
@@ -578,6 +598,29 @@ function activateStepListItem(data,stepNum) {
     }
 }
 
+
+/*
+ * function addStepListener
+ * @param data: The content of a tutorial's JSON file
+ * @param direction: (string) either 'next' or 'previous'
+ * Adds a click listener to the next/previous step button
+ * and loads the next/previous step
+ */
+function addStepListener(data, direction) {
+    document.getElementById(direction + 'StepButton').addEventListener('click',(e) => {
+        var dataAttr = 'data-' + direction + '-stepnum';
+        stepNum = parseInt(e.target.getAttribute(dataAttr), 10);
+
+        //catch any non numbers
+        if (isNaN(stepNum)) {
+            console.error(`error getting ${direction} step number: ${stepNum} for event: ${e}`);
+        } else {
+            //load next step
+            loadTutorialStep(data, stepNum);
+        }
+    }); 
+}
+
 /* 
  * function fetchFile
  * @param file: The name of the file to retrieve