guided_tour 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 34caeb0b7eb9107de61ce073bc57113b2a78b1c814845e37f60dc20a2d695b33
+  data.tar.gz: 14cb5604d87c7c09e3c69b51aaa5cc3cc6a89d446662ff76269f56be05d13713
+SHA512:
+  metadata.gz: ba8083446e4a314a2d4a7385f4813e5a2149ef3c0e6adf12212c611c9c722ae7ae1115d641da821008b5c11e629b602c9ec73421a0d77703d4c3b7cf1a78d9c9
+  data.tar.gz: bdd249f0f7dad550a40ec913fba847cc88c3839319f3752b7ead1e41272b93e1894825e82fc4bbdab1a4c7c092470882924c946d01fd3385455c9d086100ddf1

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Benjamin Deutscher
+
+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,84 @@
+# GuidedTour
+
+A simple Stimulus controller and a helper that enables you to show a guided tour overlay on your website. It requires Bootstrap to be installed and have Popover loaded.
+
+This gem comes with the npm package [@itsbede/guided-tour](https://www.npmjs.com/package/@itsbede/guided-tour) that is installed and included into your apps `app/javascript/controller/application.js` by running the installer.
+
+## Requirements
+
+- Rails >= 7.1
+- stimulus-rails
+- jsbundling-rails with esbuild
+- Node.js & Yarn
+
+## Installation
+
+1. Add to your Gemfile:
+    ```ruby
+    gem 'guided_tour'
+    ```
+2. Run installer
+    ```bash
+      ./bin/rails guided_tour:install
+    ```
+   
+## Usage
+In your view
+```html
+<!-- this is the example markup of you page that you want to guide the user through -->
+<ul>
+  <li id="foo">Foo</li>
+  <li id="bar">Bar</li>
+  <li id="baz">Baz</li>
+</ul>
+
+<!-- this is the gems helper code --> 
+<%= guide_through(t('home.guide')) %>
+
+<!-- if you like to go hardcoded you can hand in the map directly -->
+<%= guide_through(
+    { foo: "This is explanation for the element with the html id foo",
+      bar: "This is explanation for the element with the html id bar",
+      baz: "This is explanation for the element with the html id baz" }
+) %>
+```
+
+In your locale .yml
+```yaml
+# config/locales/en.yml
+---
+en:
+  # ...
+  home:
+    guide:
+      foo: This is explanation for the element with the html id foo
+      bar: This is explanation for the element with the html id bar
+      baz: This is explanation for the element with the html id baz
+  # ...
+```
+
+## Customization
+
+You can customize the header and the navigation buttons of the popover by defining this keys in your locale .yml
+
+```yaml
+en:
+  guided-tour:
+    next-btn-text: "Your custom Next button text"
+    prev-btn-text: "Your custom Back button text"
+    done-btn-text: "Your custom Done button text"
+    step-line: "Step {{current}} of {{total}}"
+
+de:
+  guided-tour:
+    next-btn-text: "Weiter"
+    prev-btn-text: "Zurück"
+    done-btn-text: "Fertig"
+    step-line: "Erklärung {{current}} von {{total}}"
+```
+
+Make sure to include `{{current}}` and `{{total}}` in your `step-line` key to have the progress of the tour shown.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"

data/app/controllers/guided_tour/application_controller.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module GuidedTour
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/helpers/guided_tour/application_helper.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module GuidedTour
+  module ApplicationHelper
+    # Generate guided tour markup
+    # @param map [Hash] target element ids as keys, explantions as values
+    # @return [String] the html markups as html_safe
+    def guide_through(map)
+      tag.div(class: 'guided-tour--wrapper', data: {
+        controller: 'guided-tour--tour',
+        guided_tour__tour_next_btn_text_value: t('guided-tour.next-btn-text'),
+        guided_tour__tour_prev_btn_text_value: t('guided-tour.prev-btn-text'),
+        guided_tour__tour_done_btn_text_value: t('guided-tour.done-btn-text'),
+        guided_tour__tour_step_line_text_value: t('guided-tour.step-line')
+      }) do
+        safe_join([
+                    tag.div(class: 'guided-tour--starter-btn-wrapper') do
+                      safe_join([
+                                  tag.button(type: 'button', class: 'btn btn-primary ms-auto', id: 'guidedTourStarterBtn') do
+                                    safe_join([
+                                                tag.i(class: 'bi bi-lightbulb'),
+                                                ' '.html_safe,
+                                                t('guided-tour.starter-button-text')
+                                              ])
+                                  end
+                                ])
+                    end,
+                    tag.div(class: 'guided-tour--overlay', data: {
+                      guided_tour__tour_target: 'overlay',
+                      bs_container: 'body',
+                      bs_toggle: 'popover',
+                      bs_placement: 'bottom',
+                      bs_content: ''
+                    }),
+                    tag.ol(class: 'd-none') do
+                      safe_join(
+                        map.map do |id, guide_text|
+                          tag.li(guide_text, data: {
+                            guided_tour__tour_target: 'explanation',
+                            target_element: id
+                          })
+                        end
+                      )
+                    end
+                  ])
+      end.html_safe
+    end
+  end
+end

data/config/locales/de.yml

@@ -0,0 +1,7 @@
+---
+de:
+  guided-tour:
+    next-btn-text: "Weiter"
+    prev-btn-text: "Zurück"
+    done-btn-text: "Fertig"
+    step-line: "Erklärung {{current}} von {{total}}"

data/config/locales/en.yml

@@ -0,0 +1,7 @@
+---
+en:
+  guided-tour:
+    next-btn-text: "Next"
+    prev-btn-text: "Back"
+    done-btn-text: "Done"
+    step-line: "Step {{current}} of {{total}}"

data/lib/generators/guided_tour/install/install_generator.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# lib/generators/guided_tour/install/install_generator.rb
+module GuidedTour
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+
+      def check_dependencies
+        unless File.exist?("app/javascript/controllers/index.js")
+          say "Installing stimulus-rails...", :green
+          run "rails stimulus:install"
+        end
+      end
+
+      def add_javascript
+        if File.exist?("config/importmap.rb")
+          append_to_file "config/importmap.rb" do
+            'pin "@itsbede/guided-tour"'
+          end
+        end
+
+        if File.exist?("package.json")
+          run "yarn add @itsbede/guided-tour"
+        end
+      end
+
+      def add_controller_to_application_js
+        inject_into_file "app/javascript/controllers/application.js",
+                         before: "export { application }" do
+          <<~JAVASCRIPT
+            import GuidedTourController from "@itsbede/guided-tour"
+            application.register('guided-tour--tour', GuidedTourController)
+
+          JAVASCRIPT
+        end
+      end
+    end
+  end
+end

data/lib/guided_tour/engine.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# lib/guided_tour/engine.rb
+module GuidedTour
+  class Engine < ::Rails::Engine
+    isolate_namespace GuidedTour
+
+    # Verify dependencies are installed
+    config.after_initialize do |_app|
+      begin
+        require "stimulus-rails"
+      rescue LoadError
+        raise "GuidedTour requires stimulus-rails to be installed. Add `gem 'stimulus-rails'` to your Gemfile."
+      end
+
+      # Only check for package.json in non-test environments
+      unless Rails.env.test?
+        unless File.exist?(Rails.root.join("package.json"))
+          raise "GuidedTour requires jsbundling-rails to be installed. Run `rails javascript:install:esbuild`"
+        end
+      end
+    end
+
+    # Initialize locales
+    initializer "guided_tour.locales" do |app|
+      app.config.i18n.load_path += Dir[
+        Engine.root.join("config", "locales", "**", "*.{rb,yml}").to_s
+      ]
+    end
+
+    initializer 'guided_tour.action_controller' do
+      ActiveSupport.on_load :action_controller do
+        helper GuidedTour::ApplicationHelper
+      end
+    end
+  end
+end

data/lib/guided_tour/version.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module GuidedTour
+  # update this version number when the used Rails version changes
+  MAJOR = 1
+  MINOR = 0
+  TINY = 0
+  PRE = nil
+
+  VERSION = [MAJOR, MINOR, TINY, PRE].compact.join(".")
+end

data/lib/guided_tour.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "guided_tour/version"
+require "guided_tour/engine"
+
+module GuidedTour
+  # Your code goes here...
+end

metadata

@@ -0,0 +1,189 @@
+--- !ruby/object:Gem::Specification
+name: guided_tour
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Benjamin Deutscher
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-11-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: actionview
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: rails-i18n
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: stimulus-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'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !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: jsbundling-rails
+  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'
+description: When building UIs for 'non tech people' things tend to get difficult
+  to explain since some people do not know terms like button, select, etc. guided-tour
+  helps with that.
+email:
+- ben@bdeutscher.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/controllers/guided_tour/application_controller.rb
+- app/helpers/guided_tour/application_helper.rb
+- config/locales/de.yml
+- config/locales/en.yml
+- lib/generators/guided_tour/install/install_generator.rb
+- lib/guided_tour.rb
+- lib/guided_tour/engine.rb
+- lib/guided_tour/version.rb
+homepage: https://github.com/its-bede/guided-tour
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/its-bede/guided-tour
+  source_code_uri: https://github.com/its-bede/guided-tour
+  changelog_uri: https://github.com/its-bede/guided-tourblob/main/CHANGELOG.md
+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: []
+rubygems_version: 3.5.21
+signing_key:
+specification_version: 4
+summary: Gem to guide users through the UI and explain things.
+test_files: []