first commit

2021-10-09 21:59:14 -04:00
commit 2e1a4017c3
6336 changed files with 864678 additions and 0 deletions
@@ -0,0 +1,105 @@
+# Framework7 Plugin Tour Guide
+
+## Brief description
+A plugin that takes advantage of Framework7 Popover elements to display a tour guide through your application.
+
+## Screenshots
+
+### Main Screen
+<img src="https://github.com/razekteixeira/Framework7-Plugin-Tour-Guide/blob/master/example/assets/screens/Main%20Screen.png" width="250">
+
+### First Step
+<img src="https://github.com/razekteixeira/Framework7-Plugin-Tour-Guide/blob/master/example/assets/screens/First%20Step.png" width="250">
+
+### Second Step
+<img src="https://github.com/razekteixeira/Framework7-Plugin-Tour-Guide/blob/master/example/assets/screens/Second%20Step.png" width="250">
+
+### Last Step
+<img src="https://github.com/razekteixeira/Framework7-Plugin-Tour-Guide/blob/master/example/assets/screens/Last%20Step.png" width="250">
+
+## Setup
+
+1) Copy tourguide.css and tourguide.js to your project and reference them:
+
+```html
+<link rel="stylesheet" href="tourguide.css">
+<script src="tourguide.js"></script>
+```
+2) Define tour steps
+
+```javascript
+var tourSteps = [
+    {
+        step: 0, 
+        header: '1st Tour Step', 
+        message: 'This is our first tour step.<br />Please click "next" or "back" to move forward and backwards respectively', 
+        element: "body > div.views > div > div.toolbar > div > a:nth-child(1)", 
+        action: function ()
+        {
+            console.log('Started guided tour');
+            console.log('Step 0');
+        }
+    }, 
+    {
+        step: 1, 
+        header: '2nd Tour Step', 
+        message: 'This is our seconds tour step.<br />You can use icons and images too! Wow!<br /><br /> F7 Icon:<br /> <i class="icon icon-back"></i><br /><br />Image:<br /> <div style="background-image: url(http://cdn.framework7.io/i/logo-new.png); width: 100px; height: 100px; background-size: cover; margin: 0 auto";></div><br />Please click "next" or "back" to move forward and backwards respectively', 
+        element: "body > div.views > div > div.navbar > div > div.right > a", 
+        action: function ()
+        {
+            console.log('Step 1');
+        }
+    }, 
+    {
+        step: 2, 
+        header: '3rd and Final Step', 
+        message: 'Congratulations! You have finished your Tour Guide tutorial. Enjoy it :D', 
+        element: "body > div.views > div > div.navbar > div > div.right > a", 
+        action: function ()
+        {
+            console.log('Step 2');
+            console.log('Last step on guided tour');
+        }
+    }];
+```
+
+Parameters
+
+- *step* Set a step id for this tour step
+- *header* Set the tour step header (plain text, HTML, ...)
+- *message* Set the tour step message (plain text, HTML, ...)
+- *element* Set the element where you want to point the tour step (CSS Selector)
+- *action* Define a function to execute some code snippet on current tour step or null if you don't want to do anything
+
+3) Initialize & options
+
+```javascript
+var myApp = new Framework7();
+var options = {...};
+            
+var tourguide = myApp.tourguide(tourSteps, options);
+```
+
+Available options (if not set, default will be used)
+
+- **previousButton** // optional, defaults to false
+- **nextButtonText** // optional next button text, defaults to 'Next'
+- **endTourButtonText** // optional endTourButtonText, defaults to 'Done'
+- **previousButtonText** // optional previousButtonText, defaults to 'Previous'
+- **template** // optional template for tour step, defaults to the defaultTourGuideTemplate
+- **customCSS** // optional css class, defaults to 'tour-guide-popover'
+
+## API
+
+The following methods are available on a tourguide instance
+
+```javascript
+tourguide.moveForward();         // moves to next step
+tourguide.moveBackward();        // moves to previous step if allowed
+```
+
+## Credits
+
+Developed by www.cesarteixeira.pt
+
+Please contribute ;)
@@ -0,0 +1,15 @@
+.tour-guide-popover {
+	border-radius: 0;
+}
+
+.tour-guide-popover .tour-guide-header-wrapper {
+	padding: 0 14px;
+}
+
+.tour-guide-popover .tour-guide-message-wrapper {
+	padding: 0 14px;
+}
+
+.tour-guide-popover .tour-guide-buttons-row {
+	width: 100%;
+}
@@ -0,0 +1,289 @@
+/*jslint browser: true*/
+/*global console, Framework7, alert, Dom7, Template7*/
+
+/**
+ * A plugin for Framework7 to help you with a tour guide within your app
+ *
+ * @module Framework7/prototype/plugins/tourguide
+ * @author www.timo-ernst.net
+ * @license MIT
+ */
+Framework7.prototype.plugins.tourguide = function (app) {
+  'use strict';
+  // Variables in module scope
+  var $$ = Dom7,
+    t7 = Template7, 
+    defaultTourGuideTemplate, 
+    TourGuide;
+    
+  /**
+   * Represents the tour guide
+   *
+   * @class
+   * @memberof module:Framework7/prototype/plugins/tourguide
+   */
+  TourGuide = function (tourSteps, options, currentStep) {
+    
+    // Private properties
+    var self = this,
+            defaults = {
+               previousButton: false, 
+               nextButtonText: 'Next', 
+               endTourButtonText: 'Done', 
+               previousButtonText: 'Previous', 
+               template: defaultTourGuideTemplate, 
+               customCSS: 'tour-guide-popover'
+            }, 
+            template, 
+            options = options || {}, 
+            tourSteps = tourSteps || [], 
+            currentStep = currentStep || 0;
+    
+    function setDefaultTemplate () {
+        defaultTourGuideTemplate = '<div class="popover popover-step-tutorial {{#if options.customCSS}}{{options.customCSS}}{{/if}}">' + 
+                                        '<div class="popover-angle"></div>' + 
+                                        '<div class="popover-inner">' + 
+                                            '<div class="tour-guide-container-wrapper">' + 
+                                                '<div class="tour-guide-header-wrapper"><p class="tour-guide-header">{{header}}</p></div>' + 
+                                                '<div class="tour-guide-message-wrapper"><p class="tour-guide-message">{{message}}</p></div>' + 
+                                            '</div>' + 
+                                            '<div class="tour-guide-toolbar-wrapper">' + 
+                                                '<div class="toolbar">' + 
+                                                    '<div class="toolbar-inner">' + 
+                                                        '<div class="row tour-guide-buttons-row">' + 
+                                                            '{{#if options.previousButton}}' + 
+                                                                '<div class="col-50">' + 
+                                                                    '<a href="#" class="button tour-guide-button tour-guide-previous-button" {{#unless options.enablePreviousButton}}disabled="disabled"{{/unless}}>{{options.previousButtonText}}</a>' + 
+                                                                '</div>' + 
+                                                            '{{/if}}' +
+                                                            '<div class="col-{{#if options.previousButton}}50{{else}}100{{/if}}">' + 
+                                                              '<a href="#" class="button tour-guide-button tour-guide-next-button">{{#if options.lastStep}}{{options.endTourButtonText}}{{else}}{{options.nextButtonText}}{{/if}}</a>' + 
+                                                            '</div>' +  
+                                                        '</div> ' + 
+                                                    '</div>' + 
+                                                '</div>' + 
+                                            '</div>' + 
+                                        '</div>' + 
+                                    '</div>';
+    };
+    
+    self.setMoveForwardAction = function () {
+        // Click handler to move forward on tour
+        $$(document).on('click', '.tour-guide-next-button', function (e) {
+          e.preventDefault();
+          e.stopImmediatePropagation();
+          e.stopPropagation();
+          
+            currentStep++;
+            
+            if (tourSteps.length === currentStep) {
+              console.log('No more steps');
+            }
+            else {
+                console.log('Next step');
+            }
+            
+            self.showTour(tourSteps, currentStep);
+        });
+    };
+    
+    self.setMoveBackwardAction = function () {
+        // Click handler to move forward on tour
+        $$(document).on('click', '.tour-guide-previous-button', function (e) {
+          e.preventDefault();
+          e.stopImmediatePropagation();
+          e.stopPropagation();
+          console.log('previous step');
+          
+            currentStep--;
+            
+            self.showTour(tourSteps, currentStep);
+        });
+    };
+    
+    self.moveFoward = function ()
+    {
+        if (+currentStep === tourSteps.length)
+        {
+            console.log('Last step, cannot move forward.');
+            return;
+        }
+        
+        currentStep++;
+            
+        if (tourSteps.length === currentStep) {
+          console.log('No more steps');
+        }
+        else {
+            console.log('Next step');
+        }
+
+        self.showTour(tourSteps, currentStep);
+    };
+    
+    self.moveBackward = function ()
+    {
+        if (+currentStep === 0)
+        {
+            console.log('First step, cannot move backwards.');
+            return;
+        }
+        
+        currentStep--;
+            
+        if (tourSteps.length === currentStep) {
+          console.log('No more steps');
+        }
+        else {
+            console.log('Next step');
+        }
+
+        self.showTour(tourSteps, currentStep);
+    };
+    
+    /**
+     * Shows the tour guide
+     *
+     * @public
+     * @memberof module:Framework7/prototype/plugins/tourguide
+     */
+    self.showTour = function () {
+        setTimeout(function () {
+            try {
+                // close previous modal if exists
+                app.closeModal();
+
+                // terminate tour
+                if (currentStep === (tourSteps.length)) {
+                    if (typeof tourSteps[currentStep] !== 'undefined' && 
+                        tourSteps[currentStep] !== null && 
+                        typeof tourSteps[currentStep].action !== "undefined" && 
+                        tourSteps[currentStep].action !== null && 
+                        typeof tourSteps[currentStep].action === "function") {
+                        tourSteps[currentStep].action();
+                    }
+                    
+                    currentStep = 0;
+
+                    return;
+                }
+
+                if (typeof tourSteps[currentStep].action !== "undefined" && 
+                        tourSteps[currentStep].action !== null && 
+                        typeof tourSteps[currentStep].action === "function") {
+                    tourSteps[currentStep].action();
+                }
+                
+                /*
+                 * popover arguments:
+                 *  - tourStep html
+                 *  - tourStep element
+                 *  - removeOnClose
+                 *  - animated
+                 *  - closeByOutside
+                 */
+                app.popover(tourSteps[currentStep].html, tourSteps[currentStep].element, true, true, false);
+            }
+            catch (framework7NotReadyException) {
+                console.log("Framework7 is not ready yet");
+                console.log(framework7NotReadyException);
+            }
+        }, 100);
+    };
+    
+    /**
+     * Sets the options that were required
+     *
+     * @private
+     */
+    function applyOptions() {
+      var def;
+      options = options || {};
+      for (def in defaults) {
+        if (typeof options[def] === 'undefined') {
+          options[def] = defaults[def];
+        }
+      }
+    }
+    
+    /**
+     * Compiles the template
+     *
+     * @private
+     */
+    function compileTemplate() {
+      if (!options.template) {
+        // Cache compiled templates
+        if (!app._compiledTemplates.tourguide) {
+          app._compiledTemplates.tourguide = t7.compile(defaultTourGuideTemplate);
+        }
+        template = app._compiledTemplates.tourguide;
+      } else {
+        template = t7.compile(options.template);
+      }
+    }
+    
+    self.prepareSteps = function () {
+        for (var step in tourSteps) {
+            var context = {};
+            
+            if (tourSteps[step].header) {
+                context.header = tourSteps[step].header;
+            }
+            
+            if (tourSteps[step].message) {
+                context.message = tourSteps[step].message;
+            }
+            
+            if (options.previousButton && 
+                    step > 0) {
+                options.enablePreviousButton = true;
+            }
+            
+            if (+step === tourSteps.length-1)
+            {
+                options.lastStep = true;
+            }
+            
+            context.options = options;
+            
+            try {
+                tourSteps[step].html = template(context);
+            }
+            catch (TemplateNotDefinedException) {
+                console.log('Failed to compile template with context');
+                console.log(TemplateNotDefinedException);
+            }
+        }
+    };
+
+    /**
+     * Initialize the instance
+     *
+     * @method init
+     */
+    (function () {
+        // define default template
+        setDefaultTemplate();
+        // Compile template
+        compileTemplate();
+        // apply options
+        applyOptions();
+        // Prepare steps
+        self.prepareSteps();
+        // set move forward action
+        self.setMoveForwardAction();
+        // set move backwards action
+        self.setMoveBackwardAction();
+      
+    }());
+    
+    // Return instance
+    return self;
+  };
+  
+  app.tourguide = function (tourSteps, options, currentStep) {
+    return new TourGuide(tourSteps, options, currentStep);
+  };
+  
+};