class-action 0.0.1

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in class-action.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Joost Lubach
+
+MIT License
+
+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,168 @@
+# ClassAction
+
+This gem allows you to write controller actions as classes rather than methods. This is particularly useful for those actions that are too complex, and may require a lot of support methods.
+
+Within your action class, you may access controller methods, and you can access assignment instance variables.
+
+Additional benefits include:
+
+* Action-specific helper methods
+* Support for responders (future support)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'class-action'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install class-action
+
+## Usage
+
+### Setting up your controller
+
+In your controller, make sure you have included `ClassAction`, and declare which class actions you wish to use.
+
+    class PostsController
+      include ClassAction
+
+      class_action :show
+    end
+
+### Create an action
+
+Then, create your `show` action class (the default is to name this class `PostsController::Show`, but you may customize this).
+
+All *public* methods are executed in order when the action is run. Any support methods you need, you will need to make protected. You may also declare that you need some controller methods.
+
+Some default controller methods (`params`, `request`, `render`, `redirect_to`, `respond_to` and `respond_with`) are available at all times.
+
+    class PostController
+      class Show < ClassAction::Action
+
+        # We need this method from the controller.
+        controller_method :current_user
+
+        def prepare
+          load_post
+        end
+
+        def update_timestamp
+          @post.last_read_at = DateTime.now
+          @post.last_read_by = current_user
+        end
+
+        def render
+          respond_to do |format|
+            format.html { render @post }
+            format.json { render json: @post }
+          end
+        end
+
+        protected
+
+          # Note - this method is not executed by ClassAction. It is meant as
+          # support action.
+          def load_post
+            @post = Post.find(params[:id])
+          end
+
+          # Declare a helper method - this helper method is only available for
+          # this action.
+          def current_section
+            params[:section] || @post.sections.first
+          end
+          helper_method :current_section
+
+      end
+    end
+
+Note that any of your execution methods may call `render` or `redirect`. The execution of the action will stop after any method if it uses these methods (or more formally, when the response body in the controller is set). This removes the need for complex control-flow in your action.
+
+    class Show < ClassAction::Action
+
+      def check_security
+        redirect_to root_path unless authorized?
+      end
+
+      def only_performed_if_authorized
+        render :show
+      end
+
+      protected
+
+      def authorized?
+        # Custom logic for this action, perhaps?
+      end
+
+    end
+
+### Responses
+
+You can run an action fine like above, where you use `respond_to` or `respond_with` (or even just `render`/`redirect_to`) from within any execution method.
+
+However, `ClassAction` provides a bit more support for responses. You may define any responders directly in the action:
+
+    class Show < ClassAction::Action
+
+      respond_to :html do
+        render :show
+      end
+      respond_to :json do
+        render :json => @post
+      end
+
+    end
+
+This employs the use of `ActionController#respond_to`. Additionally, there is support for the Rails 3 style `respond_with`. To illustrate, this:
+
+    class Show < ClassAction::Action
+
+      controller_method :post
+
+      respond_with :post
+      respond_to :html, :json
+
+      respond_to :text do
+        render :text => @post.to_yaml
+      end
+
+    end
+
+is roughly equivalent to:
+
+    class PostsController < ActionController::Base
+
+      respond_to :html, :json, :text, :only => [ :show ]
+
+      def show
+        respond_with post do |format|
+          format.text do
+            render :text => @post.to_yaml
+          end
+        end
+      end
+
+    end
+
+In other words, using `respond_with` in conjunction with `respond_to` allows you to:
+
+1. Specify which method to use to obtain the response object (the first argument to `ActionController#respond_with`). Note that this method must exist on the action, or must be exposed using `controller_method`.
+2. Specify the formats that this action responds to. `ClassAction` will make sure that the controller mime types are modified accordingly.
+3. Create a custom responder block in one breath.
+
+The only caveat is that you have to specify all your controller-level `respond_to` declarations *before* defining your actions using `class_action`, or you might override the `respond_to` array of your controller.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/class-action.gemspec

@@ -0,0 +1,27 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'class_action/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "class-action"
+  spec.version       = ClassAction::VERSION
+  spec.authors       = ["Joost Lubach"]
+  spec.email         = ["joost@yoazt.com"]
+  spec.description   = %q{Allows you to write controller actions as classes, rather than methods.}
+  spec.summary       = spec.description
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency 'activesupport', '~> 3.2'
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec", "~> 2.14"
+  spec.add_development_dependency "actionpack", "~> 3.2"
+end

data/lib/class-action.rb

@@ -0,0 +1,2 @@
+# File provided as the gem is called 'class-action'.
+require 'class_action'

data/lib/class_action/action.rb

@@ -0,0 +1,178 @@
+module ClassAction
+
+  # Base class for controller actions.
+  class Action
+
+    ######
+    # Initialization
+
+      def initialize(controller)
+        @_controller = controller
+      end
+
+    ######
+    # Attributes
+
+      attr_internal_reader :controller
+
+      def available?
+        true
+      end
+      protected :controller, :available?
+
+    ######
+    # Controller method exposure
+
+      class << self
+
+        # Exposes the given controller methods into the action.
+        def controller_method(*methods, sync_assigns: true)
+          if sync_assigns
+            assigns_copy_to   = "copy_assigns_to_controller"
+            assigns_copy_from = "copy_assigns_from_controller"
+          end
+
+          methods.each do |method|
+            class_eval <<-RUBY, __FILE__, __LINE__+1
+              def #{method}(*args, &block)
+                #{assigns_copy_to}
+                controller.send :#{method}, *args, &block
+              ensure
+                #{assigns_copy_from}
+              end
+              protected :#{method}
+            RUBY
+          end
+        end
+
+        def action_methods
+          methods  = public_instance_methods
+          methods -= [ :_execute ]
+          methods -= Object.public_instance_methods
+          methods
+        end
+
+      end
+
+      controller_method :params, :request, :format, sync_assigns: false
+      controller_method :render, :redirect_to, :respond_to, :respond_with
+
+    ######
+    # Helper methods
+
+      class << self
+
+        attr_accessor :helpers
+
+        def inherited(klass)
+          klass.helpers = Module.new
+        end
+
+        def helper_method(*methods)
+          methods.each do |method|
+            helpers.class_eval <<-RUBY, __FILE__, __LINE__+1
+              def #{method}(*args, &block)
+                controller.class_action.send(:#{method}, *args, &block)
+              end
+            RUBY
+          end
+        end
+
+      end
+
+    ######
+    # Execution
+
+      def _execute
+        raise ActionNotAvailable unless available?
+
+        # Execute the action by running all public methods in order.
+        self.class.action_methods.each do |method|
+          send method
+
+          # Break execution of the action when some response body is set.
+          # E.g. when the action decides to redirect halfway.
+          break if controller.response_body
+        end
+
+        # Perform a default response if not done so yet.
+        _respond unless controller.response_body
+      end
+
+      private
+
+      def _respond
+        copy_assigns_to_controller
+
+        if self.class.respond_with_method
+          response_object = send(self.class.respond_with_method)
+          controller.respond_with response_object, &_respond_block
+        elsif _respond_block
+          controller.respond_to &_respond_block
+        end
+      end
+
+      def _respond_block
+        responders = self.class.responders
+        return if responders.none? { |format, block| !!block }
+
+        action = self
+        proc do |collector|
+          responders.each do |format, block|
+            next unless block
+            collector.send(format) do
+              action.instance_exec &block
+            end
+          end
+        end
+      end
+
+
+    ######
+    # Responding
+
+      class << self
+
+        attr_accessor :respond_with_method
+        def responders
+          @reponders ||= {}
+        end
+
+        def respond_with(method)
+          self.respond_with_method = method
+        end
+
+        def respond_to(*formats, &block)
+          formats.each do |format|
+            responders[format.to_sym] = block
+          end
+        end
+
+        def respond_to_any(&block)
+          respond_to :any, &block
+        end
+
+      end
+
+    ######
+    # Assigns
+
+      private
+
+      def copy_assigns_from_controller
+        controller.view_assigns.each do |key, value|
+          instance_variable_set "@#{key}", value
+        end
+      end
+
+      def copy_assigns_to_controller
+        ivars  = instance_variables
+        ivars -= [ :@_controller, :@_responders, :@_default_responder ]
+        ivars.each do |ivar|
+          controller.instance_variable_set ivar, instance_variable_get(ivar)
+        end
+      end
+
+  end
+
+end

data/lib/class_action/version.rb

@@ -0,0 +1,3 @@
+module ClassAction
+  VERSION = "0.0.1"
+end

data/lib/class_action.rb

@@ -0,0 +1,105 @@
+require 'active_support/inflector'
+
+module ClassAction
+
+  class ActionNotAvailable < RuntimeError
+  end
+
+  class << self
+    def included(target)
+      target.extend ClassMethods
+      setup target
+    end
+
+    def setup(target)
+      target.class_eval <<-RUBY, __FILE__, __LINE__+1
+        def class_action
+          @_class_action
+        end
+      RUBY
+    end
+  end
+
+  module ClassMethods
+
+    def class_action(*actions, klass: nil)
+      actions.each do |action|
+        action_class = klass || const_get(action.to_s.camelize)
+        raise ArgumentError, "ClassAction does not support anonymous classes" if action_class.name.nil?
+
+        class_eval <<-RUBY, __FILE__, __LINE__+1
+          def #{action}
+            _execute_class_action :#{action}, #{action_class.name}
+          end
+        RUBY
+
+        inject_class_action_mimes action.to_s, action_class
+      end
+    end
+
+    private
+
+    # Injects the mimes (formats) that the action responds to into the controller
+    # mimes_for_respond_to hash.
+    def inject_class_action_mimes(action, klass)
+      # If no responders or a default responder is given, we don't do anything.
+      return if klass.responders.empty? || klass.responders.has_key?(:any)
+
+      mimes = mimes_for_respond_to.dup
+
+      # Make sure no extra mimes are allowed for the action.
+      mimes.each do |mime, restrictions|
+        next if klass.responders.key?(mime)
+        exclude_class_action_in_mime_type mime, restrictions, action
+      end
+
+      # Include all action mimes.
+      klass.responders.each do |mime, _block|
+        mimes[mime] ||= { :only => [] }
+        include_class_action_in_mime_type mime, mimes[mime], action
+      end
+
+      self.mimes_for_respond_to = mimes
+    end
+
+    def include_class_action_in_mime_type(mime, restrictions, action)
+      if restrictions && restrictions[:except] && restrictions[:except].include?(action)
+        logger.warn "Warning: action #{action} (ClassAction) responds to `#{mime}` but it does not accept this mime type"
+      elsif restrictions && restrictions[:only] && !restrictions[:only].include?(action)
+        restrictions[:only] << action
+      end
+    end
+
+    def exclude_class_action_in_mime_type(mime, restrictions, action)
+      restrictions[:except] ||= []
+      restrictions[:except] << action if !restrictions[:except].include?(action)
+    end
+
+  end
+
+  def view_context
+    view_context = super
+
+    if class_action
+      # Extend the current view context with the action helpers.
+      view_context.singleton_class.send :include, class_action.class.helpers
+    end
+
+    view_context
+  end
+
+  private
+
+  def _execute_class_action(name, klass)
+    @_class_action = klass.new(self)
+    @_class_action._execute
+  end
+
+end
+
+if defined?(AbstractController::Rendering::DEFAULT_PROTECTED_INSTANCE_VARIABLES)
+  AbstractController::Rendering::DEFAULT_PROTECTED_INSTANCE_VARIABLES << '@_class_action'
+end
+
+require 'class_action/version'
+require 'class_action/action'