RubyGems - testimonials - Versions diffs - 0.7.9 → 0.8.0 - Mend

testimonials 0.7.9 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (45) hide show

checksums.yaml +4 -4
data/AGENTS.md +210 -0
data/CHANGELOG.md +68 -0
data/README.md +30 -4
data/app/controllers/concerns/testimonials/request_context.rb +75 -0
data/app/controllers/testimonials/application_controller.rb +10 -56
data/app/controllers/testimonials/dashboard_controller.rb +40 -0
data/app/controllers/testimonials/events_controller.rb +9 -0
data/app/controllers/testimonials/nps_responses_controller.rb +1 -4
data/app/controllers/testimonials/submissions_controller.rb +169 -0
data/app/controllers/testimonials/testimonials_controller.rb +6 -166
data/app/helpers/testimonials/widget_helper.rb +4 -0
data/app/models/testimonials/prompt_event.rb +12 -0
data/app/views/layouts/testimonials/application.html.erb +5 -8
data/app/views/testimonials/nps_responses/index.html.erb +154 -152
data/app/views/testimonials/nps_responses/show.html.erb +7 -5
data/app/views/testimonials/shared/_dashboard.html.erb +18 -0
data/app/views/testimonials/testimonials/index.html.erb +110 -108
data/app/views/testimonials/testimonials/show.html.erb +7 -5
data/config/routes.rb +18 -5
data/examples/README.md +17 -0
data/examples/badge.html.erb +13 -0
data/examples/json_ld.html.erb +28 -0
data/examples/static_site.md +43 -0
data/examples/testimonial_card.html.erb +17 -0
data/examples/wall_of_love.html.erb +43 -0
data/lib/generators/testimonials/install/install_generator.rb +22 -10
data/lib/generators/testimonials/install/templates/create_testimonials_tables.rb.tt +7 -5
data/lib/generators/testimonials/install/templates/initializer.rb.tt +25 -2
data/lib/generators/testimonials/migration_helpers.rb +35 -0
data/lib/generators/testimonials/nps/nps_generator.rb +2 -6
data/lib/generators/testimonials/nps/templates/create_testimonials_nps_responses.rb.tt +1 -1
data/lib/generators/testimonials/prompt_events/prompt_events_generator.rb +35 -0
data/lib/generators/testimonials/prompt_events/templates/create_testimonials_prompt_events.rb.tt +17 -0
data/lib/generators/testimonials/tenant/templates/add_tenant_to_testimonials.rb.tt +11 -8
data/lib/generators/testimonials/tenant/tenant_generator.rb +2 -6
data/lib/testimonials/configuration.rb +34 -1
data/lib/testimonials/dashboard.css +278 -221
data/lib/testimonials/prompt_helper.rb +4 -0
data/lib/testimonials/seeds.rb +3 -2
data/lib/testimonials/version.rb +1 -1
data/lib/testimonials/widget.js +4 -1
data/lib/testimonials/widget.rb +3 -0
data/lib/testimonials.rb +8 -0
metadata +15 -1

data/config/routes.rb CHANGED Viewed

@@ -22,14 +22,27 @@ Testimonials::Engine.routes.draw do
   end
   # Media by testimonial id, gated (admin, author, or public_api + publishable).
-  get ':id/video', to: 'media#video', as: :testimonial_video, constraints: { id: /\d+/ }
-  get ':id/poster', to: 'media#poster', as: :testimonial_poster, constraints: { id: /\d+/ }
-  get ':id/avatar', to: 'media#avatar', as: :testimonial_avatar, constraints: { id: /\d+/ }
+  get ':id/video', to: 'media#video', as: :testimonial_video
+  get ':id/poster', to: 'media#poster', as: :testimonial_poster
+  get ':id/avatar', to: 'media#avatar', as: :testimonial_avatar
   # Flat, human URLs: the mount path IS the resource. /testimonials is the
   # dashboard, POST /testimonials the widget endpoint, /testimonials/2 a testimonial.
