halorgium-actionpack 3.0.pre

data/lib/action_controller/metal/layouts.rb

@@ -0,0 +1,171 @@
+module ActionController
+  # 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
+  #
+  # 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
+  #
+  # == Layout assignment
+  #
+  # You can either specify a layout declaratively (using the #layout class method) or give
+  # it the same name as your controller, and place it in <tt>app/views/layouts</tt>.
+  # If a subclass does not have a layout specified, it inherits its layout using normal Ruby inheritance.
+  #
+  # For instance, if you have PostsController and a template named <tt>app/views/layouts/posts.html.erb</tt>,
+  # that template will be used for all actions in PostsController and controllers inheriting
+  # from PostsController.
+  #
+  # If you use a module, for instance Weblog::PostsController, you will need a template named
+  # <tt>app/views/layouts/weblog/posts.html.erb</tt>.
+  #
+  # Since all your controllers inherit from ApplicationController, they will use
+  # <tt>app/views/layouts/application.html.erb</tt> if no other layout is specified
+  # or provided.
+  #
+  # == Inheritance Examples
+  #
+  #   class BankController < ActionController::Base
+  #     layout "bank_standard"
+  #
+  #   class InformationController < BankController
+  #
+  #   class TellerController < BankController
+  #     # teller.html.erb exists
+  #
+  #   class TillController < TellerController
+  #
+  #   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.
+  #
+  # The TellerController uses +teller.html.erb+, and TillController inherits that layout and
+  # uses it as well.
+  #
+  # == 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 <tt>app/views/layouts/</tt>.
+  # 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.
+  # Sometimes you'll have exceptions where one action wants to use a different layout than the rest of the controller.
+  # You can do this by passing a <tt>:layout</tt> option to the <tt>render</tt> call. For example:
+  #
+  #   class WeblogController < ActionController::Base
+  #     layout "weblog_standard"
+  #
+  #     def help
+  #       render :action => "help", :layout => "help"
+  #     end
+  #   end
+  #
+  # This will render the help action with the "help" layout instead of the controller-wide "weblog_standard" layout.
+  module Layouts
+    extend ActiveSupport::Concern
+
+    include ActionController::RenderingController
+    include AbstractController::Layouts
+
+    module ClassMethods
+      # If no layout is provided, look for a layout with this name.
+      def _implied_layout_name
+        controller_path
+      end
+    end
+  end
+end

data/lib/action_controller/metal/mime_responds.rb

