rails_onboarding 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b5f1d40794e4959c807fd7fd7077c81c60821cbf8e1bd79fd69089543e718790
-  data.tar.gz: 3ce1ebd746fc540b491460bf1c0c7e2dee36709182bee72beab9a6c5e4b56ec0
+  metadata.gz: c0a6325415445d0fcf87f3513dcfda910866b9bbbf93b8edde3e2c904af7ee15
+  data.tar.gz: 4db74bd332e05a95ba79404499c314c4dbb251511d075ef1b56746559a96963b
 SHA512:
-  metadata.gz: ac1a9a964c82891f05512236f1930c753082efa29e16f34621da582f962cabdd7761611c4538f4857a6ffc08f5388c123f8837b3923aba3d2392b6d72c178ce2
-  data.tar.gz: ed7976e143fc227f068324ac48c6d93e01acad26a3fcd6a445599fd628411b0b22f8353a9f5c87085929cc07025b18e956391c6d7973cb9742aab6dd4e522cf3
+  metadata.gz: 4a3f455ac868d10a4cc011f434f5e2f8ab4e7b72c9769ebbfccd7ad2a0af78af0dc132d23771bd899926a05075ab025e1c53e2d4dacd8df329220e43b55899e9
+  data.tar.gz: 5a6d4ab7899f89c143754b9c2c5d85efb44efaeb5e8a7c0f1a0df9dd009961cf39614f91085f4d51de8ccfb76eacf85d56a205c857b5d4298af984e4b82b14b0

data/README.md

@@ -537,7 +537,11 @@ current_user.complete_onboarding!
 # Skip onboarding
 current_user.skip_onboarding!
 
-# Restart onboarding
+# Reset onboarding state (clears milestones too; pass clear_milestones: false to keep them)
+current_user.reset_onboarding!
+
+# Restart onboarding - resets and walks the user through the steps again, even
+# if their data already satisfies every :complete_if
 current_user.restart_onboarding!
 ```
 
@@ -1016,7 +1020,9 @@ RailsOnboarding::Templates.apply('saas')
 - `go_back!` - Move to previous step
 - `complete_onboarding!` - Mark onboarding as complete
 - `skip_onboarding!` - Skip onboarding
-- `restart_onboarding!` - Restart from beginning
+- `reset_onboarding!(clear_milestones: true)` - Clear onboarding state
+- `restart_onboarding!` - Reset and re-walk the flow (replay mode)
+- `replaying_onboarding?` - Is the user re-walking the flow?
 
 #### Progress Methods
 - `onboarding_progress` - Returns completion percentage (0-100)

data/app/controllers/rails_onboarding/admin/users_controller.rb

@@ -61,7 +61,19 @@ module RailsOnboarding
         @user = user_class.find(params[:id])
 
         @user.restart_onboarding!
-        flash[:notice] = "Onboarding restarted for user #{@user.id}"
+
+        # Without the replay columns a restart can't stop :complete_if from
+        # auto-advancing an established user straight back to "completed",
+        # which looks like the button did nothing. Say so rather than claiming
+        # a restart that won't survive their next page load.
+        flash[:notice] = if !user_class.respond_to?(:onboarding_replay_supported?) ||
+                            user_class.onboarding_replay_supported?
+          "Onboarding restarted for user #{@user.id}"
+        else
+          "Onboarding restarted for user #{@user.id}. Steps whose completion criteria " \
+            "are already met will be skipped - run the add_onboarding_replay_to_users " \
+            "migration to walk this user through them again."
+        end
         redirect_to admin_user_path(@user)
       rescue StandardError => e
         flash[:alert] = "Error restarting onboarding: #{e.message}"

data/app/controllers/rails_onboarding/onboarding_controller.rb

@@ -55,6 +55,12 @@ module RailsOnboarding
         )
       end
 
+      # Record that the user has now been shown this step. That's what lets
+      # :complete_if advance them past it when they come back, and it is what
+      # makes a restart re-walk a flow the user's data already satisfies.
+      # No-op outside a replay.
+      mark_step_replayed(@current_step)
+
       # Steps that own a real page in the host app: route there instead of
       # rendering a gem template, so the existing controller/view do the work.
       if @current_step[:path]
@@ -231,7 +237,11 @@ module RailsOnboarding
     def advance_completed_steps
       awarded_milestones = []
       RailsOnboarding.configuration.total_steps.times do
-        break unless @current_step && step_criteria_met?(@current_step)
+        break unless @current_step && onboarding_step_criteria_met?(@current_step)
+        # During a replay, a satisfied :complete_if is not enough on its own -
+        # the user has to have been shown the step again first, or a restart
+        # would auto-advance them straight back to "completed".
+        break unless step_replayed?(@current_step)
 
         if defined?(RailsOnboarding::MilestoneService)
           milestones = RailsOnboarding::MilestoneService.check_onboarding_step_milestones(
@@ -258,17 +268,19 @@ module RailsOnboarding
       set_step
     end
 
-    # A buggy :complete_if must not brick onboarding - if it raises, treat the
-    # step as not yet complete instead of letting the shared StandardError
-    # handler redirect back to /onboarding (which would re-raise on arrival,
-    # redirecting again in an endless browser loop).
-    def step_criteria_met?(step)
-      return false unless step[:complete_if].is_a?(Proc)
+    # Replay bookkeeping. Both tolerate a host User that predates replay
+    # support (or isn't Onboardable at all), falling back to the ordinary
+    # auto-advance behaviour.
+    def step_replayed?(step)
+      return true unless current_user.respond_to?(:onboarding_step_replayed?)
 
-      step[:complete_if].call(current_user)
-    rescue StandardError => e
-      Rails.logger.error("RailsOnboarding: complete_if for step '#{step[:name]}' raised #{e.class} - #{e.message}")
-      false
+      current_user.onboarding_step_replayed?(step[:name])
+    end
+
+    def mark_step_replayed(step)
+      return unless current_user.respond_to?(:mark_onboarding_step_replayed!)
+
+      current_user.mark_onboarding_step_replayed!(step[:name])
     end
 
     # Redirect to the host-app page that owns the current step. Returns false

data/app/models/concerns/rails_onboarding/onboardable.rb

@@ -18,6 +18,8 @@ module RailsOnboarding
       # - milestones_achieved: text (serialized JSON array)
       # - milestone_points: integer
       # - last_milestone_at: datetime
+      # - onboarding_replay_started_at: datetime
+      # - onboarding_replay_steps: text (serialized JSON array)
 
       # Fix for Rails 8: Use the new serialize syntax
       if columns_hash["feature_tooltips_shown"]&.type == :text
@@ -28,6 +30,10 @@ module RailsOnboarding
         serialize :milestones_achieved, coder: JSON
       end
 
+      if columns_hash["onboarding_replay_steps"]&.type == :text
+        serialize :onboarding_replay_steps, coder: JSON
+      end
+
       # Association with analytics events (only if ActiveRecord is available)
       if respond_to?(:has_many)
         has_many :analytics_events,
@@ -43,6 +49,19 @@ module RailsOnboarding
       end
     end
 
+    class_methods do
+      # Replay mode needs two columns that predate no host app: installs from
+      # before it existed simply don't have them. Everything replay-related
+      # degrades to the old auto-advance behaviour when they're missing rather
+      # than raising on a column that isn't there.
+      def onboarding_replay_supported?
+        return false unless respond_to?(:column_names)
+
+        column_names.include?("onboarding_replay_started_at") &&
+          column_names.include?("onboarding_replay_steps")
+      end
+    end
+
     # Determines if the user needs to go through onboarding
     #
     # This method checks the configuration setting and user state to determine
@@ -163,9 +182,11 @@ module RailsOnboarding
 
     def complete_onboarding!(session_id: nil, completion_time: nil)
       persist_and_track!(
-        onboarding_completed: true,
-        onboarding_completed_at: Time.current,
-        onboarding_current_step: nil
+        {
+          onboarding_completed: true,
+          onboarding_completed_at: Time.current,
+          onboarding_current_step: nil
+        }.merge(replay_reset_attributes)
       ) do
         AnalyticsEvent.track_onboarding_completed(
           user: self,
@@ -179,10 +200,12 @@ module RailsOnboarding
 
     def skip_onboarding!(session_id: nil)
       persist_and_track!(
-        onboarding_completed: true,
-        onboarding_completed_at: Time.current,
-        onboarding_skipped: true,
-        onboarding_current_step: nil
+        {
+          onboarding_completed: true,
+          onboarding_completed_at: Time.current,
+          onboarding_skipped: true,
+          onboarding_current_step: nil
+        }.merge(replay_reset_attributes)
       ) do
         AnalyticsEvent.track_onboarding_completed(
           user: self,
@@ -193,14 +216,35 @@ module RailsOnboarding
       end
     end
 
-    def reset_onboarding!
-      update!(
+    # Clear onboarding state so the user starts over.
+    #
+    # Milestones are cleared by default. achieve_milestone! is idempotent
+    # (it returns false for anything already in milestones_achieved), so
+    # leaving them behind means a user sent back through the flow can never
+    # re-earn them and finishes with no milestone notice at all. Pass
+    # clear_milestones: false to keep them - worth doing where a host app's
+    # milestones record real achievements rather than onboarding progress.
+    #
+    # Any in-flight replay is cancelled: a bare reset drops the user back to
+    # the default behaviour, where a step whose :complete_if already passes is
+    # advanced past automatically. Use restart_onboarding! to reset *and*
+    # replay.
+    #
+    # @param clear_milestones [Boolean] also wipe milestones, points and
+    #   last_milestone_at (default: true)
+    # @return [Boolean] true
+    def reset_onboarding!(clear_milestones: true)
+      attributes = {
         onboarding_completed: false,
         onboarding_completed_at: nil,
         onboarding_skipped: false,
         onboarding_current_step: nil,
         feature_tooltips_shown: {}
-      )
+      }
+      attributes.merge!(milestone_reset_attributes) if clear_milestones
+      attributes.merge!(replay_reset_attributes)
+
+      update!(attributes)
     end
 
     # Feature tooltips
@@ -432,11 +476,18 @@ module RailsOnboarding
       true
     end
 
-    def restart_onboarding!(session_id: nil)
+    # Reset and immediately re-enter the flow at step one.
+    #
+    # Unlike a bare reset this turns replay mode on, so a user whose host-app
+    # data already satisfies every :complete_if walks the steps again instead
+    # of being auto-advanced straight back to "completed" on their next visit
+    # to /onboarding. See replaying_onboarding?.
+    def restart_onboarding!(session_id: nil, clear_milestones: true)
       previous_step = onboarding_current_step
       was_completed = onboarding_completed
 
-      reset_onboarding!
+      reset_onboarding!(clear_milestones: clear_milestones)
+      start_onboarding_replay!
       start_onboarding!(session_id: session_id)
 
       AnalyticsEvent.track_custom_event(
@@ -447,6 +498,63 @@ module RailsOnboarding
       )
     end
 
+    # Replay mode
+    #
+    # A reset clears onboarding's own bookkeeping, but it cannot clear the
+    # host-app data a step's :complete_if reads. For an established user every
+    # predicate is still satisfied, so /onboarding advances through the whole
+    # flow in a single redirect and the reset looks like it did nothing.
+    #
+    # While a replay is active, :complete_if is no longer enough on its own -
+    # the user also has to have been shown the step again. That makes a
+    # restart walk the real pages a second time without touching the data
+    # those predicates read.
+
+    # Is this user currently re-walking the flow?
+    #
+    # False once they finish, so a completed user is never stuck in replay.
+    def replaying_onboarding?
+      return false unless self.class.onboarding_replay_supported?
+      return false if onboarding_completed?
+
+      onboarding_replay_started_at.present?
+    end
+
+    # @return [Boolean] false when the host app hasn't run the replay migration
+    def start_onboarding_replay!
+      return false unless self.class.onboarding_replay_supported?
+
+      update!(onboarding_replay_started_at: Time.current, onboarding_replay_steps: [])
+      true
+    end
+
+    def end_onboarding_replay!
+      return false unless self.class.onboarding_replay_supported?
+
+      update!(replay_reset_attributes)
+      true
+    end
+
+    # Has the user been shown this step since the current replay began?
+    #
+    # True whenever no replay is active, so callers can gate auto-advance on
+    # it unconditionally and get the ordinary behaviour outside a replay.
+    def onboarding_step_replayed?(step_name)
+      return true unless replaying_onboarding?
+
+      (onboarding_replay_steps || []).map(&:to_s).include?(step_name.to_s)
+    end
+
+    # Record that the user has now seen this step. No-op outside a replay.
+    def mark_onboarding_step_replayed!(step_name)
+      return false unless replaying_onboarding?
+      return false if onboarding_step_replayed?(step_name)
+
+      self.onboarding_replay_steps = (onboarding_replay_steps || []) + [ step_name.to_s ]
+      save!
+      true
+    end
+
     # API-friendly aliases and helper methods
     alias_method :complete_step, :complete_onboarding_step!
     alias_method :skip_step, :skip_onboarding_step!
@@ -552,6 +660,26 @@ module RailsOnboarding
     # triggers) must never fire for a state change that didn't actually get
     # persisted - update!/save! raise on failure, so if that happens, this
     # method never reaches the block.
+    # Milestone columns arrive in a separate migration, so a host app can be
+    # running without them. Only reset what actually exists.
+    def milestone_reset_attributes
+      attributes = {}
+      attributes[:milestones_achieved] = [] if onboarding_column?("milestones_achieved")
+      attributes[:milestone_points] = 0 if onboarding_column?("milestone_points")
+      attributes[:last_milestone_at] = nil if onboarding_column?("last_milestone_at")
+      attributes
+    end
+
+    def replay_reset_attributes
+      return {} unless self.class.onboarding_replay_supported?
+
+      { onboarding_replay_started_at: nil, onboarding_replay_steps: [] }
+    end
+
+    def onboarding_column?(name)
+      self.class.respond_to?(:column_names) && self.class.column_names.include?(name)
+    end
+
     def persist_and_track!(attributes = nil)
       if attributes
         update!(attributes)

data/app/views/rails_onboarding/shared/_onboarding_banner.html.erb

@@ -34,11 +34,15 @@
       </span>
     </div>
     <div class="onboarding-banner-actions">
-      <%# For :path steps, /onboarding re-checks complete_if and either
-          advances or routes back to the step's page - so "Continue" is
-          always the right link. %>
-      <%= link_to "Continue setup →", onboarding_root,
-                  class: "onboarding-banner-continue" %>
+      <%# /onboarding re-checks complete_if and either advances or routes back
+          to the step's page. That makes "Continue" the right link from
+          anywhere else in the app - but on the step's own page, with the
+          criteria not yet met, it redirects straight back here and the click
+          does nothing visible. Offer it only when it leads somewhere. %>
+      <% if !defined?(onboarding_continue_available?) || onboarding_continue_available? %>
+        <%= link_to "Continue setup →", onboarding_root,
+                    class: "onboarding-banner-continue" %>
+      <% end %>
       <% if step[:skippable] %>
         <%= button_to "Skip this step", rails_onboarding.skip_onboarding_path,
                       method: :post, class: "onboarding-banner-skip" %>

data/lib/generators/rails_onboarding/install_generator.rb

@@ -60,6 +60,11 @@ module RailsOnboarding
                            "db/migrate/add_robustness_fields_to_users.rb"
       end
 
+      def copy_onboarding_replay_migration
+        migration_template "add_onboarding_replay_to_users.rb",
+                           "db/migrate/add_onboarding_replay_to_users.rb"
+      end
+
       def copy_initializer
         template "rails_onboarding.rb", "config/initializers/rails_onboarding.rb"
       end
@@ -87,6 +92,7 @@ module RailsOnboarding
           "add_milestone_tracking_to_users.rb",
           "add_onboarding_indexes.rb",
           "add_robustness_fields_to_users.rb.tt",
+          "add_onboarding_replay_to_users.rb",
           "rails_onboarding.rb",
           "onboarding.css",
           "README"

data/lib/generators/rails_onboarding/templates/add_onboarding_replay_to_users.rb

@@ -0,0 +1,22 @@
+class AddOnboardingReplayToUsers < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def up
+    # Replay mode: when set, the user is walking the flow again after a
+    # restart, and a step's :complete_if is not allowed to advance them past a
+    # step they have not been shown yet. See Onboardable#replaying_onboarding?.
+    #
+    # No DB-level default on the text column: MySQL/MariaDB reject a literal
+    # DEFAULT on TEXT, and Onboardable already treats nil as an empty array.
+    unless column_exists?(:users, :onboarding_replay_started_at)
+      add_column :users, :onboarding_replay_started_at, :datetime
+    end
+
+    unless column_exists?(:users, :onboarding_replay_steps)
+      add_column :users, :onboarding_replay_steps, :text
+    end
+  end
+
+  def down
+    remove_column :users, :onboarding_replay_steps if column_exists?(:users, :onboarding_replay_steps)
+    remove_column :users, :onboarding_replay_started_at if column_exists?(:users, :onboarding_replay_started_at)
+  end
+end

data/lib/rails_onboarding/controller_helpers.rb

@@ -4,7 +4,7 @@ module RailsOnboarding
     extend ActiveSupport::Concern
 
     included do
-      helper_method :needs_onboarding?, :onboarding_path
+      helper_method :needs_onboarding?, :onboarding_path, :onboarding_continue_available?
     end
 
     # Configuration at the controller level
@@ -105,6 +105,59 @@ module RailsOnboarding
       path.is_a?(Proc) ? instance_exec(&path) : main_app.public_send(path)
     end
 
+    # Has this step's :complete_if been satisfied?
+    #
+    # A buggy :complete_if must not brick onboarding - if it raises, treat the
+    # step as not yet complete instead of letting the engine's shared
+    # StandardError handler redirect back to /onboarding (which would re-raise
+    # on arrival, redirecting again in an endless browser loop).
+    def onboarding_step_criteria_met?(step)
+      return false unless step.is_a?(Hash) && step[:complete_if].is_a?(Proc)
+
+      step[:complete_if].call(current_user)
+    rescue StandardError => e
+      Rails.logger.error("RailsOnboarding: complete_if for step '#{step[:name]}' raised #{e.class} - #{e.message}")
+      false
+    end
+
+    # Would following the banner's "Continue" link actually move the user?
+    #
+    # Anywhere else in the app, yes: /onboarding routes them to the current
+    # step. Standing on the step's own page it depends - /onboarding re-checks
+    # :complete_if and only advances once it passes. Until then it resolves the
+    # step's path and redirects straight back to the page the user is already
+    # on, so the link renders but the click does nothing visible. The banner
+    # asks this before offering it.
+    #
+    # The comparison is deliberately an exact path match rather than
+    # on_current_step_page?, which also treats any other action on the same
+    # controller as "on the step page". That breadth is right for the loop
+    # guard - it keeps the guard off the PATCH that completes the step - but
+    # wrong here: /profiles/123 is a different page from a step pointing at
+    # /profiles/123/edit, and Continue really does move the user between them.
+    def onboarding_continue_available?
+      return false unless user_signed_in?
+      return false unless current_user.respond_to?(:current_onboarding_step)
+
+      step = current_user.current_onboarding_step
+      # No :path means the step renders a gem template at /onboarding, which is
+      # always somewhere other than the host page showing this banner.
+      return true unless step.is_a?(Hash) && step[:path]
+
+      # The resolved route may carry a query string or be a full URL;
+      # request.path never does.
+      resolved_path = URI.parse(resolve_onboarding_step_path(step[:path]).to_s).path
+      return true unless request.path == resolved_path
+
+      onboarding_step_criteria_met?(step)
+    rescue StandardError => e
+      # An unresolvable :path means the engine can't redirect to it either - it
+      # falls back to rendering a gem template, so Continue still goes
+      # somewhere. Offer it.
+      Rails.logger.warn("RailsOnboarding: could not resolve step path for the banner link: #{e.class} - #{e.message}")
+      true
+    end
+
     private
 
     # True when the current request is for the page a :path-based step points

data/lib/rails_onboarding/requirements_validator.rb

@@ -167,7 +167,9 @@ module RailsOnboarding
             "feature_tooltips_shown" => [ :jsonb, :text ],
             "milestones_achieved" => [ :text, :jsonb ],
             "milestone_points" => :integer,
-            "last_milestone_at" => :datetime
+            "last_milestone_at" => :datetime,
+            "onboarding_replay_started_at" => :datetime,
+            "onboarding_replay_steps" => [ :text, :jsonb ]
           }
 
           # Check required columns

data/lib/rails_onboarding/version.rb

@@ -1,3 +1,3 @@
 module RailsOnboarding
-  VERSION = "0.6.1"
+  VERSION = "0.7.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_onboarding
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.0
 platform: ruby
 authors:
 - David Lewis
@@ -234,6 +234,7 @@ files:
 - lib/generators/rails_onboarding/templates/add_analytics_to_rails_onboarding.rb
 - lib/generators/rails_onboarding/templates/add_milestone_tracking_to_users.rb
 - lib/generators/rails_onboarding/templates/add_onboarding_indexes.rb
+- lib/generators/rails_onboarding/templates/add_onboarding_replay_to_users.rb
 - lib/generators/rails_onboarding/templates/add_onboarding_to_users.rb
 - lib/generators/rails_onboarding/templates/add_robustness_fields_to_users.rb.tt
 - lib/generators/rails_onboarding/templates/create_rails_onboarding_flows.rb
@@ -281,7 +282,7 @@ licenses:
 metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/bunnahabhain/rails_onboarding
-  source_code_uri: https://github.com/bunnahabhain/rails_onboarding/tree/v0.6.1
+  source_code_uri: https://github.com/bunnahabhain/rails_onboarding/tree/v0.7.0
   changelog_uri: https://github.com/bunnahabhain/rails_onboarding/blob/master/docs/CHANGELOG.md
 rdoc_options: []
 require_paths: