controll 0.2.0 → 0.3.0

data/README.md

@@ -1,14 +1,24 @@
 # Controll
 
-Some nice and nifty utilities to help you manage complex controller logic. 
+Some nice and nifty utilities to help you manage complex controller logic.
+
+## Requirements
+
+This gem is designed for Rails 3+ and currently only supports (has been tested with)  Ruby 1.9+. The gem is under development but stable releases will be pushed to rubygems. Note that older versions may not support the same API described in the README. Go back in history and/or browse the code for that specific version.
+
+Enjoy :)
 
 ## Background
 
-This gem contains logic extracted from my `oauth_assist` gem/engine which again was a response to this article [oauth pure tutorial](http://www.communityguides.eu/articles/16).
+This gem contains logic extracted from my [oauth_assist](https://github.com/kristianmandrup/oauth_assist) gem (and engine) which was a response to this article [oauth pure tutorial](http://www.communityguides.eu/articles/16).
+
+Note that the *oauth_assist* gem is not yet fully functional and done, as it "awaits" a stable release of this gem. Please feel free to help out in this effort!
 
 ## Justification
 
-As you can see, the following `#create` REST action is a nightmare of complexity and flow control leading to various different flash messages and redirect/render depending on various outcomes... there MUST be a better way!
+As you can see, the following `#create` REST action is a nightmare of complexity and flow control leading to various different flash messages and redirect/render depending on various outcomes... 
+
+Then I naturally thought: *There MUST be a better way!*
 
 ```ruby
 def create
@@ -77,22 +87,51 @@ end
 Using the tools contained in `controll` the above logic can be encapsulated like this:
 
 ```ruby
-def create    
-  FlowHandler::CreateService.new(self).execute
+class ServicesController < ApplicationController
+  include Controll::Enabler
+
+  def create
+    execute # action.perform
+  end
 end
 ```
 
-A `FlowHandler` can use Executors to encapsulate execution logic, which again can execute Commands that encapsulate business logic related to the user Session or models (data).
+A `Flow` can use Executors to encapsulate execution logic, which again can execute Commands that encapsulate business logic related to the user Session or models (data).
+
+The Flow takes the last event on the event stack and consults the ActionPaths registered, usually a Redirecter and Renderer. An ActionPath is a type of Action which can return a path. The Flow initiates an Executor which iterates the ActionPaths to find the first one which can match the event.
+
+The first one with a match is returned as the Action, which the controller can then perform in order to either render or redirect.
+
+If none of the ActionPaths can match the event, a Fallback Action is returned. The controller should then be configured to handle a Fallback Action appropriately.
 
-The FlowHandler can manage Redirect, Render and Notifications in a standardized, much more Object Oriented fashion, which adheres to the Single Responsibility pattern.
+Controll has built in Notification Management which work both for flash messages (or other types of notifications) and as return codes for use in flow-control logic.
 
-Controll has built in notification management which work both for flash messages (or other types of notifications) and as return codes for use in flow-control logic.
+All events in the event stack are processed and can fx be put on the flash hash according to event type, fx `flash[:error]` for an `:error` event etc.
 
-Using the `controll` helpers, you can avoid the typical Rails anti-pattern of Thick controllers, without bloating your Models with unrelated model logic or pulling in various Helper modules which pollute the space of the Controller anyhow!
+The Notification system works by mapping events to messages in a central location, similar to mapping events to paths.
+
+Using these Controll artifacts/systems, you can avoid the typical Rails anti-pattern of Thick controllers, without bloating your Models with unrelated model logic or pulling in various Helper modules which pollute the space of the Controller!
 
 ## Usage
 
-In your controller include the `Controll::Helper` helper module.
+The recommended approach to handle complex Controller logic using Controll:
+
+* Enable Controll on Controller
+* Configure Controller with Flow, Commander and Notifier
+
+* Create Commands for Commander
+* Define events corresponding to commands
+* Configure Commander with Command methods
+
+* Create Flow
+* Configure Flow with Render and Redirect event mappings
+
+* Create Notifier
+* Configure Notifier with Event handlers and event -> message mappings
+
+## Controll enabling a Controller
+
+In your controller include the `Controll::Enabler` module.
 
 ```ruby
 class ServicesController < ApplicationController
@@ -100,7 +139,7 @@ class ServicesController < ApplicationController
   protect_from_forgery :except => :create
 
   # see 'controll' gem
-  include Controll::Helper
+  include Controll::Enabler
 end
 ```
 
@@ -108,87 +147,159 @@ Better yet, to make it available for all controllers, include it in your Applica
 
 ```ruby
 class ApplicationController
-  include Controll::Helper
+  include Controll::Enabler
 end
 ```
 
-In your Controller you should define a MessageHandler and Commander to be used.
+You can also include the `Controll::Macros` module in a base Controller class of your choosing, fx:
+
+```ruby
+class ApplicationController
+  include Controll::Macros
+end
+```
+
+Then you can use the `#enable_controll` macro in any subclass Controller class:
 
 ```ruby
 class ServicesController < ApplicationController
-  include Controll::Helper
+  enable_controll
+end
+```
+
+## Controll configuration
+
+In your Controller you should define a Notifier and Commander to be used.
+
+```ruby
+class ServicesController < ApplicationController
+  enable_controll
 
   ...
 
   protected
 
-  message_handler :services
+  notifier :services
   commander :services
+
+  # or simply (using naming convention)
+  controll :notifier, :commander
+
+  def create
+    create_action.perform
+  end
+
+  protected
+
+  def create_action
+    @create_action ||= Flows::CreateService.new(self)
+  end
+
+  fallback do |event|
+    event == :no_auth ? render(:text => omniauth.to_yaml) : fallback_action
+  end        
+
+  def fallback_action
+    redirect_to root_url
+  end
 end
 ```
 
-The Commander is where you register a set of related commands, typically for a specific controller.
+### Focused Controller config
+
+In case you use Focused Controller, this can be strutctured even better like this:
 
 ```ruby
-class ServicesCommander < Controll::Commander
+class ServicesController
 
-  # register commands with controller
-  commands :cancel_commit, :create_account, :signout
+  # could be extracted into "global" namespace for reuse across controllers...
+  module ControllAction
+    extend ActiveSupport::Concern
+
+    included do
+      controll :notifier, :commander, :flow
+    end
 
-  def sign_in_command
-    @sign_in_command ||= SignInCommand.new auth_hash: auth_hash, user_id: user_id, service_id: service_id, service_hash: service_hash, initiator: self
+    def fallback_action
+      redirect_to root_url
+    end
   end
 
-  # delegations
-  controller_methods :auth_hash, :user_id, :service_id, :service_hash
+  class Create < FocusedAction
+    include ControllAction
+
+    run do
+      execute
+    end
+
+    protected
+
+    fallback do |event|
+      event == :no_auth ? render(:text => omniauth.to_yaml) : fallback_action
+    end        
+  end
 end
 ```
 
-The `#commands` class macro can be used to create command methods that only take the initiator (in this case the controller) as argument.
+*Wow! Now we're talking!!!!*
 
-For how to implement the commands, see the `imperator` gem, or see the `oauth_assist` engine for a full example.
+## Creating a Commander
 
-We will implement this MessageHandler later when we know which notifications and errors we want to use/issue.
+The Commander is your command center for a group of related commands. Typically you will want to define a Commander for a specific controller if the controller has more than 3 commands. If you put your Commander under the `Commanders` namespace (module) you get direct access to the Commander constant to be used as subclass.
 
-For Controller actions that require complex flow control, use a FlowHandler:
+The Commander should contain a group of command methods that are conceptually in the same "category", fx all the command for a particular controller.
 
 ```ruby
-module Controll::FlowHandler
-  class CreateService < Control
-    protected
+module Commanders
+  class Services < Commander
+    # create basic command methods
+    command_methods :cancel_commit, :create_account, :signout
+
+    # create custom command method with custom argument hash
+    def sign_in_command
+      @sign_in_command ||= SignInCommand.new auth_hash: auth_hash, user_id: user_id, service_id: service_id, service_hash: service_hash, initiator: self
+    end
 
-    # use for more advanced render/redirect logic (fx when using paths with arguments)
-    def use_alternatives      
+    command_method :sign_out do
+      @sign_out_command ||= SignOutCommand.new user_id: user_id, service_id: service_id, service_hash: service_hash, initiator: self
     end
 
-    def use_fallback
-      event == :no_auth ? do_render(:text => omniauth.to_yaml) : fallback_action
-    end      
+    # delegations (alias for initiator_methods )
+    controller_methods :auth_hash, :user_id, :service_id, :service_hash
+  end
+end
+```
 
-    def action_handlers
-      [Redirect, Render]
-    end
+The `Commander class extends `Imperator::Command::MethodFactory` making `#command_method` and `#command_methods` available. These class macros can be used to create command methods that only take the initiator (in this case the controller) as argument.
 
-    def event
-      @event ||= authentication
-    end
+For how to implement the Commands themselves, see the [imperator-ext](https://github.com/kristianmandrup/imperator-ext) gem. 
 
-    def authentication
-      @authentication ||= Authenticator.new(controller).execute
-    end
+## Flows
 
-    class Render < Controll::FlowHandler::Render
-      def self.default_path
-        :signup_services_path
-      end
+For Controller actions that require complex flow control, use a Flow:
 
-      def self.events
-        [:signed_in_new_user]
+```ruby
+module Flows
+  class CreateService < Flow
+
+    # event method that returns the event to be processed by the flow handler
+    event do
+      Executors::Authenticator.new(controller).execute
+    end
+
+    # configuration of the Renderer ActionHandler
+    # will return a Renderer Action if it matches the event
+    renderer :simple do
+      events :signed_in_new_user, :signed_in do
+        signup_services_path
       end
     end
 
-    class Redirect < Controll::FlowHandler::Render
-      def self.redirections
+    # configuration of the Redirecter ActionHandler
+    # will return a Redirecter Action if it matches the event
+    redirecter :complex do
+      # redirection mappings for :notice events
+      event_map :notice do
         {        
           signup_services_path: :signed_in_new_user
           services_path:        [:signed_in_connect, :signed_in_new_connect]
@@ -196,39 +307,56 @@ module Controll::FlowHandler
         }
       end
 
-      def self.error_redirections
-        {
-          signin_path:          [:error, :invalid, :auth_error]
-        }
-      end
+      # redirection mappings for :error events
+      event_map :error, signin_path: [:error, :invalid, :auth_error]
     end  
   end
 end
 ```
 
-In the `Redirect` class we are setting up a mapping for various path, specifying which notifications/event should cause a redirect to that path.
+The `#renderer` and `#redirector` macros will each create a Class of the same name that inherit from Controll::Flow::ActionMapper::Simple or Controll::Flow::ActionMapper::Complex. 
+You can also define these classes directly yourself instead of using the macros.
+The *simple* action mapper maps a list of events to a single path and otherwise falls back.
+The complex action mapper maps the event to an event hash for each registered event type.
 
-If you are rendering or redirecting to paths that take arguments, you can either extend the `#action` class method of your Redirect or Render class implementation or you can define a `#use_alternatives` method in your `FlowHandler` that contains this particular flow logic. You can also use the `#use_fallback` method for this purpose.
+In the `Redirecter` class we are setting up a mapping for various paths, for each path specifying which events should cause a redirect to that path.
 
-## The Authenticator Executor
+If you are rendering or redirecting to paths that take arguments, you can either extend the `#action` class method of your Redirect or Render class implementation or you can define a `#use_alternatives` method in your `Flow` that contains this particular flow logic.
 
-The `Authenticator` inherits from `Executor::Notificator` which uses `#method_missing` in order to delegate any missing method back to the initiator of the Executor, in this case the FlowHandler. The `#result` call at the end of `#execute` ensures that the last notification event is returned, to be used for deciding what to render or where to redirect (see FlowHandler).
+Note: For mapping paths that take arguments, there should be an option to take a block (closure) to be late-evaluated on the controller context ;)
+
+## The Executor
+
+The `Authenticator` class shown below inherits from `Executor::Notificator` which uses `#method_missing` in order to delegate any missing method back to the controller of the Executor. The Flow passed in the controller. This means that calls can be executed directly on the controller, such as making notifications etc.
+
+The `#result` call at the end of `#execute` ensures that the last notification event is returned, to be used for deciding what to render or where to redirect (see Flow).
 
 ```ruby
-module Controll::Executor
-  class Authenticator < Notificator
+module Executors
+  class Authenticator < Controlled
+
+    # ensures pattern:
+    # - perform validations and only execute command if no error
     def execute
-      # creates an error notification named :error
-      error and return unless valid_params?
+      super      
+      result      
+    end
 
-      # creates an error notification named :auth_invalid
-      error(:auth_invalid) and return unless auth_valid?
+    protected
+
+    controller_methods :omniauth, :service, :auth_hash, :auth_valid?
 
+    def do_command
       command! :sign_in
-      result      
     end
 
-    protected
+    def validations
+      # creates an error notification named :error
+      error and return unless valid_params?
+
+      # creates an error notification named :auth_invalid
+      error(:auth_invalid) and return unless auth_valid?
+    end    
 
     def valid_params?
       omniauth and service and auth_hash
@@ -237,25 +365,32 @@ module Controll::Executor
 end
 ```
 
-To encapsulate more complex busines logic affecting the user Session or Model data, we execute an the Imperator Command (see `imperator` gem) called :sign_in that we registered in the Commander of the Controller.
+Alternatively you can use the execute block macro to generate the `#execute` instance method and ensure that it ends by returning result.
+
+```ruby
+execute do
+  # error/validation checks? ...
+  command! :sign_in
+end
+```
+
+To encapsulate more complex busines logic affecting the user Session or Model data, we execute an Imperator Command (see `imperator` gem) called :sign_in that we registered in the Commander of the Controller.
 
 ## Notifier
 
-Now we are finally ready to define the message handler for each notification event we have defined (this should ideally be done as you define each event!).
+Now we are finally ready to define the notifier to handle the different types of notification events.
 
 The example below demonstrates several different ways you can define messages for events: 
 
 * using the `#messages` method to return a hash of mappings. 
-* define a method for the event name that returns a String (w argument replacement)
-* i18n locale mapping [msghandler name].[notification type].[event name].
+* define a method for the event name that returns a String (handles argument replacement)
+* i18n locale mapping `[handler class path].[notification type].[event name]`.
 
 ```ruby
-module Controll::Notify
+module Notifiers
   class Services < Typed
-    class ErrorMsg < Controll::Notify::Base
-      type :error
-
-      def messages
+    handler :error do
+      messages do
         {
           must_sign_in: 'You need to sign in before accessing this page!',
           
@@ -267,35 +402,33 @@ You have not been signed in.},
         }
       end
 
-      def auth_error!
-        'Error while authenticating via ' + service_name + '. The service did not return valid data.'
+      msg :auth_error! do
+        "Error while authenticating via #{service_name}. The service did not return valid data."
       end
 
-      def auth_invalid!
+      msg :auth_invalid! do
         'Error while authenticating via {{full_route}}. The service returned invalid data for the user id.'
       end
     end
 
 
-    class NoticeMsg < Controll::Notify::Base
-      type :notice
-
+    handler :notice do
       # for :signed_in and :signed_out - defined in locale file under:
+      # notifiers:
+      #   services:
+      #     notice:
+      #       signed_in:  'Your account has been created and you have been signed in!'
+      #       signed_out: 'You have been signed out!'
 
-      # services:
-      #   notice:
-      #     signed_in:  'Your account has been created and you have been signed in!'
-      #     signed_out: 'You have been signed out!'
-
-      def already_connected
+      msg :already_connected do
         'Your account at {{provider_name}} is already connected with this site.'
       end
 
-      def account_added
+      msg :account_added do
         'Your {{provider_name}} account has been added for signing in at this site.'
       end
 
-      def sign_in_success
+      msg :sign_in_success do
         'Signed in successfully via {{provider_name}}.'
       end
     end
@@ -303,6 +436,33 @@ You have not been signed in.},
 end
 ```
 
+## Rails Generators
+
+### Setup generator
+
+`$ rails g controll:setup`
+
+Generate only specific controll folders
+
+`$ rails g controll:setup commanders notifiers`
+
+### Controll artifact generators
+
+* assistant
+* executor
+* flow
+* notifier
+
+Example usage:
+
+`$ rails g controll:flow create_service`
+
+Use `-h` for help on any specific controller for more usage options and info.
+
+## Notice
+
+Due to a lot of recent API changes in order to simplify and improve usage, the README docs for the API might potentially contain a few inconsistencies with the code. Please notify me if you spot one. Thanks. See the specs and/or code in order to see the real API in this case.
+
 ## Contributing to controll
  
 * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
@@ -313,7 +473,7 @@ end
 * Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
 * Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
 
-== Copyright
+## Copyright
 
 Copyright (c) 2012 Kristian Mandrup. See LICENSE.txt for
 further details.

data/Rakefile

@@ -18,7 +18,7 @@ Jeweler::Tasks.new do |gem|
   gem.homepage = "http://github.com/kristianmandrup/controll"
   gem.license = "MIT"
   gem.summary = %Q{Utils for handling complex Controller/Business logic}
-  gem.description = %Q{FlowHandler, Executor, Notifier and more, all tied together tool pack}
+  gem.description = %Q{Flow, Executor, Notifier and more, all tied together tool pack}
   gem.email = "kmandrup@gmail.com"
   gem.authors = ["Kristian Mandrup"]
   # dependencies defined in Gemfile

data/VERSION

@@ -1 +1 @@
-0.2.0
+0.3.0