crudable-rails 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6eb33d21180100aca344bcdc68bb1c170e28bff416b95c3bb4332fcb7c1eef16
-  data.tar.gz: a08037ec9a25220ba87697becdc928bf78400240088fb1f4c5157730dbfae162
+  metadata.gz: '082ec216ec1a73916737ffc58f6db08819237176efcaceb3b8c3978b5d3667e7'
+  data.tar.gz: 4ff9fd3a946d9ee5bb2839d0c41b72eac71a5139f26b87d01c9a608c8fa9204a
 SHA512:
-  metadata.gz: ec33c0349fa255e003542bd431b5a84ea4b49ca981713409f372655944158dc9656070499d67c915d6dfb70e635136f736310ce84522bfa4e268b94bfb879896
-  data.tar.gz: 2226bedef0b794653978bfd8deab2302d2023909857de65bbec4e600df3a545a171a2c9575271a3a8ca1e6041f3fdec9b86fc1775dcf2dc6d65fd543057ccf84
+  metadata.gz: 894987edb86a9fd16948ea85009387f8872667bfa2b49b0852193a3277147ffa39186450dcd7632a0984881ca3fea5723e3a024d8516e1ffacea5f2d72a7d50b
+  data.tar.gz: 9b3cd6f17af0ef03e9e95186fac23a7fbfd9e9572d079a93c4e1886fc29b112348bc23f0d39476a5b91843c98781035781e4d81b8cf44e506053f1505de854f4

data/README.md

