reactive-mvc 0.2.0

data/lib/reactive-mvc/controller/output.rb

@@ -0,0 +1,262 @@
+module Reactive::Mvc::Controller #:nodoc:
+  class InvalidOption < Error
+  end
+
+  module Output #:nodoc:
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.class_eval { include InstanceMethods }
+    end
+
+    # output :pdf, :show => {:treatment => 'print', :handler => 'system_viewer'}
+    # output :pdf, :show => 'print'  # same as above but without the handler (the available handler will be used (like nil in :handler))
+    # output :pdf, :treatment => 'print', :handler => 'system_viewer'    # all actions will have this settings (like :all => {})
+    # output :pdf, 'print'    # all actions will have this settings (with a nil handler) (like :all => :print}
+    
+    # output :pdf, [:show, :index, :new] => {:treatment => 'print', :handler => 'system_viewer'}, :delete => 'display'
+    # output :pdf, :all => {:treatment => 'print', :handler => 'system_viewer'}, :delete => 'display' # acts like all but delete (a bit like except for layout)
+    # output :pdf, :all => false, :delete => 'display' # acts like all: disable handling but delete
+    # output :pdf, :all => {:treatment => 'print', :handler => 'system_viewer'}, :delete => :depends # delete will call a method on the controller named depends that have to return the options
+
+    # By default, the settings are inherited from the parent controller, thus settings like: "output :pdf, :delete => :display" will only override the settings
+    # for delete. If you specify "output :pdf, :all => :print" it will override what was inherited.
+    
+    # There may be several "output" statement per format but it is not recommended. If you do, the statment will be applied in the order they appear, so a last statement
+    # with :all => {} will simply override any previous ones, beware!
+
+    # Layouts reverse the common pattern of including shared headers and footers in many templates to isolate changes in
+    # repeated setups. The inclusion pattern has pages that look like this:
+    #
+    #   <%= render "shared/header" %>
+    #   Hello World
+    #   <%= render "shared/footer" %>
+    #
+    # This approach is a decent way of keeping common structures isolated from the changing content, but it's verbose
+    # and if you ever want to change the structure of these two includes, you'll have to change all the templates.
+    #
+    # With layouts, you can flip it around and have the common structure know where to insert changing content. This means
+    # that the header and footer are only mentioned in one place, like this:
+    #
+    #   // The header part of this layout
+    #   <%= yield %>
+    #   // The footer part of this layout -->
+    #
+    # And then you have content pages that look like this:
+    #
+    #    hello world
+    #
+    # Not a word about common structures. At rendering time, the content page is computed and then inserted in the layout, 
+    # like this:
+    #
+    #   // The header part of this layout
+    #   hello world
+    #   // The footer part of this layout -->
+    #
+    # == Accessing shared variables
+    #
+    # Layouts have access to variables specified in the content pages and vice versa. This allows you to have layouts with
+    # references that won't materialize before rendering time:
+    #
+    #   <h1><%= @page_title %></h1>
+    #   <%= yield %>
+    #
+    # ...and content pages that fulfill these references _at_ rendering time:
+    #
+    #    <% @page_title = "Welcome" %>
+    #    Off-world colonies offers you a chance to start a new life
+    #
+    # The result after rendering is:
+    #
+    #   <h1>Welcome</h1>
+    #   Off-world colonies offers you a chance to start a new life
+    #
+    # == Automatic layout assignment
+    #
+    # If there is a template in <tt>app/views/layouts/</tt> with the same name as the current controller then it will be automatically
+    # set as that controller's layout nless explicitly told otherwise. Say you have a WeblogController, for example. If a template named 
+    # <tt>app/views/layouts/weblog.erb</tt> or <tt>app/views/layouts/weblog.builder</tt> exists then it will be automatically set as
+    # the layout for your WeblogController. You can create a layout with the name <tt>application.erb</tt> or <tt>application.builder</tt>
+    # and this will be set as the default controller if there is no layout with the same name as the current controller and there is 
+    # no layout explicitly assigned with the +layout+ method. Nested controllers use the same folder structure for automatic layout.
+    # assignment. So an Admin::WeblogController will look for a template named <tt>app/views/layouts/admin/weblog.erb</tt>.
+    # Setting a layout explicitly will always override the automatic behaviour for the controller where the layout is set.
+    # Explicitly setting the layout in a parent class, though, will not override the child class's layout assignment if the child
+    # class has a layout with the same name. 
+    #
+    # == Inheritance for layouts
+    #
+    # Layouts are shared downwards in the inheritance hierarchy, but not upwards. Examples:
+    #
+    #   class BankController < ActionController::Base
+    #     layout "bank_standard"
+    #
+    #   class InformationController < BankController
+    #
+    #   class VaultController < BankController
+    #     layout :access_level_layout
+    #
+    #   class EmployeeController < BankController
+    #     layout nil
+    #
+    # The InformationController uses "bank_standard" inherited from the BankController, the VaultController overwrites
+    # and picks the layout dynamically, and the EmployeeController doesn't want to use a layout at all.
+    #
+    # == Types of layouts
+    #
+    # Layouts are basically just regular templates, but the name of this template needs not be specified statically. Sometimes
+    # you want to alternate layouts depending on runtime information, such as whether someone is logged in or not. This can
+    # be done either by specifying a method reference as a symbol or using an inline method (as a proc).
+    #
+    # The method reference is the preferred approach to variable layouts and is used like this:
+    #
+    #   class WeblogController < ActionController::Base
+    #     layout :writers_and_readers
+    #
+    #     def index
+    #       # fetching posts
+    #     end
+    #
+    #     private
+    #       def writers_and_readers
+    #         logged_in? ? "writer_layout" : "reader_layout"
+    #       end
+    #
+    # Now when a new request for the index action is processed, the layout will vary depending on whether the person accessing 
+    # is logged in or not.
+    #
+    # If you want to use an inline method, such as a proc, do something like this:
+    #
+    #   class WeblogController < ActionController::Base
+    #     layout proc{ |controller| controller.logged_in? ? "writer_layout" : "reader_layout" }
+    #
+    # Of course, the most common way of specifying a layout is still just as a plain template name:
+    #
+    #   class WeblogController < ActionController::Base
+    #     layout "weblog_standard"
+    #
+    # If no directory is specified for the template name, the template will by default be looked for in +app/views/layouts/+. 
+    # Otherwise, it will be looked up relative to the template root.
+    #
+    # == Conditional layouts
+    #
+    # If you have a layout that by default is applied to all the actions of a controller, you still have the option of rendering
+    # a given action or set of actions without a layout, or restricting a layout to only a single action or a set of actions. The 
+    # <tt>:only</tt> and <tt>:except</tt> options can be passed to the layout call. For example:
+    #
+    #   class WeblogController < ActionController::Base
+    #     layout "weblog_standard", :except => :rss
+    # 
+    #     # ...
+    #
+    #   end
+    #
+    # This will assign "weblog_standard" as the WeblogController's layout  except for the +rss+ action, which will not wrap a layout 
+    # around the rendered view.
+    #
+    # Both the <tt>:only</tt> and <tt>:except</tt> condition can accept an arbitrary number of method references, so 
+    # #<tt>:except => [ :rss, :text_only ]</tt> is valid, as is <tt>:except => :rss</tt>.
+    #
+    # == Using a different layout in the action render call
+    # 
+    # If most of your actions use the same layout, it makes perfect sense to define a controller-wide layout as described above.
+    # Some times you'll have exceptions, though, where one action wants to use a different layout than the rest of the controller.
+    # This is possible using the <tt>render</tt> method. It's just a bit more manual work as you'll have to supply fully
+    # qualified template and layout names as this example shows:
+    #
+    #   class WeblogController < ActionController::Base
+    #     def help
+    #       render :action => "help/index", :layout => "help"
+    #     end
+    #   end
+    #
+    # As you can see, you pass the template as the first parameter, the status code as the second ("200" is OK), and the layout
+    # as the third.
+    #
+    module ClassMethods
+      def output(format, conditions = {})
+        conditions = normalize_output_conditions(conditions)
+        if conditions[:all]
+          write_inheritable_attribute("output_#{format}", conditions)
+        else
+          write_inheritable_hash("output_#{format}", conditions)
+        end
+      end
+
+      def default_output(format, action) #:nodoc:
+        conditions = read_inheritable_attribute("output_#{format}") || {}
+        conditions[:all] || conditions[action.to_sym] || {}
+      end
+      
+      private
+        def normalize_output_conditions(conditions)
+          normalized = if conditions.is_a?(Hash) && (conditions.has_key?(:handler) || conditions.has_key?(:treatment))
+            {:all => conditions}
+          elsif [NilClass, FalseClass, TrueClass, Symbol, Proc].find {|klass| conditions.is_a? klass}
+            {:all => conditions}
+          else
+            conditions
+          end
+          normalized.inject({}) {|hash, (key, value)| hash.merge(key => normalize_output_options(value))}
+        end
+      
+        def normalize_output_options(options)
+          case options
+            when String
+              case (parts = options.split('/')).size
+                when 1 then {:handler => nil, :treatment => options}
+                when 2 then {:handler => parts.first, :treatment => parts.last}
+                else raise InvalidOption, "Output option '#{options}' contains several slashes, this is invalid!"
+              end
+            when Hash then options
+            when Symbol, Proc then options
+            when FalseClass then {:handler => false}
+            when NilClass, TrueClass then {:handler => nil}
+            else raise InvalidOption, "Output option '#{options}' isn't handled!"
+          end
+        end
+    end
+
+    module InstanceMethods # :nodoc:
+      def self.included(base)
+        base.class_eval do
+          alias_method_chain :render, :output
+        end
+      end
+
+      # Returns an output hash containing the name of the handler and the treatment to apply on output.
+      # If the output specs were specified as a method reference (through a symbol), this method is called and the return
+      # value is used. Likewise if the output specs were specified as an inline method (through a proc or method object).
+      def active_output(passed_output = nil)
+        output = passed_output || self.class.default_output(request.format, action_name)
+        case output
+          when Symbol then send(output)
+          when Proc   then output.call(self)
+          else output
+        end
+      end
+  
+      protected
+      
+      def render_with_output(options = nil, &block)
+        set_output_info(options.is_a?(Hash) ? options[:output] : nil)
+        render_without_output(options, &block)
+      end
+      
+      def set_output_info(options)
+        output = pick_output(options)
+        response.handler_name = output[:handler]
+        response.treatment = request.treatment || output[:treatment]
+        response.format = request.format
+      end
+      
+      def pick_output(options)
+        if options.is_a?(Hash) && options.has_key?(:output)
+          active_output(self.class.normalize_output_options(options.delete(:output)))
+        else
+          active_output
+        end
+      end
+
+    end
+  end
+end

