crudable-rails 1.3 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55f8eea5d65ce4caa175212c791a16bf9513306f54924b859868f6e62dba4011
-  data.tar.gz: 5fad24b510a2b29ab90b77e784b06cf114cb54fb11001dbb582bb2353ba02ac1
+  metadata.gz: '082ec216ec1a73916737ffc58f6db08819237176efcaceb3b8c3978b5d3667e7'
+  data.tar.gz: 4ff9fd3a946d9ee5bb2839d0c41b72eac71a5139f26b87d01c9a608c8fa9204a
 SHA512:
-  metadata.gz: 4e0242ef6e4a90c2b83f5cfdfd535776f7ec233c227f88d1e6ec2d39d6d9bd766ae8e650b452078d72c30327d3de94a2ac965f3dfa0d988e53a4fc2be6add0d2
-  data.tar.gz: 4af78bf8f8ffe06a7ca77f46b34c746db1d137ad53788af62434347db7d7a4769c7b0f4577d9087a368ef215145c92936087d2b26dd96f7912e74467aa5a7479
+  metadata.gz: 894987edb86a9fd16948ea85009387f8872667bfa2b49b0852193a3277147ffa39186450dcd7632a0984881ca3fea5723e3a024d8516e1ffacea5f2d72a7d50b
+  data.tar.gz: 9b3cd6f17af0ef03e9e95186fac23a7fbfd9e9572d079a93c4e1886fc29b112348bc23f0d39476a5b91843c98781035781e4d81b8cf44e506053f1505de854f4

data/README.md

@@ -30,22 +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. You can also specify if the controller is nested by passing the `nested: true` option.
+To use crudable-rails in your controllers, call the `crudable` method.
 
-```ruby
-class ProductsController < ApplicationController
-  crudable
-end
+### Generators
 
-class ProductSizesController < ApplicationController
-  crudable nested: true
-end
+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:
@@ -93,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:
@@ -137,6 +269,14 @@ This method should return a boolean value to determine if the resource should be
 
 This method should return a boolean value to determine if the resource is a singleton. Default: `false`.
 
+### `use_parent_as_scope?`
+
+This method should return a boolean value to determine if the resource should be found using the nested parent. Default: `true`.
+
+### `parent_id_param`
+
+When using nested routes, this determines which `*_id` param is treated as the parent id. If multiple `*_id` params are present (multi-level nesting), Crudable will default to the **deepest/last** `*_id` from the route path parameters.
+
 ### `finder_param`
 
 This method should return the parameter used to find the resource. Default: `:id`.
@@ -147,15 +287,59 @@ This method should return a boolean value to determine if the resource should be
 
 ### `friendly_finders?`
 
-This method should return a boolean value to determine if the resource should be found using friendly finders. Default: `true` if FriendlyId is available, otherwise `false`.
+This method should return a boolean value to determine if the resource should be found using friendly finders.
+
+Default: `true` when `FriendlyId` is available **and** the model responds to `.friendly`, otherwise `false`.
+
+### `parent_friendly_finders?`
+
+When using nested routes (e.g. `/:parent_id/:id`), this method controls whether the **parent** should be found using FriendlyId.
+
+Default: `friendly_finders?` (and additionally requires `FriendlyId` to be defined and the parent model to respond to `.friendly`).
 
 ### `skip_initialize_create?`
 
 This method should return a boolean value to determine if the resource should be initialized on create. Default: `false`.
 
+### `authorize_with_pundit?`
+
+This method controls whether Pundit authorization should be performed. By default, it returns `true` when Pundit is defined. You can override this method to customize authorization behavior based on feature flags, user roles, or other conditions.
+
+For example:
+
+```ruby
+class ProductsController < ApplicationController
+  crudable
+
+  private
+
+  def authorize_with_pundit?
+    super && current_user.present? && feature_enabled?(:authorization)
+  end
+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/Rakefile

@@ -1,3 +1,5 @@
-require "bundler/setup"
+# frozen_string_literal: true
 
-require "bundler/gem_tasks"
+require 'bundler/setup'
+
+require 'bundler/gem_tasks'

data/lib/crudable/rails/base.rb

@@ -5,47 +5,76 @@ module Crudable
     module Base
       extend ActiveSupport::Concern
 
+      # Status code for unprocessable entity (422)
+      # Rails 7.1+ uses :unprocessable_content (replaces deprecated :unprocessable_entity)
+      UNPROCESSABLE_STATUS = :unprocessable_content
+
       included do
         include Crudable::Rails::Resourceable
+        include Crudable::Rails::Nestable
 
         before_action :find_resource, only: %i[show edit update destroy]
-        before_action :authorize_class_action, only: %i[index] if defined?(Pundit)
-        after_action :authorize_resource, only: %i[new show edit] if defined?(Pundit)
 
         decorates_assigned plural_resource_var_name.to_sym, resource_var_name.to_sym if defined?(Draper)
       end
 
       def index
+        authorize_class_action if authorize_with_pundit?
         instance_variable_set("@#{plural_resource_var_name}", resource_scope)
         paginate_resource
       end
 
-      def show; end
+      def show
+        render_not_found if instance_variable_get("@#{resource_var_name}").blank?
+        authorize_resource if authorize_with_pundit?
+      end
 
       def new
-        instance_variable_set("@#{resource_var_name}", resource_class.new)
+        instance = new_instance
+        # Ensure we always set a valid instance to prevent nil model warnings in Rails 8
+        raise ActiveRecord::RecordNotFound, "Could not create new #{resource_class.name}" if instance.nil?
+
+        instance_variable_set("@#{resource_var_name}", instance)
+        authorize_resource if authorize_with_pundit?
       end
 
-      def create # rubocop:disable Metrics/MethodLength
-        instance_variable_set("@#{resource_var_name}", resource_class.new(create_params)) unless skip_initialize_create?
-        if defined?(Pundit)
+      def create
+        unless skip_initialize_create?
+          instance_variable_set("@#{resource_var_name}", new_instance)
+          instance_variable_get("@#{resource_var_name}").assign_attributes(create_params)
+        end
+        resource = instance_variable_get("@#{resource_var_name}")
+        # If skip_initialize_create? is true, resource might be nil - that's expected
+        # Only return 404 if we tried to initialize but resource is still nil
+        return render_not_found if resource.nil? && !skip_initialize_create?
+
+        # Only authorize if resource exists (skip authorization when skip_initialize_create? is true)
+        if authorize_with_pundit? && resource.present?
           before_authorize_create
           authorize_resource
           after_authorize_create
+        elsif authorize_with_pundit?
+          skip_authorization
         end
-        if instance_variable_get("@#{resource_var_name}").save
+        if resource&.save
           on_successful_create
           on_successful_create_render
         else
           on_failed_create_setup
           on_failed_create_render
         end
+      rescue ActionController::ParameterMissing
+        head :bad_request
       end
 
-      def edit; end
+      def edit
+        render_not_found if instance_variable_get("@#{resource_var_name}").blank?
+        authorize_resource if authorize_with_pundit?
+      end
 
       def update
-        if defined?(Pundit)
+        render_not_found if instance_variable_get("@#{resource_var_name}").blank?
+        if authorize_with_pundit?
           before_authorize_update
           authorize_resource
           after_authorize_update
@@ -57,10 +86,12 @@ module Crudable
           on_failed_update_setup
           on_failed_update_render
         end
+      rescue ActionController::ParameterMissing
+        head :bad_request
       end
 
       def destroy
-        authorize_resource(destroy_method) if defined?(Pundit)
+        authorize_resource(destroy_method) if authorize_with_pundit?
         if instance_variable_get("@#{resource_var_name}").send(destroy_method)
           on_successful_destroy
           on_successful_destroy_render
@@ -72,6 +103,10 @@ module Crudable
 
       private
 
+      def authorize_with_pundit?
+        defined?(Pundit)
+      end
+
       def destroy_method
         return :destroy unless defined?(Discard)
         return :destroy if params[:destroy]
@@ -85,11 +120,38 @@ module Crudable
 
       def find_resource
         resource = friendly_finders? ? resource_class.friendly : resource_class
-        instance = singleton? ? resource.first : resource.find(params[finder_param])
+        instance = find_instance(resource)
 
         return redirect_to (resource_namespace + [instance]), status: :moved_permanently if should_redirect?(instance)
 
         instance_variable_set("@#{resource_var_name}", instance)
+      rescue ActiveRecord::RecordNotFound
+        render_not_found
+      end
+
+      def find_instance(resource)
+        if singleton?
+          resource.first
+        elsif parent_resource_association.present?
+          scope = instance_variable_get("@#{parent_var_name}").send(parent_resource_association)
+          scope = scope.friendly if friendly_finders?
+          scope.find(params[finder_param])
+        else
+          resource.find(params[finder_param])
+        end
+      end
+
+      def new_instance
+        if parent_resource_association.present?
+          parent = instance_variable_get("@#{parent_var_name}")
+          # If parent is nil, it means find_parent failed - this shouldn't happen
+          # but we guard against it to prevent nil errors
+          raise ActiveRecord::RecordNotFound, "Parent #{parent_var_name} not found" if parent.nil?
+
+          parent.send(parent_resource_association).new
+        else
+          resource_class.new
+        end
       end
 
       def should_redirect?(instance)
@@ -111,7 +173,27 @@ module Crudable
       end
 
       def authorizable_scope
-        defined?(Pundit) ? policy_scope(resource_namespace + [resource_class]) : resource_class.all
+        scope = find_scope
+        return scope.all unless authorize_with_pundit?
+        # Check if Pundit::Authorization is available
+        return scope.all unless if respond_to?(:pundit_authorization_available?,
+                                               true)
+                                  pundit_authorization_available?
+                                else
+                                  self.class.included_modules.include?(Pundit::Authorization) || respond_to?(
+                                    :policy_scope, true
+                                  )
+                                end
+
+        policy_scope(resource_namespace + [scope])
+      end
+
+      def find_scope
+        if parent_resource_association.present?
+          instance_variable_get("@#{parent_var_name}").send(parent_resource_association)
+        else
+          resource_class
+        end
       end
 
       def paginate_resource?
@@ -140,6 +222,14 @@ module Crudable
       end
 
       def after_create_redirect_path
+        if respond_to?(:parent_present?) && parent_present? && instance_variable_get("@#{parent_var_name}")
+          parent = instance_variable_get("@#{parent_var_name}")
+          resource_namespace + [parent, plural_resource_var_name.to_sym]
+        else
+          resource_namespace + [plural_resource_var_name.to_sym]
+        end
+      rescue NoMethodError
+        # Fallback if parent_present? or parent_var_name methods aren't available
         resource_namespace + [plural_resource_var_name.to_sym]
       end
 
@@ -216,16 +306,24 @@ module Crudable
       def after_authorize_update; end
 
       def on_failed_create_render
+        # Ensure resource is set before rendering the new template
+        # This prevents Rails 8 deprecation warnings about nil model arguments
+        resource = instance_variable_get("@#{resource_var_name}")
+        if resource.nil?
+          # Always initialize for rendering, even if skip_initialize_create? is true
+          # The skip_initialize_create? flag only affects the create action, not rendering
+          instance_variable_set("@#{resource_var_name}", new_instance)
+        end
         respond_to do |format|
           format.turbo_stream { render_action(:new) }
-          format.html { render :new, status: :unprocessable_entity }
+          format.html { render :new, status: UNPROCESSABLE_STATUS }
         end
       end
 
       def on_failed_update_render
         respond_to do |format|
           format.turbo_stream { render_action(:edit) }
-          format.html { render :edit, status: :unprocessable_entity }
+          format.html { render :edit, status: UNPROCESSABLE_STATUS }
         end
       end
 
@@ -237,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
@@ -246,14 +352,22 @@ module Crudable
       end
 
       def render_action(default_action_name)
-        logger.debug "Rendering relevant action for #{controller_path}/#{default_action_name} as #{request.format.symbol}"
-        return render default_action_name if lookup_context.template_exists?("#{controller_path}/#{default_action_name}")
+        logger.debug "Rendering relevant action for #{controller_path}/#{default_action_name} " \
+                     "as #{request.format.symbol}"
+        if lookup_context.template_exists?("#{controller_path}/#{default_action_name}")
+          return render default_action_name
+        end
 
-        Crudable::Rails.deprecator.warn("Rendering fallback: #{action_name}, format: #{request.format.symbol}. Rename your template to #{default_action_name}")
+        Crudable::Rails.deprecator.warn("Rendering fallback: #{action_name}, format: #{request.format.symbol}. " \
+                                        "Rename your template to #{default_action_name}")
 
         logger.debug "Rendering fallback: #{action_name}"
         render
       end
+
+      def render_not_found
+        head :not_found
+      end
     end
   end
 end

data/lib/crudable/rails/controller.rb

@@ -7,9 +7,8 @@ module Crudable
       extend ActiveSupport::Concern
 
       class_methods do
-        def crudable(nested: false)
+        def crudable
           include Crudable::Rails::Base
-          include Crudable::Rails::Nestable if nested
         end
       end
     end

data/lib/crudable/rails/engine.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Crudable
   module Rails
     class Engine < ::Rails::Engine
@@ -5,9 +7,13 @@ module Crudable
         ::ActionController::Base.include Crudable::Rails::Controller
       end
 
-      initializer "crudable-rails.deprecator" do |app|
+      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