-  resources :testimonials, path: '', only: %i[create index show update destroy],
-                           constraints: { id: /\d+/ }
+  #
+  # No `id: /\d+/` constraint: it made these routes bigint-only, which forced
+  # the tables to be bigint too, which meant a uuid-keyed host could never
+  # attach a video or avatar (its active_storage_attachments.record_id is a
+  # uuid column). The constraint was never load-bearing — every fixed-name
+  # route above is declared first, so ordering already does the disambiguating,
+  # and an id that matches no record still 404s, just via RecordNotFound rather
+  # than a routing error.
+  #
+  # POST goes to SubmissionsController, not to this resource: the widget's write
+  # endpoint is public and the rest is staff-only, and only the staff half
+  # inherits config.base_controller_class. Sharing one controller would put a
+  # host's admin authentication in front of a member leaving a review.
+  post '', to: 'submissions#create', as: :submissions
+  resources :testimonials, path: '', only: %i[index show update destroy]
   root to: 'testimonials#index'
 end

data/examples/README.md ADDED Viewed

@@ -0,0 +1,17 @@
+# Display examples
+testimonials deliberately ships **no display UI** — approved testimonials are
+yours to render, via `Testimonials::Testimonial.publishable` inside the app or
+via the JSON API anywhere else. These files are copy-paste starting points so
+you can see the end result in minutes. Take them, restyle them, own them.
+| File | What it renders |
+| --- | --- |
+| [`wall_of_love.html.erb`](wall_of_love.html.erb) | A responsive grid of text + video testimonials |
+| [`testimonial_card.html.erb`](testimonial_card.html.erb) | A single quote card for a landing/pricing page |
+| [`badge.html.erb`](badge.html.erb) | The "★ 4.9 from 87 reviews" chip |
+| [`json_ld.html.erb`](json_ld.html.erb) | schema.org AggregateRating + Review markup for Google rich snippets |
+| [`static_site.md`](static_site.md) | Rendering testimonials on a separate marketing site (Astro & friends) from the public API |
+In-app examples read the models directly — no HTTP, no `public_api` needed.
+The static-site example is the one place the public API earns its keep.

data/examples/badge.html.erb ADDED Viewed

@@ -0,0 +1,13 @@
+<%# The "★ 4.9 from 87 reviews" chip. Same numbers the API's /api/stats serves. %>
+<% scope = Testimonials::Testimonial.publishable.where.not(rating: nil) %>
+<% if (count = scope.count).positive? %>
+  <a href="#wall-of-love"
+     style="display: inline-flex; align-items: center; gap: 6px; padding: 6px 14px;
+            border: 1px solid #e5e7eb; border-radius: 999px; text-decoration: none;
+            font: 600 14px system-ui, sans-serif; color: inherit;">
+    <span style="color: #f59e0b;">★</span>
+    <%= scope.average(:rating).to_f.round(1) %>
+    <span style="font-weight: 400; color: #6b7280;">from <%= count %> reviews</span>
+  </a>
+<% end %>

data/examples/json_ld.html.erb ADDED Viewed

@@ -0,0 +1,28 @@
+<%# schema.org structured data for Google rich snippets (star ratings in
+    search results). Put it in the <head> of the page that shows the reviews. %>
+<% scope = Testimonials::Testimonial.publishable %>
+<% rated = scope.where.not(rating: nil) %>
+<% if rated.exists? %>
+  <script type="application/ld+json">
+    <%= raw({
+          '@context' => 'https://schema.org',
+          '@type' => 'Product',
+          name: Testimonials.app_name,
+          aggregateRating: {
+            '@type' => 'AggregateRating',
+            ratingValue: rated.average(:rating).to_f.round(2),
+            reviewCount: rated.count
+          },
+          review: scope.featured_first.limit(5).map do |testimonial|
+            {
+              '@type' => 'Review',
+              reviewBody: testimonial.quote,
+              author: { '@type' => 'Person', name: testimonial.name },
+              reviewRating: testimonial.rating &&
+                { '@type' => 'Rating', ratingValue: testimonial.rating }
+            }.compact
+          end
+        }.to_json) %>
+  </script>
+<% end %>

data/examples/static_site.md ADDED Viewed

