wicked-pipeline 0.1.0

data/app/controllers/wicked/pipeline/base_steps_controller.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+module Wicked
+  module Pipeline
+    class BaseStepsController < parent_controller.constantize
+      include Wicked::Wizard
+
+      before_action :_set_steps
+      before_action :setup_wizard
+
+      rescue_from Wicked::Wizard::InvalidStepError, with: :handle_invalid_step!
+
+      attr_reader :step_processor
+      helper_method :step_processor
+
+      def show
+        yield if block_given?
+
+        _set_processor_required!
+
+        if step == Wicked::FINISH_STEP && steps_metadata[steps.last][:valid] && steps_metadata[steps.last][:accessible]
+          jump_to(steps.last) if steps_metadata[steps.last][:blocking]
+          render_wizard(nil, {}, resource_url_params)
+        elsif _accessible_steps.include?(step_processor.step_name)
+          render_step(step_processor.step_name)
+        else
+          jump_to(_accessible_steps.last)
+          render_wizard(nil, {}, resource_url_params)
+        end
+      end
+
+      def update
+        params.require(:id)
+
+        yield if block_given?
+
+        _set_processor_required!
+
+        unless step_processor.resource.new_record?
+          render_wizard(step_processor, {}, resource_url_params)
+          return
+        end
+
+        process_resource!(step_processor)
+
+        if step_processor.saved?
+          render_wizard(nil, {}, resource_url_params)
+        else
+          render_step(step_processor.step_name)
+        end
+      end
+
+      protected
+
+      def resource_param_name
+        raise NotImplementedError, "resource_param_name must be implemented in subclasses of #{self.class.name}"
+      end
+
+      def resource_url_params
+        _set_processor_required!
+        {resource_param_name => step_processor.id}
+      end
+
+      def find_resource
+        raise NotImplementedError, "find_resource must be implemented in subclasses of #{self.class.name}"
+      end
+
+      def steps_pipeline
+        raise NotImplementedError, "steps_pipeline must be implemented in subclasses of #{self.class.name}"
+      end
+      helper_method :steps_pipeline
+
+      def step_classes
+        Array(steps_pipeline)
+      end
+
+      def step_class
+        return @step_class if @step_class
+
+        the_step =
+          case step
+          when Wicked::FIRST_STEP
+            steps.first
+          when Wicked::LAST_STEP
+            steps.last
+          when Wicked::FINISH_STEP
+            steps.last
+          else
+            step || steps.first
+          end
+
+        @step_class = _step_classes.fetch(the_step.to_s)
+      end
+
+      def step_path(step_name: nil, **options)
+        wizard_path(step_name.presence || step_class.step_name, options.reverse_merge(resource_url_params))
+      end
+      helper_method :step_path
+
+      def steps_metadata
+        return @steps_metadata if @steps_metadata
+
+        @steps_metadata = step_classes.each_with_index.with_object(ActiveSupport::HashWithIndifferentAccess.new) do |(klass, idx), obj|
+          processor = klass.new(_shallow_resource)
+
+          obj[processor.step_name] = {
+            url: step_path(step_name: processor.step_name),
+            active: (step.present? && processor.step_name.to_s == step.to_s) || (step.blank? && idx == 0)
+          }.merge(_steps_metadata[processor.step_name])
+        end
+      end
+      helper_method :steps_metadata
+
+      def current_step
+        return @current_step if @current_step
+
+        _set_processor_required!
+
+        @current_step = step_processor.step_name
+      end
+      helper_method :current_step
+
+      def step_i18n_scope
+        return @step_i18n_scope if @step_i18n_scope
+
+        _set_processor_required!
+
+        @step_i18n_scope = "#{controller_path}.#{step_processor.step_name}".tr("/", ".")
+      end
+      helper_method :step_i18n_scope
+
+      def handle_invalid_step!(exception)
+        if block_given?
+          yield
+        else
+          error_details = {
+            :step => params[:id],
+            resource_param_name => params[resource_param_name],
+            :controller => params[:controller],
+            :action => params[:action]
+          }
+
+          logger = ActiveSupport::TaggedLogging.new(Rails.logger)
+          logger.tagged("[#{self.class.name}]") do
+            logger.error("#{exception.class.name}: #{exception.message} -- details: #{error_details.to_json}")
+          end
+        end
+
+        redirect_to url_for({
+          :controller => params[:controller],
+          :action => params[:action],
+          resource_param_name => params[resource_param_name]
+        })
+      end
+
+      private
+
+      def _shallow_resource
+        @_shallow_resource ||= find_resource
+      end
+
+      def _set_processor_required!
+        raise "@step_processor must not be nil" if step_processor.nil?
+      end
+
+      def _step_classes
+        @_step_classes ||= step_classes.each_with_object(ActiveSupport::HashWithIndifferentAccess.new) do |klass, obj|
+          obj[klass.step_name] = klass
+        end
+      end
+
+      def _steps_metadata
+        return @_steps_metadata if @_steps_metadata
+
+        @_steps_metadata = steps_pipeline.metadata(_shallow_resource)
+      end
+
+      def _accessible_steps
+        @_accessible_steps ||= _steps_metadata.each_with_object([]) do |(step_name, step_metadata), obj|
+          break obj unless step_metadata[:accessible]
+
+          obj << step_name
+        end
+      end
+
+      def _set_steps
+        self.steps = _step_classes.keys
+      end
+    end
+  end
+end

data/lib/wicked/pipeline/base_pipeline.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Wicked
+  module Pipeline
+    class BasePipeline
+      def steps
+        []
+      end
+
+      def valid?(resource)
+        steps.all? { |step| step.new(resource).valid? }
+      end
+
+      def blocked?(resource)
+        steps.any? { |step| step.new(resource).blocking? }
+      end
+
+      def first_step?(step)
+        steps.first == step
+      end
+
+      def last_step?(step)
+        steps.last == step
+      end
+
+      def find_step(the_step)
+        steps.find { |step| step == the_step || step.step_name == the_step }
+      end
+
+      def next_step(current_step)
+        step, step_index = steps.each_with_index.find { |step, _| step == current_step || step.step_name == current_step }
+
+        last_step?(step) || step_index.nil? ? nil : steps[step_index + 1]
+      end
+
+      def previous_step(current_step)
+        step, step_index = steps.each_with_index.find { |step, _| step == current_step || step.step_name == current_step }
+
+        first_step?(step) || step_index.nil? ? nil : steps[step_index - 1]
+      end
+
+      def next_step?(current_step, step)
+        !current_step.nil? && !step.nil? &&
+          next_step(current_step) == step
+      end
+
+      def previous_step?(current_step, step)
+        !current_step.nil? && !step.nil? &&
+          previous_step(current_step) == step
+      end
+
+      def metadata(resource)
+        steps.each_with_index.with_object(ActiveSupport::HashWithIndifferentAccess.new) do |(step, idx), obj|
+          processor = step.new(resource)
+          previous_step_metadata = obj.fetch(obj.keys[idx - 1], {})
+
+          obj[processor.step_name] = {
+            valid: processor.valid?,
+            blocking: processor.blocking?,
+            accessible: idx == 0 || (
+              !previous_step_metadata[:blocking] &&
+              previous_step_metadata[:accessible] &&
+              previous_step_metadata[:valid]
+            )
+          }
+        end
+      end
+
+      def to_ary
+        steps
+      end
+      alias_method :to_a, :to_ary
+
+      class << self
+        def steps
+          new.steps
+        end
+
+        def valid?(resource)
+          new.valid?(resource)
+        end
+
+        def blocked?(resource)
+          new.blocked?(resource)
+        end
+
+        def first_step?(step)
+          new.first_step?(step)
+        end
+
+        def last_step?(step)
+          new.last_step?(step)
+        end
+
+        def find_step(step)
+          new.find_step(step)
+        end
+
+        def next_step(current_step)
+          new.next_step(current_step)
+        end
+
+        def previous_step(current_step)
+          new.previous_step(current_step)
+        end
+
+        def next_step?(current_step, step)
+          new.next_step(current_step, step)
+        end
+
+        def previous_step?(current_step, step)
+          new.previous_step(current_step, step)
+        end
+
+        def metadata(resource)
+          new.metadata(resource)
+        end
+
+        def to_ary
+          new.to_ary
+        end
+        alias_method :to_a, :to_ary
+      end
+    end
+  end
+end

data/lib/wicked/pipeline/base_step.rb

@@ -0,0 +1,304 @@
+# frozen_string_literal: true
+
+require "active_model"
+
+module Wicked
+  module Pipeline
+    class BaseStep
+      include ActiveModel::Attributes
+      include ActiveModel::AttributeAssignment
+      include ActiveModel::Validations
+
+      # @return [ActiveRecord::Base] The record associated with the step
+      attr_reader :resource
+
+      # @param resource [ActiveRecord::Base] The record associated with the step
+      # @param params [Hash, ActionController::Parameters] Attribute changes to be applied to the resource
+      def initialize(resource, params = nil)
+        super()
+
+        @resource = resource
+
+        attributes.each_key do |key|
+          public_send("#{key}=", resource.public_send(key)) if resource.respond_to?(key)
+        end
+
+        unless params.nil?
+          parameters = _permit_params!(params)
+          self.attributes = parameters.select { |key, _| respond_to?("#{key}=") }
+          resource.attributes = parameters.select { |key, _| resource.respond_to?("#{key}=") }
+        end
+
+        regenerate_blocking_reasons!
+      end
+
+      # Saves the resource
+      #
+      # If the step is readonly the record will not
+      # be saved and the method will return +true+
+      #
+      # @return [Boolean]
+      def save(**options, &block)
+        return true if readonly?
+
+        cleanup_stale_data
+
+        valid? && resource.save(**options, &block)
+      end
+
+      # Check if both the step and the resource are valid
+      #
+      # Always returns +true+ if the step is readonly
+      #
+      # @return [Boolean]
+      def valid?
+        return true if readonly?
+
+        is_valid = super
+        resource.validate
+        resource.errors.merge!(errors)
+        regenerate_blocking_reasons!
+        is_valid && resource.errors.none?
+      end
+
+      # Checks if the resource exists in the database
+      #
+      # Always returns +true+ if the step is readonly
+      #
+      # @return [Boolean]
+      def persisted?
+        readonly? || resource.persisted?
+      end
+
+      # Checks that the step has been successfully saved and there are no unsaved changes
+      #
+      # Always returns +true+ if the step is readonly
+      #
+      # @return [Boolean]
+      def saved?
+        readonly? || (persisted? && resource.saved_changes? && !resource.has_changes_to_save?)
+      end
+
+      # Checks if the step is blocking subsequent steps in a pipeline. In other words,
+      # if a step is "blocking", all the subsequent steps in the pipeline will be marked
+      # as inaccessible.
+      #
+      # This can be used to short-circuit a pipeline.
+      #
+      # @return [Boolean]
+      def blocking?
+        false
+      end
+
+      # Check if the step is readonly
+      #
+      # @return [Boolean]
+      def readonly?
+        false
+      end
+
+      # Returns the reason why a step is blocking, or +nil+ if it is not blocking.
+      #
+      # This should be used to set an overall blocking reason.
+      # To set per-attribute blocking reasons use {#blocking_reasons}.
+      #
+      # @return [String, nil]
+      # @see #blocking?
+      # @see #blocking_reasons
+      def blocking_reason
+        nil
+      end
+
+      # Returns reasons for each attribute why a step is blocking.
+      #
+      # @note This method should not be overridden, it should just be used to access
+      #   blocking reasons. To add a new reason, just add it to the hash. To reset all
+      #   the reasons, override the {#regenerate_blocking_reasons!} method in subsclasses.
+      #
+      # @note Warning: Every time {#valid?} is called the blocking reasons will be regenereted.
+      #
+      # @return [Hash{String,Symbol => Array<String>}] hash of reasons for each attribute.
+      # @see #blocking?
+      def blocking_reasons
+        @blocking_reasons ||= ActiveSupport::HashWithIndifferentAccess.new { |h, k| h[k] = [] }
+      end
+
+      # Returns the String representation of the step object
+      #
+      # @example Step object without a namespace
+      #   FinancialSituationnStep.to_s #=> "financial_situation"
+      #
+      # @example Nested step object
+      #   Users::FinancialSituationnStep.to_s #=> "users/financial_situation"
+      #
+      # @return [String]
+      def self.to_s
+        @_to_s ||= name.to_s.underscore.sub(/_step\z/, "")
+      end
+
+      # Returns the step name of the step object
+      #
+      # @example Step object without a namespace
+      #   FinancialSituationnStep.step_name #=> "financial_situation"
+      #
+      # @example Nested step object
+      #   Users::FinancialSituationnStep.step_name #=> "financial_situation"
+      #
+      # @return [String]
+      def self.step_name
+        @_step_name ||= to_s.gsub(%r{(?:\w+/)*}, "")
+      end
+
+      # Returns the String representation of the step object
+      #
+      # @example Step object without a namespace
+      #   FinancialSituationnStep.new(resource).to_s #=> "financial_situation"
+      #
+      # @example Nested step object
+      #   Users::FinancialSituationnStep.new(resource).to_s #=> "users/financial_situation"
+      #
+      # @see .to_s
+      #
+      # @return [String]
+      def to_s
+        self.class.to_s
+      end
+
+      # Returns the step name of the step object
+      #
+      # @example Step object without a namespace
+      #   FinancialSituationnStep.new(resource).step_name #=> "financial_situation"
+      #
+      # @example Nested step object
+      #   Users::FinancialSituationnStep.new(resource).step_name #=> "financial_situation"
+      #
+      # @see .step_name
+      #
+      # @return [String]
+      def step_name
+        self.class.step_name
+      end
+
+      # Check whether two steps are the same
+      #
+      # It returns +true+ only if +other+ is the same step class then +self+ or if +self.to_s+ is equal to +other+.
+      # +other.step_name+.
+      #
+      # @param other [BaseStep, String, Symbol] the other step tested for equality
+      # @return [Boolean]
+      #
+      # @see .to_s
+      def self.==(other)
+        super || to_s == other.to_s
+      end
+
+      # (see .==)
+      def self.eql?(other)
+        self == other
+      end
+
+      # (see .==)
+      # @see .==
+      def self.equal?(other)
+        self == other
+      end
+
+      # (see .equal?)
+      def self.===(other)
+        equal?(other)
+      end
+
+      # (see .equal?)
+      def equal?(other)
+        self.class.equal?(other)
+      end
+
+      # (see .equal?)
+      def ===(other)
+        equal?(other)
+      end
+
+      # @return [Number, Symbol] The ID of the resource or :new if the the resource is a new record
+      def id
+        resource.id || :new
+      end
+
+      # Validate the associations of of the resource
+      #
+      # @param associations [Symbol]
+      # @param options [void] <b>Do not use!</b> It is here for compatibility reasons.
+      # @note Do not use the +options+ param, it is here for compatibility with
+      #       the +ActiveRecord::Validations::AssociatedValidator+.
+      #
+      # @example
+      #   class OwnershipStep < BaseStep
+      #     validates_associated :beneficiaries
+      #   end
+      def self.validates_associated(*associations, **options)
+        if options.present?
+          warn "WARN: calling .validates_associated with options from step objects is not supported."
+        end
+
+        associations.each do |association|
+          unless respond_to?(association)
+            delegate association, to: :resource
+          end
+
+          validate do
+            Array(public_send(association)).each do |associated_object|
+              unless associated_object.valid?
+                errors.add(association, :invalid)
+                break
+              end
+            end
+          end
+        end
+      end
+      private_class_method :validates_associated
+
+      def self.i18n_scope
+        @_i18n_scope ||= name.underscore.tr("/", ".").prepend("steps.")
+      end
+
+      delegate :i18n_scope, to: :class
+
+      protected
+
+      def permitted_params
+        raise NotImplementedError, "permitted_params must be implemented in subclasses of BaseStep"
+      end
+
+      # This method is meant to be overridden.
+      # Make sure to call #super before any custom code!
+      def regenerate_blocking_reasons!
+        blocking_reasons.clear
+      end
+
+      def stale_attributes
+        []
+      end
+
+      def cleanup_stale_data
+        unless stale_attributes.blank?
+          stale_attributes_params = Array(stale_attributes).zip([]).to_h
+          self.attributes = stale_attributes_params
+          resource.attributes = stale_attributes_params
+        end
+      end
+
+      private
+
+      def _permit_params!(params)
+        case params
+        when ActionController::Parameters
+          params.permit(*permitted_params)
+        when Hash
+          normalized_permitted_params = permitted_params.flat_map { |param| param.is_a?(Hash) ? param.keys : param }
+          params.slice(*normalized_permitted_params)
+        else
+          raise ArgumentError, "expected one of ActionController::Parameters, Hash but received #{params.class}"
+        end
+      end
+    end
+  end
+end

