hot-glue 0.8 → 0.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 555bc8c92663c9e6797856debce6569ef5532f1d8f0536d862f1226b08b3e297
-  data.tar.gz: 2cc566882dc10083d857ebf8e254a126cf2842cde280509ff56ce37a86c4766e
+  metadata.gz: 4b7fb9cf9f9337373e86732ff6db9b2904de11b9d00450f78d44235820e9bdba
+  data.tar.gz: 7213c6c5680a3390559944d2e390b913269d9fee5c016db358f5ac64f6e7c1b8
 SHA512:
-  metadata.gz: 9592d760df6d8b79e41fdd71bb8e8a89f62745056c512b56cf1d31bed0174e9169146531febdec68dfb7ca2017e26e048f52055718ab04279e444c2742016482
-  data.tar.gz: c4e5ab6b7289ba6ac225eb4f40267bd2bb5b0163b1dc029ba43b55161552255ae4e541028a89aa4b988f6a83ea8123da7102216d4afe52a226dead4ca0e71c98
+  metadata.gz: 759e7b6343a5ed0457b13cdc039732ada8187ebaf27e9da04cf8203130861210bd5dccb50795712fe43ae68e7e51f8eeb2a6afb55d3cfcf2a45533d65bee20a7
+  data.tar.gz: 841e4b699b8d5f8b416618a768fc58f9748c6b1e1c1e90337a92e55ced89893b872a4ef883e16bcd6c555685caa42e68e8348b295a001d40503e2ae92dd1a7df

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    hot-glue (0.7.9)
+    hot-glue (0.9)
       ffaker (~> 2.16)
       rails (> 5.1)
 

data/README.md

@@ -2009,6 +2009,74 @@ List of field names (separated by commas)
 Leave off (do not specify) to sort by all sort-eligible fields
 
 
