context-pattern 1.0.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 160ec1333c94272d332b55acccaee5b32435a2d6
-  data.tar.gz: 96a764e13dec3cad58a5e43639f59946daf63bb2
+  metadata.gz: f9fcef9a074a4fcc09344918329dc47c42a766a0
+  data.tar.gz: 5f067d37cd45e1f921e24f1e3852e139f85f8011
 SHA512:
-  metadata.gz: ae92a3e686f0164548e11d882c4e19bec842ed29198a62b432e0868524e95b719aee3125e152e17e91cf20758aec29d7f448cc9fde994ecf22d56195f123b7a2
-  data.tar.gz: 7d2f947aaf3a9e3a4ca66de889e0a78e597e2df35824acb1da4cf34acf71ac229aef9b62d3345fb8bc1a443a1013f25009fd5bd911256ac6670a4a08186c17a9
+  metadata.gz: 5e0818e724627fccb128a91984d6281314101af23378eb138d40467d6be401fabdf450bc90b86c33c271af0d2c703e7d160968c355ab9526a9807ee4e6416c95
+  data.tar.gz: cc29966bdc2088c8d7dd4ec7e22ccc72002b020174c40713f13b26573f8da7837a53e2ebef80fbec3baabdb8ba4db4c4d6f3edf80dfe8d3b8d6960f8e1821595

data/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+## [1.1.1]
+* Fix naming bug in BaseContextHelper
+
+## [1.1.0]
+* Add method_missing logic to Context::Controller, so that controllers can
+  easily access public methods in the context chain
+* Add BaseContextHelper module, which is used to provide views access to
+  view_helpers defined in the context chain
+* Fix gem dependencies in this gemfile
+* Add README file
+* Add this changelog
+
+## [1.0.0]
+* Prevent contexts from overriding public methods already available in the
+  context chain
+
+## [0.2.0]
+* Add specs for BaseContext
+* Add the introspection methods to BaseContext:
+  #context_chain_class, #context_method_mapping, and #whereis
+* Add BaseContext.decorate interface
+
+## [0.1.0]
+* Initial code ported from the WegoWise app

data/Gemfile

@@ -1,12 +1,2 @@
 source 'https://rubygems.org'
 gemspec
-
-# The AR environment variable lets you test against different
-# versions of Rails. For example:
-#
-#  AR=3.2.13 rm Gemfile.lock && bundle install && bundle exec rspec
-#  AR=4.0.0  rm Gemfile.lock && bundle install && bundle exec rspec
-#
-if ENV['AR']
-  gem 'activerecord', ENV['AR']
-end

data/README.md