@@ -0,0 +1,317 @@
+module ActionController #:nodoc:
+  module MimeResponds #:nodoc:
+    extend ActiveSupport::Concern
+
+    included do
+      extlib_inheritable_accessor :responder, :mimes_for_respond_to, :instance_writer => false
+      self.responder = ActionController::Responder
+      clear_respond_to
+    end
+
+    module ClassMethods
+      # Defines mimes that are rendered by default when invoking respond_with.
+      #
+      # Examples:
+      #
+      #   respond_to :html, :xml, :json
+      #
+      # All actions on your controller will respond to :html, :xml and :json.
+      #
+      # But if you want to specify it based on your actions, you can use only and
+      # except:
+      #
+      #   respond_to :html
+      #   respond_to :xml, :json, :except => [ :edit ]
+      #
+      # The definition above explicits that all actions respond to :html. And all
+      # actions except :edit respond to :xml and :json.
+      #
+      # You can specify also only parameters:
+      #
+      #   respond_to :rjs, :only => :create
+      #
+      def respond_to(*mimes)
+        options = mimes.extract_options!
+
+        only_actions   = Array(options.delete(:only))
+        except_actions = Array(options.delete(:except))
+
+        mimes.each do |mime|
+          mime = mime.to_sym
+          mimes_for_respond_to[mime]          = {}
+          mimes_for_respond_to[mime][:only]   = only_actions   unless only_actions.empty?
+          mimes_for_respond_to[mime][:except] = except_actions unless except_actions.empty?
+        end
+      end
+
+      # Clear all mimes in respond_to.
+      #
+      def clear_respond_to
+        self.mimes_for_respond_to = ActiveSupport::OrderedHash.new
+      end
+    end
+
+    # Without web-service support, an action which collects the data for displaying a list of people
+    # might look something like this:
+    #
+    #   def index
+    #     @people = Person.find(:all)
+    #   end
+    #
+    # Here's the same action, with web-service support baked in:
+    #
+    #   def index
+    #     @people = Person.find(:all)
+    #
+    #     respond_to do |format|
+    #       format.html
+    #       format.xml { render :xml => @people.to_xml }
+    #     end
+    #   end
+    #
+    # What that says is, "if the client wants HTML in response to this action, just respond as we
+    # would have before, but if the client wants XML, return them the list of people in XML format."
+    # (Rails determines the desired response format from the HTTP Accept header submitted by the client.)
+    #
+    # Supposing you have an action that adds a new person, optionally creating their company
+    # (by name) if it does not already exist, without web-services, it might look like this:
+    #
+    #   def create
+    #     @company = Company.find_or_create_by_name(params[:company][:name])
+    #     @person  = @company.people.create(params[:person])
+    #
+    #     redirect_to(person_list_url)
+    #   end
+    #
+    # Here's the same action, with web-service support baked in:
+    #
+    #   def create
+    #     company  = params[:person].delete(:company)
+    #     @company = Company.find_or_create_by_name(company[:name])
+    #     @person  = @company.people.create(params[:person])
+    #
+    #     respond_to do |format|
+    #       format.html { redirect_to(person_list_url) }
+    #       format.js
+    #       format.xml  { render :xml => @person.to_xml(:include => @company) }
+    #     end
+    #   end
+    #
+    # If the client wants HTML, we just redirect them back to the person list. If they want Javascript
+    # (format.js), then it is an RJS request and we render the RJS template associated with this action.
+    # Lastly, if the client wants XML, we render the created person as XML, but with a twist: we also
+    # include the person's company in the rendered XML, so you get something like this:
+    #
+    #   <person>
+    #     <id>...</id>
+    #     ...
+    #     <company>
+    #       <id>...</id>
+    #       <name>...</name>
+    #       ...
+    #     </company>
+    #   </person>
+    #
+    # Note, however, the extra bit at the top of that action:
+    #
+    #   company  = params[:person].delete(:company)
+    #   @company = Company.find_or_create_by_name(company[:name])
+    #
+    # This is because the incoming XML document (if a web-service request is in process) can only contain a
+    # single root-node. So, we have to rearrange things so that the request looks like this (url-encoded):
+    #
+    #   person[name]=...&person[company][name]=...&...
+    #
+    # And, like this (xml-encoded):
+    #
+    #   <person>
+    #     <name>...</name>
+    #     <company>
+    #       <name>...</name>
+    #     </company>
+    #   </person>
+    #
+    # In other words, we make the request so that it operates on a single entity's person. Then, in the action,
+    # we extract the company data from the request, find or create the company, and then create the new person
+    # with the remaining data.
+    #
+    # Note that you can define your own XML parameter parser which would allow you to describe multiple entities
+    # in a single request (i.e., by wrapping them all in a single root node), but if you just go with the flow
+    # and accept Rails' defaults, life will be much easier.
+    #
+    # If you need to use a MIME type which isn't supported by default, you can register your own handlers in
+    # environment.rb as follows.
+    #
+    #   Mime::Type.register "image/jpg", :jpg
+    #
+    # Respond to also allows you to specify a common block for different formats by using any:
+    #
+    #   def index
+    #     @people = Person.find(:all)
+    #
+    #     respond_to do |format|
+    #       format.html
+    #       format.any(:xml, :json) { render request.format.to_sym => @people }
+    #     end
+    #   end
+    #
+    # In the example above, if the format is xml, it will render:
+    #
+    #   render :xml => @people
+    #
+    # Or if the format is json:
+    #
+    #   render :json => @people
+    #
+    # Since this is a common pattern, you can use the class method respond_to
+    # with the respond_with method to have the same results:
+    #
+    #   class PeopleController < ApplicationController
+    #     respond_to :html, :xml, :json
+    #
+    #     def index
+    #       @people = Person.find(:all)
+    #       respond_with(@person)
+    #     end
+    #   end
+    #
+    # Be sure to check respond_with and respond_to documentation for more examples.
+    #
+    def respond_to(*mimes, &block)
+      raise ArgumentError, "respond_to takes either types or a block, never both" if mimes.any? && block_given?
+
+      if response = retrieve_response_from_mimes(mimes, &block)
+        response.call
+      end
+    end
+
+    # respond_with wraps a resource around a responder for default representation.
+    # First it invokes respond_to, if a response cannot be found (ie. no block
+    # for the request was given and template was not available), it instantiates
+    # an ActionController::Responder with the controller and resource.
+    #
+    # ==== Example
+    #
+    #   def index
+    #     @users = User.all
+    #     respond_with(@users)
+    #   end
+    #
+    # It also accepts a block to be given. It's used to overwrite a default
+    # response:
+    #
+    #   def destroy
+    #     @user = User.find(params[:id])
+    #     flash[:notice] = "User was successfully created." if @user.save
+    #
+    #     respond_with(@user) do |format|
+    #       format.html { render }
+    #     end
+    #   end
+    #
+    # All options given to respond_with are sent to the underlying responder,
+    # except for the option :responder itself. Since the responder interface
+    # is quite simple (it just needs to respond to call), you can even give
+    # a proc to it.
+    #
+    def respond_with(*resources, &block)
+      if response = retrieve_response_from_mimes([], &block)
+        options = resources.extract_options!
+        options.merge!(:default_response => response)
+        (options.delete(:responder) || responder).call(self, resources, options)
+      end
+    end
+
+  protected
+
+    # Collect mimes declared in the class method respond_to valid for the
+    # current action.
+    #
+    def collect_mimes_from_class_level #:nodoc:
+      action = action_name.to_sym
+
+      mimes_for_respond_to.keys.select do |mime|
+        config = mimes_for_respond_to[mime]
+
+        if config[:except]
+          !config[:except].include?(action)
+        elsif config[:only]
+          config[:only].include?(action)
+        else
+          true
+        end
+      end
+    end
+
+    # Collects mimes and return the response for the negotiated format. Returns
+    # nil if :not_acceptable was sent to the client.
+    #
+    def retrieve_response_from_mimes(mimes, &block)
+      collector = Collector.new { default_render }
+      mimes = collect_mimes_from_class_level if mimes.empty?
+      mimes.each { |mime| collector.send(mime) }
+      block.call(collector) if block_given?
+
+      if format = request.negotiate_mime(collector.order)
+        self.formats = [format.to_sym]
+        collector.response_for(format)
+      else
+        head :not_acceptable
+        nil
+      end
+    end
+
+    class Collector #:nodoc:
+      attr_accessor :order
+
+      def initialize(&block)
+        @order, @responses, @default_response = [], {}, block
+      end
+
+      def any(*args, &block)
+        if args.any?
+          args.each { |type| send(type, &block) }
+        else
+          custom(Mime::ALL, &block)
+        end
+      end
+      alias :all :any
+
+      def custom(mime_type, &block)
+        mime_type = mime_type.is_a?(Mime::Type) ? mime_type : Mime::Type.lookup(mime_type.to_s)
+        @order << mime_type
+        @responses[mime_type] ||= block
+      end
+
+      def response_for(mime)
+        @responses[mime] || @responses[Mime::ALL] || @default_response
+      end
+
+      def self.generate_method_for_mime(mime)
+        sym = mime.is_a?(Symbol) ? mime : mime.to_sym
+        const = sym.to_s.upcase
+        class_eval <<-RUBY, __FILE__, __LINE__ + 1
+          def #{sym}(&block)                # def html(&block)
+            custom(Mime::#{const}, &block)  #   custom(Mime::HTML, &block)
+          end                               # end
+        RUBY
+      end
+
+      Mime::SET.each do |mime|
+        generate_method_for_mime(mime)
+      end
+
+      def method_missing(symbol, &block)
+        mime_constant = Mime.const_get(symbol.to_s.upcase)
+
+        if Mime::SET.include?(mime_constant)
+          self.class.generate_method_for_mime(mime_constant)
+          send(symbol, &block)
+        else
+          super
+        end
+      end
+
+    end
+  end
+end