rails_onboarding 0.6.3 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54c87e18cdea35b440ea3d1f9dcd93984da008e6690bbf0dba255e8b1b803266
-  data.tar.gz: 6675e0f3bf44029a6ee5d2b6c6d051edf877dd388e087b44925a716f51070a1b
+  metadata.gz: c0a6325415445d0fcf87f3513dcfda910866b9bbbf93b8edde3e2c904af7ee15
+  data.tar.gz: 4db74bd332e05a95ba79404499c314c4dbb251511d075ef1b56746559a96963b
 SHA512:
-  metadata.gz: fd7a88c2058c5ea08bc5636990af96fd58775bfa98bf8f5a93849793564afe09bb51dcdf4983641dab499cd850213e6b24c2c867c44137b4ae30b7cc469697b0
-  data.tar.gz: 75827eaa49ba15a510ae5212be0ba4f6ea67739b32e1da632c9e9fd36eaa452a721d635f839e01f77922755ed15742e9d31f91618dcca0485f4c012b4e6088d3
+  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]
@@ -232,6 +238,10 @@ module RailsOnboarding
       awarded_milestones = []
       RailsOnboarding.configuration.total_steps.times do
         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,6 +268,21 @@ module RailsOnboarding
       set_step
     end
 
+    # 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?)
+
+      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
     # (without redirecting) when the configured path can't be resolved, so
     # show can fall back to rendering a gem template instead of stranding the

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/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/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.3"
+  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.3
+  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.3
+  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: