rails_onboarding 0.8.1 → 0.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 968d937235787bd7b4b096707cd9e44f2152d11c5b9d6f92f8f684d4b0807e98
-  data.tar.gz: f3b564a235899a551598ae48c9877ef5090261240a9e5b33cf0f63af6c155fc4
+  metadata.gz: 6a33d58aa73f7c851196a6ed683c0a907eabc60addda69cc841206ef7765201e
+  data.tar.gz: 28b37e7d218f6503e256e35292eb71c48a2074bb18f89be4581e417a98365cc0
 SHA512:
-  metadata.gz: 35466bcb9f4c22021d9a8012cb4f0fc0bf3a2b3ccaeedf270f0681711d1a686e41b6a3e102b6a5084955ca7b0c2bc5ad84203b284303604b1e27c5c93a032a58
-  data.tar.gz: 1674b9b08636d82c3d71fb78b80d8aae49d7f7510f91ff948dbbf642c79ddf21118248d465bce33b84e5630c24ee37b04cdfc2d30542047cc50fa2469210babd
+  metadata.gz: b1e1fa8588b97a8402ae6f68c0c968e88a0e8229fff82f9f1e79249bfec60b067f465369800241f56bcf63543663d979dcc5dbb14eefabd7982af921695edcaa
+  data.tar.gz: eb6c36a63a60df9e93e83713022ffa175d6579fba9cd9b73246f1a82f8c1cc7fa165729b8d5f852564d494e246e7e0b099fcd3a6478bf184cb5a7d1e36ec125a

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

@@ -46,18 +46,30 @@ module RailsOnboarding
         @analytics_error = e.message
       end
 
+      # Milestones have no table of their own. They are *defined* in the host's
+      # initializer (RailsOnboarding.configuration.milestones) and *awarded*
+      # onto the user record: `milestones_achieved` holds a serialized array of
+      # {"key", "achieved_at"} hashes, with `milestone_points` and
+      # `last_milestone_at` beside it.
+      #
+      # This panel used to query a RailsOnboarding::Milestone model and a
+      # rails_onboarding_milestone_achievements join table. Neither has ever
+      # existed in the engine, so the `defined?` guard was always false and the
+      # whole section returned early - silently, while real achievements piled
+      # up on the users table. Guard on the two things actually required
+      # instead: milestones being switched on, and a user model that speaks
+      # Onboardable.
       def load_milestone_data
-        return unless defined?(RailsOnboarding::Milestone)
+        return unless RailsOnboarding.configuration.enable_milestones
+        return unless user_class.method_defined?(:achieved_milestone_entries)
 
-        @total_milestones = RailsOnboarding::Milestone.count
+        @total_milestones = RailsOnboarding.configuration.milestones.size
 
-        # Use Arel to build safe SQL
-        users_table = user_class.arel_table
-        @milestone_achievements = user_class
-          .joins("LEFT JOIN rails_onboarding_milestone_achievements ON rails_onboarding_milestone_achievements.user_id = #{users_table.name}.id")
-          .group(users_table[:id])
-          .count
-        @top_milestones = top_achieved_milestones
+        stats = milestone_achievement_stats
+        @milestones_awarded = stats[:awarded]
+        @milestone_points_awarded = stats[:points]
+        @users_with_milestones = stats[:users]
+        @top_milestones = stats[:top]
       rescue StandardError => e
         logger.error "Error loading milestone data: #{e.message}"
         @milestone_error = e.message
@@ -154,16 +166,78 @@ module RailsOnboarding
         trend
       end
 
