undercarriage 0.5.5 → 1.0.0

data/lib/undercarriage/controllers/restful/flash_concern.rb

@@ -10,30 +10,32 @@ module Undercarriage
       #
       # Flash messages
       #
-      # Usage
-      #   class ExamplesController < ApplicationController
-      #     include Undercarriage::Controllers::Restful::FlashConcern
-      #   end
+      # FlashConcern is not meant to be included alone
       #
-      #   # config/locales/flash.en.yml
-      #   flash:
-      #     actions:
-      #       create:
-      #         notice: "%{resource_name} was successfully created."
-      #       update:
-      #         notice: "%{resource_name} was successfully updated."
-      #       destroy:
-      #         notice: "%{resource_name} was successfully destroyed."
-      #     posts:
-      #       create:
-      #         notice: "Your %{downcase_resource_name} was created."
-      #       update:
-      #         notice_html: "<strong>Huzzah!</strong> Your %{downcase_resource_name} was updated."
-      #         notice: "Huzzah! Your %{downcase_resource_name} was updated." # Not used since `notice_html` is defined
-      #     things:
-      #       destroy:
-      #         notice: "Good riddance. That wasn't needed anyway."
+      # I18n - config/locales/flash.en.yml:
       #
+      #    flash:
+      #       actions:
+      #         create:
+      #           notice: "%{resource_name} was successfully created."
+      #         update:
+      #           notice: "%{resource_name} was successfully updated."
+      #         destroy:
+      #           notice: "%{resource_name} was successfully destroyed."
+      #       posts:
+      #         create:
+      #           notice: "Your %{downcase_resource_name} was created."
+      #         update:
+      #           notice_html: "<strong>Huzzah!</strong> Your %{downcase_resource_name} was updated."
+      #           notice: "Huzzah! Your %{downcase_resource_name} was updated."
+      #       things:
+      #         destroy:
+      #           notice: "Good riddance. That wasn't needed anyway."
+      #
+      # @example Controller
+      #   class ExamplesController < ApplicationController
+      #     include Undercarriage::Controllers::RestfulConcern
+      #   end
       module FlashConcern
         extend ActiveSupport::Concern
 
@@ -49,8 +51,9 @@ module Undercarriage
         #
         # Translate create flash message
         #
+        # @return [String] translation
         def flash_created_message
-          flash_message_builder(:create, flash_status_type, 'created')
+          flash_message_builder(:create, flash_status_type, "created")
         end
 
         ##
@@ -58,8 +61,9 @@ module Undercarriage
         #
         # Translate update flash message
         #
+        # @return [String] translation
         def flash_updated_message
-          flash_message_builder(:update, flash_status_type, 'updated')
+          flash_message_builder(:update, flash_status_type, "updated")
         end
 
         ##
@@ -67,12 +71,23 @@ module Undercarriage
         #
         # Translate destroy flash message
         #
+        # @return [String] translation
         def flash_destroyed_message
-          flash_message_builder(:destroy, flash_status_type, 'destroyed')
+          flash_message_builder(:destroy, flash_status_type, "destroyed")
         end
 
         private
 
+        ##
+        # Flash message builder
+        #
+        # Builds and translates the flash message for the given action, looking up translations through
+        # `flash_message_defaults`'s fallback chain.
+        #
+        # @param action [Symbol] the controller action (`:create`, `:update`, `:destroy`)
+        # @param status [Symbol] the flash status type (e.g. `:success`)
+        # @param past_tense [String] past-tense verb used in the hardcoded English fallback
+        # @return [String] translated flash message
         def flash_message_builder(action, status, past_tense)
           defaults = flash_message_defaults(controller_name_singular_title, action, status, past_tense)
           message = defaults.shift
@@ -91,17 +106,20 @@ module Undercarriage
         #   flash.[NAMESPACE].[CONTROLLER].[ACTION].[STATUS]
         #   flash.[CONTROLLER].[ACTION].[STATUS]_html
         #   flash.[CONTROLLER].[ACTION].[STATUS]
+        #   flash.actions.[ACTION].[STATUS]_html
         #   flash.actions.[ACTION].[STATUS]
         #   English default
         #
+        # @return [Array] possible translation paths
         def flash_message_defaults(resource_name, action, status, past_tense)
-          controller_with_namespace = [resource_namespace, controller_name].compact.join('.')
+          controller_with_namespace = [resource_namespace, controller_name].compact.join(".")
 
           [
             :"flash.#{controller_with_namespace}.#{action}.#{status}_html",
             :"flash.#{controller_with_namespace}.#{action}.#{status}",
             :"flash.#{controller_name}.#{action}.#{status}_html",
             :"flash.#{controller_name}.#{action}.#{status}",
+            :"flash.actions.#{action}.#{status}_html",
             :"flash.actions.#{action}.#{status}",
             "#{resource_name} was successfully #{past_tense}."
           ]

data/lib/undercarriage/controllers/restful/location_after_concern.rb

@@ -10,11 +10,12 @@ module Undercarriage
       #
       # Redirect locations after create, update or destroy
       #
-      # Usage
+      # LocationAfterConcern is not meant to be included alone
+      #
+      # @example Controller
       #   class ExamplesController < ApplicationController
-      #     include Undercarriage::Controllers::Restful::LocationAfterConcern
+      #     include Undercarriage::Controllers::RestfulConcern
       #   end
-      #
       module LocationAfterConcern
         extend ActiveSupport::Concern
 
@@ -25,6 +26,7 @@ module Undercarriage
         #
         # The path of the created resource
         #
+        # @return [String] path after create redirect
         def location_after_create
           resource_id = @create_resource
 
@@ -36,6 +38,7 @@ module Undercarriage
         #
         # The path of the updated resource
         #
+        # @return [String] path after update redirect
         def location_after_update
           resource_id = @update_resource
 
@@ -47,6 +50,7 @@ module Undercarriage
         #
         # The path of the resources
         #
+        # @return [String] path after destroy redirect
         def location_after_destroy
           location_after_save
         end
@@ -56,18 +60,34 @@ module Undercarriage
         #
         # The path of the resources
         #
+        # @return [String] generic path after save redirect
         def location_after_save
           resources_path
         end
 
         private
 
+        ##
+        # Resource path
+        #
+        # The path for a single resource, honoring any inferred admin/nested namespace.
+        #
+        # @param resource [Object] resource to build the path for
+        # @param options [Hash] additional options forwarded to the path helper
+        # @return [String] resource path
         def resource_path(resource, options = {})
           location_path = [resource_namespace, controller_name_singular].compact
 
           send("#{location_path.join('_')}_path", resource, options)
         end
 
+        ##
+        # Resources path
+        #
+        # The path for the resource collection, honoring any inferred admin/nested namespace.
+        #
+        # @param options [Hash] additional options forwarded to `polymorphic_path`
+        # @return [String] resources path
         def resources_path(options = {})
           location_path = [resource_namespace, controller_name].compact.map(&:to_sym)
 

data/lib/undercarriage/controllers/restful/namespace_concern.rb

@@ -8,11 +8,12 @@ module Undercarriage
       ##
       # Namespace
       #
-      # Usage
+      # NamespaceConcern is not meant to be included alone
+      #
+      # @example Controller
       #   class ExamplesController < ApplicationController
-      #     include Undercarriage::Controllers::Restful::NamespaceConcern
+      #     include Undercarriage::Controllers::RestfulConcern
       #   end
-      #
       module NamespaceConcern
         extend ActiveSupport::Concern
 
@@ -24,14 +25,13 @@ module Undercarriage
         # Best guess for namespace. Take `controller_path` and if there is more than one segment, assume the first is
         # the namespace. When there is one segment, the namespace is `nil`
         #
-        # Example
+        # @example Controller
         #   # Override method that builds namespace
         #   def resource_namespace
         #     :admin
         #   end
-        #
         def resource_namespace
-          segments = controller_path.split('/')
+          segments = controller_path.split("/")
 
           segments.length > 1 ? segments.first : nil
         end

data/lib/undercarriage/controllers/restful/permitted_attributes_concern.rb

@@ -8,11 +8,12 @@ module Undercarriage
       ##
       # Permitted attributes
       #
-      # Usage
+      # PermittedAttributesConcern is not meant to be included alone
+      #
+      # @example Controller
       #   class ExamplesController < ApplicationController
-      #     include Undercarriage::Controllers::Restful::PermittedAttributesConcern
+      #     include Undercarriage::Controllers::RestfulConcern
       #   end
-      #
       module PermittedAttributesConcern
         extend ActiveSupport::Concern
 
@@ -24,7 +25,9 @@ module Undercarriage
         # Permitted attributes for the `create` action. If `create` and `update` do not need to be different, you can
         # still override the `permitted_attributes` method which would be applied to both `create` and `update`.
         #
-        # Example
+        # @return [Array,Hash] permitted create attributes
+        #
+        # @example Controller
         #   def permitted_create_attributes
         #     %i[thingy dilly whatsit]
         #   end
@@ -36,7 +39,6 @@ module Undercarriage
         #       { whosits_attributes: %i[id _destroy name] }
         #     ]
         #   end
-        #
         def permitted_create_attributes
           permitted_attributes_fallback
         end
@@ -47,7 +49,9 @@ module Undercarriage
         # Permitted attributes for the `update` action. If `create` and `update` do not need to be different, you can
         # still override the `permitted_attributes` method which would be applied to both `create` and `update`.
         #
-        # Example
+        # @return [Array,Hash] permitted update attributes
+        #
+        # @example Controller
         #   def permitted_update_attributes
         #     %i[thingy dilly whatsit]
         #   end
@@ -59,7 +63,6 @@ module Undercarriage
         #       { whosits_attributes: %i[id _destroy name] }
         #     ]
         #   end
-        #
         def permitted_update_attributes
           permitted_attributes_fallback
         end
@@ -70,36 +73,42 @@ module Undercarriage
         # For the `new` action, resource params are `nil`. For the `create` action, resource params are the posted
         # params from `create_resource_params` method
         #
+        # @return [Array,Hash,nil] permitted new attributes
         def resource_new_params
-          action_name == 'new' ? nil : create_resource_params
+          action_name == "new" ? nil : create_resource_params
         end
 
         ##
         # Permitted params for `create` action
         #
         # Permitted params for the `create` action scoped to the resource.
-        #
         def create_resource_params
           permitted = permitted_create_attributes
 
-          params.require(resource_scope).permit(permitted)
+          params.require(model_scope).permit(permitted)
         end
 
         ##
         # Permitted params for `update` action
         #
         # Permitted params for the `update` action scoped to the resource.
-        #
         def update_resource_params
           permitted = permitted_update_attributes
 
-          params.require(resource_scope).permit(permitted)
+          params.require(model_scope).permit(permitted)
         end
 
         private
 
+        ##
+        # Permitted attributes fallback
+        #
+        # Falls back to the controller's `permitted_attributes` method, if defined, when
+        # `permitted_create_attributes`/`permitted_update_attributes` are not individually overridden.
+        #
+        # @return [Array,Hash] permitted attributes, or an empty array if `permitted_attributes` is not defined
         def permitted_attributes_fallback
-          with_method = self.class.instance_methods(false).include?(:permitted_attributes)
+          with_method = self.class.method_defined?(:permitted_attributes)
 
           with_method ? permitted_attributes : []
         end

data/lib/undercarriage/controllers/restful/utility_concern.rb

@@ -10,11 +10,12 @@ module Undercarriage
       #
       # Utility helper methods
       #
-      # Usage
+      # UtilityConcern is not meant to be included alone
+      #
+      # @example Controller
       #   class ExamplesController < ApplicationController
-      #     include Undercarriage::Controllers::Restful::UtilityConcern
+      #     include Undercarriage::Controllers::RestfulConcern
       #   end
-      #
       module UtilityConcern
         extend ActiveSupport::Concern
 
@@ -23,6 +24,7 @@ module Undercarriage
         ##
         # Singular controller name
         #
+        # @return [String] singular controller name
         def controller_name_singular
           controller_name.to_s.singularize
         end
@@ -30,6 +32,7 @@ module Undercarriage
         ##
         # Titleized controller name
         #
+        # @return [String] titelized controller name
         def controller_name_singular_title
           controller_name_singular.titleize
         end
@@ -38,6 +41,7 @@ module Undercarriage
         ##
         # Model name
         #
+        # @return [String] model name
         def model_name
           controller_name_singular
         end
@@ -45,13 +49,23 @@ module Undercarriage
         ##
         # Model class
         #
