wallaby-core 0.1.2 → 0.2.3

data/lib/concerns/wallaby/resources_concern.rb

@@ -0,0 +1,434 @@
+# frozen_string_literal: true
+
+module Wallaby
+  # Resources concern
+  module ResourcesConcern
+    extend ActiveSupport::Concern
+
+    # @!parse
+    #   include ApplicationConcern
+    #   include AuthenticationConcern
+    #   extend Authorizable::ClassMethods
+    #   extend Baseable::ClassMethods
+    #   extend Decoratable::ClassMethods
+    #   extend Paginatable::ClassMethods
+    #   extend Resourcable::ClassMethods
+    #   extend Servicable::ClassMethods
+    #
+    #   include View
+    #   prepend Prefixable
+    #
+    #   include Authorizable
+    #   include Decoratable
+    #   include Defaultable
+    #   include Paginatable
+    #   include Resourcable
+    #   include Servicable
+    #
+    #   alias index! index
+    #   alias new! new
+    #   alias create! create
+    #   alias show! show
+    #   alias edit! edit
+    #   alias update! update
+    #   alias destroy! destroy
+    #   alias collection! collection
+    #   alias resource! resource
+
+    # @!method home
+    # @note This is a template method that can be overridden by subclasses.
+    # This is an action for landing page display. It does nothing more than rendering `home` template.
+    #
+    # It can be replaced completely in subclasses as below:
+    #
+    # ```
+    # def home
+    #   generate_dashboard_report
+    # end
+    # ```
+
+    # @!method index(options = {}, &block)
+    # @note This is a template method that can be overridden by subclasses.
+    # This is a resourceful action to list records that user can access.
+    #
+    # It can be customized as below in subclasses:
+    #
+    # `WARN: Please keep in mind that Wallaby User Interface requires **index**
+    # action to respond to **csv** and **json** format as well.`
+    #
+    # ```
+    # def index
+    #   # do something before the origin action
+    #   options = {} # NOTE: see `options` parameter for more details
+    #   index!(options) do |format| # NOTE: this is better than using `super`
+    #     # NOTE: this block is for `respond_with` which works similar to `respond_to`
+    #     # customize response behaviour, or do something before the request is rendered
+    #   end
+    # end
+    # ```
+    #
+    # Otherwise, it can be replaced completely in subclasses:
+    #
+    # `WARN: Please keep in mind that Wallaby User Interface requires **index**
+    # action to respond to **csv** and **json** format as well.`
+    #
+    # ```
+    # def index
+    #   # NOTE: `@collection` will be used by the view, please ensure it is assigned, for example:
+    #   @collection = Product.all
+    #   respond_with @collection
+    # end
+    # ```
+    # @param options [Hash] (since 5.2.0) options for
+    #   {https://www.rubydoc.info/gems/responders/ActionController/RespondWith#respond_with-instance_method
+    #   respond_with}
+    # @yield [format] block for
+    #   {https://www.rubydoc.info/gems/responders/ActionController/RespondWith#respond_with-instance_method
+    #   respond_with}
+    #   to customize response behaviour.
+    # @raise [Wallaby::Forbidden] if user has no access
+
+    # @!method new(options = {}, &block)
+    # @note This is a template method that can be overridden by subclasses.
+    # This is a resourceful action to show the form to create record that user is allowed to.
+    #
+    # It can be customized as below in subclasses:
+    #
+    # ```
+    # def new
+    #   # do something before the origin action
+    #   options = {} # NOTE: see `options` parameter for more details
+    #   new!(options) do |format| # NOTE: this is better than using `super`
+    #     # NOTE: this block is for `respond_with` which works similar to `respond_to`
+    #     # customize response behaviour, or do something before the request is rendered
+    #   end
+    # end
+    # ```
+    #
+    # Otherwise, it can be replaced completely in subclasses:
+    #
+    # ```
+    # def new
+    #   # NOTE: `@resource` will be used by the view, please ensure it is assigned, for example:
+    #   @resource = Product.new new_arrival: true
+    # end
+    # ```
+    # @param options [Hash] (since 5.2.0) options for
+    #   {https://www.rubydoc.info/gems/responders/ActionController/RespondWith#respond_with-instance_method
+    #   respond_with}
+    # @yield [format] block for
+    #   {https://www.rubydoc.info/gems/responders/ActionController/RespondWith#respond_with-instance_method
+    #   respond_with}
+    #   to customize response behaviour.
+    # @raise [Wallaby::Forbidden] if user has no access
+
+    # @!method create(options = {}, &block)
+    # @note This is a template method that can be overridden by subclasses.
+    # This is a resourceful action to create a record that user is allowed to.
+    #
+    # If record is created successfully, user will be navigated to the record show page.
+    # Otherwise, the form will be shown again with error messages.
+    #
+    # It can be customized as below in subclasses:
+    #
+    # ```
+    # def create
+    #   # do something before the origin action
+    #   options = {} # NOTE: see `options` parameter for more details
+    #   create!(options) do |format| # NOTE: this is better than using `super`
+    #     # NOTE: this block is for `respond_with` which works similar to `respond_to`
+    #     # customize response behaviour, or do something before the request is rendered
+    #   end
+    # end
+    # ```
+    #
+    # Otherwise, it can be replaced completely in subclasses:
+    #
+    # ```
+    # def create
+    #   # NOTE: `@resource` will be used by the view, please ensure it is assigned, for example:
+    #   @resource = Product.new resource_params.merge(new_arrival: true)
+    #   if @resource.save
+    #     redirect_to helper.index_path(current_model_class)
+    #   else
+    #     render :new
+    #   end
+    # end
+    # ```
+    # @param options [Hash] (since 5.2.0) options for
+    #   {https://www.rubydoc.info/gems/responders/ActionController/RespondWith#respond_with-instance_method
+    #   respond_with}. In addition, options `:params` is supported, see below
+    # @option options [ActionController::Parameters, Hash] :params
+    #   permitted parameters for servicer to create the record. _(defaults to: {#resource_params})_
+    # @yield [format] block for
+    #   {https://www.rubydoc.info/gems/responders/ActionController/RespondWith#respond_with-instance_method
+    #   respond_with}
+    #   to customize response behaviour.
+    # @raise [Wallaby::Forbidden] if user has no access
+
+    # @!method show(options = {}, &block)
+    # @note This is a template method that can be overridden by subclasses.
+    # This is a resourceful action to display the record details that user is allowed to.
+    #
+    # It can be customized as below in subclasses:
+    #
+    # ```
+    # def show
+    #   # do something before the origin action
+    #   options = {} # NOTE: see `options` parameter for more details
+    #   show!(options) do |format| # NOTE: this is better than using `super`
+    #     # NOTE: this block is for `respond_with` which works similar to `respond_to`
+    #     # customize response behaviour, or do something before the request is rendered
+    #   end
+    # end
+    # ```
+    #
+    # Otherwise, it can be replaced completely in subclasses:
+    #
+    # ```
+    # def show
+    #   # NOTE: `@resource` will be used by the view, please ensure it is assigned, for example:
+    #   @resource = Product.find_by_slug params[:id]
+    # end
+    # ```
+    # @param options [Hash] (since 5.2.0) options for
+    #   {https://www.rubydoc.info/gems/responders/ActionController/RespondWith#respond_with-instance_method
+    #   respond_with}
+    # @yield [format] block for
+    #   {https://www.rubydoc.info/gems/responders/ActionController/RespondWith#respond_with-instance_method
+    #   respond_with}
+    #   to customize response behaviour.
+    # @raise [Wallaby::Forbidden] if user has no access
+
+    # @!method edit(options = {}, &block)
+    # @note This is a template method that can be overridden by subclasses.
+    # This is a resourceful action to show the form to edit record that user is allowed to.
+    #
+    # It can be customized as below in subclasses:
+    #
+    # ```
+    # def edit
+    #   # do something before the origin action
+    #   options = {} # NOTE: see `options` parameter for more details
+    #   edit!(options) do |format| # NOTE: this is better than using `super`
+    #     # NOTE: this block is for `respond_with` which works similar to `respond_to`
+    #     # customize response behaviour, or do something before the request is rendered
+    #   end
+    # end
+    # ```
+    #
+    # Otherwise, it can be replaced completely in subclasses:
+    #
+    # ```
+    # def edit
+    #   # NOTE: `@resource` will be used by the view, please ensure it is assigned, for example:
+    #   @resource = Product.find_by_slug params[:id]
+    # end
+    # ```
+    # @param options [Hash] (since 5.2.0) options for
+    #   {https://www.rubydoc.info/gems/responders/ActionController/RespondWith#respond_with-instance_method
+    #   respond_with}
+    # @yield [format] block for
+    #   {https://www.rubydoc.info/gems/responders/ActionController/RespondWith#respond_with-instance_method
+    #   respond_with}
+    #   to customize response behaviour.
+    # @raise [Wallaby::Forbidden] if user has no access
+
+    # @!method update(options = {}, &block)
+    # @note This is a template method that can be overridden by subclasses.
+    # This is a resourceful action to update the record that user is allowed to.
+    #
+    # If record is updated successfully, user will be navigated to the record show page.
+    # Otherwise, the form will be shown again with error messages.
+    #
+    # It can be customized as below in subclasses:
+    #
+    # ```
+    # def update
+    #   # do something before the origin action
+    #   options = {} # NOTE: see `options` parameter for more details
+    #   update!(options) do |format| # NOTE: this is better than using `super`
+    #     # NOTE: this block is for `respond_with` which works similar to `respond_to`
+    #     # customize response behaviour, or do something before the request is rendered
+    #   end
+    # end
+    # ```
+    #
+    # Otherwise, it can be replaced completely in subclasses:
+    #
+    # ```
+    # def update
+    #   # NOTE: `@resource` will be used by the view, please ensure it is assigned, for example:
+    #   @resource = Product.find_by_slug params[:id]
+    #   @resource.assign_attributes resource_params.merge(new_arrival: true)
+    #   if @resource.save
+    #     redirect_to helper.index_path(current_model_class)
+    #   else
+    #     render :new
+    #   end
+    # end
+    # ```
+    # @param options [Hash] (since 5.2.0) options for
+    #   {https://www.rubydoc.info/gems/responders/ActionController/RespondWith#respond_with-instance_method
+    #   respond_with}. In addition, options `:params` is supported, see below
+    # @option options [ActionController::Parameters, Hash] :params
+    #   permitted parameters for servicer to update the record. _(defaults to: {#resource_params})_
+    # @yield [format] block for
+    #   {https://www.rubydoc.info/gems/responders/ActionController/RespondWith#respond_with-instance_method
+    #   respond_with}
+    #   to customize response behaviour.
+    # @raise [Wallaby::Forbidden] if user has no access
+
+    # @!method destroy(options = {}, &block)
+    # @note This is a template method that can be overridden by subclasses.
+    # This is a resourceful action to delete the record that user is allowed to.
+    #
+    # It can be customized as below in subclasses:
+    #
+    # ```
+    # def destroy
+    #   # do something before the origin action
+    #   options = {} # NOTE: see `options` parameter for more details
+    #   destroy!(options) do |format| # NOTE: this is better than using `super`
+    #     # NOTE: this block is for `respond_with` which works similar to `respond_to`
+    #     # customize response behaviour, or do something before the request is rendered
+    #   end
+    # end
+    # ```
+    #
+    # Otherwise, it can be replaced completely in subclasses:
+    #
+    # ```
+    # def destroy
+    #   # NOTE: `@resource` will be used by the view, please ensure it is assigned, for example:
+    #   @resource = Product.find_by_slug params[:id]
+    #   @resource.destroy
+    #   redirect_to helper.index_path(current_model_class)
+    # end
+    # ```
+    # @param options [Hash] (since 5.2.0) options for
+    #   {https://www.rubydoc.info/gems/responders/ActionController/RespondWith#respond_with-instance_method
+    #   respond_with}. In addition, options `:params` is supported, see below
+    # @option options [ActionController::Parameters, Hash] :params
+    #   permitted parameters for servicer to destroy the record. _(defaults to: {#resource_params})_
+    # @yield [format] block for
+    #   {https://www.rubydoc.info/gems/responders/ActionController/RespondWith#respond_with-instance_method
+    #   respond_with}
+    #   to customize response behaviour.
+    # @raise [Wallaby::Forbidden] if user has no access
+
+    # @!method resource_params
+    # @note This is a template method that can be overridden by subclasses.
+    # To whitelist the params for {#create} and {#update} actions.
+    #
+    # If Wallaby cannot generate the correct strong parameters, it can be replaced, for example:
+    #
+    # ```
+    # def resource_params
+    #   params.fetch(:product, {}).permit(:name, :sku)
+    # end
+    # ```
+    # @return [ActionController::Parameters] whitelisted params
+
+    included do # rubocop:disable Metrics/BlockLength
+      include ApplicationConcern
+      include AuthenticationConcern
+
+      extend Authorizable::ClassMethods
+      extend Baseable::ClassMethods
+      extend Decoratable::ClassMethods
+      extend Paginatable::ClassMethods
+      extend Servicable::ClassMethods
+
+      include View
+      prepend Prefixable
+
+      include Authorizable
+      include Decoratable
+      include Defaultable
+      include Paginatable
+      include Resourcable
+      include Servicable
+
+      base_class!
+
+      # NOTE: to ensure Wallaby's layout
+      # is not inheriting from/impacted by parent controller's layout.
+      public_send(
+        # inherit? or include?
+        self == ResourcesController ? :layout : :theme_name=,
+        ResourcesController.controller_path
+      )
+
+      self.responder = ResourcesResponder
+      respond_to :html
+      respond_to :json
+      respond_to :csv
+      helper ResourcesHelper
+      before_action :authenticate_wallaby_user!
+
+      def home
+        # do nothing
+      end
+
+      def index(options = {}, &block)
+        current_authorizer.authorize :index, current_model_class
+        respond_with collection, options, &block
+      end
+
+      alias_method :index!, :index
+
+      def new(options = {}, &block)
+        current_authorizer.authorize :new, resource
+        respond_with resource, options, &block
+      end
+
+      alias_method :new!, :new
+
+      def create(options = {}, &block)
+        set_defaults_for :create, options
+        current_authorizer.authorize :create, resource
+        current_servicer.create resource, options.delete(:params)
+        respond_with resource, options, &block
+      end
+
+      alias_method :create!, :create
+
+      def show(options = {}, &block)
+        current_authorizer.authorize :show, resource
+        respond_with resource, options, &block
+      end
+
+      alias_method :show!, :show
+
+      def edit(options = {}, &block)
+        current_authorizer.authorize :edit, resource
+        respond_with resource, options, &block
+      end
+
+      alias_method :edit!, :edit
+
+      def update(options = {}, &block)
+        set_defaults_for :update, options
+        current_authorizer.authorize :update, resource
+        current_servicer.update resource, options.delete(:params)
+        respond_with resource, options, &block
+      end
+
+      alias_method :update!, :update
+
+      def destroy(options = {}, &block)
+        set_defaults_for :destroy, options
+        current_authorizer.authorize :destroy, resource
+        current_servicer.destroy resource, options.delete(:params)
+        respond_with resource, options, &block
+      end
+
+      alias_method :destroy!, :destroy
+
+      def resource_params
+        @resource_params ||= current_servicer.permit params, action_name
+      end
+    end
+  end
+end

data/lib/concerns/wallaby/servicable.rb

@@ -20,7 +20,7 @@ module Wallaby
       # @return [Class] model servicer
       # @raise [ArgumentError] when **model_servicer** doesn't inherit from **application_servicer**
       # @see Wallaby::ModelServicer
-      # @since 5.2.0
+      # @since wallaby-5.2.0
       attr_reader :model_servicer
 
       # @!attribute [w] application_servicer
@@ -38,7 +38,7 @@ module Wallaby
       # @return [Class] application decorator
       # @raise [ArgumentError] when **model_servicer** doesn't inherit from **application_servicer**
       # @see Wallaby::ModelServicer
-      # @since 5.2.0
+      # @since wallaby-5.2.0
       def application_servicer
         @application_servicer ||= ModuleUtils.try_to superclass, :application_servicer
       end
@@ -49,20 +49,14 @@ module Wallaby
     # - controller configuration {Wallaby::Servicable::ClassMethods#model_servicer .model_servicer}
     # - a generic servicer based on {Wallaby::Servicable::ClassMethods#application_servicer .application_servicer}
     # @return [Wallaby::ModelServicer] model servicer
-    # @since 5.2.0
+    # @since wallaby-5.2.0
     def current_servicer
       @current_servicer ||=
         (controller_to_get(:model_servicer) \
           || Map.servicer_map(current_model_class, controller_to_get(:application_servicer))).try do |klass|
-          Rails.logger.info %(  - Current servicer: #{klass})
+          Logger.debug %(Current servicer: #{klass}), sourcing: false
           klass.new current_model_class, current_authorizer, current_model_decorator
         end
     end
-
-    # @deprecated Use {#current_servicer} instead. It will be removed from 5.3.*
-    def current_model_service
-      Utils.deprecate 'deprecation.current_model_service', caller: caller
-      current_servicer
-    end
   end
 end

data/lib/decorators/wallaby/resource_decorator.rb

@@ -1,10 +1,53 @@
 # frozen_string_literal: true
 
 module Wallaby
-  # Resource Decorator base class, designed for decorator pattern.
-  # @see Wallaby::ModelDecorator
+  # Decorator base class. It's designed to be used as the decorator (AKA presenter/view object)
+  # for the associated model instance (which means it should be used in the views only).
+  #
+  # And it holds the following metadata information for associated model class:
+  #
+  # - {#fields}
+  # - {#field_names}
+  # - {#index_fields}
+  # - {#index_field_names}
+  # - {#show_fields}
+  # - {#show_field_names}
+  # - {#form_fields}
+  # - {#form_field_names}
+  #
+  # For better practice, please create an application decorator class (see example)
+  # to better control the functions shared between different resource decorators.
+  # @example Create an application class for Admin Interface usage
+  #   class Admin::ApplicationDecorator < Wallaby::ResourceDecorator
+  #     base_class!
+  #   end
   class ResourceDecorator
     extend Baseable::ClassMethods
+    base_class!
+
+    # @!attribute fields
+    #   (see Wallaby::ModelDecorator#fields)
+
+    # @!attribute field_names
+    #   (see Wallaby::ModelDecorator#field_names)
+
+    # @!attribute index_fields
+    #   (see Wallaby::ModelDecorator#index_fields)
+
+    # @!attribute index_field_names
+    #   (see Wallaby::ModelDecorator#index_field_names)
+
+    # @!attribute show_fields
+    #   (see Wallaby::ModelDecorator#show_fields)
+
+    # @!attribute show_field_names
+    #   (see Wallaby::ModelDecorator#show_field_names)
+
+    # @!attribute form_fields
+    #   (see Wallaby::ModelDecorator#form_fields)
+
+    # @!attribute form_field_names
+    #   (see Wallaby::ModelDecorator#form_field_names)
 
     DELEGATE_METHODS =
       ModelDecorator.public_instance_methods(false) + Fieldable.public_instance_methods(false) - %i(model_class)
@@ -12,85 +55,15 @@ module Wallaby
     class << self
       delegate(*DELEGATE_METHODS, to: :model_decorator, allow_nil: true)
 
-      # @!attribute [w] model_class
-      attr_writer :model_class
-
-      # @!attribute [r] model_class
-      # Return associated model class, e.g. return **Product** for **ProductDecorator**.
-      #
-      # If Wallaby can't recognise the model class for Decorator, it's required to be configured as below example:
-      # @example To configure model class
-      #   class Admin::ProductDecorator < Admin::ApplicationDecorator
-      #     self.model_class = Product
-      #   end
-      # @example To configure model class for version below 5.2.0
-      #   class Admin::ProductDecorator < Admin::ApplicationDecorator
-      #     def self.model_class
-      #       Product
-      #     end
-      #   end
-      # @return [Class] assoicated model class
-      # @return [nil] if current class is marked as base class
-      # @return [nil] if current class is the same as the value of {Wallaby::Configuration::Mapping#resource_decorator}
-      # @return [nil] if current class is {Wallaby::ResourceDecorator}
-      # @return [nil] if assoicated model class is not found
-      def model_class
-        return unless self < ResourceDecorator
-        return if base_class? || self == Wallaby.configuration.mapping.resource_decorator
-
-        @model_class ||= Map.model_class_map(name.gsub(/(^#{namespace}::)|(Decorator$)/, EMPTY_STRING))
-      end
-
-      # @!attribute [w] application_decorator
-      def application_decorator=(application_decorator)
-        ModuleUtils.inheritance_check self, application_decorator
-        @application_decorator = application_decorator
-      end
-
-      # @note This attribute have to be the same as the one defined in the controller in order to make things working.
-      #   see {Wallaby::Decoratable::ClassMethods#application_decorator}
-      # @!attribute [r] application_decorator
-      # Assoicated base class.
-      #
-      # Wallaby will try to get the application decorator class from current class's ancestors chain.
-      # For instance, if current class is **ProductDecorator**, and it inherits from **CoreDecorator**,
-      # then Wallaby will return application decorator class **CoreDecorator**.
-      #
-      # However, there is a chance that Wallaby doesn't get it right.
-      # For instance, if **CoreDecorator** in the above example inherits from **Admin::ApplicationDecorator**, and
-      # the controller that needs **ProductDecorator** has set its **application_decorator** to
-      # **Admin::ApplicationDecorator**, then it's needed to configure **application_decorator** as the example
-      # describes
-      # @example To set application decorator class
-      #   class ProductController < Admin::ApplicationController
-      #     self.application_decorator = Admin::ApplicationDecorator
-      #   end
-      #
-      #   class CoreDecorator < Admin::ApplicationDecorator
-      #     base_class!
-      #   end
-      #
-      #   class ProductDecorator < CoreDecorator
-      #     self.application_decorator = Admin::ApplicationDecorator
-      #   end
-      # @return [Class] assoicated base class.
-      # @return [nil] if assoicated base class is not found from its ancestors chain
-      # @raise [ArgumentError] when current class doesn't inherit from given value
-      # @since 5.2.0
-      def application_decorator
-        @application_decorator ||= ancestors.find { |parent| parent < ResourceDecorator && !parent.model_class }
-      end
-
-      # Return associated model decorator.
-      #
-      # Fetch model decorator instance from cached map using keys {.model_class} and {.application_decorator}
-      # so that model decorator can be used in its sub classes declaration/scope.
+      # Return associated model decorator. It is the instance that pull out all the metadata
+      # information for the associated model.
       # @param model_class [Class]
       # @return [Wallaby::ModelDecorator]
+      # @return [nil] if itself is a base class or the given model_class is blank
       def model_decorator(model_class = self.model_class)
-        return unless self < ResourceDecorator || model_class
+        return if model_class.blank?
 
-        Map.model_decorator_map model_class, application_decorator
+        Map.model_decorator_map model_class, base_class
       end
 
       # @!attribute [w] h
@@ -164,13 +137,13 @@ module Wallaby
 
     # @return [ActiveModel::Name]
     def model_name
-      ModuleUtils.try_to(resource, :model_name) || ActiveModel::Name.new(model_class)
+      resource.try(:model_name) || ActiveModel::Name.new(model_class)
     end
 
     # @return [nil] if no primary key
     # @return [Array<String>] primary key
     def to_key
-      key = ModuleUtils.try_to(resource, primary_key)
+      key = resource.try primary_key
       key ? [key] : nil
     end
 
@@ -181,7 +154,7 @@ module Wallaby
       resource.try method_id, *args, &block
     end
 
-    # Delegate missing method check to context
+    # Delegate missing method check to {#resource}
     def respond_to_missing?(method_id, _include_private)
       resource.respond_to?(method_id) || super
     end

data/lib/errors/wallaby/{cell_handling.rb → class_not_found.rb}

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Wallaby
-  class CellHandling < ::StandardError
+  class ClassNotFound < GeneralError
   end
 end

data/lib/errors/wallaby/model_not_found.rb

@@ -5,7 +5,9 @@ module Wallaby
   class ModelNotFound < NotFound
     # @return [String] not found error message
     def message
-      I18n.t 'errors.not_found.model', model: super
+      return super if super.include? "\n"
+
+      Locale.t 'errors.not_found.model', model: super
     end
   end
 end

data/lib/errors/wallaby/resource_not_found.rb

@@ -5,7 +5,7 @@ module Wallaby
   class ResourceNotFound < NotFound
     # @return [String] resource not found error message
     def message
-      I18n.t 'errors.not_found.resource', resource: super
+      Locale.t 'errors.not_found.resource', resource: super
     end
   end
 end