-      def top_achieved_milestones
-        return [] unless defined?(RailsOnboarding::Milestone)
+      # Roll every user's achievements up into the numbers the panel shows.
+      #
+      # `milestones_achieved` is a serialized text column, so this cannot be a
+      # GROUP BY - the rows have to be loaded and counted in Ruby. Two things
+      # keep that honest: only users who hold at least one achievement are
+      # loaded, and only the three columns needed are selected. It is still
+      # O(users-with-milestones), which is fine into the tens of thousands and
+      # is the price of milestones not having a table. An install that outgrows
+      # it should denormalise achievements into their own table rather than
+      # paginate this.
+      #
+      # Achievements are counted within the dashboard's selected date range,
+      # like every other time-based figure here. Undated achievements are
+      # counted regardless: a legacy string entry on a record with no
+      # last_milestone_at is still a real award, and dropping it would repeat
+      # in miniature exactly the bug this method replaces.
+      def milestone_achievement_stats
+        counts = Hash.new(0)
+        awarded = 0
+        points = 0
+        users = 0
+
+        achievement_holders.find_each do |user|
+          keys = user.achieved_milestone_entries.filter_map do |key, achieved_at|
+            key if achieved_at.nil? || achieved_at >= @start_date
+          end
+          next if keys.empty?
+
+          users += 1
+          awarded += keys.size
+          keys.each do |key|
+            counts[key] += 1
+            points += RailsOnboarding.configuration.milestone_by_key(key)&.dig(:points).to_i
+          end
+        end
+
+        { awarded: awarded, points: points, users: users, top: top_milestones_from(counts) }
+      end
+
+      # Users holding at least one achievement. The empty cases are the column's
+      # default (NULL) and a serialized empty array, which is what
+      # reset_onboarding! leaves behind.
+      #
+      # The empty-string checks go through raw SQL on purpose: `milestones_achieved`
+      # is a serialized attribute, so `where.not(milestones_achieved: "[]")` would
+      # hand "[]" to the JSON coder and compare against the string '"[]"' instead.
+      # A bare nil is safe - the serialized type passes it straight through.
+      def achievement_holders
+        column = "#{user_class.quoted_table_name}.milestones_achieved"
 
-        RailsOnboarding::Milestone
-          .joins("LEFT JOIN rails_onboarding_milestone_achievements ON rails_onboarding_milestone_achievements.milestone_id = rails_onboarding_milestones.id")
-          .group("rails_onboarding_milestones.id", "rails_onboarding_milestones.name", "rails_onboarding_milestones.title")
-          .order("COUNT(rails_onboarding_milestone_achievements.id) DESC")
-          .limit(5)
-          .pluck("rails_onboarding_milestones.name", "rails_onboarding_milestones.title", "COUNT(rails_onboarding_milestone_achievements.id)")
-          .map { |name, title, count| { name: name, title: title, count: count } }
+        user_class
+          .where.not(milestones_achieved: nil)
+          .where("#{column} NOT IN (?, ?)", "", "[]")
+          .select(:id, :milestones_achieved, :last_milestone_at)
+      end
+
+      # The five most-awarded milestones, resolved against the configuration for
+      # their display copy. A key with no matching configuration entry is one the
+      # host has since renamed or removed; show it under its raw key rather than
+      # dropping it, so the leftover data is visible and can be cleaned up.
+      def top_milestones_from(counts)
+        counts.sort_by { |key, count| [ -count, key ] }.first(5).map do |key, count|
+          milestone = RailsOnboarding.configuration.milestone_by_key(key)
+
+          {
+            name: key,
+            title: milestone&.dig(:title) || key.to_s.humanize,
+            icon: milestone&.dig(:icon),
+            configured: !milestone.nil?,
+            count: count
+          }
+        end
       end
 
       def date_range_start(range)

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

@@ -307,6 +307,30 @@ module RailsOnboarding
       milestones.map { |m| m.is_a?(Hash) ? m["key"] : m.to_s }
     end
 
+    # Every achievement as a [key, achieved_at] pair, in the order it was
+    # awarded.
+    #
+    # #achieved_milestones gives the keys and #milestone_achieved_at dates one
+    # key at a time; anything that needs both at once (the admin dashboard
+    # counting achievements per period, for one) would otherwise re-scan the
+    # array once per key and re-implement the two stored formats for itself.
+    #
+    # +achieved_at+ is nil only for a legacy string entry on a record with no
+    # last_milestone_at to fall back on - the achievement is real, its date
+    # simply was never stored. Callers filtering by date should decide
+    # deliberately what to do with those rather than dropping them by accident.
+    #
+    # @return [Array<Array(String, Time, nil)>]
+    def achieved_milestone_entries
+      (milestones_achieved || []).map do |entry|
+        if entry.is_a?(Hash)
+          [ entry["key"].to_s, parse_achieved_at(entry["achieved_at"]) ]
+        else
+          [ entry.to_s, last_milestone_at ]
+        end
+      end
+    end
+
     def milestone_achieved?(milestone_key)
       achieved_milestones.include?(milestone_key.to_s)
     end