+## CSV / Excel Export
+A scaffold can export its list (respecting whatever search filters and sort order the user currently has applied) as a CSV or Excel file. Small result sets download immediately; large result sets are built in background job and the browser is notified via Turbo Streams when the file is ready, then the download starts automatically.
+
+### One-time setup
+
+Run this once per app, **before** generating any scaffold with `--csv`:
+
+```
+bin/rails generate hot_glue:csv_export_install
+```
+
+This copies the shared pieces every exporting controller depends on (`CsvConstructor`, the `CsvRequest` model + migration, `BuildCsvJob`, `DestroyCsvRequestJob`, `CsvRequestsController`, the Turbo Stream partials, and an `auto-download` Stimulus controller), and prints a checklist to finish:
+
+1. Add gems:
+```ruby
+gem "caxlsx"   # .xlsx / Excel export
+gem "csv"      # required on Ruby 3.4+ (csv is no longer in the default gemset)
+```
+
+2. Install Active Storage (the export file is stored as an attachment):
+```
+bin/rails active_storage:install
+```
+
+3. Add routes — the global download route once:
+```ruby
+resources :csv_requests, only: [] do
+  member { get :download }
+end
+```
+...then, for **each** scaffold you build with `--csv`, add an export route to
+that resource:
+```ruby
+resources :things do
+  collection { post :export }
+end
+```
+
+4. **Action Cable must be cross-process.** A large export runs in a background job and, on completion, broadcasts a Turbo Stream telling the browser the file is ready. The job and the web server are separate processes in any real deployment (and in dev too, if you run a separate worker), so the Action Cable adapter must be shared across processes — `solid_cable` or `redis` both work. The `async` adapter (Rails' dev default) only works in-process and will make the export appear to hang forever on "Preparing...". If you use the redis adapter, note Action Cable requires `redis < 6`:
+
+```ruby
+gem "redis", "~> 5.0"
+```
+
+### `--csv` (default: false)
+Builds the exporter into this controller: an `EXPORTABLE_FIELDS` constant, a `self.load_all_<plural>_query` class method (shared with `CsvConstructor` so an export always reflects the same search+sort logic as the interactive index), an `export` action, and an Export dropdown button (CSV / Excel) above the list. Opt in per scaffold with `--csv`.
+
+### `--csv-fields=name,desc,age`
+Comma-separated whitelist of which columns are written to the export file, and in what order. Defaults to every field passed to `--include`. Raises at generation time if you list a field that isn't in `--include`. `id` is never exportable, whitelisted or not.
+
+`--csv` cannot be combined with `--no-list` — there's no list to export — and raises at generation time if you try.
+
+### How it behaves at runtime
+- **Quick mode** (≤ 100 matching rows): the file is built in-process and streamed back immediately as an attachment — no job, no polling.
+
+- **Background mode** (> 100 matching rows): a `CsvRequest` row is created, a `BuildCsvJob` is queued, and the page shows a "Preparing your export…" panel. When the job finishes it attaches the file (via Active Storage) and broadcasts a Turbo Stream that replaces that panel with a download link, which the `auto-download` Stimulus controller clicks automatically — no second click required. The `CsvRequest` (and its attached file) are destroyed automatically ~5 minutes after download.
+
+### `--csv` with `--pundit`
+The export respects your Pundit scopes. `--csv` generates a `self.csv_export_scope(owner)` class method (`Pundit.policy_scope!(owner, Model)`) that `CsvConstructor` calls whenever it's present, for both quick and background exports:
+- Quick (synchronous) exports run inside the request, so the scope is the same `policy_scope(...)` the interactive index already uses.
+- Background exports run in a separate job process with no request/session, so the `export` action stores `pundit_user` on the `CsvRequest` (`owner`, the same nullable polymorphic column mentioned below) at creation time, and the job recomputes `Pundit.policy_scope!(owner, Model)` from that stored value when it runs.
+
+### Known limitations
+- Scaffolds generated without `--gd` and without `--pundit` (auth-scoped some other way, e.g. `current_user.things`) correctly scope the interactive index to `current_user`, but a *background* export's `CsvConstructor` call doesn't yet receive that scope — it falls back to the model's default. To be addressed once there's a dummy app with real login to build and test it against. (`--pundit` scoping is handled — see above.)
+
+- The `export` route helper only handles top-level and namespaced resources today, not `nested_set`-style nested routes.
+
+
 ## Attachments
 
 #### `--attachments=` Long form syntax with 1st and 2nd parameters
@@ -2176,8 +2244,10 @@ For Pagy version 9 or below
 4. add `include Pagy::Frontend` to ApplicationHelper
 
 For Pagy version 43 (there was a version jump)
-*NOT YET COMPATIBLE WITH PAGY 43*
-TODO: implement pagy 43
+Include pagy in your code (usually application_controller.rb)
+`include Pagy::Method`
+
+Breaking changes bewteen Pagy version 9 and version 42 force you to rebuild everything (every view) when upgrading Pagy. Hot Glue now detects which version of Pagy is installed and outputs the syntax for that version.
 
 ## "Thing" Label
 
@@ -2498,6 +2568,10 @@ These automatic pickups for partials are detected at build time. This means that
 
 # VERSION HISTORY
 
+#### 2026-09-05 - v0.9
+- CSV / Excel export: `--csv` (default false) and `--csv-fields=`. New `hot_glue:csv_export_install` generator sets up the shared `CsvConstructor`/`CsvRequest`/`BuildCsvJob` infrastructure. Quick (in-process) and background (job + Turbo Stream + auto-download) modes; the data output respects that you have sorted and searched too. Respects `--pundit` policy scopes on both quick and background exports. Raises if combined with `--no-list`. See "CSV / Excel Export" above for full docs.
+
+
 #### 2026-08-30 - v0.8
 - `--sortable` (true of flagged; false otherwise; does not take an argument)
 To add sorting to your columns add `--sortable` to your build

data/lib/generators/hot_glue/csv_export_install_generator.rb

@@ -0,0 +1,100 @@
+
+
+module HotGlue
+  class CsvExportInstallGenerator < Rails::Generators::Base
+    source_root File.expand_path('templates', __dir__)
+
+    def filepath_prefix
+      # todo: inject the context
+      'spec/dummy/' if $INTERNAL_SPECS
+    end
+
+    def initialize(*args) #:nodoc:
+      super
+
+      # global service object, model, jobs, controller & views shared by every
+      # scaffold's CSV/Excel exporter (built per-controller with the --csv flag)
+      copy_file "csv_export/csv_constructor.rb", "#{filepath_prefix}app/services/csv_constructor.rb"
+      copy_file "csv_export/csv_request.rb", "#{filepath_prefix}app/models/csv_request.rb"
+      copy_file "csv_export/build_csv_job.rb", "#{filepath_prefix}app/jobs/build_csv_job.rb"
+      copy_file "csv_export/destroy_csv_request_job.rb", "#{filepath_prefix}app/jobs/destroy_csv_request_job.rb"
+      copy_file "csv_export/csv_requests_controller.rb", "#{filepath_prefix}app/controllers/csv_requests_controller.rb"
+
+      copy_file "csv_export/_pending.erb", "#{filepath_prefix}app/views/csv_requests/_pending.erb"
+      copy_file "csv_export/_ready.erb", "#{filepath_prefix}app/views/csv_requests/_ready.erb"
+      copy_file "csv_export/_failed.erb", "#{filepath_prefix}app/views/csv_requests/_failed.erb"
+
+      # Stimulus controller that auto-triggers the download when the background
+      # export's "ready" Turbo Stream arrives (registers it in the manifest,
+      # then overwrites the stub with the real implementation)
+      system("./bin/rails generate stimulus AutoDownload")
+      copy_file "csv_export/auto_download_controller.js", "#{filepath_prefix}app/javascript/controllers/auto_download_controller.js"
+
+      timestamp = Time.now.utc.strftime("%Y%m%d%H%M%S")
+      migration_version = ActiveRecord::Migration.current_version
+      create_file "#{filepath_prefix}db/migrate/#{timestamp}_create_csv_requests.rb", <<~RUBY
+        class CreateCsvRequests < ActiveRecord::Migration[#{migration_version}]
+          def change
+            create_table :csv_requests do |t|
+              t.string :controller_name, null: false
+              t.string :format, null: false, default: "csv"
+              t.jsonb :query_params, null: false, default: {}
+              t.string :status, null: false, default: "pending"
+              t.string :owner_type
+              t.bigint :owner_id
+              t.text :error_message
+              t.datetime :downloaded_at
+
+              t.timestamps
+            end
+            add_index :csv_requests, [:owner_type, :owner_id]
+          end
+        end
+      RUBY
+
+      puts <<~MSG
+
+        ============================================================
+        HOT GLUE --> CSV/Excel export installed.
+
+        Finish setup with these one-time steps:
+
+        1. Add these gems to your Gemfile:
+             gem "caxlsx"   # .xlsx / Excel export
+             gem "csv"      # required on Ruby 3.4+ (csv is no longer default)
+
+        2. Install Active Storage (the export file is stored as an attachment):
+             bin/rails active_storage:install
+
+        3. Run migrations:
+             bin/rails db:migrate
+
+        4. Add routes to config/routes.rb:
+
+           a) the global download route (once):
+                resources :csv_requests, only: [] do
+                  member { get :download }
+                end
+
+           b) for EACH scaffold you build with --csv, add an export
+              collection route to that resource, e.g. for Things:
+                resources :things do
+                  collection { post :export }
+                end
+
+        5. IMPORTANT — Action Cable must be CROSS-PROCESS.
+           When an export is too large it runs in a background job and, on
+           completion, broadcasts a Turbo Stream to the browser. The job and the
+           web server are separate processes in any real deployment (and in dev
+           if you run a separate worker), so your Action Cable adapter must be
+           shared across processes -- solid_cable, or redis. The `async` adapter
+           (Rails' dev default) only works in-process and will make the export
+           appear to hang on "Preparing...". If you use the redis adapter, note
+           that Action Cable requires the redis gem < 6:
+                gem "redis", "~> 5.0"
+        ============================================================
+
+      MSG
+    end
+  end
+end

data/lib/generators/hot_glue/layout_strategy/base.rb

@@ -24,6 +24,7 @@ module LayoutStrategy
       (col_width/(builder.columns.count)).to_i
     end
     def list_classes; ""; end
+    def top_button_row_classes; ""; end
     def magic_button_classes; ""; end
     def row_classes; ""; end
     def row_heading_classes; ""; end

data/lib/generators/hot_glue/layout_strategy/bootstrap.rb

@@ -54,6 +54,10 @@ class LayoutStrategy::Bootstrap < LayoutStrategy::Base
     "row hg-row"
   end
 
+  def top_button_row_classes
+    "d-flex justify-content-between align-items-start"
+  end
+
   def page_end
     '</div> </div>'
   end

data/lib/generators/hot_glue/layout_strategy/hot_glue.rb

@@ -35,6 +35,10 @@ class LayoutStrategy::HotGlue < LayoutStrategy::Base
     "scaffold-list"
   end
 
+  def top_button_row_classes
+    "scaffold-button-row"
+  end
+
   def row_classes
     "scaffold-row"
   end

data/lib/generators/hot_glue/layout_strategy/tailwind.rb

@@ -19,6 +19,7 @@ class LayoutStrategy::Tailwind < LayoutStrategy::Base
   end
 
   def list_classes; "overflow-x-auto w-full"; end
+  def top_button_row_classes; "flex justify-between items-start"; end
   def row_classes; "grid grid-cols-4 gap-x-16 py-5 px-4 text-sm text-gray-700 border-b border-gray-200 dark:border-gray-700"; end
   def row_heading_classes; "grid grid-cols-4 gap-x-16 p-4 text-sm font-medium text-gray-900 bg-gray-100 border-t border-b border-gray-200 dark:bg-gray-800 dark:border-gray-700 dark:text-white"; end
   def page_begin; '<div class="overflow-hidden min-w-max"> '; end

data/lib/generators/hot_glue/markup_templates/erb.rb

@@ -13,7 +13,8 @@ module  HotGlue
                   :form_path, :layout_object, :search_clear_button, :search_autosearch,
                   :stimmify, :stimmify_camel, :hidden_create, :hidden_update, :invisible_create,
                   :invisible_update, :plural, :phantom_search, :pagination_style,
-                  :namespace, :controller_build_folder, :sortable, :sortable_fields
+                  :namespace, :controller_build_folder, :sortable, :sortable_fields,
+                  :csv, :csv_fields
 
 
     def initialize(singular:, singular_class: ,
@@ -28,11 +29,14 @@ module  HotGlue
                  form_path: , stimmify: , stimmify_camel:, hidden_create:, hidden_update: ,
                  invisible_create:, invisible_update: , plural: , phantom_search:,
                    pagination_style:, namespace: nil, controller_build_folder: nil,
-                   sortable: false, sortable_fields: [] )
+                   sortable: false, sortable_fields: [],
+                   csv: true, csv_fields: [] )
 
 
       @sortable = sortable
       @sortable_fields = sortable_fields