@@ -1 +1,193 @@
-# context-pattern
+# Context pattern
+
+This gem gives you the scaffolding needed to easily use the Context Pattern in
+your Ruby on Rails application
+
+## What is the context pattern?
+
+The context pattern provides a way of thinking about and writing Rails
+applications that results in better code that is easier to maintain. This is
+done through the introduction of a new category of object known as a Context
+Object.
+
+A Context Object is responsible for interpreting the current state of the
+request, providing the context for a controller to do its work, and defining an
+interface that may be referenced by views. Every request has exactly one
+context object associated with it. This context is built up throughout the life
+cycle of a request.
+
+If you have never encountered the context pattern before, you should read
+[the explanatory blog post](http://barunsingh.com/2018/03/04/context_pattern.html)
+to get a thorough understanding of the motivations behind and benefits of this
+code pattern, examples of before and after code, and a thorough explanation of
+how everything works.
+
+This README is intended to provide a reference for those who are already
+somewhat familiar with the context pattern.
+
+## Setting up the gem
+
+To use this gem, you need to do two things:
+
+1. Require it in your Gemfile:
+   ```ruby
+   gem 'context-pattern'
+   ```
+
+2. Add the following two lines to your `ApplicationController`:
+   ```ruby
+   include Context::Controller
+   helper Context::BaseContextHelper
+   ```
+
+## Simple example
+
+The example below is a simple one that is used to demonstrate various facets
+of how this gem and the context pattern work. Suppose we have an online
+bookstore and are looking at a `BooksController#show` action. We want to
+retrieve the logged in user from the session and the book being viewed from the
+params. We use a decorator to provide some functionality around showing the
+user's name (this is contrived, but demonstrative).
+
+```ruby
+class ApplicationController < ActionController::Base
+  include Context::Controller
+  helper Context::BaseContextHelper
+
+  before_action :set_application_context
+
+  def set_application_context
+    extend_context :Application, params: params, session: session
+  end
+end
+
+class BooksController < ApplicationController
+  def show
+    extend_context :BookShow
+  end
+end
+
+class ApplicationContext < Context::BaseContext
+  view_helpers :current_user
+
+  attr_accessor :session, :params
+
+  def current_user
+    User.find_by(id: session[:user_id])
+  end
+  memoize :current_user
+end
+
+class BookShowContext < Context::BaseContext
+  view_helpers :book
+
+  decorate :current_user, decorator: UserPresenter, memoize: true
+
+  def book
+    Book.find(params[:id])
+  end
+  memoize :book
+end
+
+class UserPresenter < SimpleDelegator
+  def abbreviated_name
+    "#{first_name} #{last_name[0]}"
+  end
+end
+```
+
+View file:
+```erb
+Hi, <%= current_user.abbreviated_name %>.
+Here is information about <%= book.title %>
+```
+
+## Basic components of using the gem
+
+* All context classes must inherit from `Context::BaseContext`
+* To add a context to the context stack, use `extend_context`. Usage example:
+  ```ruby
+  extend_context :Foo, arg1: 1, arg2: 2
+  # The above is equivalent to adding the following object to the context stack:
+  #   FooContext.new(arg1: 1, arg2: 2)
+  ```
+* If you want to be able to provide arguments when initializing a context as
+  in the example above, your context class needs to use `attr_accessor` to
+  declare those attribute names.
+* A context object has access to all public methods already defined in the
+  context stack. It does not have access to any non-public methods used by
+  other objects in the context stack.
+* The order in which you add to the context stack is important. While a context
+  object can reference public methods from earlier in the context stack, it can
+  not make reference to public methods from objects added later to the context
+  stack.
+* Controllers have access to all public methods defined anywhere in the context
+  stack.
+* Views have access to all public methods in the context stack that are declared
+  to be `view_helpers`.
+* Methods do not necessarily need to be defined in the same context in which
+  they are declarated to be `view_helpers`. But a method must be available to
+  the context in which it is declared to be a view helper. This means the method
+  must either be defined in that context or in a context that is already part
+  of the context stack at the time.
+* A context can not overwrite a public method that is already defined in the
+  context stack. Trying to do so will cause a `Context::MethodOverrideError`
+  exception to be raised.
+* The `decorate` declaration provides a way to get around the above restriction
+  in situations where we reasonably wish to decorate or present an object
+  already available in the context stack. This declaration may be used as
+  follows:
+  ```ruby
+  class BlahContext < Context::BaseContext
+    # Suppose `foo` is a public method already available in the context stack
+    decorate :foo, decorator: FooDecorator, args: [:bar, :baz], memoize: true
+
+    # The above is functionaly equivalent to the code below:
+    # def foo
+    #   FooDecorator.new(@parent_context.foo, bar: bar, baz: baz)
+    # end
+    # memoize :foo
+
+    def bar; end
+    def baz; end
+  end
+  ```
+* You can reference application routes in your context objects.
+  `Context::BaseContext` includes `Rails.application.routes.url_helpers`. You
+  can also use `link_to` within your contexts.
+
+
+## Best practices for usage
+
+The following suggestions are not requirements for using this gem, but bits of
+advice that have been pulled together from using the context pattern across
+the WegoWise codebase over a period of five years.
+
+* You should have something like an `ApplicationContext` that takes params,
+  session, etc. as arguments on initialization. The example in this README
+  shows a simple version of this. If you do this, all later contexts will have
+  access to the params, which will greatly simplify things.
+* Aside from `ApplicationContext`, you should almost never need to provide any
+  arguments to a context when initializing it via `extend_context`. This means
+  those contexts shouldn't make use of `attr_accessor`. There may be some
+  exceptions, but generally speaking a context should be able to figure out
+  everything it needs from `params` and methods already available via the
+  context stack.
+* If you find yourself wanting to override methods from earlier contexts in
+  ways that do not follow the decorator pattern, this is a sign you are not
+  thinking about your code properly. Sometimes this may simply be a matter of
+  having different method names for different concepts, Other times it may mean
+  that your contexts are conceptually ambiguous.
+* It is a best practice to add a comment at the top of each context file stating
+  in plain language what the context is for the usage of that object. This
+  should not need to be more than a couple short sentences. If you are having
+  difficulty doing this, it may be a sign that you are trying to do too much
+  within a single context object.
+* `memoize` is made available via the `memoizer` gem, which is a dependency of
+  this gem. It is a best practice to memoize all view helpers that do any sort
+  of work, and to memoize objects that use the `decorate` declaration.
+
+
+## How to test context objects
+
+To be filled in soon.

data/context-pattern.gemspec

@@ -16,7 +16,7 @@ Gem::Specification.new do |s|
   s.extra_rdoc_files = ["README.md", "LICENSE.txt"]
   s.license = 'MIT'
 
-  s.add_dependency('rails', '>= 3.2', '< 5.2')
+  s.add_dependency('rails', '>= 4.0')
   s.add_dependency('memoizer')
 
   s.add_development_dependency('rspec', '~> 3.0')

data/lib/context-pattern.rb

@@ -1,4 +1,7 @@
-require 'context/base_context'
-require 'context/controller'
+require_relative 'context/base_context'
+require_relative 'context/controller'
 
-require 'context/railtie' if defined?(Rails)
+if defined?(Rails)
+  require_relative 'context/railtie'
+  require_relative 'context/base_context_helper'
+end

data/lib/context/base_context_helper.rb

@@ -0,0 +1,15 @@
+module Context
+  module BaseContextHelper
+    def method_missing(method_name, *args, &block)
+        if @__context && @__context.has_view_helper?(method_name)
+        @__context.public_send(method_name, *args, &block)
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method_name, _include_private = false)
+      @__context.has_view_helper?(method_name)
+    end
+  end
+end

data/lib/context/controller.rb

@@ -6,11 +6,25 @@ module Context
 
     def extend_context(context, **args)
     context_class = "#{context}Context".constantize
-    @context = context_class.wrap(@context, **args)
+    @__context = context_class.wrap(@__context, **args)
     end
 
     def __set_base_context
-      @context = Context::BaseContext.new
+      @__context = Context::BaseContext.new
+    end
+
+    private
+
+    def method_missing(method_name, *args, &block)
+      if @__context.respond_to?(method_name)
+        @__context.public_send(method_name, *args, &block)
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      @__context.respond_to?(method_name, include_private)
     end
   end
 end

data/lib/context/version.rb

@@ -1,3 +1,3 @@
 module Context
-  VERSION = '1.0.0'
+  VERSION = '1.1.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: context-pattern
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Barun Singh
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-02-08 00:00:00.000000000 Z
+date: 2019-03-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -16,20 +16,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '3.2'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '5.2'
+        version: '4.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '3.2'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '5.2'
+        version: '4.0'
 - !ruby/object:Gem::Dependency
   name: memoizer
   requirement: !ruby/object:Gem::Requirement
@@ -81,6 +75,7 @@ extra_rdoc_files:
 - LICENSE.txt
 files:
 - ".gitignore"
+- CHANGELOG.md
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -88,6 +83,7 @@ files:
 - context-pattern.gemspec
 - lib/context-pattern.rb
 - lib/context/base_context.rb
+- lib/context/base_context_helper.rb
 - lib/context/controller.rb
 - lib/context/railtie.rb
 - lib/context/version.rb