@@ -0,0 +1,43 @@
+# Testimonials on a separate marketing site
+Your Rails app collects and curates; your marketing site (Astro, Eleventy,
+plain HTML on Cloudflare — anything) renders. Turn on the public API:
+```ruby
+# config/initializers/testimonials.rb
+config.public_api = true
+```
+`GET https://app.example.com/testimonials/api/testimonials` now serves approved +
+consented records to anyone (CORS `*`), and `/testimonials/api/stats` serves the
+badge numbers. Emails are never included.
+## Astro example (build-time fetch)
+```astro
+---
+const res = await fetch("https://app.example.com/testimonials/api/testimonials?limit=12");
+const { testimonials } = await res.json();
+const stats = await (await fetch("https://app.example.com/testimonials/api/stats")).json();
+---
+<p>★ {stats.average_rating} from {stats.count} reviews</p>
+<div class="wall">
+  {testimonials.map((t) => (
+    <figure>
+      {t.rating && <div>{"★".repeat(t.rating)}</div>}
+      {t.video_url && <video controls preload="metadata" poster={t.poster_url} src={t.video_url}></video>}
+      {t.quote && <blockquote>“{t.quote}”</blockquote>}
+      <figcaption>
+        {t.avatar_url && <img src={t.avatar_url} alt="" width="36" height="36" />}
+        <b>{t.name}</b> {t.title_company && <span>— {t.title_company}</span>}
+      </figcaption>
+    </figure>
+  ))}
+</div>
+```
+Media URLs (`video_url`, `avatar_url`) point back at the Rails app, which
+redirects to signed Active Storage URLs with Range support — videos play
+directly in a `<video>` tag.

data/examples/testimonial_card.html.erb ADDED Viewed

@@ -0,0 +1,17 @@
+<%# One hero quote for a pricing or landing page. Pick it explicitly, or take
+    the newest featured one as below. %>
+<% testimonial = Testimonials::Testimonial.publishable.where(featured: true).newest_first.first %>
+<% if testimonial %>
+  <figure style="max-width: 560px; margin: 0 auto; padding: 24px; border: 1px solid #e5e7eb;
+                 border-radius: 16px; font: 17px/1.6 system-ui, sans-serif; text-align: center;">
+    <% if testimonial.rating %>
+      <div style="color: #f59e0b; letter-spacing: 3px; margin-bottom: 8px;"><%= '★' * testimonial.rating %></div>
+    <% end %>
+    <blockquote style="margin: 0 0 16px; font-weight: 500;">“<%= testimonial.quote %>”</blockquote>
+    <figcaption style="font-size: 14px; color: #6b7280;">
+      <b style="color: inherit;"><%= testimonial.name %></b>
+      <% if testimonial.title_company.present? %> — <%= testimonial.title_company %><% end %>
+    </figcaption>
+  </figure>
+<% end %>

data/examples/wall_of_love.html.erb ADDED Viewed

@@ -0,0 +1,43 @@
+<%# A wall of love: drop into any view of the host app and restyle at will.
+    Videos stream through the engine's gated media route (admin, or
+    public_api + publishable). %>
+<style>
+  .wall { display: grid; grid-template-columns: repeat(auto-fill, minmax(260px, 1fr)); gap: 16px; }
+  .wall-card { border: 1px solid #e5e7eb; border-radius: 14px; padding: 18px; background: #fff;
+               font: 15px/1.5 system-ui, sans-serif; break-inside: avoid; }
+  .wall-stars { color: #f59e0b; letter-spacing: 2px; margin-bottom: 6px; }
+  .wall-quote { margin: 0 0 12px; }
+  .wall-author { display: flex; align-items: center; gap: 10px; }
+  .wall-author img { width: 36px; height: 36px; border-radius: 50%; object-fit: cover; }
+  .wall-author b { display: block; font-size: 14px; }
+  .wall-author span { font-size: 13px; color: #6b7280; }
+  .wall-card video { width: 100%; border-radius: 10px; background: #000; margin-bottom: 10px; }
+</style>
+<div class="wall">
+  <% Testimonials::Testimonial.publishable.featured_first.limit(12).each do |testimonial| %>
+    <figure class="wall-card">
+      <% if testimonial.rating %>
+        <div class="wall-stars"><%= '★' * testimonial.rating %></div>
+      <% end %>
+      <% if testimonial.video_attached? %>
+        <video controls preload="metadata"
+               poster="<%= testimonials.testimonial_poster_path(testimonial) if testimonial.poster_attached? %>"
+               src="<%= testimonials.testimonial_video_path(testimonial) %>"></video>
+      <% end %>
+      <% if testimonial.quote.present? %>
+        <blockquote class="wall-quote">“<%= testimonial.quote %>”</blockquote>
+      <% end %>
+      <figcaption class="wall-author">
+        <% if testimonial.avatar_attached? %>
+          <img src="<%= testimonials.testimonial_avatar_path(testimonial) %>" alt="">
+        <% end %>
+        <div>
+          <b><%= testimonial.name %></b>
+          <span><%= testimonial.title_company %></span>
+        </div>
+      </figcaption>
+    </figure>
+  <% end %>
+</div>

data/lib/generators/testimonials/install/install_generator.rb CHANGED Viewed

@@ -2,23 +2,34 @@
 require 'rails/generators'
 require 'rails/generators/active_record'
+require_relative '../migration_helpers'
 module Testimonials
   module Generators
     class InstallGenerator < Rails::Generators::Base
       include ActiveRecord::Generators::Migration
+      include MigrationHelpers
       source_root File.expand_path('templates', __dir__)
       desc 'Installs testimonials: config initializer, migration, and engine mount.'
-      # NPS is the one part of the gem an app can genuinely not want. Skipping
-      # it leaves out the table and writes `config.nps = false`, so nothing
-      # ever reaches a table that isn't there — no runtime introspection, no
-      # boot-time database call. `testimonials:nps` adds it later.
+      # Two parts of the gem an app can genuinely not want. Skipping either
+      # leaves out its table and writes the matching config flag as false, so
+      # nothing ever reaches a table that isn't there — no runtime
+      # introspection, no boot-time database call. `testimonials:nps` and
+      # `testimonials:prompt_events` add them later.
       class_option :skip_nps, type: :boolean, default: false,
                               desc: 'Leave out the NPS table and turn the NPS flow off'
+      # The throttle ledger only earns its rows if the app auto-prompts. An
+      # app that opens the widget from its own button writes one row per
+      # dismissal for nothing, so it can leave the table out — and then
+      # testimonial_prompt! no longer auto-opens, since nothing could throttle
+      # it. Explicit opens are unaffected.
+      class_option :skip_prompt_events, type: :boolean, default: false,
+                                        desc: 'Leave out the prompt-history table; no auto-prompts, only explicit opens'
       def create_initializer
         template 'initializer.rb.tt', 'config/initializers/testimonials.rb'
       end
@@ -39,15 +50,16 @@ module Testimonials
         samples = options[:skip_nps] ? 'testimonials' : 'testimonials and NPS'
         say "Optional: run `bin/rails testimonials:seed_demo` for sample #{samples}."
         say "Collect from outside the app via /testimonials/new.\n"
-        return unless options[:skip_nps]
-        say 'Installed without NPS. Add it later with `bin/rails generate testimonials:nps`.', :yellow
-      end
+        if options[:skip_nps]
+          say 'Installed without NPS. Add it later with `bin/rails generate testimonials:nps`.', :yellow
+        end
-      private
+        return unless options[:skip_prompt_events]
-      def migration_version
-        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+        say 'Installed without prompt history, so testimonial_prompt! will not auto-open the ' \
+            'widget — open it from your own button. Add it later with ' \
+            '`bin/rails generate testimonials:prompt_events`.', :yellow
       end
     end
   end

data/lib/generators/testimonials/install/templates/create_testimonials_tables.rb.tt CHANGED Viewed

@@ -2,7 +2,7 @@
 class CreateTestimonialsTables < ActiveRecord::Migration<%= migration_version %>
   def change
-    create_table :testimonials_testimonials do |t|
+    create_table :testimonials_testimonials<%= primary_key_type_option %> do |t|
       t.string :kind, null: false, default: 'text'
       t.text :body
       t.integer :rating
@@ -26,9 +26,9 @@ class CreateTestimonialsTables < ActiveRecord::Migration<%= migration_version %>
     add_index :testimonials_testimonials, :status
     add_index :testimonials_testimonials, %i[tenant status]
     add_index :testimonials_testimonials, %i[tenant status consent_given]
 <% unless options[:skip_nps] -%>
-    create_table :testimonials_nps_responses do |t|
+    create_table :testimonials_nps_responses<%= primary_key_type_option %> do |t|
       t.integer :score, null: false
       t.text :comment
       t.string :author_id
@@ -42,9 +42,10 @@ class CreateTestimonialsTables < ActiveRecord::Migration<%= migration_version %>
       t.timestamps
     end
     add_index :testimonials_nps_responses, %i[tenant score]
 <% end -%>
-    create_table :testimonials_prompt_events do |t|
+<% unless options[:skip_prompt_events] -%>
+    create_table :testimonials_prompt_events<%= primary_key_type_option %> do |t|
       t.string :kind, null: false
       t.string :action, null: false
       t.string :author_id
@@ -55,5 +56,6 @@ class CreateTestimonialsTables < ActiveRecord::Migration<%= migration_version %>
     end
     add_index :testimonials_prompt_events, %i[tenant author_id kind]
     add_index :testimonials_prompt_events, %i[tenant visitor_token kind]
+<% end -%>
   end
 end

data/lib/generators/testimonials/install/templates/initializer.rb.tt CHANGED Viewed

@@ -13,9 +13,17 @@ Testimonials.configure do |config|
   # only — override before deploying.
   # config.authorize_admin = ->(request) { request.env["warden"]&.user&.admin? }
   #
-  # Render the dashboard inside your app's admin layout. Default: the gem's
-  # standalone dashboard layout.
+  # Two ways to put the dashboard inside an admin you already have.
+  #
+  # The layout only — the gem's controllers, your shell:
   # config.admin_layout = "admin/application"
+  #
+  # Or the whole stack. Name the controller your own admin inherits from and
+  # the dashboard picks up its layout, helpers, authentication and any request
+  # context its before_actions set up. Only the dashboard inherits it; the
+  # widget's endpoints stay public, so this cannot ask a member leaving a
+  # review for a staff session.
+  # config.base_controller_class = "Admin::BaseController"
   # Attribute submissions to a user (optional). Return an object responding
   # to #id, or nil. Receives the request.
@@ -69,6 +77,21 @@ Testimonials.configure do |config|
   # config.reprompt_after = 90.days
   # config.max_prompts = 3
+  # The prompt history the throttle reads (testimonials_prompt_events).
+<% if options[:skip_prompt_events] -%>
+  # Installed with --skip-prompt-events, so there is no table and no history is
+  # written. Nothing is throttled, so nothing auto-opens either:
+  # testimonial_prompt! is a no-op here and the widget opens from your own
+  # button, data-testimonial-prompt, or window.Testimonials.open(). To turn
+  # auto-prompts on later: `bin/rails generate testimonials:prompt_events &&
+  # bin/rails db:migrate`, then flip this to true.
+  config.prompt_events = false
+<% else -%>
+  # False keeps no history — and then nothing auto-opens, since nothing could
+  # throttle it. For apps that only open the widget on a click.
+  # config.prompt_events = true
+<% end -%>
   # The public-use consent line, stored verbatim when a customer picks
   # "use publicly". nil = localized default ("You can use my testimonial
   # publicly in your marketing and sales."). The private-use line is

data/lib/generators/testimonials/migration_helpers.rb ADDED Viewed

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+module Testimonials
+  module Generators
+    # Shared bits every migration-writing generator needs.
+    module MigrationHelpers
+      private
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+      # Follow the host's own key type instead of forcing bigint. An app that
+      # keys its models with uuids sets this, and its
+      # `active_storage_attachments.record_id` is then a uuid column — bigint
+      # tables here could never take a video or avatar attachment, because a
+      # uuid foreign key has nowhere to point.
+      #
+      # Same lookup Rails' own Active Storage, Action Text and Action Mailbox
+      # migrations do, so a host that set it once gets consistent tables from
+      # all of them.
+      #
+      # Rendered as a `create_table` option rather than a bare value, because a
+      # template is expanded at generate time: emitting the method name would
+      # put `id: primary_key_type` in the migration, where nothing defines it.
+      # A host with no setting gets no option at all, so the migration reads
+      # exactly as it always did.
+      def primary_key_type_option
+        config = Rails.configuration.generators
+        type = config.options[config.orm][:primary_key_type]
+        type ? ", id: :#{type}" : ''
+      end
+    end
+  end
+end

data/lib/generators/testimonials/nps/nps_generator.rb CHANGED Viewed

@@ -2,6 +2,7 @@
 require 'rails/generators'
 require 'rails/generators/active_record'
+require_relative '../migration_helpers'
 module Testimonials
   module Generators
@@ -12,6 +13,7 @@ module Testimonials
     #   bin/rails generate testimonials:nps && bin/rails db:migrate
     class NpsGenerator < Rails::Generators::Base
       include ActiveRecord::Generators::Migration
+      include MigrationHelpers
       source_root File.expand_path('templates', __dir__)
@@ -26,12 +28,6 @@ module Testimonials
         say "\nNPS table queued. Run `rails db:migrate`, then set", :green
         say 'config.nps = true in config/initializers/testimonials.rb to turn the flow on.'
       end
-      private
-      def migration_version
-        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
-      end
     end
   end
 end

data/lib/generators/testimonials/nps/templates/create_testimonials_nps_responses.rb.tt CHANGED Viewed

@@ -2,7 +2,7 @@
 class CreateTestimonialsNpsResponses < ActiveRecord::Migration<%= migration_version %>
   def change
-    create_table :testimonials_nps_responses do |t|
+    create_table :testimonials_nps_responses<%= primary_key_type_option %> do |t|
       t.integer :score, null: false
       t.text :comment
       t.string :author_id

data/lib/generators/testimonials/prompt_events/prompt_events_generator.rb ADDED Viewed

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+require 'rails/generators'
+require 'rails/generators/active_record'
+require_relative '../migration_helpers'
+module Testimonials
+  module Generators
+    # For apps that installed with --skip-prompt-events and later want
+    # auto-prompts: creates the testimonials_prompt_events table, the ledger
+    # the throttle reads. A full install already has it. Additive and safe —
+    # nothing reads or writes the table until config.prompt_events is true.
+    #
+    #   bin/rails generate testimonials:prompt_events && bin/rails db:migrate
+    class PromptEventsGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+      include MigrationHelpers
+      source_root File.expand_path('templates', __dir__)
+      desc 'Adds the prompt history table for an install that skipped it.'
+      def create_migration_file
+        migration_template 'create_testimonials_prompt_events.rb.tt',
+                           'db/migrate/create_testimonials_prompt_events.rb'
+      end
+      def post_install
+        say "\nPrompt history table queued. Run `rails db:migrate`, then set", :green
+        say 'config.prompt_events = true in config/initializers/testimonials.rb to let'
+        say 'testimonial_prompt! auto-open the widget again.'
+      end
+    end
+  end
+end

data/lib/generators/testimonials/prompt_events/templates/create_testimonials_prompt_events.rb.tt ADDED Viewed

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+class CreateTestimonialsPromptEvents < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :testimonials_prompt_events<%= primary_key_type_option %> do |t|
+      t.string :kind, null: false
+      t.string :action, null: false
+      t.string :author_id
+      t.string :visitor_token
+      t.string :tenant # opaque per-tenant key; nil = single global collection
+      t.timestamps
+    end
+    add_index :testimonials_prompt_events, %i[tenant author_id kind]
+    add_index :testimonials_prompt_events, %i[tenant visitor_token kind]
+  end
+end

data/lib/generators/testimonials/tenant/templates/add_tenant_to_testimonials.rb.tt CHANGED Viewed

@@ -3,17 +3,20 @@
 class AddTenantToTestimonials < ActiveRecord::Migration<%= migration_version %>
   def change
     add_column :testimonials_testimonials, :tenant, :string
-    add_column :testimonials_prompt_events, :tenant, :string
     add_index :testimonials_testimonials, %i[tenant status]
     add_index :testimonials_testimonials, %i[tenant status consent_given]
-    add_index :testimonials_prompt_events, %i[tenant author_id kind]
-    add_index :testimonials_prompt_events, %i[tenant visitor_token kind]
-    # An install run with --skip-nps has no NPS table to add the column to.
-    return unless table_exists?(:testimonials_nps_responses)
+    # The optional tables: an install run with --skip-nps or
+    # --skip-prompt-events has no table to add the column to.
+    if table_exists?(:testimonials_nps_responses)
+      add_column :testimonials_nps_responses, :tenant, :string
+      add_index :testimonials_nps_responses, %i[tenant score]
+    end
-    add_column :testimonials_nps_responses, :tenant, :string
-    add_index :testimonials_nps_responses, %i[tenant score]
+    return unless table_exists?(:testimonials_prompt_events)
+    add_column :testimonials_prompt_events, :tenant, :string
+    add_index :testimonials_prompt_events, %i[tenant author_id kind]
+    add_index :testimonials_prompt_events, %i[tenant visitor_token kind]
   end
 end

data/lib/generators/testimonials/tenant/tenant_generator.rb CHANGED Viewed

@@ -2,6 +2,7 @@
 require 'rails/generators'
 require 'rails/generators/active_record'
+require_relative '../migration_helpers'
 module Testimonials
   module Generators
@@ -15,6 +16,7 @@ module Testimonials
     #   bin/rails generate testimonials:tenant && bin/rails db:migrate
     class TenantGenerator < Rails::Generators::Base
       include ActiveRecord::Generators::Migration
+      include MigrationHelpers
       source_root File.expand_path('templates', __dir__)
@@ -29,12 +31,6 @@ module Testimonials
         say "\ntenant column queued. Run `rails db:migrate`, then set", :green
         say 'config.tenant in config/initializers/testimonials.rb to scope per tenant.'
       end
-      private
-      def migration_version
-        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
-      end
     end
   end
 end

data/lib/testimonials/configuration.rb CHANGED Viewed

@@ -5,6 +5,10 @@ module Testimonials
   # works with zero configuration; the hooks below let an app decide who gets
   # prompted, who can triage, and how submissions are attributed.
   class Configuration
+    # The gem's own dashboard layout. Compared against, so DashboardController
+    # can tell "the host left this alone" from "the host chose this".
+    DEFAULT_ADMIN_LAYOUT = 'testimonials/application'
     # Shown in the widget ("Enjoying %{app}?") and interpolated into the
     # default questions. nil resolves to the Rails application name.
     attr_accessor :app_name
@@ -19,8 +23,26 @@ module Testimonials
     # Layout used by the built-in dashboard. Override this to render
     # Testimonials inside your app's admin shell, e.g. "admin/application".
+    # The lighter of the two ways to adopt a host's chrome; see
+    # base_controller_class for the other.
     attr_accessor :admin_layout
+    # The controller the DASHBOARD inherits from, as a String so it resolves
+    # lazily rather than at config time. Default: a plain
+    # 'ActionController::Base', where `authorize_admin` is the only gate.
+    #
+    # Name the controller your own admin already inherits from and the
+    # dashboard adopts that whole stack — layout, helpers, authentication, and
+    # any request context your before_actions set up (a `Current` attribute the
+    # layout reads, say). `admin_layout` covers only the layout, which leaves a
+    # host layout calling its own helpers to raise NameError under the engine's
+    # isolated namespace.
+    #
+    # Only the dashboard uses it. The widget's endpoints stay on the engine's
+    # own public controller, so an admin base controller here can never demand
+    # a staff session from a member leaving a review.
+    attr_accessor :base_controller_class
     # Resolve the current user for attribution (optional). Return an object
     # responding to #id, or nil. Receives the request.
     attr_accessor :current_user
@@ -69,6 +91,15 @@ module Testimonials
     # (clicking your link) always work.
     attr_accessor :reprompt_after, :max_prompts
+    # The throttling ledger itself (testimonials_prompt_events). Off means no
+    # per-user prompt history is written — and therefore no auto-prompts:
+    # `testimonial_prompt!` stops opening the widget, because a prompt that
+    # can't be throttled would reopen on every page. Explicit opens — your
+    # own button, `data-testimonial-prompt`, `window.Testimonials.open()`,
+    # the public pages — are unaffected. For apps that only ever open the
+    # widget on a click; `--skip-prompt-events` writes it at install time.
+    attr_accessor :prompt_events
     # Consent line stored verbatim with each submission. nil uses the
     # localized default.
     attr_accessor :consent_text
@@ -108,7 +139,8 @@ module Testimonials
       @app_name = nil
       @enabled = ->(_request) { true }
       @authorize_admin = ->(_request) { Rails.env.development? }
-      @admin_layout = 'testimonials/application'
+      @admin_layout = DEFAULT_ADMIN_LAYOUT
+      @base_controller_class = 'ActionController::Base'
       @current_user = ->(_request) {}
       @tenant = ->(_request) {}
       @user_display = lambda { |user|
@@ -123,6 +155,7 @@ module Testimonials
       @storage_service = nil
       @reprompt_after = 90 * 24 * 60 * 60
       @max_prompts = 3
+      @prompt_events = true
       @consent_text = nil
       @public_collection = true
       @public_api = false