@@ -30,12 +30,57 @@ Or install it yourself as:
 $ gem install crudable-rails
 ```
 
+Then run the install generator in your Rails application:
+
+```bash
+bin/rails generate crudable:install
+```
+
+This sets `config.action_controller.raise_on_missing_callback_actions` to `true` in any environment file under `config/environments/` that currently sets it to `false`. Crudable controllers rely on `before_action` callbacks; enabling this setting helps catch invalid `only` / `except` options early in development and test.
+
+You can also run the same step as a Rake task:
+
+```bash
+bin/rails crudable:install
+```
+
 ## Usage
 
 ### Controller Setup
 
 To use crudable-rails in your controllers, call the `crudable` method.
 
+### Generators
+
+The gem ships Rails generators to scaffold resources with a Crudable controller. Generated controllers include `crudable`, a `permitted_params` method, and commented examples of every override hook with its default implementation — uncomment and tailor as needed.
+
+**Full scaffold** — model, migration, views, routes, tests, and a Crudable controller (same output as `rails generate scaffold`, but with a Crudable controller):
+
+```bash
+bin/rails generate crudable:scaffold Post title:string body:text
+bin/rails generate crudable:scaffold Post title:string body:text --turbo-forms
+```
+
+With `--turbo-forms`, generated `new` and `edit` views wrap the `_form` partial in a `dom_id(record, :form)` target and add matching `new.turbo_stream.erb` / `edit.turbo_stream.erb` templates. Failed create/update actions rendered by crudable will replace that form partial with validation errors inline.
+
+**Controller only** — when you already have a model and views, or want to wire up the controller yourself:
+
+```bash
+bin/rails generate crudable:controller Post title:string body:text
+```
+
+You can also pass `--crudable` to the built-in Rails generators:
+
+```bash
+bin/rails generate scaffold Post title:string body:text --crudable
+bin/rails generate scaffold Post title:string body:text --crudable --turbo-forms
+bin/rails generate scaffold_controller Post title:string body:text --crudable
+```
+
+Use `rails generate scaffold` without `--crudable` when you want the standard Rails scaffold controller.
+
+Nested routing is supported automatically: when a parent `*_id` param is present and an association exists between the parent and resource, collections and member actions are scoped through the parent.
+
 ## Customizing CRUD Actions
 
 You can override the default behavior of CRUD actions by defining the following methods in your controller:
@@ -83,6 +128,103 @@ By default, Turbo Streams are supported for create, update, and destroy actions.
 
 This method should return the permitted parameters for the resource as an array. It's required to be defined on all controllers.
 
+The example below uses a `Product` with a `has_many :product_sizes` association and `accepts_nested_attributes_for`:
+
+```ruby
+# app/models/product.rb
+class Product < ApplicationRecord
+  has_many :product_sizes
+  accepts_nested_attributes_for :product_sizes, allow_destroy: true
+end
+
+# app/controllers/products_controller.rb
+class ProductsController < ApplicationController
+  crudable
+
+  private
+
+  def permitted_params
+    [:name, product_sizes_attributes: [[:id, :name, :_destroy]]]
+  end
+end
+```
+
+A typical request payload for create/update looks like:
+
+```json
+{
+  "product": {
+    "name": "T-shirt",
+    "product_sizes_attributes": {
+      "0": { "name": "Small" },
+      "1": { "id": "42", "name": "Medium" },
+      "2": { "id": "43", "_destroy": "1" }
+    }
+  }
+}
+```
+
+For `has_many` nested attributes, Rails 8 `expect` requires **double array brackets** — an array wrapped in an array — to declare that each nested record is a hash (`[[:id, :name, :_destroy]]`). This form also works with `require.permit` on hash-style payloads from `fields_for` / `accepts_nested_attributes_for`, so the same `permitted_params` definition works on both Rails versions.
+
+### `param_method`
+
+Controls how strong parameters are required and permitted in `resource_params`. On **Rails 8+**, the default is `:expect`, which uses `params.expect` to require and permit in a single step. On earlier Rails versions, it falls back to `:require` (`params.require(...).permit(...)`).
+
+**Rails 8 (default — `:expect`)**
+
+```ruby
+class ProductsController < ApplicationController
+  crudable
+
+  private
+
+  def permitted_params
+    [:name, product_sizes_attributes: [[:id, :name, :_destroy]]]
+  end
+end
+
+# resource_params is equivalent to:
+# params.expect(product: [:name, product_sizes_attributes: [[:id, :name, :_destroy]]])
+```
+
+**Rails 7 and earlier (default — `:require`)**
+
+```ruby
+class ProductsController < ApplicationController
+  crudable
+
+  private
+
+  def permitted_params
+    [:name, product_sizes_attributes: [[:id, :name, :_destroy]]]
+  end
+end
+
+# resource_params is equivalent to:
+# params.require(:product).permit(:name, product_sizes_attributes: [[:id, :name, :_destroy]])
+```
+
+**Override to use `require` on Rails 8**
+
+```ruby
+class ProductsController < ApplicationController
+  crudable
+
+  private
+
+  def param_method
+    :require
+  end
+
+  def permitted_params
+    [:name, product_sizes_attributes: [[:id, :name, :_destroy]]]
+  end
+end
+
+# resource_params is equivalent to:
+# params.require(:product).permit(:name, product_sizes_attributes: [[:id, :name, :_destroy]])
+```
+
 ### Optional Private Methods
 
 The following private methods are available for use in your controllers:
@@ -179,7 +321,25 @@ end
 
 ### `(create|update)_params`
 
-These methods should return the permitted parameters for the resource as an array. They are optional and can be defined if create and update methods need different parameters allowed.
+These methods delegate to `resource_params` by default. Override them when create and update actions need different permitted parameters — for example, allowing new sizes on create but only updates and destroys on update:
+
+```ruby
+class ProductsController < ApplicationController
+  crudable
+
+  private
+
+  def create_params
+    params.expect(product: [:name, product_sizes_attributes: [[:name]]])
+  end
+
+  def update_params
+    params.expect(product: [:name, product_sizes_attributes: [[:id, :name, :_destroy]]])
+  end
+end
+```
+
+See `param_method` and `permitted_params` for the default strong-parameter handling.
 
 ## Overriding `authorizable_resource` with a Namespace
 

data/lib/crudable/rails/base.rb

@@ -335,8 +335,16 @@ module Crudable
         resource_params
       end
 
+      def param_method
+        @param_method ||= ActionController::Parameters.method_defined?(:expect) ? :expect : :require
+      end
+
       def resource_params
-        params.require(resource_var_name).permit(*permitted_params)
+        if param_method == :expect
+          params.send(param_method, resource_var_name.to_sym => permitted_params)
+        else
+          params.send(param_method, resource_var_name).permit(*permitted_params)
+        end
       end
 
       def permitted_params

data/lib/crudable/rails/engine.rb

@@ -10,6 +10,10 @@ module Crudable
       initializer 'crudable-rails.deprecator' do |app|
         app.deprecators[:crudable_rails] = Crudable::Rails.deprecator
       end
+
+      initializer 'crudable-rails.generators' do
+        require_relative 'generators/scaffold_controller_extension'
+      end
     end
   end
 end

data/lib/crudable/rails/generators/scaffold_controller_extension.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative '../../../generators/crudable/controller_helpers'
+require_relative 'turbo_forms_generator_option'
+
+module Crudable
+  module Rails
+    module Generators
+      module ScaffoldControllerExtension
+        extend ActiveSupport::Concern
+
+        prepended do
+          include TurboFormsGeneratorOption
+          include ::Crudable::Generators::ControllerHelpers
+
+          class_option :crudable, type: :boolean, default: false,
+                                   desc: 'Generate with crudable controller'
+        end
+
+        def create_controller_files
+          return super unless options.crudable?
+
+          template 'crudable_controller.rb',
+                   File.join('app/controllers', controller_class_path, "#{controller_file_name}_controller.rb")
+        end
+      end
+    end
+  end
+end
+
+Rails.application.config.after_initialize do
+  require 'rails/generators'
+  require 'rails/generators/named_base'
+  require 'rails/generators/resource_helpers'
+  require 'rails/generators/erb/scaffold/scaffold_generator'
+  require 'rails/generators/rails/scaffold_controller/scaffold_controller_generator'
+  require 'rails/generators/rails/scaffold/scaffold_generator'
+  require_relative 'scaffold_extension'
+  require_relative 'turbo_forms_scaffold_extension'
+
+  unless Rails::Generators::ScaffoldControllerGenerator
+        .ancestors.include?(Crudable::Rails::Generators::ScaffoldControllerExtension)
+    Rails::Generators::ScaffoldControllerGenerator.prepend Crudable::Rails::Generators::ScaffoldControllerExtension
+  end
+
+  unless Rails::Generators::ScaffoldGenerator
+        .included_modules.include?(Crudable::Rails::Generators::ScaffoldExtension)
+    Rails::Generators::ScaffoldGenerator.include Crudable::Rails::Generators::ScaffoldExtension
+  end
+
+  unless Erb::Generators::ScaffoldGenerator
+        .ancestors.include?(Crudable::Rails::Generators::TurboFormsScaffoldExtension)
+    Erb::Generators::ScaffoldGenerator.prepend Crudable::Rails::Generators::TurboFormsScaffoldExtension
+  end
+end

data/lib/crudable/rails/generators/scaffold_extension.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'turbo_forms_generator_option'
+
+module Crudable
+  module Rails
+    module Generators
+      module ScaffoldExtension
+        extend ActiveSupport::Concern
+
+        included do
+          include TurboFormsGeneratorOption
+          include ::Crudable::Generators::ControllerHelpers
+
+          class_option :crudable, type: :boolean, default: false,
+                                   desc: 'Generate with crudable controller'
+        end
+
+        def crudable_controller
+          return unless options.crudable?
+
+          template 'crudable_controller.rb',
+                   File.join('app/controllers', controller_class_path, "#{controller_file_name}_controller.rb"),
+                   force: true
+        end
+      end
+    end
+  end
+end

data/lib/crudable/rails/generators/turbo_forms_generator_option.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Crudable
+  module Rails
+    module Generators
+      module TurboFormsGeneratorOption
+        extend ActiveSupport::Concern
+
+        included do
+          class_option :turbo_forms, type: :boolean, default: false,
+                                     desc: 'Generate turbo stream form templates for new and edit actions'
+        end
+      end
+    end
+  end
+end

data/lib/crudable/rails/generators/turbo_forms_scaffold_extension.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative 'turbo_forms_generator_option'
+require_relative '../../../generators/crudable/controller_helpers'
+
+module Crudable
+  module Rails
+    module Generators
+      module TurboFormsScaffoldExtension
+        extend ActiveSupport::Concern
+
+        prepended do
+          include TurboFormsGeneratorOption
+          include ::Crudable::Generators::ControllerHelpers
+        end
+
+        def copy_view_files
+          super
+          return unless options.turbo_forms?
+
+          copy_turbo_forms_view_files
+        end
+
+        private
+
+        def copy_turbo_forms_view_files
+          view_path = File.join('app/views', controller_file_path)
+
+          template 'turbo_forms/_form.html.erb',
+                   File.join(view_path, '_form.html.erb'),
+                   force: true
+
+          %w[new edit].each do |view|
+            template "turbo_forms/#{view}.html.erb",
+                     File.join(view_path, "#{view}.html.erb"),
+                     force: true
+            template "turbo_forms/#{view}.turbo_stream.erb",
+                     File.join(view_path, "#{view}.turbo_stream.erb")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/crudable/rails/installer.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Crudable
+  module Rails
+    module Installer
+      CALLBACK_ACTIONS_FALSE =
+        /config\.action_controller\.raise_on_missing_callback_actions\s*=\s*false/
+
+      module_function
+
+      def postinstall(root: ::Rails.root)
+        environments_path = root.join('config/environments')
+        return [] unless environments_path.directory?
+
+        environments_path.glob('*.rb').filter_map do |file|
+          update_raise_on_missing_callback_actions(file)
+        end
+      end
+
+      def update_raise_on_missing_callback_actions(file)
+        contents = file.read
+        return unless contents.match?(CALLBACK_ACTIONS_FALSE)
+
+        updated_contents = contents.gsub(
+          CALLBACK_ACTIONS_FALSE,
+          'config.action_controller.raise_on_missing_callback_actions = true'
+        )
+        return if updated_contents == contents
+
+        file.write(updated_contents)
+        file.basename.to_s
+      end
+    end
+  end
+end

data/lib/crudable/rails/version.rb

@@ -3,6 +3,6 @@
 # Crudable Version
 module Crudable
   module Rails
-    VERSION = '1.4.0'
+    VERSION = '1.5.0'
   end
 end

data/lib/crudable-rails.rb

@@ -3,6 +3,7 @@
 require 'turbo-rails'
 
 require 'crudable/rails/version'
+require 'crudable/rails/installer'
 require 'crudable/rails/engine'
 require 'crudable/rails/controller'
 require 'crudable/rails/base'
@@ -14,5 +15,9 @@ module Crudable
     def self.deprecator
       @deprecator ||= ActiveSupport::Deprecation.new('2.0', 'Crudable::Rails')
     end
+
+    def self.postinstall(**)
+      Installer.postinstall(**)
+    end
   end
 end

data/lib/generators/crudable/controller/USAGE

@@ -0,0 +1,23 @@
+Description:
+    Generates a Crudable controller with documented override hooks.
+
+    Pass the model name, either CamelCased or under_scored. The controller name
+    is retrieved as a pluralized version of the model name.
+
+    To create a controller within a module, specify the model name as a path like
+    'parent_module/controller_name'.
+
+Example:
+    bin/rails generate crudable:controller Post title:string body:text
+
+    This will create:
+        Controller: app/controllers/posts_controller.rb
+
+Notes:
+    The generated controller includes `crudable` and a `permitted_params` method.
+    All other customization hooks are included as commented examples with their
+    defaults. Uncomment and tailor as needed.
+
+    Nested routing is automatically supported: if a parent `*_id` param is present
+    and an association exists between the parent and resource, collections and
+    resources will be scoped through the parent.

data/lib/generators/crudable/controller/controller_generator.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative '../controller_helpers'
+
+module Crudable
+  class ControllerGenerator < ::Rails::Generators::NamedBase
+    include ::Rails::Generators::ResourceHelpers
+    include Crudable::Generators::ControllerHelpers
+
+    argument :attributes, type: :array, default: [], banner: 'field:type field:type'
+
+    check_class_collision suffix: 'Controller'
+
+    def create_controller_file
+      template 'crudable_controller.rb',
+               File.join('app/controllers', controller_class_path, "#{controller_file_name}_controller.rb")
+    end
+  end
+end

data/lib/generators/crudable/controller_helpers.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Crudable
+  module Generators
+    module ControllerHelpers
+      extend ActiveSupport::Concern
+
+      class_methods do
+        def crudable_template_root
+          @crudable_template_root ||= File.expand_path('templates', __dir__)
+        end
+      end
+
+      included do
+        source_paths << crudable_template_root
+      end
+
+      private
+
+      def permitted_params_list
+        attachments, others = attributes_names.partition { |name| attachments?(name) }
+        params = others.map { |name| ":#{name}" }
+        params += attachments.map { |name| "#{name}: []" }
+        params.join(', ')
+      end
+
+      def attachments?(name)
+        attribute = attributes.find { |attr| attr.name == name }
+        attribute&.attachments?
+      end
+
+      def reference_attributes
+        attributes.select { |attr| attr.respond_to?(:reference?) && attr.reference? }
+      end
+
+      def form_attributes
+        return attributes if reference_attributes.empty?
+
+        attributes.reject { |attr| attr.respond_to?(:reference?) && attr.reference? }
+      end
+
+      def form_with_model
+        segments = []
+        segments.concat(controller_class_path.map { |namespace| ":#{namespace}" }) if controller_class_path.any?
+
+        reference_attributes.each do |attribute|
+          segments << "@#{attribute.name}"
+        end
+
+        segments << "@#{singular_table_name}"
+
+        return segments.first if segments.size == 1
+
+        "[#{segments.join(', ')}]"
+      end
+    end
+  end
+end

data/lib/generators/crudable/install/USAGE

@@ -0,0 +1,8 @@
+Description:
+    Installs crudable-rails configuration in the host application.
+
+Example:
+    bin/rails generate crudable:install
+
+    This will set config.action_controller.raise_on_missing_callback_actions
+    to true in any environment file that currently sets it to false.

data/lib/generators/crudable/install/install_generator.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Crudable
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      desc 'Install crudable-rails configuration'
+
+      def postinstall
+        updated = ::Crudable::Rails::Installer.postinstall
+
+        if updated.any?
+          say "Set raise_on_missing_callback_actions to true in: #{updated.join(', ')}", :green
+        else
+          say 'No environment files with raise_on_missing_callback_actions = false were found.', :yellow
+        end
+      end
+    end
+  end
+end

data/lib/generators/crudable/scaffold/USAGE

@@ -1,13 +1,20 @@
 Description:
-    Generates a Rails scaffold and replaces the generated controller with a Crudable controller.
+    Generates a full Rails scaffold (model, migration, views, routes, tests) with a
+    Crudable controller instead of the default scaffold controller.
+
+    Pass the model name, either CamelCased or under_scored, and optional attributes.
 
 Example:
-    bin/rails generate crudable:scaffold Thing
+    bin/rails generate crudable:scaffold Post title:string body:text
+    bin/rails generate crudable:scaffold Post title:string body:text --turbo-forms
+
+    This will create the same files as `rails generate scaffold`, but the controller
+    will use `crudable` with documented override hooks.
 
-    This will create:
-        It will generate a rails scaffold with a Crudable controller.
+    With --turbo-forms, new and edit views wrap the form partial in a dom_id target
+    and generate matching turbo_stream templates for validation error responses.
 
 Notes:
-    Nested routing is automatically supported: if a parent `*_id` param is present and an association
-    exists between the parent and resource, collections and resources will be scoped through the parent.
-    Override `use_parent_as_scope?` in your controller to disable parent scoping.
+    Nested routing is automatically supported: if a parent `*_id` param is present
+    and an association exists between the parent and resource, collections and
+    resources will be scoped through the parent.

data/lib/generators/crudable/scaffold/scaffold_generator.rb

@@ -1,32 +1,16 @@
 # frozen_string_literal: true
 
-module Crudable
-  class ScaffoldGenerator < Rails::Generators::NamedBase
-    include Rails::Generators::ResourceHelpers
-
-    source_root File.expand_path('templates', __dir__)
-
-    argument :attributes, type: :array, default: [], banner: 'field:type field:type'
+require 'rails/generators/rails/scaffold/scaffold_generator'
+require_relative '../controller_helpers'
 
-    hook_for :scaffold_controller, in: :rails
+module Crudable
+  class ScaffoldGenerator < ::Rails::Generators::ScaffoldGenerator
+    include Crudable::Generators::ControllerHelpers
 
-    def crudable
+    def crudable_controller
       template 'crudable_controller.rb',
-               File.join('app/controllers', controller_class_path, "#{controller_file_name}_controller.rb"), force: true
-    end
-
-    private
-
-    def permitted_params
-      attachments, others = attributes_names.partition { |name| attachments?(name) }
-      params = others.map { |name| ":#{name}" }
-      params += attachments.map { |name| "#{name}: []" }
-      params.join(', ')
-    end
-
-    def attachments?(name)
-      attribute = attributes.find { |attr| attr.name == name }
-      attribute&.attachments?
+               File.join('app/controllers', controller_class_path, "#{controller_file_name}_controller.rb"),
+               force: true
     end
   end
 end