wicked-pipeline 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 315fc6476825e5f4e336eb28b3951fdc6851902919916547c0a3f046da73c353
+  data.tar.gz: 1af17136066174c31e7bed32aa43e477f1b1bbdc1c1e0775a6eb4d256806ac37
+SHA512:
+  metadata.gz: bd19625bc5ee76db912dc057f8f2425c23e423ca9775253701a45884f3a4c734fc013e8dac350cd40df4a000c9c96f3bf3399991f68975cfada8a277a5b23c4f
+  data.tar.gz: b925b48b9a027cc8cc18b346fe92be23e036c85e44252082768248771daad59b2b98a384eeab631c42d90e598ae31fb1884dca9d38b21cc42e895f9b100aa8ae

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/.standard.yml

@@ -0,0 +1,6 @@
+ruby_version: 2.6
+parallel: true
+format: progress
+
+ignore:
+  - "spec/rails_app/db/schema.rb"

data/.yardopts

@@ -0,0 +1 @@
+--no-private

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+[Unreleased]
+------------
+
+[0.1.0] - 2022-04-15
+--------------------
+
+- Initial release

data/Gemfile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+git_source(:github) { |repo| "https://github.com/#{repo}.git" }
+
+gemspec
+
+gem "rails", ">= 6.1", "< 7"
+gem "rake", "~> 13.0"
+gem "standard", "~> 1.3"
+gem "yard", "~> 0.9"
+
+group :development, :test do
+  gem "rspec-rails", "~> 5.0"
+  gem "sqlite3"
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 Robert Audi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,449 @@
+Wicked::Pipeline
+================
+
+A step by step pipeline is comprised of multiple "blocks" that will be described here:
+
+- Step objects for each step
+- A step pipeline class that encapsulates all the steps in a pipeline
+- A step controller
+
+Table of Contents
+-----------------
+
+- [Installation](#installation)
+- [Step objects](#step-objects)
+  - [Attributes](#attributes)
+  - [Validations](#validations)
+  - [Blocking](#blocking)
+    * [Blocking reason](#blocking-reason)
+- [Step pipelines](#step-pipelines)
+- [Steps controllers](#steps-controllers)
+  - [Routes](#routes)
+  - [Nested routes](#nested-routes)
+  - [Actions](#actions)
+  - [Flash messages](#flash-messages)
+  - [Views](#views)
+  - [Forms](#forms)
+  - [Breadcrumbs](#breadcrumbs)
+
+Installation
+------------
+
+Install the gem and add to the application's Gemfile by executing:
+
+```console
+$ bundle add wicked-pipeline
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```console
+$ gem install wicked-pipeline
+```
+
+Step objects
+------------
+
+A step object is very similar to a form object. It takes a "resource" (the `ActiveRecord` model) and optional params as arguments and will contain attribute definitions, validations for the step, a list of permitted params and a `#save` method. The validations are specific to the step but the resource will also be validated before being saved.
+
+Step objects are subclasses of the `BaseStep` class, and they live in the `app/steps` directory. Here are the rules that must be respected in a step object:
+
+- The name of a step class must end with `Step`
+- Attributes must be defined using the `ActiveModel::Attributes` API (more on that later)
+  * Nested attributes must **not** be defined as attributes in the step object.
+- The class must implement the `permitted_params` method which returns an array of attributes.
+- If the `#save` method is overridden, `super` must be called and its value must be used.
+  * The `#save` method **must** return a boolean value.
+
+The only method that needs to be implemented is the `permitted_params` private method, everything else is optional. Here is the most basic step object that can exist:
+
+```ruby
+module Users
+  class ProfileStep < ::BaseStep
+    private
+
+    def permitted_params
+      []
+    end
+  end
+end
+```
+
+That's it!
+
+As mentioned before, step objects require a resource:
+
+```ruby
+Users::ProfileStep.new(User.last)
+```
+
+### Attributes
+
+The attributes of a step object are defined using the `.attribute` method. The first argument is the name of the attribute, and the second argument is the type of the attribute. The type argument is optional but it **must** be specified for boolean attributes.
+
+To define a String attributes as an Array, the second argument must be `array: true` and the `:string` type **must not** be specified.
+
+```ruby
+module Users
+  class ProfileStep < ::BaseStep
+    attribute :email
+    attribute :first_name
+    attribute :last_name
+    attribute :is_us_citizen, :boolean
+    attribute :investment_goals, array: true
+
+    private
+
+    def permitted_params
+      %i[email first_name last_name is_us_citizen investment_goals]
+    end
+  end
+end
+```
+
+The attributes **must** be in the list of permitted parameters!
+
+### Validations
+
+Validations are used the same way as in `ActiveRecord` models. One exception is the uniqueness validation which is **not** available in step objects.
+
+_Hint: A custom validation method must be used for uniqueness validations, but usually uniqueness validations should be defined in the model._
+
+```ruby
+module Users
+  class ProfileStep < ::BaseStep
+    # ...
+
+    validates_presence_of :email, :first_name, :last_name
+    validates :is_us_citizen, inclusion: { in: [true, false] }
+    validate :full_name_must_not_be_too_long
+
+    private
+
+    def full_name_must_not_be_too_long
+      unless "#{first_name} #{last_name}".length <= 255
+        errors.add(:base, :too_long, count: 255)
+      end
+    end
+
+    # ...
+  end
+end
+```
+
+Custom validation errors must be added to the step object **not** the resource itself, they will be merged into the resource's errors automatically.
+
+### Blocking
+
+A blocking step will short-circuit a pipeline. In other words, all step following a blocking step will be inaccessible.
+
+A step can be marked as "blocking" by overriding the `blocking?` predicate method:
+
+```ruby
+module Users
+  class ProfileStep < ::BaseStep
+    attribute :first_name
+    attribute :is_us_citizen, :boolean
+
+    def blocking?
+      first_name == "John" || is_us_citizen
+    end
+
+    # ...
+  end
+end
+```
+
+Since the `blocking?` method is a predicate method, it **must** return a boolean value.
+
+#### Blocking reason
+
+To specify a reason why the step is marked as blocking, the `blocking_reason` method should be overridden:
+
+```ruby
+module Users
+  class ProfileStep < ::BaseStep
+    attribute :first_name
+    attribute :is_us_citizen, :boolean
+
+    def blocking?
+      first_name == "John" || is_us_citizen
+    end
+
+    def blocking_reason
+      return nil unless blocking?
+
+      if first_name == "John"
+        "Too cool for school"
+      elsif is_us_citizen
+        "Vive la France"
+      end
+    end
+
+    # ...
+  end
+end
+```
+
+Step pipelines
+--------------
+
+A step pipeline class is a subclass of the `BasePipeline` class and live in `app/steps`. At the most basic level should contain a list of step classes.
+
+**Note:** Step pipeline should only be used with step objects!
+
+```ruby
+class UserAccountPipeline < BasePipeline
+  def steps
+    [
+      User::ProfileStep,
+      User::BankingInfoStep,
+      User::ObjectivesStep
+    ]
+  end
+end
+```
+
+The order of the steps will be used in the controller/views, so it's easy to reorder steps at any time.
+
+Steps metadata can be accessed using the pipeline. This includes the name of a step, whether or not it is valid and whether or not it is accessible:
+
+```ruby
+UserAccountPipeline.metadata(User.last)
+#=> {
+#     profile: { valid: true, accessible: true },
+#     banking_info: { valid: false, accessible: true },
+#     objectives: { valid: false, accessible: false }
+#   }
+```
+
+A step is accessible if the previous step is valid and accessible. The first step is always accessible.
+
+Finally, pipelines are also used to check if all steps are valid for a given resource:
+
+```ruby
+UserAccountPipeline.valid?(User.last)
+```
+
+Steps controllers
+-----------------
+
+A steps controller is a subclass of `BaseStepsController`, it can have any name and can be placed anywhere under the `app/controllers` directory. Unlike a regular controller, the `:id` parameter references the current step **not** the ID of a resource. For this reason, the name of the resource ID parameter must be specified using the `#resource_param_name` private method.
+
+Steps controllers **must** implement the following private methods:
+
+- `#resource_param_name`: This method must return the name of the resource ID parameter (eg: `:user_id`).
+- `#steps_pipeline`: This method must return the pipeline class that will be used in the steps controller (eg: `UserAccountPipeline`)
+- `#find_resource`: This method takes care of finding the resource object from the database.
+
+```ruby
+class UsersController < BaseStepsController
+  # ...
+
+  private
+
+  def resource_param_name
+    :user_id
+  end
+
+  def steps_pipeline
+    UserAccountPipeline
+  end
+
+  def find_resource
+    User.find(params[resource_param_name])
+  end
+end
+```
+
+**Rules to follow**
+
+- The `#find_resource` method **must not** set any instance variables.
+- The `#find_resource` method must only retrieve the record associated with the resource ID (`#includes` is allowed), **not** a collection of records.
+- The `#find_resource` method must return the record.
+
+### Routes
+
+The `param` option must be specified when defining resource routes:
+
+```ruby
+resources :users, only: [:show, :update], param: :user_id
+```
+
+**DO NOT** use nested routes with the step routes.
+
+### Nested routes
+
+When the controller has an `index` action, nested routes can be defined in the following way:
+
+```ruby
+resources :users, only: [:show, :update], param: :user_id
+
+resources :users, only: [:index] do
+  resources :profiles
+end
+```
+
+When the controller doesn't have an `index` action, nested routes should be defined in the following way instead:
+
+```ruby
+resources :users, only: [:show, :update], param: :user_id
+
+scope path: "users/:user_id" do
+  resources :profiles
+end
+```
+
+### Actions
+
+A step controller has the `show` and `update` actions. **It cannot have the `new`, `edit` and `create` actions!** The `index` and `destroy` actions can be implemented but they will be independent of the pipeline.
+
+Both action must call `super` with a block and set the `@step_processor` instance variable inside of that block:
+
+```ruby
+class UsersController < BaseStepsController
+  def show
+    super do
+      @user = find_resource
+      @step_processor = step_class.new(@user)
+    end
+  end
+
+  def update
+    super do
+      @user = find_resource
+      @step_processor = step_class.new(@user, params.require(:user))
+    end
+  end
+
+  # ...
+end
+```
+
+**Notes:**
+
+- The `step_class` method returns the step object class associated with the current step.
+- Other instance variables can be set before calling `super` or inside the block.
+
+**Rules to follow:**
+
+- **DO NOT** implement the `new`, `edit` or `create` actions.
+- **Always** call `super` with a block in the `show` and `update` actions.
+- **Always** set the `@step_processor` instance variable inside the `super` block.
+- **DO NOT** call `#save` manually, this will be done automatically.
+- **DO NOT** set the the following instance variable:
+  - `@step`
+  - `@next_step`
+  - `@previous_step`
+
+### Flash messages
+
+Flash messages can be set manually **after** calling `super`. Step objects have a `#saved?` method which can be used to verify that it was successfully saved. The method should be used before setting a flash messages:
+
+```ruby
+class UsersController < BaseStepsController
+  # ...
+
+  def update
+    super do
+      @user = find_resource
+      @step_processor = step_class.new(@user, params.require(:user))
+    end
+
+    if @step_processor.saved?
+      flash[:success] = t(".success")
+    end
+  end
+
+  # ...
+end
+```
+
+### Views
+
+There must be a view for each step, **not** a partial, it must have the name of the step and it should live in the root directory of the controller's view directory:
+
+```
+app
+└── views/
+    └── users/
+        ├── banking_info.html.erb
+        ├── objectives.html.erb
+        └── profile.html.erb
+```
+
+**Rules to follow**
+
+- **DO NOT** create a view for the `show` action.
+- **DO NOT** create views named `new` or `edit`.
+
+### Forms
+
+The form in step view must be declared in the following way:
+
+```erb
+<%= form_for @user, url: step_path, method: :patch do |f| %>
+  <% # ... %>
+<% end %>
+```
+
+**Notes**
+
+- The `step_path` method refers to the path of the current step. It can also be used to get the path of a specific step:
+
+  ```ruby
+    step_path(step_name: "objectives")
+  ```
+
+**Rules to follow**
+
+- The resource object must be passed to `form_for`, **not** the step processor
+- The form's method must be either `:put` or `:patch`
+
+### Breadcrumbs
+
+Step controllers provide a extended version of their pipeline's steps metadata with the following added info:
+
+- `:url`: The URL of a step
+- `:active`: Whether or not a step is currently active
+
+This information is made to be used to build breadcrumbs. Here is a basic way to use steps metadata to build breadcrumbs:
+
+```erb
+<nav aria-label="breadcrumb" class="p-0">
+  <ol class="breadcrumb p-0">
+    <% steps_metadata.each do |step_name, step_metadata| %>
+      <li class="<%= "active-step" if step_metadata[:active] %> <%= "user-#{step_name.dasherize}-step" %> py-2 px-4">
+        <% if step_metadata[:accessible] %>
+          <%= link_to step_metadata[:url] do %>
+            <i class="far <%= step_metadata[:valid] ? "fa-check-square" : "fa-square" %> mr-1"></i>
+            <%== t ".#{step_name}" %>
+          <% end %>
+        <% else %>
+          <span>
+            <i class="far fa-square mr-1"></i>
+            <%== t ".#{step_name}" %>
+          </span>
+        <% end %>
+      </li>
+    <% end %>
+  </ol>
+</nav>
+```
+
+Development
+-----------
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+Contributing
+------------
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/RobertAudi/wicked-pipeline.
+
+License
+-------
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "standard/rake"
+require "yard"
+
+RSpec::Core::RakeTask.new(:spec)
+
+YARD::Rake::YardocTask.new do |t|
+  t.files = ["lib/**/*.rb"]
+end
+
+task default: [:standard, :spec]