intro 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 05b237765af1bce1116c0200ead3508884e27c6c25836ad9f77dd4d0ab46daec
+  data.tar.gz: 4549d34e11f742793c0777864b2cae15af2af560dbc5699d536eb00212f21fbc
+SHA512:
+  metadata.gz: 093c5406aeac8563ebc3fa0570368a8a6fb3a9d740db83926d74bd1c13cee5b93f1bb7a8537ac6cdf2818df59dcd2723e353557576b09d38e6ae47f77429784a
+  data.tar.gz: 705c2f9ae8ab41f811b240aee3728aefb4c87b2555138ac0376296d4f7046afa647e3fc23c5ee02e3565a83f68790049ca09aa500d13e40e04722fb042fc080b

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2019 jimcheung
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,111 @@
+# Intro
+
+[![Gem Version](https://badge.fury.io/rb/intro.svg)](https://badge.fury.io/rb/intro)
+[![Build Status](https://travis-ci.org/jinhucheung/intro.svg?branch=master)](https://travis-ci.org/jinhucheung/intro)
+
+Intro brings your rails application to new feature introduction and step-by-step users guide.
+
+Intro injects dynamically-generated [Shepherd.js](https://github.com/shipshapecode/shepherd) code into  your application whenever user should see a guided tour.
+
++ Define tour content supports image in a backstage.
++ Easy to change tours styles or add a theme.
++ Play nicely with Turbolinks.
++ Friendly to non-developers.
+
+## Todo
+
++ Supporting tour content with many languages.
++ Supporting to display tour when user is not logined.
+
+## Demo
+
+[Demo](https://intro-demo.herokuapp.com/)
+
+## Installation
+
+Add `intro` to application's Gemfile:
+
+```
+gem 'intro'
+```
+
+And then execute:
+
+```
+$ bundle install
+```
+
+Copy migrations and configurations:
+
+```
+$ rails generate intro:install
+```
+
+Then do migrate:
+
+```
+$ bundle exec rake db:migrate
+```
+
+## Usage
+
+### Inserting assets into view
+
+Insert `intro_tags` into common layout, just before the closing body tag:
+
+```
+<%= intro_tags %>
+</body>
+</html>
+```
+
+`intro_tags` imports assets of intro and adds `_intro` global variable with options.
+
+**Note**: `intro_tags` must be inserted into body tag for refreshing `_intro` variable if you need to use Turbolinks.
+
+### Adding tour in backstage
+
+Visit `http://localhost:3000/intro/admin` to backstage after starting server. In `config/initializers/intro.rb` file, you can get the default username and password for logining.
+
+Then add tour and define content. After filling out the content, you need to publish tour.
+
+### Customizing tour style
+
+If the default style doesn't satisfy you, you need to run assets generator:
+
+```
+$ rails generate intro:assets
+```
+
+Then you would get the asset files:
+
+```
+app/assets/stylesheets/intro/shepherd/_variables.scss
+app/assets/stylesheets/intro/shepherd/base.scss
+```
+
+Change them for your need.
+
+### Configuring intro
+
+see `config/initializers/intro.rb` for detail configuration.
+
+## Thanks
+
++ [shepherd](https://github.com/shipshapecode/shepherd)
++ [abraham](https://github.com/actmd/abraham)
+
+## Contributing
+
+Bug report or pull request are welcome.
+
+1. Fork it
+2. Create your feature branch (git checkout -b my-new-feature)
+3. Commit your changes (git commit -am 'Add some feature')
+4. Push to the branch (git push origin my-new-feature)
+
+Please write unit test with your code if necessary.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](MIT-LICENSE).

data/Rakefile

@@ -0,0 +1,12 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+APP_RAKEFILE = File.expand_path("../spec/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+
+load 'rails/tasks/statistics.rake'
+
+Bundler::GemHelper.install_tasks

data/app/assets/javascripts/intro/admin/application.js

@@ -0,0 +1,2 @@
+//= require jquery
+//= require jquery_ujs

data/app/assets/javascripts/intro/application.js

@@ -0,0 +1 @@
+//= require ./shepherd

data/app/assets/javascripts/intro/shepherd.js

@@ -0,0 +1,314 @@
+//= require shepherd.min
+
+(function () {
+  // utils
+
+  /**
+   * Merge defaults with user options
+   * @private
+   * @param {Object} defaults Default settings
+   * @param {Object} options User options
+   * @returns {Object} Merged values of defaults and options
+   * @thanks https://gist.github.com/pbojinov/8f3765b672efec122f66
+   */
+  function extend (defaults, options) {
+    var extended = {}
+    var prop
+    for (prop in defaults) {
+      if (Object.prototype.hasOwnProperty.call(defaults, prop)) {
+        extended[prop] = defaults[prop]
+      }
+    }
+    for (prop in options) {
+      if (Object.prototype.hasOwnProperty.call(options, prop)) {
+        extended[prop] = options[prop]
+      }
+    }
+    return extended
+  }
+
+  /**
+   * JavaScript cookies - cookies.js
+   * @thanks https://gist.github.com/abhiomkar/1363648
+   */
+  function getCookie (name) {
+    var dc = document.cookie
+    var prefix = name + '='
+    var begin = dc.indexOf('; ' + prefix)
+    if (begin == -1) {
+      begin = dc.indexOf(prefix)
+      if (begin != 0) return null
+    } else {
+      begin += 2
+    }
+    var end = document.cookie.indexOf(';', begin)
+    if (end == -1) {
+      end = dc.length
+    }
+    return unescape(dc.substring(begin + prefix.length, end))
+  }
+
+  function createCookie (name, value, days) {
+    if (days) {
+      var date = new Date()
+      date.setTime(date.getTime() + (days*24*60*60*1000))
+      var expires = '; expires=' + date.toGMTString()
+    }
+    else var expires = ''
+    document.cookie = name + '=' + value + expires + '; path=/'
+  }
+
+  function loadIntro () {
+    var intro = window._intro
+
+    if (!intro) return
+
+    var locale = intro.locale
+    var shepherdOptions = intro.shepherd_options
+
+    function Tour(tour) {
+      this.tour = tour
+      this.shepherd = new Shepherd.Tour(extend({
+        classPrefix: 'intro',
+        defaultStepOptions: {
+          scrollTo: true
+        },
+        useModalOverlay: tour.options.overlay_visible
+      }, shepherdOptions))
+    }
+
+    Tour.prototype.setup = function () {
+      this.configure()
+      this.start()
+      return this
+    }
+
+    Tour.prototype.test = function (options) {
+      this.tour.options.steps.forEach(function (step) {
+        if (step.element && !document.querySelector(step.element)) {
+          step.element = options.element
+        }
+      })
+
+      this.configure()
+      this.start()
+    }
+
+    Tour.prototype.configure = function () {
+      locale.complete = this.tour.options.btn_complete_text || locale.complete
+
+      this.configureSteps(this.tour.options.steps)
+
+      this.shepherd.on('complete', this.complete.bind(this))
+      this.shepherd.on('cancel', this.cancel.bind(this))
+      this.shepherd.on('show', this.show.bind(this))
+    }
+
+    Tour.prototype.configureSteps = function (steps) {
+      var self = this
+
+      steps.forEach(function (step, index) {
+        var baseOptions = self.configureStepBase(step, index)
+        var btnOptions  = self.configureStepButtons(step, index, steps)
+
+        self.shepherd.addStep(extend(baseOptions, btnOptions))
+      })
+    }
+
+    Tour.prototype.configureStepBase = function (step, index) {
+      var options = {}
+      var popperOptions = {}
+
+      options.id = 'tour-' + index
+
+      if (step.title) {
+        options.title = step.title
+      }
+
+      if (step.image_url) {
+        options.text = '<div class="shepherd-image-box" x-placement="' + (step.image_placement || 'top') + '">' +
+                          '<div class="shepherd-image-box-content"><img height="' + step.image_height + 'px" width="' + step.image_width + 'px" src="' + encodeURI(step.image_url) + '"></div>' +
+                          (step.content ? ('<div class="shepherd-image-box-text">' + step.content + '</div>') : '') +
+                       '</div>'
+      } else if (step.content) {
+        options.text = '<div class="shepherd-text-box">' + step.content + '</div>'
+      }
+
+      if (step.element) {
+        options.attachTo = {
+          element: step.element,
+          on: (step.placement || 'bottom')
+        }
+        options.showOn = function () {
+          return document.querySelector(step.element)
+        }
+      }
+
+      options.showCancelLink = step.cancel_link
+
+      // @see https://github.com/FezVrasta/popper.js/issues/670
+      if (step.fixed_placement) {
+        popperOptions.modifiers = {
+          preventOverflow: {
+            escapeWithReference: true
+          }
+        }
+      }
+
+      options.tippyOptions = {
+        zIndex: (step.z_index || 99),
+        maxWidth: null,
+        popperOptions: popperOptions
+      }
+
+      return options
+    }
+
+    Tour.prototype.configureStepButtons = function (step, index, steps) {
+      var options = {}
+
+      if (this.tour.options.btn_visible == 1) {
+        if (index === 0) {
+          options.buttons = [{ text: locale.exit, action: this.shepherd.cancel, secondary: true }]
+          if (steps.length === 1) {
+            options.buttons.push({ text: locale.complete, action: this.shepherd.complete })
+          } else {
+            options.buttons.push({ text: locale.next, action: this.next.bind(this) })
+          }
+        } else if (index === steps.length - 1) {
+          options.buttons = [
+            { text: locale.back, action: this.shepherd.back, secondary: true },
+            { text: locale.complete, action: this.shepherd.complete }
+          ]
+        } else {
+          options.buttons = [
+            { text: locale.back, action: this.shepherd.back, secondary: true },
+            { text: locale.next, action: this.next.bind(this) }
+          ]
+        }
+      } else {
+        options.buttons = []
+      }
+
+      return options
+    }
+
+    Tour.prototype.start = function () {
+      var firstStep = this.shepherd.steps[0]
+
+      if (firstStep && (!firstStep.options.attachTo || firstStep.options.showOn())) {
+        this.shepherd.start()
+      } else {
+        this.shepherd.cancel()
+      }
+    }
+
+    Tour.prototype.next = function () {
+      var shepherd = this.shepherd
+      var nextStep = shepherd.steps[shepherd.steps.indexOf(shepherd.getCurrentStep()) + 1]
+
+      if (nextStep && (!nextStep.options.attachTo || nextStep.options.showOn())) {
+        shepherd.next()
+      } else {
+        shepherd.cancel()
+      }
+    }
+
+    Tour.prototype.hide = function () {
+      this.shepherd.hide()
+    }
+
+    Tour.prototype.show = function (e) {
+      var self = this
+
+      setTimeout(function () {
+        var element = e.step.el
+
+        var image = element.querySelector('.shepherd-image-box img')
+        if (image) {
+          image.onload = function () {
+            document.body.scrollTop = document.documentElement.scrollTop = window.screenTop + 1
+          }
+        }
+
+        if (self.tour.options.overlay_visible) {
+          var container = element.closest('.tippy-popper')
+          var preContrainer = container && container.previousElementSibling
+
+          if (preContrainer.classList.contains((self.shepherd.classPrefix || '') + 'shepherd-modal-overlay-container')) {
+            preContrainer.style.zIndex = e.step.options.tippyOptions.zIndex
+          }
+        }
+      }, 0)
+    }
+
+    Tour.prototype.complete = function () {
+      this.record('complete')
+
+      if (this.tour.options.btn_complete_link) {
+        window.open(this.tour.options.btn_complete_link)
+      }
+    }
+
+    Tour.prototype.cancel = function () {
+      this.record('cancel')
+    }
+
+    Tour.prototype.record = function (action) {
+      if (!this.tour.id) return
+
+      createCookie('intro-tour-' + this.tour.id, (action || 'complete'), 7300)
+
+      var xhr = new XMLHttpRequest()
+      var csrfToken = document.querySelector('meta[name="csrf-token"]')
+
+      xhr.open('POST', intro.record_tours_path)
+      csrfToken && xhr.setRequestHeader('X-CSRF-Token', csrfToken.content)
+      xhr.setRequestHeader('Content-Type', 'application/json')
+      xhr.send(JSON.stringify({
+        id: this.tour.id
+      }))
+    }
+
+    intro.Tour = Tour
+
+    function loadTours () {
+      var xhr = new XMLHttpRequest()
+
+      xhr.open(
+        'GET',
+        intro.tours_path +
+        '?controller_path=' + encodeURIComponent(intro.controller) +
+        '&action_name=' + encodeURIComponent(intro.action) +
+        '&original_url=' + encodeURIComponent(intro.original_url)
+      )
+      xhr.onload = function () {
+        if (xhr.status !== 200) return
+
+        var res = JSON.parse(xhr.response)
+
+        if (res.data) {
+          res.data.forEach(function (tour) {
+            if (tour && tour.options && !getCookie('intro-tour-' + tour.id)) {
+              new Tour(tour).setup()
+            }
+          })
+        }
+      }
+
+      xhr.send()
+    }
+
+    loadTours()
+  }
+
+  if (typeof Turbolinks !== 'undefined' && Turbolinks.supported) {
+    if (!window._introBindTurbolinks) {
+      document.addEventListener('turbolinks:load', loadIntro)
+
+      window._introBindTurbolinks = true
+    }
+  } else {
+    document.addEventListener('DOMContentLoaded', loadIntro)
+  }
+})()