data/lib/reactive-mvc/controller/rescue.rb

@@ -0,0 +1,208 @@
+module Reactive::Mvc::Controller #:nodoc:
+  # Actions that fail to perform as expected throw exceptions. These exceptions can either be rescued for the public view
+  # (with a nice user-friendly explanation) or for the developers view (with tons of debugging information). The developers view
+  # is already implemented by the Action Controller, but the public view should be tailored to your specific application. 
+  # 
+  # The default behavior for public exceptions is to render a static html file with the name of the error code thrown.  If no such 
+  # file exists, an empty response is sent with the correct status code.
+  #
+  # Custom rescue behavior is achieved by overriding the <tt>rescue_action</tt> method.
+  module Rescue
+    DEFAULT_RESCUE_RESPONSE = :internal_server_error
+    DEFAULT_RESCUE_RESPONSES = {
+      'Reactive::Mvc::Controller::UnknownAction'        => :not_found,
+      'ActiveRecord::RecordNotFound'               => :not_found,
+      'ActiveRecord::StaleObjectError'             => :conflict,
+      'ActiveRecord::RecordInvalid'                => :unprocessable_entity,
+      'ActiveRecord::RecordNotSaved'               => :unprocessable_entity,
+      'Reactive::Mvc::Controller::MethodNotAllowed'     => :method_not_allowed,
+      'Reactive::Mvc::Controller::NotImplemented'       => :not_implemented,
+    }
+
+    DEFAULT_RESCUE_TEMPLATE = 'diagnostics'
+    DEFAULT_RESCUE_TEMPLATES = {
+      'Reactive::Mvc::View::MissingTemplate'       => 'missing_template',
+      'Reactive::Mvc::Controller::UnknownAction'   => 'unknown_action',
+      'Reactive::Mvc::View::TemplateError'         => 'template_error'
+    }
+
+    def self.included(base) #:nodoc:
+      base.cattr_accessor :rescue_responses
+      base.rescue_responses = Hash.new(DEFAULT_RESCUE_RESPONSE)
+      base.rescue_responses.update DEFAULT_RESCUE_RESPONSES
+
+      base.cattr_accessor :rescue_templates
+      base.rescue_templates = Hash.new(DEFAULT_RESCUE_TEMPLATE)
+      base.rescue_templates.update DEFAULT_RESCUE_TEMPLATES
+
+      base.class_inheritable_array :rescue_handlers
+      base.rescue_handlers = []
+
+      base.extend(ClassMethods)
+      base.class_eval do
+        alias_method_chain :perform_action, :rescue
+      end
+    end
+
+    module ClassMethods
+      def process_with_exception(request, response, exception) #:nodoc:
+        new.process(request, response, :rescue_the_action, exception)
+      end
+
+      # Rescue exceptions raised in controller actions.
+      #
+      # <tt>rescue_from</tt> receives a series of exception classes or class
+      # names, and a trailing <tt>:with</tt> option with the name of a method
+      # or a Proc object to be called to handle them. Alternatively a block can
+      # be given.
+      #
+      # Handlers that take one argument will be called with the exception, so
+      # that the exception can be inspected when dealing with it.
+      #
+      # Handlers are inherited. They are searched from right to left, from
+      # bottom to top, and up the hierarchy. The handler of the first class for
+      # which <tt>exception.is_a?(klass)</tt> holds true is the one invoked, if
+      # any.
+      #
+      #   class ApplicationController < ActionController::Base
+      #     rescue_from User::NotAuthorized, :with => :deny_access # self defined exception
+      #     rescue_from ActiveRecord::RecordInvalid, :with => :show_errors
+      #
+      #     rescue_from 'MyAppError::Base' do |exception|
+      #       render :xml => exception, :status => 500
+      #     end
+      #
+      #     protected
+      #       def deny_access
+      #         ...
+      #       end
+      #
+      #       def show_errors(exception)
+      #         exception.record.new_record? ? ...
+      #       end
+      #   end
+      def rescue_from(*klasses, &block)
+        options = klasses.extract_options!
+        unless options.has_key?(:with)
+          block_given? ? options[:with] = block : raise(ArgumentError, "Need a handler. Supply an options hash that has a :with key as the last argument.")
+        end
+
+        klasses.each do |klass|
+          key = if klass.is_a?(Class) && klass <= Exception
+            klass.name
+          elsif klass.is_a?(String)
+            klass
+          else
+            raise(ArgumentError, "#{klass} is neither an Exception nor a String")
+          end
+
+          # Order is important, we put the pair at the end. When dealing with an
+          # exception we will follow the documented order going from right to left.
+          rescue_handlers << [key, options[:with]]
+        end
+      end
+    end
+
+    protected
+      # Exception handler called when the performance of an action raises an exception.
+      def rescue_the_action(exception)
+        log_error(exception) if logger
+        erase_results if performed?
+
+        # Let the exception alter the response if it wants.
+        # For example, MethodNotAllowed sets the Allow header.
+        if exception.respond_to?(:handle_response!)
+          exception.handle_response!(response)
+        end
+
+        rescue_action(exception)
+      end
+
+      # Overwrite to implement custom logging of errors. By default logs as fatal.
+      def log_error(exception) #:doc:
+        ActiveSupport::Deprecation.silence do
+          if exception.respond_to? :template_error
+            logger.fatal(exception.to_s)
+          else
+            logger.fatal(
+              "\n\n#{exception.class} (#{exception.message}):\n    " +
+              clean_backtrace(exception).join("\n    ") +
+              "\n\n"
+            )
+          end
+        end
+      end
+
+      # Overwrite to implement exception handling. By default the exception will be re-raised.
+      # Override this method to provide more user friendly error messages.
+      def rescue_action(exception) #:doc:
+        raise exception
+      end
+      
+      # Render detailed diagnostics for unhandled exceptions rescued from
+      # a controller action.
+#      def rescue_action_locally(exception)
+#        @template.instance_variable_set("@exception", exception)
+#        @template.instance_variable_set("@rescues_path", File.dirname(rescues_path("stub")))
+#        @template.instance_variable_set("@contents", @template.render(:file => template_path_for_local_rescue(exception)))
+#
+#        response.content_type = Mime::HTML
+#        render_for_file(rescues_path("layout"), response_code_for_rescue(exception))
+#      end
+
+      # Tries to rescue the exception by looking up and calling a registered handler.
+      def rescue_action_with_handler(exception)
+        if handler = handler_for_rescue(exception)
+          if handler.arity != 0
+            handler.call(exception)
+          else
+            handler.call
+          end
+          true # don't rely on the return value of the handler
+        end
+      end
+
+    private
+      def perform_action_with_rescue #:nodoc:
+        perform_action_without_rescue
+      rescue Exception => exception
+        rescue_action_with_handler(exception) || rescue_action(exception)
+      end
+
+      def handler_for_rescue(exception)
+        # We go from right to left because pairs are pushed onto rescue_handlers
+        # as rescue_from declarations are found.
+        _, handler = *rescue_handlers.reverse.detect do |klass_name, handler|
+          # The purpose of allowing strings in rescue_from is to support the
+          # declaration of handler associations for exception classes whose
+          # definition is yet unknown.
+          #
+          # Since this loop needs the constants it would be inconsistent to
+          # assume they should exist at this point. An early raised exception
+          # could trigger some other handler and the array could include
+          # precisely a string whose corresponding constant has not yet been
+          # seen. This is why we are tolerant to unknown constants.
+          #
+          # Note that this tolerance only matters if the exception was given as
+          # a string, otherwise a NameError will be raised by the interpreter
+          # itself when rescue_from CONSTANT is executed.
+          klass = self.class.const_get(klass_name) rescue nil
+          klass ||= klass_name.constantize rescue nil
+          exception.is_a?(klass) if klass
+        end
+
+        case handler
+        when Symbol
+          method(handler)
+        when Proc
+          handler.bind(self)
+        end
+      end
+
+      def clean_backtrace(exception)
+        if backtrace = exception.backtrace
+          backtrace.map { |line| line.sub Reactive.configuration.root_dir, '' }
+        end
+      end
+  end
+end