actionpack 0.9.0

data/lib/action_controller/flash.rb

@@ -0,0 +1,65 @@
+module ActionController #:nodoc:
+  # The flash provides a way to pass temporary objects between actions. Anything you place in the flash will be exposed
+  # to the very next action and then cleared out. This is a great way of doing notices and alerts, such as a create action
+  # that sets <tt>flash["notice"] = "Succesfully created"</tt> before redirecting to a display action that can then expose 
+  # the flash to its template. Actually, that exposure is automatically done. Example:
+  #
+  #   class WeblogController < ActionController::Base
+  #     def create
+  #       # save post
+  #       flash["notice"] = "Succesfully created post"
+  #       redirect_to :action => "display", :params => { "id" => post.id }
+  #     end
+  #
+  #     def display
+  #       # doesn't need to assign the flash notice to the template, that's done automatically
+  #     end
+  #   end
+  #
+  #   display.rhtml
+  #     <% if @flash["notice"] %><div class="notice"><%= @flash["notice"] %></div><% end %>
+  #
+  # This example just places a string in the flash, but you can put any object in there. And of course, you can put as many
+  # as you like at a time too. Just remember: They'll be gone by the time the next action has been performed.
+  module Flash
+    def self.append_features(base) #:nodoc:
+      super
+      base.before_filter(:fire_flash)
+      base.after_filter(:clear_flash)
+    end
+
+    protected
+      # Access the contents of the flash. Use <tt>flash["notice"]</tt> to read a notice you put there or 
+      # <tt>flash["notice"] = "hello"</tt> to put a new one.
+      def flash #:doc:
+        if @session["flash"].nil?
+          @session["flash"]   = {}
+          @session["flashes"] ||= 0
+        end
+        @session["flash"]
+      end    
+
+      # Can be called by any action that would like to keep the current content of the flash around for one more action.
+      def keep_flash #:doc:
+        @session["flashes"] = 0
+      end    
+
+    private
+      # Records that the contents of @session["flash"] was flashed to the action
+      def fire_flash
+        if @session["flash"]
+          @session["flashes"] += 1 unless @session["flash"].empty?
+          @assigns["flash"] = @session["flash"]
+        else
+          @assigns["flash"] = {}
+        end
+      end
+
+      def clear_flash
+        if @session["flash"] && (@session["flashes"].nil? || @session["flashes"] >= 1)
+          @session["flash"]   = {}
+          @session["flashes"] = 0 
+        end
+      end    
+  end
+end

data/lib/action_controller/layout.rb

@@ -0,0 +1,143 @@
+module ActionController #:nodoc:
+  module Layout #:nodoc:
+    def self.append_features(base)
+      super
+      base.extend(ClassMethods)
+      base.class_eval do
+        alias_method :render_without_layout, :render
+        alias_method :render, :render_with_layout
+      end
+    end
+
+    # 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 is only mentioned in one place, like this:
+    #
+    #   <!-- The header part of this layout -->
+    #   <%= @content_for_layout %>
+    #   <!-- 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>
+    #   <%= @content_for_layout %>
+    #
+    # ...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
+    #
+    # == Inheritance for layouts
+    #
+    # Layouts are shared downwards in the inheritance hierarchy, but not upwards. Examples:
+    #
+    #   class BankController < ActionController::Base
+    #     layout "layouts/bank_standard"
+    #
+    #   class InformationController < BankController
+    #
+    #   class VaultController < BankController
+    #     layout :access_level_layout
+    #
+    #   class EmployeeController < BankController
+    #     layout nil
+    #
+    # The InformationController uses "layouts/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 path:
+    #
+    #   class WeblogController < ActionController::Base
+    #     layout "layouts/weblog_standard"
+    module ClassMethods
+      # If a layout is specified, all actions rendered through render and render_action will have their result assigned 
+      # to <tt>@content_for_layout</tt>, which can then be used by the layout to insert their contents with
+      # <tt><%= @content_for_layout %></tt>. This layout can itself depend on instance variables assigned during action
+      # performance and have access to them as any normal template would.
+      def layout(template_name)
+        write_inheritable_attribute "layout", template_name
+      end
+    end
+
+    # Returns the name of the active layout. If the layout was specified as a method reference (through a symbol), this method
+    # is called and the return value is used. Likewise if the layout was specified as an inline method (through a proc or method
+    # object). If the layout was defined without a directory, layouts is assumed. So <tt>layout "weblog/standard"</tt> will return
+    # weblog/standard, but <tt>layout "standard"</tt> will return layouts/standard.
+    def active_layout(passed_layout = nil)
+      layout = passed_layout || self.class.read_inheritable_attribute("layout")
+      active_layout = case layout
+        when Symbol then send(layout)
+        when Proc   then layout.call(self)
+        when String then layout
+      end
+      active_layout.include?("/") ? active_layout : "layouts/#{active_layout}" if active_layout
+    end
+
+    def render_with_layout(template_name = "#{controller_name}/#{action_name}", status = nil, layout = nil) #:nodoc:
+      if layout || active_layout
+        add_variables_to_assigns
+        logger.info("Rendering #{template_name} within #{layout || active_layout}") unless logger.nil?
+        @content_for_layout = @template.render_file(template_name, true)
+        render_without_layout(layout || self.active_layout, status)
+      else
+        render_without_layout(template_name, status)
+      end
+    end
+  end
+end

data/lib/action_controller/request.rb

@@ -0,0 +1,92 @@
+module ActionController
+  class AbstractRequest #:nodoc:
+    # Returns both GET and POST parameters in a single hash.
+    def parameters
+      @parameters ||= request_parameters.update(query_parameters)
+    end
+
+    def method
+      env['REQUEST_METHOD'].downcase.intern
+    end
+
+    def get?
+      method == :get
+    end
+
+    def post?
+      method == :post
+    end
+
+    def put?
+      method == :put
+    end
+
+    def delete?
+      method == :delete
+    end
+
+    # Determine originating IP address.  REMOTE_ADDR is the standard
+    # but will fail if the user is behind a proxy.  HTTP_CLIENT_IP and/or
+    # HTTP_X_FORWARDED_FOR are set by proxies so check for these before
+    # falling back to REMOTE_ADDR.  HTTP_X_FORWARDED_FOR may be a comma-
+    # delimited list in the case of multiple chained proxies; the first is
+    # the originating IP.
+    def remote_ip
+      if env['HTTP_CLIENT_IP']
+        env['HTTP_CLIENT_IP']
+      elsif env['HTTP_X_FORWARDED_FOR']
+        env['HTTP_X_FORWARDED_FOR'].split(',').reject { |ip|
+            ip =~ /^unknown$|^(10|172\.16|192\.168)\./i
+        }.first.strip
+      else
+        env['REMOTE_ADDR']
+      end
+    end
+
+    def request_uri
+      env["REQUEST_URI"]
+    end
+
+    def protocol
+      port == 443 ? "https://" : "http://"
+    end
+
+    def path
+      request_uri ? request_uri.split("?").first : ""
+    end
+
+    def port
+      env["SERVER_PORT"].to_i
+    end
+
+    def host_with_port
+      if (protocol == "http://" && port == 80) || (protocol == "https://" && port == 443)
+        host
+      else
+        host + ":#{port}"
+      end
+    end
+
+    # Must be implemented in the concrete request
+    def query_parameters
+    end
+
+    def request_parameters
+    end
+
+    def env
+    end
+
+    def host
+    end
+
+    def cookies
+    end
+
+    def session
+    end
+
+    def reset_session
+    end    
+  end
+end

data/lib/action_controller/rescue.rb