@@ -654,6 +678,16 @@ module RailsOnboarding
 
     private
 
+    # A stored achieved_at, or last_milestone_at when it is missing or
+    # unparseable - the same fallback #milestone_achieved_at applies.
+    def parse_achieved_at(value)
+      return last_milestone_at if value.blank?
+
+      Time.parse(value.to_s)
+    rescue StandardError
+      last_milestone_at
+    end
+
     # Persists +attributes+ (or just re-saves already-assigned attributes if
     # none given), then runs the tracking block only after that succeeds.
     # Analytics tracking (and, transitively, any milestone-achievement it

data/app/views/rails_onboarding/admin/dashboard/index.html.erb

@@ -126,19 +126,43 @@
 <!-- Bottom Row -->
 <div class="admin-bottom-grid">
   <!-- Milestone Stats -->
-  <% if defined?(RailsOnboarding::Milestone) %>
+  <%# @total_milestones is assigned only when milestones are enabled and the
+      user model speaks Onboardable, so it doubles as the render guard. %>
+  <% if @total_milestones %>
     <div class="admin-card">
       <div class="admin-card-header">
-        <h3 class="admin-card-title">Top Milestones</h3>
+        <h3 class="admin-card-title">Milestones</h3>
+        <span class="admin-card-action"><%= pluralize(@total_milestones, "configured") %></span>
       </div>
       <div class="admin-card-body">
-        <% if @top_milestones && @top_milestones.any? %>
+        <div class="admin-stats-grid admin-stats-compact">
+          <div class="admin-stat-card">
+            <div class="admin-stat-content">
+              <div class="admin-stat-label">Awarded</div>
+              <div class="admin-stat-value"><%= number_with_delimiter(@milestones_awarded) %></div>
+              <div class="admin-stat-change">to <%= pluralize(@users_with_milestones, "user") %></div>
+            </div>
+          </div>
+          <div class="admin-stat-card">
+            <div class="admin-stat-content">
+              <div class="admin-stat-label">Points</div>
+              <div class="admin-stat-value"><%= number_with_delimiter(@milestone_points_awarded) %></div>
+              <div class="admin-stat-change">in selected period</div>
+            </div>
+          </div>
+        </div>
+
+        <% if @top_milestones&.any? %>
           <div class="admin-list">
             <% @top_milestones.each do |milestone| %>
               <div class="admin-list-item">
                 <div class="admin-list-content">
-                  <div class="admin-list-title"><%= milestone[:title] %></div>
-                  <div class="admin-list-meta"><%= milestone[:name] %></div>
+                  <div class="admin-list-title">
+                    <% if milestone[:icon].present? %><span aria-hidden="true"><%= milestone[:icon] %></span> <% end %><%= milestone[:title] %>
+                  </div>
+                  <div class="admin-list-meta">
+                    <%= milestone[:name] %><% unless milestone[:configured] %> — no longer configured<% end %>
+                  </div>
                 </div>
                 <div class="admin-list-value">
                   <span class="admin-badge"><%= number_with_delimiter(milestone[:count]) %> achieved</span>
@@ -147,7 +171,7 @@
             <% end %>
           </div>
         <% else %>
-          <p class="admin-empty-state">No milestone data available</p>
+          <p class="admin-empty-state">No milestones achieved in this period</p>
         <% end %>
       </div>
     </div>

data/lib/rails_onboarding/version.rb

@@ -1,3 +1,3 @@
 module RailsOnboarding
-  VERSION = "0.8.1"
+  VERSION = "0.8.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_onboarding
 version: !ruby/object:Gem::Version
-  version: 0.8.1
+  version: 0.8.2
 platform: ruby
 authors:
 - David Lewis
@@ -282,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.8.1
+  source_code_uri: https://github.com/bunnahabhain/rails_onboarding/tree/v0.8.2
   changelog_uri: https://github.com/bunnahabhain/rails_onboarding/blob/master/docs/CHANGELOG.md
 rdoc_options: []
 require_paths: