abraham 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 798c89c53a20fc5d954a4cee99c150957ff815e7
+  data.tar.gz: 2d6a3652a30b984510758e00fbf3683701b75c13
+SHA512:
+  metadata.gz: 2999a0ea6b03b1552d5c5d3acb9a48799c5241b5ab5d0a7b2964594848cb15688e1811a2c973fe119dab2d60e14488cb6731508fe52dbebacd473db40be80ca2
+  data.tar.gz: 3a3beb3fdc9eee073339a2269d783b6f683a22e5b280859ce6ecc28fb652eacee16b010d3e4ecd1f55105662f6e252c42d46193a69ee5129f61087277236503d

data/README.md

@@ -0,0 +1,108 @@
+# Abraham
+
+_Guide your users in the one true path._
+
+![Watercolor Sheep](https://upload.wikimedia.org/wikipedia/commons/e/e4/Watercolor_Sheep_Drawing.jpg)
+
+Abraham injects dynamically-generated [Shepherd.js](http://github.hubspot.com/shepherd/docs/welcome/) code into your Rails application whenever a user should see a guided tour. Skip a tour, and we'll try again next time; complete a tour, and it won't show up again.
+
+* Define tour content with simple YAML files, in any/many languages.
+* Organize tours by controller and action.
+* Plays nicely with Turbolinks.
+
+## Requirements
+
+* devise? (for current_user)
+
+## Installation
+
+Add Abraham to your Gemfile:
+
+```
+gem 'abraham'
+```
+
+Then run:
+
+```
+$ bundle install
+$ rails generate abraham:install
+```
+
+Require Shepherd.js in `app/assets/javascripts/application.js`
+
+```
+//= require shepherd.js.js
+```
+
+Require a Shepherd.js CSS theme in `app/assets/stylesheets/application.scss`
+
+```
+//= require "shepherd.js/dist/css/shepherd-theme-default"
+```
+
+Shepherd.js provides the following themes:
+
+- `shepherd-theme-arrows`
+- `shepherd-theme-arrows-fix`
+- `shepherd-theme-arrows-plain-buttons`
+- `shepherd-theme-dark`
+- `shepherd-theme-default`
+- `shepherd-theme-square`
+- `shepherd-theme-square-dark`
+
+## Defining your tours
+
+Define your tours in the `config/tours` directory. Its directory structure should mirror your application's controllers, and the tour files should mirror your actions/views.
+
+```
+config/
+└── tours/
+    └── blog/
+    │   ├── show.en.yml
+    │   └── show.es.yml    
+    └── articles/
+        ├── index.en.yml
+        ├── index.es.yml
+        ├── show.en.yml
+        └── show.es.yml
+```
+
+NB: You must specify a locale in the filename, even if you're only supporting one language.
+
+### Tour content
+
+A tour is composed of a series of steps. A step may have a title and must have a description. You may attach a step to a particular element on the page, and place the callout to the left, right, top, or bottom. 
+
+```yaml
+intro:
+  steps:
+    1:
+      text: "Welcome to your dashboard! This is where we'll highlight key information to manage your day."
+    2:
+      title: "Events"
+      text: "If you're participating in any events today, we'll show that here."
+      attachTo:
+        element: ".dashboard-events"
+        placement: "right"
+    3:
+      title: "Search"
+      text: "You can find anything else by using the search bar."
+      attachTo:
+        element: ".navbar-primary form"
+        placement: "bottom"
+```
+
+Abraham takes care of which buttons should appear with each step:
+
+* "Later" and "Continue" buttons on the first step
+* "Exit" and "Next" buttons on intermediate steps
+* "Done" button on the last step
+
+### Testing your tours
+
+Abraham loads tour definitions once when you start your server. If you'd like to iteratively test changes without restarting your server, use the Rails console to rerun the initializer:
+
+```
+???
+```

data/Rakefile

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Abraham'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path('../test/dummy/Rakefile', __FILE__)
+load 'rails/tasks/engine.rake'
+
+load 'rails/tasks/statistics.rake'
+
+require 'bundler/gem_tasks'
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+task default: :test

data/app/controllers/abraham_histories_controller.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+class AbrahamHistoriesController < ApplicationController
+  def create
+    @abraham_history = AbrahamHistory.new(abraham_history_params)
+    @abraham_history.creator_id = current_user
+    respond_to do |format|
+      if @abraham_history.save
+        format.json { render json: @abraham_history, status: :created }
+      else
+        format.json { render json: @abraham_history.errors, status: :unprocessable_entity }
+      end
+    end
+  end
+
+  private
+
+  # Never trust parameters from the scary internet, only allow the white list through.
+  def abraham_history_params
+    params.require(:abraham_history).permit(:controller_name, :action_name, :tour_name)
+  end
+end

data/app/helpers/abraham_helper.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+module AbrahamHelper
+  def abraham_tour
+    # Do we have tours for this controller/action in the user's locale?
+    tours = Rails.configuration.abraham.tours["#{controller_name}.#{action_name}.#{I18n.locale}"]
+
+    unless tours
+      # How about the default locale?
+      tours = Rails.configuration.abraham.tours["#{controller_name}.#{action_name}.#{I18n.default_locale}"]
+    end
+
+    if tours
+      completed = AbrahamHistory.where(
+        creator_id: current_user, controller_name: controller_name,
+        action_name: action_name
+      )
+      remaining = tours.keys - completed.map(&:tour_name)
+
+      if remaining.any?
+        # Generate the javascript snippet for the next remaining tour
+        render(partial: 'application/abraham',
+               locals: { tour_name: remaining.first,
+                         steps: tours[remaining.first]['steps'] })
+      end
+    end
+  end
+end

data/app/models/abraham_history.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+class AbrahamHistory < ApplicationRecord
+end

data/app/models/application_record.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+class ApplicationRecord < ActiveRecord::Base
+  self.abstract_class = true
+end

data/app/views/application/_abraham.html.erb

@@ -0,0 +1,49 @@
+<script>
+  var tour = new Shepherd.Tour({
+    defaults: {
+      classes: '<%= Rails.configuration.abraham.default_theme %>'
+    }
+  });
+
+  tour.on("complete", function() {
+    // ajax
+    return $.ajax({
+      url: "/abraham_histories/",
+      type: "POST",
+      dataType: "json",
+      contentType: "application/json",
+      data: JSON.stringify({
+        controller_name: '<%= controller_name %>',
+        action_name: '<%= action_name %>',
+        tour_name: '<%= tour_name %>'
+      })
+    });
+  });
+
+  <% steps.each_with_index do |(key, step), index| %>
+  tour.addStep('step-<%= key %>', {
+    <% if step.key?('title') %>
+    title: "<%= step['title'] %>",
+    <% end %>
+    text: "<%= step['text'] %>",
+    <% if step.key?('attachTo') %>
+    attachTo: { element: "<%= step['attachTo']['element'] %>", on: "<%= step['attachTo']['placement'] %>" },
+    <% end %>
+    buttons: [
+    <% if index == 0 %>
+      { text: '<%= t('abraham.later') %>', action: tour.cancel, classes: 'shepherd-button-secondary' },
+      { text: '<%= t('abraham.continue') %>', action: tour.next }
+    <% else %>
+        <% if index == steps.size - 1 %>
+      { text: '<%= t('abraham.done') %>', action: tour.complete }
+        <% else %>
+      { text: '<%= t('abraham.exit') %>', action: tour.cancel, classes: 'shepherd-button-secondary' },
+      { text: '<%= t('abraham.next') %>', action: tour.next }
+        <% end %>
+    <% end %>
+    ]
+  });
+  <% end %>
+
+  tour.start();
+</script>

data/config/locales/en.yml

@@ -0,0 +1,7 @@
+en:
+  abraham:
+    later: "Later"
+    continue: "Continue"
+    exit: "Exit"
+    done: "Done"
+    next: "Next"

data/config/locales/es.yml

@@ -0,0 +1,7 @@
+es:
+  abraham:
+    later: "Luego"
+    continue: "Continuar"
+    exit: "Dejar"
+    done: "Hecho"
+    next: "Siguiente"

data/config/routes.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+Rails.application.routes.draw do
+  resources :abraham_histories, only: :create
+end

data/lib/abraham.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+require 'abraham/engine'
+
+module Abraham
+end

data/lib/abraham/engine.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+require 'rubygems'
+require 'rails-assets-shepherd.js'
+require 'jquery-rails'
+
+module Abraham
+  class Engine < ::Rails::Engine
+  end
+end

data/lib/abraham/version.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+module Abraham
+  VERSION = '0.1.0'
+end

data/lib/generators/abraham/install_generator.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+require 'rails/generators'
+require 'rails/generators/active_record'
+
+module Abraham
+  module Generators
+    class InstallGenerator < ActiveRecord::Generators::Base
+      argument :name, type: :string, default: 'random_name'
+
+      class_option :'skip-migration', type: :boolean, desc: "Don't generate a migration for the histories table"
+      class_option :'skip-initializer', type: :boolean, desc: "Don't generate an initializer"
+
+      source_root File.expand_path(File.join(File.dirname(__FILE__), 'templates'))
+
+      # Copies the migration template to db/migrate.
+      def copy_files
+        return if options['skip-migration']
+        migration_template 'migration.rb', 'db/migrate/create_abraham_histories.rb'
+      end
+
+      def create_initializer
+        return if options['skip-initializer']
+        copy_file 'initializer.rb', 'config/initializers/abraham.rb'
+      end
+    end
+  end
+end

data/lib/generators/abraham/templates/initializer.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+Rails.application.configure do
+  tours = {}
+
+  if Rails.root.join('config/tours').exist?
+    Dir[Rails.root.join('config/tours/*/')].each do |dir|
+      Dir[dir + '*.yml'].each do |yml|
+        path_parts = yml.split(File::SEPARATOR)
+        controller = path_parts[path_parts.size - 2]
+        file_parts = path_parts[path_parts.size - 1].split('.')
+        action = file_parts[0]
+        locale = file_parts[1]
+        t = YAML.load_file(yml)
+        tours["#{controller}.#{action}.#{locale}"] = t
+      end
+    end
+  end
+
+  config.abraham.default_theme = 'shepherd-theme-default'
+  config.abraham.tours = tours
+end

data/lib/generators/abraham/templates/migration.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+class CreateAbrahamHistories < ActiveRecord::Migration[5.0]
+  def change
+    create_table :abraham_histories do |t|
+      t.string :controller_name
+      t.string :action_name
+      t.string :tour_name
+      t.references :creator, null: false, index: true
+
+      t.timestamps index: true
+    end
+  end
+end

data/lib/tasks/abraham_tasks.rake

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+# desc "Explaining what the task does"
+# task :abraham do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,152 @@
+--- !ruby/object:Gem::Specification
+name: abraham
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jonathan Abbett
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-11-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.0.0
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.0.0.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.0.0
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.0.0.1
+- !ruby/object:Gem::Dependency
+  name: sass-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rails-assets-shepherd.js
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: jquery-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Guide your users in the one true path.
+email:
+- jonathan@act.md
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- app/assets/config/abraham_manifest.js
+- app/controllers/abraham_histories_controller.rb
+- app/helpers/abraham_helper.rb
+- app/models/abraham_history.rb
+- app/models/application_record.rb
+- app/views/application/_abraham.html.erb
+- config/locales/en.yml
+- config/locales/es.yml
+- config/routes.rb
+- lib/abraham.rb
+- lib/abraham/engine.rb
+- lib/abraham/version.rb
+- lib/generators/abraham/install_generator.rb
+- lib/generators/abraham/templates/initializer.rb
+- lib/generators/abraham/templates/migration.rb
+- lib/tasks/abraham_tasks.rake
+homepage: http://getabraham.com
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.8
+signing_key: 
+specification_version: 4
+summary: Trackable application tours for Rails with i18n support.
+test_files: []