+      @csv = csv
+      @csv_fields = csv_fields
       @form_path = form_path
       @search = search
       @search_fields = search_fields

data/lib/generators/hot_glue/scaffold_generator.rb

@@ -35,7 +35,8 @@ class HotGlue::ScaffoldGenerator < Erb::Generators::ScaffoldGenerator
                 :stimmify, :stimmify_camel, :hidden_create, :hidden_update,
                 :invisible_create, :invisible_update, :phantom_create_params,
                 :phantom_update_params, :lazy, :back_link_to_parent, :polymorphic_parents,
-                :sortable, :sortable_fields
+                :sortable, :sortable_fields,
+                :csv, :csv_fields
 
   # important: using an attr_accessor called :namespace indirectly causes a conflict with Rails class_name method
   # so we use namespace_value instead
@@ -149,6 +150,11 @@ class HotGlue::ScaffoldGenerator < Erb::Generators::ScaffoldGenerator
   class_option :sortable, type: :boolean, default: false
   class_option :sort_fields, default: nil # comma separated whitelist; defaults to all sortable-type fields
 
+  # CSV/EXCEL EXPORT OPTIONS
+  # requires a one-time `rails generate hot_glue:csv_export_install`
+  class_option :csv, type: :boolean, default: false # build the CSV/Excel exporter into this controller
+  class_option :csv_fields, default: nil # comma separated whitelist; defaults to all included fields
+
 
 
   def initialize(*meta_args)
@@ -778,6 +784,27 @@ class HotGlue::ScaffoldGenerator < Erb::Generators::ScaffoldGenerator
       @sortable_fields = []
     end
 
+    @csv = options['csv']
+
+    if @csv && @no_list
+      raise "--csv cannot be combined with --no-list: there is no list to export."
+    end
+
+    if @csv
+      if options['csv_fields']
+        @csv_fields = options['csv_fields'].split(',').collect(&:to_sym)
+        @csv_fields.each do |field|
+          if !@columns_map[field]
+            raise "You specified a csv field for #{field} but that field is not in the list of columns"
+          end
+        end
+      else
+        @csv_fields = @columns
+      end
+    else
+      @csv_fields = []
+    end
+
 
     @columns_map.each do |key, field|
       if field.is_a?(AssociationField)
@@ -956,7 +983,9 @@ class HotGlue::ScaffoldGenerator < Erb::Generators::ScaffoldGenerator
         namespace: @namespace,
         controller_build_folder: @controller_build_folder,
         sortable: @sortable,
-        sortable_fields: @sortable_fields
+        sortable_fields: @sortable_fields,
+        csv: @csv,
+        csv_fields: @csv_fields
       )
     elsif @markup == "slim"
       raise(HotGlue::Error, "SLIM IS NOT IMPLEMENTED")
@@ -1854,6 +1883,10 @@ class HotGlue::ScaffoldGenerator < Erb::Generators::ScaffoldGenerator
       res << '_lazy_list'
     end
 
+    if @csv && !@no_list
+      res << '_export_button'
+    end
+
     res
   end
 
@@ -2037,36 +2070,70 @@ class HotGlue::ScaffoldGenerator < Erb::Generators::ScaffoldGenerator
   end
 
   def load_all_code
-    # the inner method definition of the load_all_* method
+    # the inner method definition of the load_all_* method (non-CSV path):
+    # query-building followed immediately by pagination (unchanged behavior)
+    load_all_query_code + load_all_pagination_code
+  end
+
+  def load_all_query_class_method_code
+    # the same query-building code but rewritten to use LOCAL variables so it
+    # can live in the class-level load_all_<plural>_query method that the CSV
+    # exporter shares with the controller. (no pagination — the exporter needs
+    # the full result set; pagination stays in the instance load_all_ method)
+    #
+    # For non-god controllers the base relation depends on controller context
+    # (current_user, policy_scope, etc.) which does not exist in a class method,
+    # so it is injected as `scope`. God controllers have a context-free base
+    # (Model.all) and keep it inline.
+    # Pundit's `policy_scope` is a controller-instance method (it depends on
+    # pundit_user), so even a --gd controller needs its scope injected from
+    # the instance when --pundit is enabled -- only a non-pundit --gd
+    # controller can compute its scope inline in the class method.
+    base = (@god && !pundit) ? nil : "scope"
+    load_all_query_code(base_override: base).gsub("@#{plural}", plural).gsub("@q", "q")
+  end
+
+  def load_all_base_scope
+    # the base relation expression used by the instance load_all_ method; for
+    # non-god controllers it is passed into the class-level query method as
+    # `scope:` (it may reference current_user / policy_scope, which only exist
+    # in controller-instance context)
+    if pundit
+      "policy_scope(#{ object_scope })#{record_scope}"
+    elsif !@self_auth
+      "#{ object_scope.gsub("@",'') }#{record_scope}#{ n_plus_one_includes }#{".all" if n_plus_one_includes.blank? && record_scope.blank? }"
+    elsif @nested_set[0] && @nested_set[0][:optional]
+      "#{ class_name }.#{record_scope}.all"
+    else
+      "#{ class_name }.#{record_scope}.where(id: #{ auth_object.gsub("@",'') }.id)#{ n_plus_one_includes }"
+    end
+  end
+
+  def load_all_query_code(base_override: nil)
+    # the query-building portion of load_all (search where-clauses, phantom
+    # search, and sort) — WITHOUT pagination. When base_override is given (the
+    # class-level query method), the base relation is that expression (e.g. an
+    # injected `scope`) instead of the controller-context object scope.
     res = +""
     if @search_fields
-      res << @search_fields.collect{ |field|
+      search_field_assignments = @search_fields.collect{ |field|
         if !@columns_map[field.to_sym].load_all_query_statement.empty?
           @columns_map[field.to_sym].load_all_query_statement
         end
-      }.compact.join("\n" + spaces(4)) + "\n"
+      }.compact
+      res << spaces(4) + search_field_assignments.join("\n" + spaces(4)) + "\n" if search_field_assignments.any?
     end
 
-    if pundit
+    if base_override
+      res << spaces(4) + "@#{ plural_name } = #{ base_override }"
+      res << "\n"
+    elsif pundit
       res << "    @#{ plural_name } = policy_scope(#{ object_scope })#{record_scope}\n"
     else
       if !@self_auth
 
         res << spaces(4) + "@#{ plural_name } = #{ object_scope.gsub("@",'') }#{record_scope}#{ n_plus_one_includes }#{".all" if n_plus_one_includes.blank? && record_scope.blank? }"
 
-        if @search_fields
-          res << @search_fields.collect{ |field|
-            wqs = @columns_map[field.to_sym].where_query_statement
-            if !wqs.empty?
-              "\n" + spaces(4) +  "@#{ plural_name } = @#{ plural_name }#{ wqs } if #{field}_query"
-            end
-          }.compact.join
-        end
-
-
-
-        # res << "\n    @#{plural} = @#{plural}.page(params[:page])#{ '.per(per)' if @paginate_per_page_selector }"
-
       elsif @nested_set[0] && @nested_set[0][:optional]
         res << "@#{ plural_name } = #{ class_name }.#{record_scope}.all"
       else
@@ -2113,7 +2180,11 @@ class HotGlue::ScaffoldGenerator < Erb::Generators::ScaffoldGenerator
       res << "      @#{plural} = @#{plural}.order(params[:sort] => params[:direction].to_sym)\n"
       res << "    end"
     end
+    res
+  end
 
+  def load_all_pagination_code
+    res = +""
     if @pagination_style == "kaminari"
       res << "    @#{plural} = @#{plural}.page(params[:page])#{ ".per(per)" if @paginate_per_page_selector }"
     elsif @pagination_style == "will_paginate"

data/lib/generators/hot_glue/templates/controller.rb.erb

@@ -7,7 +7,8 @@ class <%= controller_class_name %> < <%= controller_descends_from %>
   # rubocop:enable Layout/LineLength <% end %>
 
   helper :hot_glue
-  include HotGlue::ControllerHelper
+  include HotGlue::ControllerHelper<% if @csv %>
+  extend HotGlue::ControllerHelper<% end %>
   <%= @code_in_controller.gsub(";", "\n") %>
 
   <% unless @god %>before_action :<%= "authenticate_" + @auth_identifier.split(".")[0] + "!" %><% end %><% if any_nested? %>
@@ -78,15 +79,32 @@ class <%= controller_class_name %> < <%= controller_descends_from %>
   end<% end %>
   <% unless @no_list %>
 <% if @sortable %>  SORTABLE_FIELDS = %w[<%= @sortable_fields.join(' ') %>].freeze
+<% end %><% if @csv %>  EXPORTABLE_FIELDS = %w[<%= @csv_fields.join(' ') %>].freeze
 <% end %>
-  def load_all_<%= plural %><% if @search == "set" %>
+<% if @csv %>  def self.load_all_<%= plural %>_query(params:<% if !@god || @pundit %>, scope: <%= class_name %>.all<% end %>)
+    q = params[:q]<% if @search == "set" %> || <%= search_default %><% end %>
+<%= load_all_query_class_method_code %>
+
+    [q, <%= plural %>]
+  end
+<% if @pundit %>
+  def self.csv_export_scope(owner)
+    Pundit.policy_scope!(owner, <%= class_name %>)
+  end
+<% end %>
+  def load_all_<%= plural %>
+    @q, @<%= plural %> = self.class.load_all_<%= plural %>_query(params: params<% if !@god || @pundit %>, scope: <%= load_all_base_scope %><% end %>)
+<%= load_all_pagination_code %>
+  end<% else %>  def load_all_<%= plural %><% if @search == "set" %>
     @q = params[:q] || <%= search_default %> <% end %>
 <%= load_all_code %>
-  end
+  end<% end %>
 
   def index
     load_all_<%= plural %><% if @search_fields %>
-<%= @search_fields.collect{|field_name| @columns_map[field_name.to_sym].code_to_reset_match_if_search_is_blank}.compact.join("     \n") %><% end %>
+<%= @search_fields.collect{|field_name| @columns_map[field_name.to_sym].code_to_reset_match_if_search_is_blank}.compact.join("     \n") %><% end %><% if @csv %>
+
+    @pending_csv_request = CsvRequest.find_by(id: flash[:pending_csv_request_id])<% end %>
     <% if @pundit %><% if @pundit && !@pundit_policy_override %>
     authorize @<%= plural_name %><% elsif @pundit && @pundit_policy_override %>
     skip_authorization
@@ -96,7 +114,29 @@ class <%= controller_class_name %> < <%= controller_descends_from %>
     flash[:alert] = 'You are not authorized to perform this action.'
     render 'layouts/error'<% end %>
   end<% end %>
-
+<% if @csv %>
+  def export
+    format_type = %w[csv xlsx].include?(params[:format_type]) ? params[:format_type] : "csv"
+    constructor = CsvConstructor.new(controller_name: "<%= controller_class_name %>", params: params<% if @pundit %>, owner: pundit_user<% end %>)
+
+    if constructor.count <= 100
+      send_data constructor.build(format_type),
+        filename: "<%= plural %>.#{format_type}",
+        type: mime_for_export(format_type),
+        disposition: "attachment"
+    else
+      csv_request = CsvRequest.create!(
+        controller_name: "<%= controller_class_name %>",
+        format: format_type,
+        query_params: params.slice(:sort, :direction, :q).to_unsafe_h<% if @pundit %>,
+        owner: pundit_user<% end %>
+      )
+      BuildCsvJob.perform_later(csv_request.id)
+      flash[:pending_csv_request_id] = csv_request.id
+      redirect_back fallback_location: <%= path_helper_plural %>
+    end
+  end
+<% end %>
 <% if create_action %>  def new<% if @object_owner_sym %>
     @<%= singular_name %> = <%= class_name %>.new<% if eval("#{class_name}.reflect_on_association(:#{@object_owner_sym})").class == ActiveRecord::Reflection::BelongsToReflection  %>(<%= @object_owner_sym %>: <%= @object_owner_eval %>)<% end %><% elsif @object_owner_optional && any_nested? %>
     @<%= singular_name %> = <%= class_name  %>.new({}.merge(<%= @nested_set.last[:singular] %> ? {<%= @object_owner_sym %>: <%= @object_owner_eval %>} : {}))<% else %>
@@ -324,6 +364,10 @@ class <%= controller_class_name %> < <%= controller_descends_from %>
   def namespace
     <% if @namespace %>'<%= @namespace %>/'<% else %><% end %>
   end
-end
+<% if @csv %>
+  def mime_for_export(format_type)
+    format_type == "xlsx" ? "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" : "text/csv"
+  end
+<% end %>end
 
 

data/lib/generators/hot_glue/templates/csv_export/_failed.erb

@@ -0,0 +1,5 @@
+<%= turbo_frame_tag "csv_request_#{csv_request.id}" do %>
+  <div class="alert alert-danger">
+    Your export failed<%= ": #{csv_request.error_message}" if csv_request.error_message.present? %>.
+  </div>
+<% end %>

data/lib/generators/hot_glue/templates/csv_export/_pending.erb

@@ -0,0 +1,6 @@
+<%= turbo_stream_from csv_request %>
+<%= turbo_frame_tag "csv_request_#{csv_request.id}" do %>
+  <div class="alert alert-info">
+    Preparing your <%= csv_request.format.upcase %> export&hellip;
+  </div>
+<% end %>

data/lib/generators/hot_glue/templates/csv_export/_ready.erb

