undercarriage 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 59a96756fb12afc085cd7e915c6c55d4795d354ba3e1206d2f2e4c600366f8ce
-  data.tar.gz: 18b7f4c033a3c1e0ec2b15be8a648dd6dd8c44cb77ea3df455a63b7376aa1fc0
+  metadata.gz: b8d42d984572277bb1282c5fa0306028d91ced6801f88bb7ad36f01c05fcd8e8
+  data.tar.gz: f3d7690b1fdbf864395695f4a8651bbce2a907333430df01208edd0503419144
 SHA512:
-  metadata.gz: 0b22d67b2f8fddc1b9b5ab58205557e56c2e8ed1e4087092f265252ba573fc111f121c34b403e255556b03abde62dfe8046cb17711662f8c13cb7a9aba762003
-  data.tar.gz: b9c0d216a9c6e7455dad762f88dd13c953cc1dc251c4c3be6361b7d7e766882205878a52a923eaa81ace11762a09bd5cd3b670b85c8e3c0e07f4185513314097
+  metadata.gz: 6ee506e32efb9f323e4f5dcfd8494d00050dc0e20a9d4c09244440c0b7269cc52e5024878a91e24db6da67aa88908840931c0559d0ab7028f1a4cb7e932e61cc
+  data.tar.gz: 8577454663eaec4d8b20bd5f06bf36bc2d296cca855113e77b5f9b91c33908354f69aa33645e82ba14c3f45e154790008f4d2c309bf4943814ab5b2d8fd28078

data/README.md

@@ -1,12 +1,10 @@
 # Undercarriage
 
-**\*Undercarriage is currently under development. It is not ready for production use.\***
-
 Undercarriage is a set of concerns to add to your application to trim some of the fat from controllers and models.
 
 ## Requirements
 
-* Ruby >= 3.3.0
+* Ruby >= 3.0
 * Rails >= 6.0
 
 ## Installation
@@ -14,7 +12,7 @@ Undercarriage is a set of concerns to add to your application to trim some of th
 Add to your application's Gemfile
 
 ```bash
-gem 'undercarriage', '~> 1.0'
+gem 'undercarriage', '~> 1.1'
 ```
 
 Run the bundle command
@@ -25,7 +23,37 @@ $ bundle install
 
 ## Usage
 
-TODO
+Include `Undercarriage::Controllers::RestfulConcern` in a controller to get full RESTful `index`/`show`/`new`/`create`/`edit`/`update`/`destroy` actions, driven off the controller's own name/path:
+
+```ruby
+class PostsController < ApplicationController
+  include Undercarriage::Controllers::RestfulConcern
+
+  private
+
+  def permitted_attributes
+    [:title, :body]
+  end
+end
+```
+
+This infers `Post` as the model, sets `@posts`/`@post` as appropriate, and wires up flash messages, strong params, and redirects with no further code. Override the `*_content` hooks (e.g. `show_content`, `create_content`) or `after_create_action`/`after_update_action` to customize a single action without redefining it — see the YARD docs on each `Undercarriage::Controllers::Restful::*` concern for the full hook list.
+
+The standalone concerns can be included individually where you don't want the full RESTful stack:
+
+```ruby
+class ExamplesController < ApplicationController
+  include Undercarriage::Controllers::ActionConcern  # action?/index_action?/etc. view helpers
+  include Undercarriage::Controllers::KaminariConcern # page_num/per_page params for Kaminari
+  include Undercarriage::Controllers::LocaleConcern   # I18n.locale from HTTP_ACCEPT_LANGUAGE
+end
+
+class Example < ApplicationRecord
+  include Undercarriage::Models::PublishedConcern # published/unpublished scopes
+end
+```
+
+See the YARD documentation linked below for every concern's options and examples.
 
 ## Testing
 

data/lib/undercarriage/controllers/kaminari_concern.rb

@@ -28,7 +28,8 @@ module Undercarriage
       # Items per page
       #
       # The number of items to return in pagination. Will use the Kaminari config `default_per_page` (typically `25`)
-      # for the count and will look for `per` in the URL paramaters to override.
+      # for the count and will look for `per` in the URL paramaters to override. The result is clamped between `1`
+      # and {#per_page_max} so a caller cannot force an unbounded (or negative/zero) number of records per page.
       #
       # This is asseccible from the View as `per_page`
       #
@@ -37,14 +38,16 @@ module Undercarriage
       # @example Request
       #   # GET /examples?per=100 # Return 100 items per page
       #   # GET /examples?per=10&page=3 # Return page 3 of items with 10 items per page
+      #   # GET /examples?per=999999999 # Clamped down to per_page_max
       def per_page
-        params.fetch(per_page_key, per_page_default).to_i
+        params.fetch(per_page_key, per_page_default).to_i.clamp(1, per_page_max)
       end
 
       ##
       # Page number
       #
-      # Will look for the Kaminari config `param_name` (typically `page`) in the URL paramaters.
+      # Will look for the Kaminari config `param_name` (typically `page`) in the URL paramaters. The result is
+      # clamped to a minimum of `1` so a caller cannot force a negative or zero page number.
       #
       # This is asseccible from the View as `page_num`
       #
@@ -54,7 +57,7 @@ module Undercarriage
       #   # GET /examples?page=5 # Return page 5 of items
       #   # GET /examples?per=10&page=3 # Return page 3 of items with 10 items per page
       def page_num
-        params.fetch(page_num_key, page_num_default).to_i
+        params.fetch(page_num_key, page_num_default).to_i.clamp(1, nil)
       end
 
       protected
@@ -100,6 +103,17 @@ module Undercarriage
       def page_num_default
         1
       end
+
+      ##
+      # Items per page maximum
+      #
+      # Upper bound enforced on {#per_page} regardless of what the `per` query param requests. Defaults to the
+      # Kaminari config `max_per_page` when set, otherwise `100`. Override to allow a different ceiling.
+      #
+      # @return [Integer] maximum per page count
+      def per_page_max
+        Kaminari.config.max_per_page || 100
+      end
     end
   end
 end

data/lib/undercarriage/controllers/restful/actions/base_concern.rb

@@ -37,16 +37,6 @@ module Undercarriage
             model_class
           end
 
-          ##
-          # New content action
-          #
-          # Decide what content to load based on action name
-          #
-          # @return [Object,Hash]
-          def resource_new_content
-            action_name == "new" ? new_resource_content : create_resource_content
-          end
-
           ##
           # Resource action
           #
@@ -72,12 +62,52 @@ module Undercarriage
           #     #
           #     #   authorize @example
           #     # end
+          #
+          #     ##
+          #     # To override only a single action's query, override its `*_content` hook instead of `resource_content`
+          #     # itself. The other actions keep using `resource_content`
+          #     #
+          #     # def show_content
+          #     #   super
+          #     #
+          #     #   authorize @example
+          #     # end
           #   end
           def resource_content
             resource_id = params.fetch(:id)
-            resource_query = model_class.find(resource_id)
+            resource_scope.find(resource_id)
+          end
+
+          ##
+          # Resource content for the `destroy` action
+          #
+          # @return [Object,Hash]
+          def destroy_content
+            resource_content
+          end
+
+          ##
+          # Resource content for the `edit` action
+          #
+          # @return [Object,Hash]
+          def edit_content
+            resource_content
+          end
 
-            instance_variable_set("@#{instance_name}", resource_query)
+          ##
+          # Resource content for the `show` action
+          #
+          # @return [Object,Hash]
+          def show_content
+            resource_content
+          end
+
+          ##
+          # Resource content for the `update` action
+          #
+          # @return [Object,Hash]
+          def update_content
+            resource_content
           end
 
           ##

data/lib/undercarriage/controllers/restful/actions/create_concern.rb

@@ -62,6 +62,14 @@ module Undercarriage
 
           protected
 
+          ##
+          # Create resource content
+          #
+          # @return [Object] the built resource
+          def create_content
+            resource_scope.new(create_resource_params)
+          end
+
           ##
           # Create restful action
           #
@@ -87,15 +95,16 @@ module Undercarriage
           #     # end
           #
           #     ##
-          #     # The `resource_new_content` method can also be overwritten. This method is meant to share content with
-          #     # the `new` action
+          #     # To change the underlying build without touching instance variable assignment, override
+          #     # `create_content` instead. Note this is independent from `new_content` (`create` no longer shares
+          #     # this method with `new`)
           #     #
-          #     # def resource_new_content
+          #     # def create_content
           #     #   ...
           #     # end
           #   end
           def create_resource_content
-            resource_query = resource_scope.new(create_resource_params)
+            resource_query = create_content
 
             instance_variable_set("@#{instance_name}", resource_query)
           end
@@ -109,7 +118,7 @@ module Undercarriage
           #
           # @return [Object] the built resource
           def create_resource
-            @create_resource ||= resource_new_content
+            @create_resource ||= create_resource_content
           end
         end
       end

data/lib/undercarriage/controllers/restful/actions/destroy_concern.rb

@@ -84,9 +84,17 @@ module Undercarriage
           #     # def resource_content
           #     #   ...
           #     # end
+          #
+          #     ##
+          #     # To change the query for `destroy` only, override `destroy_content` instead. The `show`, `edit` and
+          #     # `update` actions are unaffected
+          #     #
+          #     # def destroy_content
+          #     #   ...
+          #     # end
           #   end
           def destroy_resource_content
-            resource_content
+            instance_variable_set("@#{instance_name}", destroy_content)
           end
 
           private

data/lib/undercarriage/controllers/restful/actions/edit_concern.rb

@@ -76,9 +76,17 @@ module Undercarriage
           #     # def resource_content
           #     #   ...
           #     # end
+          #
+          #     ##
+          #     # To change the query for `edit` only, override `edit_content` instead. The `show`, `update` and
+          #     # `destroy` actions are unaffected
+          #     #
+          #     # def edit_content
+          #     #   ...
+          #     # end
           #   end
           def edit_resource_content
-            resource_content
+            instance_variable_set("@#{instance_name}", edit_content)
           end
 
           private

data/lib/undercarriage/controllers/restful/actions/index_concern.rb

@@ -42,6 +42,14 @@ module Undercarriage
 
           protected
 
+          ##
+          # Index resource content
+          #
+          # @return [Object] resource collection scope
+          def index_content
+            resource_scope.all
+          end
+
           ##
           # Index restful action
           #
@@ -65,9 +73,17 @@ module Undercarriage
           #     #
           #     #   authorize @examples
           #     # end
+          #
+          #     ##
+          #     # To change the underlying query without touching instance variable assignment, override
+          #     # `index_content` instead
+          #     #
+          #     # def index_content
+          #     #   ...
+          #     # end
           #   end
           def resources_content
-            resources_query = resource_scope.all
+            resources_query = index_content
 
             instance_variable_set("@#{instances_name}", resources_query)
           end

data/lib/undercarriage/controllers/restful/actions/new_concern.rb

@@ -45,6 +45,14 @@ module Undercarriage
 
           protected
 
+          ##
+          # New resource content
+          #
+          # @return [Object] the built resource
+          def new_content
+            resource_scope.new
+          end
+
           ##
           # New restful action
           #
@@ -70,15 +78,16 @@ module Undercarriage
           #     # end
           #
           #     ##
-          #     # The `resource_new_content` method can also be overwritten. This method is meant to share content with
-          #     # the `create` action
+          #     # To change the underlying build without touching instance variable assignment, override
+          #     # `new_content` instead. Note this is independent from `create_content` (`create` no longer shares
+          #     # this method with `new`)
           #     #
-          #     # def resource_new_content
+          #     # def new_content
           #     #   ...
           #     # end
           #   end
           def new_resource_content
-            resource_query = resource_scope.new
+            resource_query = new_content
 
             instance_variable_set("@#{instance_name}", resource_query)
           end
@@ -92,7 +101,7 @@ module Undercarriage
           #
           # @return [Object] the built resource
           def new_resource
-            @new_resource ||= resource_new_content
+            @new_resource ||= new_resource_content
           end
         end
       end

data/lib/undercarriage/controllers/restful/actions/show_concern.rb

@@ -73,9 +73,17 @@ module Undercarriage
           #     # def resource_content
           #     #   ...
           #     # end
+          #
+          #     ##
+          #     # To change the query for `show` only, override `show_content` instead. The `edit`, `update` and
+          #     # `destroy` actions are unaffected
+          #     #
+          #     # def show_content
+          #     #   ...
+          #     # end
           #   end
           def show_resource_content
-            resource_content
+            instance_variable_set("@#{instance_name}", show_content)
           end
 
           private

data/lib/undercarriage/controllers/restful/actions/update_concern.rb

@@ -93,9 +93,17 @@ module Undercarriage
           #     # def resource_content
           #     #   ...
           #     # end
+          #
+          #     ##
+          #     # To change the query for `update` only, override `update_content` instead. The `show`, `edit` and
+          #     # `destroy` actions are unaffected
+          #     #
+          #     # def update_content
+          #     #   ...
+          #     # end
           #   end
           def update_resource_content
-            resource_content
+            instance_variable_set("@#{instance_name}", update_content)
           end
 
           private

data/lib/undercarriage/version.rb

@@ -3,5 +3,5 @@
 module Undercarriage
   ##
   # Undercarriage version
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: undercarriage
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - David Freerksen