@@ -0,0 +1,94 @@
+module ActionController #: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. So too
+  # could the decision on whether something is a public or a developer request.
+  #
+  # You can tailor the rescuing behavior and appearance by overwriting the following two stub methods.
+  module Rescue
+    def self.append_features(base) #:nodoc:
+      super
+      base.class_eval do
+        alias_method :perform_action_without_rescue, :perform_action
+        alias_method :perform_action, :perform_action_with_rescue
+      end
+    end
+
+    protected
+      # Exception handler called when the performance of an action raises an exception.
+      def rescue_action(exception)
+        log_error(exception) unless logger.nil?
+
+        if consider_all_requests_local || local_request?
+          rescue_action_locally(exception)
+        else
+          rescue_action_in_public(exception)
+        end
+      end
+
+      # Overwrite to implement custom logging of errors. By default logs as fatal.
+      def log_error(exception) #:doc:
+        if ActionView::TemplateError === exception
+          logger.fatal(exception.to_s)
+        else
+          logger.fatal(
+            "\n\n#{exception.class} (#{exception.message}):\n    " + 
+            clean_backtrace(exception).join("\n    ") + 
+            "\n\n"
+          )
+        end
+      end
+
+      # Overwrite to implement public exception handling (for requests answering false to <tt>local_request?</tt>).
+      def rescue_action_in_public(exception) #:doc:
+        render_text "<html><body><h1>Application error (Rails)</h1></body></html>"
+      end
+
+      # Overwrite to expand the meaning of a local request in order to show local rescues on other occurances than
+      # the remote IP being 127.0.0.1. For example, this could include the IP of the developer machine when debugging
+      # remotely.
+      def local_request? #:doc:
+        @request.remote_addr == "127.0.0.1"
+      end
+
+      # Renders a detailed diagnostics screen on action exceptions. 
+      def rescue_action_locally(exception)
+        @exception = exception
+        @rescues_path = File.dirname(__FILE__) + "/templates/rescues/"
+        add_variables_to_assigns
+        @contents = @template.render_file(template_path_for_local_rescue(exception), false)
+    
+        @headers["Content-Type"] = "text/html"
+        render_file(rescues_path("layout"), "500 Internal Error")
+      end
+    
+    private
+      def perform_action_with_rescue #:nodoc:
+        begin
+          perform_action_without_rescue
+        rescue Exception => exception
+          rescue_action(exception)
+        end
+      end
+
+      def rescues_path(template_name)
+        File.dirname(__FILE__) + "/templates/rescues/#{template_name}.rhtml"
+      end
+
+      def template_path_for_local_rescue(exception)
+        rescues_path(
+          case exception
+            when MissingTemplate then "missing_template"
+            when UnknownAction   then "unknown_action"
+            when ActionView::TemplateError then "template_error"
+            else "diagnostics"
+          end
+        )
+      end
+      
+      def clean_backtrace(exception)
+        base_dir = File.expand_path(File.dirname(__FILE__) + "/../../../../")
+        exception.backtrace.collect { |line| line.gsub(base_dir, "").gsub("/public/../config/environments/../../", "").gsub("/public/../", "") }
+      end
+  end
+end

data/lib/action_controller/response.rb

@@ -0,0 +1,15 @@
+module ActionController
+  class AbstractResponse #:nodoc:
+    DEFAULT_HEADERS = { "Cache-Control" => "no-cache", "cookie" => [] }
+    attr_accessor :body, :headers, :session, :cookies, :assigns, :template, :redirected_to, :redirected_to_method_params
+
+    def initialize
+      @body, @headers, @session, @assigns = "", DEFAULT_HEADERS.dup, [], []
+    end
+
+    def redirect(to_url)
+      @headers["Status"]   = "302 Moved"
+      @headers["location"] = to_url
+    end
+  end
+end

data/lib/action_controller/scaffolding.rb