data/lib/wicked/pipeline/engine.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "action_controller"
+
+module Wicked
+  module Pipeline
+    class Engine < ::Rails::Engine
+      isolate_namespace Wicked::Pipeline
+
+      def self.i18n_scope
+        @i18n_scope ||= name.split("::").tap(&:pop).map(&:underscore).join(".")
+      end
+
+      config.generators do |g|
+        g.helper false
+      end
+
+      initializer :i18n_load_path do |app|
+        ActiveSupport.on_load(:i18n) do
+          # Prepend the engine i18n load path so that translations can be overriden in the main app
+          engine_i18n_load_path = Dir[Engine.root.join("config", "locales", "**", "wicked", "pipeline", "**", "*.yml").to_s]
+          app.config.i18n.load_path = engine_i18n_load_path.concat(app.config.i18n.load_path)
+        end
+      end
+    end
+  end
+end

data/lib/wicked/pipeline/readonly_step.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Wicked
+  module Pipeline
+    class ReadonlyStep < BaseStep
+      # @return true
+      def readonly?
+        true
+      end
+
+      # @return false
+      def blocking?
+        false
+      end
+
+      protected
+
+      def permitted_params
+        []
+      end
+    end
+  end
+end

data/lib/wicked/pipeline/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Wicked
+  module Pipeline
+    VERSION = "0.1.0"
+  end
+end