@@ -0,0 +1,6 @@
+<%= turbo_frame_tag "csv_request_#{csv_request.id}" do %>
+  <div class="alert alert-success">
+    Your <%= csv_request.format.upcase %> export is ready.
+    <%= link_to "Download", download_csv_request_path(csv_request), class: "btn btn-sm btn-primary", data: { turbo: false, controller: "auto-download" } %>
+  </div>
+<% end %>

data/lib/generators/hot_glue/templates/csv_export/auto_download_controller.js

@@ -0,0 +1,11 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Attached to the CSV/Excel export "Download" link that arrives via a Turbo
+// Stream broadcast when a background export finishes. On connect it clicks the
+// link once, so the file (served with Content-Disposition: attachment)
+// downloads automatically without the user having to click.
+export default class extends Controller {
+  connect() {
+    this.element.click()
+  }
+}

data/lib/generators/hot_glue/templates/csv_export/build_csv_job.rb

@@ -0,0 +1,36 @@
+class BuildCsvJob < ApplicationJob
+  def perform(csv_request_id)
+    csv_request = CsvRequest.find(csv_request_id)
+    csv_request.update!(status: "processing")
+
+    constructor = CsvConstructor.new(
+      controller_name: csv_request.controller_name,
+      params: csv_request.query_params_as_params,
+      owner: csv_request.owner
+    )
+    content = constructor.build(csv_request.format)
+
+    csv_request.file.attach(
+      io: StringIO.new(content),
+      filename: "export-#{csv_request.id}.#{csv_request.format}",
+      content_type: csv_request.format == "xlsx" ? "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" : "text/csv"
+    )
+    csv_request.update!(status: "completed")
+
+    csv_request.broadcast_replace_to(
+      csv_request,
+      target: "csv_request_#{csv_request.id}",
+      partial: "csv_requests/ready",
+      locals: { csv_request: csv_request }
+    )
+  rescue => e
+    csv_request&.update!(status: "failed", error_message: e.message)
+    csv_request&.broadcast_replace_to(
+      csv_request,
+      target: "csv_request_#{csv_request.id}",
+      partial: "csv_requests/failed",
+      locals: { csv_request: csv_request }
+    )
+    raise
+  end
+end

data/lib/generators/hot_glue/templates/csv_export/csv_constructor.rb

@@ -0,0 +1,68 @@
+require "csv"
+
+class CsvConstructor
+  def initialize(controller_name:, params:, owner: nil)
+    @controller_class = controller_name.to_s.constantize
+    @params = params
+    @owner = owner
+  end
+
+  def relation
+    @relation ||= begin
+      plural = @controller_class.name.underscore.sub(/_controller$/, "")
+      _, relation = if @controller_class.respond_to?(:csv_export_scope)
+        @controller_class.public_send("load_all_#{plural}_query", params: @params, scope: @controller_class.csv_export_scope(@owner))
+      else
+        @controller_class.public_send("load_all_#{plural}_query", params: @params)
+      end
+      relation
+    end
+  end
+
+  def count
+    relation.count
+  end
+
+  def columns
+    @columns ||= @controller_class::EXPORTABLE_FIELDS
+  end
+
+  def build(format)
+    format == "xlsx" ? build_xlsx : build_csv
+  end
+
+  private
+
+  def build_csv
+    CSV.generate do |csv|
+      csv << columns.map(&:humanize)
+      relation.find_each { |record| csv << columns.map { |c| format_value(record, c) } }
+    end
+  end
+
+  def build_xlsx
+    package = Axlsx::Package.new
+    package.workbook.add_worksheet(name: "Export") do |sheet|
+      sheet.add_row columns.map(&:humanize)
+      relation.find_each { |record| sheet.add_row columns.map { |c| format_value(record, c) } }
+    end
+    package.to_stream.read
+  end
+
+  def format_value(record, column)
+    value = record[column]
+    if time_column?(column) && value.respond_to?(:strftime)
+      value.strftime("%H:%M:%S")
+    else
+      value
+    end
+  end
+
+  def time_only_columns
+    @time_only_columns ||= relation.klass.columns_hash.select { |_, c| c.type == :time }.keys
+  end
+
+  def time_column?(column)
+    time_only_columns.include?(column.to_s)
+  end
+end

data/lib/generators/hot_glue/templates/csv_export/csv_request.rb

@@ -0,0 +1,10 @@
+class CsvRequest < ApplicationRecord
+  has_one_attached :file, dependent: :purge_later
+  belongs_to :owner, polymorphic: true, optional: true
+
+  validates :status, inclusion: { in: %w[pending processing completed failed] }
+
+  def query_params_as_params
+    ActionController::Parameters.new(query_params)
+  end
+end

data/lib/generators/hot_glue/templates/csv_export/csv_requests_controller.rb