@@ -0,0 +1,183 @@
+module ActionController
+  module Scaffolding # :nodoc:
+    def self.append_features(base)
+      super
+      base.extend(ClassMethods)
+    end
+
+    # Scaffolding is a way to quickly put an Active Record class online by providing a series of standardized actions
+    # for listing, showing, creating, updating, and destroying objects of the class. These standardized actions come
+    # with both controller logic and default templates that through introspection already know which fields to display
+    # and which input types to use. Example:
+    #
+    #  class WeblogController < ActionController::Base
+    #    scaffold :entry
+    #  end
+    #
+    # This tiny piece of code will add all of the following methods to the controller:
+    #
+    #  class WeblogController < ActionController::Base
+    #    def index
+    #      list
+    #    end
+    #
+    #    def list
+    #      @entries = Entry.find_all
+    #      render_scaffold "list"
+    #    end
+    #  
+    #    def show
+    #      @entry = Entry.find(@params["id"])
+    #      render_scaffold
+    #    end
+    #    
+    #    def destroy
+    #      Entry.find(@params["id"]).destroy
+    #      redirect_to :action => "list"
+    #    end
+    #    
+    #    def new
+    #      @entry = Entry.new
+    #      render_scaffold
+    #    end
+    #    
+    #    def create
+    #      @entry = Entry.new(@params["entry"])
+    #      if @entry.save
+    #        flash["notice"] = "Entry was succesfully created"
+    #        redirect_to :action => "list"
+    #      else
+    #        render "entry/new"
+    #      end
+    #    end
+    #    
+    #    def edit
+    #      @entry = Entry.find(@params["id"])
+    #      render_scaffold
+    #    end
+    #    
+    #    def update
+    #      @entry = Entry.find(@params["entry"]["id"])
+    #      @entry.attributes = @params["entry"]
+    #  
+    #      if @entry.save
+    #        flash["notice"] = "Entry was succesfully updated"
+    #        redirect_to :action => "show/" + @entry.id.to_s
+    #      else
+    #        render "entry/edit"
+    #      end
+    #    end
+    #  end
+    #
+    # The <tt>render_scaffold</tt> method will first check to see if you've made your own template (like "weblog/show.rhtml" for 
+    # the show action) and if not, then render the generic template for that action. This gives you the possibility of using the 
+    # scaffold while you're building your specific application. Start out with a totally generic setup, then replace one template 
+    # and one action at a time while relying on the rest of the scaffolded templates and actions.
+    module ClassMethods
+      # Adds a swath of generic CRUD actions to the controller. The +model_id+ is automatically converted into a class name unless
+      # one is specifically provide through <tt>options[:class_name]</tt>. So <tt>scaffold :post</tt> would use Post as the class
+      # and @post/@posts for the instance variables.
+      # 
+      # It's possible to use more than one scaffold in a single controller by specifying <tt>options[:suffix] = true</tt>. This will
+      # make <tt>scaffold :post, :suffix => true</tt> use method names like list_post, show_post, and create_post 
+      # instead of just list, show, and post. If suffix is used, then no index method is added.
+      def scaffold(model_id, options = {})
+        validate_options([ :class_name, :suffix ], options.keys)
+
+        require "#{model_id.id2name}" rescue logger.warn "Couldn't auto-require #{model_id.id2name}.rb" unless logger.nil?
+
+        singular_name = model_id.id2name
+        class_name    = options[:class_name] || Inflector.camelize(singular_name)
+        plural_name   = Inflector.pluralize(singular_name)
+        suffix        = options[:suffix] ? "_#{singular_name}" : ""
+
+        unless options[:suffix]
+          module_eval <<-"end_eval", __FILE__, __LINE__
+            def index
+              list
+            end
+          end_eval
+        end
+        
+        module_eval <<-"end_eval", __FILE__, __LINE__
+          def list#{suffix}
+            @#{plural_name} = #{class_name}.find_all
+            render#{suffix}_scaffold "list#{suffix}"
+          end
+
+          def show#{suffix}
+            @#{singular_name} = #{class_name}.find(@params["id"])
+            render#{suffix}_scaffold
+          end
+          
+          def destroy#{suffix}
+            #{class_name}.find(@params["id"]).destroy
+            redirect_to :action => "list#{suffix}"
+          end
+          
+          def new#{suffix}
+            @#{singular_name} = #{class_name}.new
+            render#{suffix}_scaffold
+          end
+          
+          def create#{suffix}
+            @#{singular_name} = #{class_name}.new(@params["#{singular_name}"])
+            if @#{singular_name}.save
+              flash["notice"] = "#{class_name} was succesfully created"
+              redirect_to :action => "list#{suffix}"
+            else
+              render "#{singular_name}/new#{suffix}"
+            end
+          end
+          
+          def edit#{suffix}
+            @#{singular_name} = #{class_name}.find(@params["id"])
+            render#{suffix}_scaffold
+          end
+          
+          def update#{suffix}
+            @#{singular_name} = #{class_name}.find(@params["#{singular_name}"]["id"])
+            @#{singular_name}.attributes = @params["#{singular_name}"]
+
+            if @#{singular_name}.save
+              flash["notice"] = "#{class_name} was succesfully updated"
+              redirect_to :action => "show#{suffix}/" + @#{singular_name}.id.to_s
+            else
+              render "#{singular_name}/edit#{suffix}"
+            end
+          end
+          
+          private
+            def render#{suffix}_scaffold(action = caller_method_name(caller))
+              if template_exists?("\#{controller_name}/\#{action}")
+                render_action(action)
+              else
+                @scaffold_class = #{class_name}
+                @scaffold_singular_name, @scaffold_plural_name = "#{singular_name}", "#{plural_name}"
+                @scaffold_suffix = "#{suffix}"
+                add_instance_variables_to_assigns
+
+                @content_for_layout = @template.render_file(scaffold_path(action.sub(/#{suffix}$/, "")), false)
+                self.active_layout ? render_file(self.active_layout, "200 OK", true) : render_file(scaffold_path("layout"))
+              end
+            end
+            
+            def scaffold_path(template_name)
+              File.dirname(__FILE__) + "/templates/scaffolds/" + template_name + ".rhtml"
+            end
+            
+            def caller_method_name(caller)
+              caller.first.scan(/`(.*)'/).first.first # ' ruby-mode
+            end
+        end_eval
+      end
+
+      private
+        # Raises an exception if an invalid option has been specified to prevent misspellings from slipping through 
+        def validate_options(valid_option_keys, supplied_option_keys)
+          unknown_option_keys = supplied_option_keys - valid_option_keys
+          raise(ActionController::ActionControllerError, "Unknown options: #{unknown_option_keys}") unless unknown_option_keys.empty?
+        end        
+    end
+  end
+end