+        # @return [Object] model class
         def model_class
           model_name.classify.constantize
         end
 
+        ##
+        # Model scope
+        #
+        # @return [Symbol] model scope
+        def model_scope
+          model_name.to_sym
+        end
+
         ##
         # Instances name
         #
+        # @return [String] instances name
         def instances_name
           controller_name.to_s
         end
@@ -59,16 +73,10 @@ module Undercarriage
         ##
         # Instance name
         #
+        # @return [String] instance name
         def instance_name
           model_name
         end
-
-        ##
-        # Resource scope
-        #
-        def resource_scope
-          model_name.to_sym
-        end
       end
     end
   end

data/lib/undercarriage/controllers/restful_concern.rb

@@ -6,21 +6,14 @@ module Undercarriage
     ##
     # Restful actions
     #
-    # Usage
+    # @example Controller
     #   class ExamplesController < ApplicationController
     #     include Undercarriage::Controllers::RestfulConcern
     #   end
-    #
     module RestfulConcern
       extend ActiveSupport::Concern
 
       included do
-        include Undercarriage::Controllers::Restful::FlashConcern
-        include Undercarriage::Controllers::Restful::LocationAfterConcern
-        include Undercarriage::Controllers::Restful::NamespaceConcern
-        include Undercarriage::Controllers::Restful::PermittedAttributesConcern
-        include Undercarriage::Controllers::Restful::UtilityConcern
-        include Undercarriage::Controllers::Restful::Actions::BaseConcern
         include Undercarriage::Controllers::Restful::Actions::IndexConcern
         include Undercarriage::Controllers::Restful::Actions::ShowConcern
         include Undercarriage::Controllers::Restful::Actions::NewConcern

data/lib/undercarriage/models/published_concern.rb

@@ -10,78 +10,78 @@ module Undercarriage
     # datetime in the column, it is considered published. You need to do your own validation to ensure the value is a
     # datetime value
     #
-    # Usage
-    #   # Model
+    # @example Model
     #   class Example < ApplicationRecord
     #     include Undercarriage::Models::PublishedConcern
     #
     #     ##
     #     # The name of the column is expected to be `published_at`. If that is not the case for you, uncomment the
     #     # following to change the column name
-    #     #
     #     # self.published_column = :ready_at
     #
     #     ##
     #     # The following are useful helpers for the model. They are not part of the concern
-    #     #
     #     scope :available, -> { published.where("#{published_column} <= ?", Time.current) }
     #
     #     def available?
     #       published? && self[published_column] <= Time.current
     #     end
     #
-    #     scope :scheduled, -> { published.where("#{published_column} > ?", , Time.current) }
+    #     scope :scheduled, -> { published.where("#{published_column} > ?", Time.current) }
     #
     #     def scheduled?
     #       published? && self[published_column] > Time.current
     #     end
     #   end
     #
-    #   # Controller
-    #   class PagesController < AdminController
+    # @example Controller
+    #   class ExamplesController < ApplicationController
     #     def index
     #       @examples = Example.published
     #     end
     #   end
     #
-    #   # View
-    #   <% @examples.each do |example| %>
-    #     Published?: <%= example.published? %>
-    #   <% end %>
-    #
+    # @example View
+    #   # <% @examples.each do |example| %>
+    #   #   Published?: <%= example.published? %>
+    #   # <% end %>
     module PublishedConcern
       extend ActiveSupport::Concern
 
+      ##
+      # @!method self.published
+      #   Published scope
+      #
+      #   Retrieve only published resources
+      #
+      #   @return [ActiveRecord::Relation] published resources
+      #
+      #   @example Controller
+      #     class ExamplesController < ApplicationController
+      #       def index
+      #         @examples = Example.published
+      #       end
+      #     end
+
+      ##
+      # @!method self.unpublished
+      #   Unpublished scope
+      #
+      #   Retrieve only unpublished resources
+      #
+      #   @return [ActiveRecord::Relation] unpublished resources
+      #
+      #   @example Controller
+      #     class ExamplesController < ApplicationController
+      #       def index
+      #         @examples = Example.unpublished
+      #       end
+      #     end
       included do
         class_attribute :published_column
         self.published_column = :published_at
 
-        ##
-        # Published scope
-        #
-        # Retrieve only published resources
-        #
-        # Usage
-        #   class PagesController < AdminController
-        #     def index
-        #       @examples = Example.published
-        #     end
-        #   end
-        #
         scope :published, -> { where.not(published_column => nil) }
-
-        ##
-        # Unpublished scope
-        #
-        # Retrieve only unpublished resources
-        #
-        # Usage
-        #   class PagesController < AdminController
-        #     def index
-        #       @examples = Example.unpublished
-        #     end
-        #   end
-        #
         scope :unpublished, -> { where(published_column => nil) }
       end
 
@@ -91,12 +91,11 @@ module Undercarriage
       # Check if an item is published based on the presence of a value in the published column. This does not take into
       # account whether the item is not currently available (scheduled). See module documentation for more information
       #
-      # Usage
-      #   @example.published? => true
-      #   @example.published? => false
-      #
       # @return [Boolean] if resource is published
       #
+      # @example Controller or View
+      #   @example.published? => true
+      #   @example.published? => false
       def published?
         self[self.class.published_column].present?
       end
@@ -106,12 +105,11 @@ module Undercarriage
       #
       # Check if an item is unpublished based on the lack of presence of a value in the published column
       #
-      # Usage
-      #   @example.unpublished? => true
-      #   @example.unpublished? => false
-      #
       # @return [Boolean] if resource is unpublished
       #
+      # @example Controller or View
+      #   @example.unpublished? => true
+      #   @example.unpublished? => false
       def unpublished?
         !published?
       end

data/lib/undercarriage/version.rb

@@ -3,6 +3,5 @@
 module Undercarriage
   ##
   # Undercarriage version
-  #
-  VERSION = '0.5.5'
+  VERSION = "1.0.0"
 end

data/lib/undercarriage.rb

@@ -1,28 +1,27 @@
 # frozen_string_literal: true
 
-require 'undercarriage/controllers/action_concern'
-require 'undercarriage/controllers/kaminari_concern'
-require 'undercarriage/controllers/locale_concern'
-require 'undercarriage/controllers/restful_concern'
-require 'undercarriage/controllers/restful/actions/base_concern'
-require 'undercarriage/controllers/restful/actions/index_concern'
-require 'undercarriage/controllers/restful/actions/show_concern'
-require 'undercarriage/controllers/restful/actions/new_concern'
-require 'undercarriage/controllers/restful/actions/create_concern'
-require 'undercarriage/controllers/restful/actions/edit_concern'
-require 'undercarriage/controllers/restful/actions/update_concern'
-require 'undercarriage/controllers/restful/actions/destroy_concern'
-require 'undercarriage/controllers/restful/flash_concern'
-require 'undercarriage/controllers/restful/location_after_concern'
-require 'undercarriage/controllers/restful/namespace_concern'
-require 'undercarriage/controllers/restful/permitted_attributes_concern'
-require 'undercarriage/controllers/restful/utility_concern'
-require 'undercarriage/models/published_concern'
+require "undercarriage/controllers/action_concern"
+require "undercarriage/controllers/kaminari_concern"
+require "undercarriage/controllers/locale_concern"
+require "undercarriage/controllers/restful_concern"
+require "undercarriage/controllers/restful/actions/base_concern"
+require "undercarriage/controllers/restful/actions/index_concern"
+require "undercarriage/controllers/restful/actions/show_concern"
+require "undercarriage/controllers/restful/actions/new_concern"
+require "undercarriage/controllers/restful/actions/create_concern"
+require "undercarriage/controllers/restful/actions/edit_concern"
+require "undercarriage/controllers/restful/actions/update_concern"
+require "undercarriage/controllers/restful/actions/destroy_concern"
+require "undercarriage/controllers/restful/flash_concern"
+require "undercarriage/controllers/restful/location_after_concern"
+require "undercarriage/controllers/restful/namespace_concern"
+require "undercarriage/controllers/restful/permitted_attributes_concern"
+require "undercarriage/controllers/restful/utility_concern"
+require "undercarriage/models/published_concern"
 
 ##
 # Undercarriage
 #
 # Undercarriage is a set of concerns to add to your application to trim some of the fat from controllers and models.
-#
 module Undercarriage
 end