@@ -0,0 +1,8 @@
+class CsvRequestsController < ApplicationController
+  def download
+    csv_request = CsvRequest.find(params[:id])
+    csv_request.update!(downloaded_at: Time.current)
+    DestroyCsvRequestJob.set(wait: 5.minutes).perform_later(csv_request.id)
+    redirect_to rails_blob_path(csv_request.file, disposition: "attachment")
+  end
+end

data/lib/generators/hot_glue/templates/csv_export/destroy_csv_request_job.rb

@@ -0,0 +1,5 @@
+class DestroyCsvRequestJob < ApplicationJob
+  def perform(csv_request_id)
+    CsvRequest.find_by(id: csv_request_id)&.destroy
+  end
+end

data/lib/generators/hot_glue/templates/erb/_export_button.erb

@@ -0,0 +1,9 @@
+<div class="dropdown d-inline-block">
+  <button class="btn btn-outline-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false">
+    Export
+  </button>
+  <ul class="dropdown-menu">
+    <li><\%= button_to "as CSV", export_<%= "#{@namespace}_" if @namespace %><%= plural %>_path(request.query_parameters.merge(format_type: "csv")), class: "dropdown-item", form: { data: { turbo: false } } %></li>
+    <li><\%= button_to "as Excel", export_<%= "#{@namespace}_" if @namespace %><%= plural %>_path(request.query_parameters.merge(format_type: "xlsx")), class: "dropdown-item", form: { data: { turbo: false } } %></li>
+  </ul>
+</div>

data/lib/generators/hot_glue/templates/erb/_list.erb

@@ -9,14 +9,24 @@
 
     <% if @new_button_position == 'above' %>
     <% unless @no_create %>
-      <%= '<%= render partial: "' + ((@namespace+"/" if @namespace) || "") +
+<% if @csv %>    <div class="<%= @layout_strategy.top_button_row_classes %>">
+<% end %>      <%= '<%= render partial: "' + ((@namespace+"/" if @namespace) || "") +
               @controller_build_folder +
               "/new_button\", locals: {
     #{@nested_set.collect{|arg| arg[:singular] + ": " + arg[:singular]}.join(",\n    ")} }" +
               ' %\>'.gsub('\\',"")  %>
-        <br />
+<% if @csv %>      <\%= render partial: "<%= namespace_with_trailing_dash %><%= @controller_build_folder %>/export_button" %>
+    </div>
+<% end %>        <br />
     <% end %>
     <% end %>
+<% if @csv %>
+    <div id="export-status">
+      <\% if @pending_csv_request %>
+        <\%= render partial: "csv_requests/pending", locals: { csv_request: @pending_csv_request } %>
+      <\% end %>
+    </div>
+<% end %>
 
     <% unless @no_list %>
       <% unless @no_list_heading %>

data/lib/hotglue/version.rb

@@ -1,5 +1,5 @@
 module HotGlue
   class Version
-    CURRENT = '0.8'
+    CURRENT = '0.9'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hot-glue
 version: !ruby/object:Gem::Version
-  version: '0.8'
+  version: '0.9'
 platform: ruby
 authors:
 - Jason Fleetwood-Boldt
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-30 00:00:00.000000000 Z
+date: 2026-09-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -63,6 +63,7 @@ files:
 - config/database.yml
 - config/hot_glue.yml
 - db/schema.rb
+- lib/generators/hot_glue/csv_export_install_generator.rb
 - lib/generators/hot_glue/default_config_loader.rb
 - lib/generators/hot_glue/direct_upload_install_generator.rb
 - lib/generators/hot_glue/dropzone_install_generator.rb
@@ -99,7 +100,17 @@ files:
 - lib/generators/hot_glue/templates/capybara_login.rb
 - lib/generators/hot_glue/templates/computer_code.jpg
 - lib/generators/hot_glue/templates/controller.rb.erb
+- lib/generators/hot_glue/templates/csv_export/_failed.erb
+- lib/generators/hot_glue/templates/csv_export/_pending.erb
+- lib/generators/hot_glue/templates/csv_export/_ready.erb
+- lib/generators/hot_glue/templates/csv_export/auto_download_controller.js
+- lib/generators/hot_glue/templates/csv_export/build_csv_job.rb
+- lib/generators/hot_glue/templates/csv_export/csv_constructor.rb
+- lib/generators/hot_glue/templates/csv_export/csv_request.rb
+- lib/generators/hot_glue/templates/csv_export/csv_requests_controller.rb
+- lib/generators/hot_glue/templates/csv_export/destroy_csv_request_job.rb
 - lib/generators/hot_glue/templates/erb/_edit.erb
+- lib/generators/hot_glue/templates/erb/_export_button.erb
 - lib/generators/hot_glue/templates/erb/_flash_notices.erb
 - lib/generators/hot_glue/templates/erb/_form.erb
 - lib/generators/hot_glue/templates/erb/_lazy_list.erb