From 39e1ac658efc80e4c54abef4f1c7679e4b3dc2ac Mon Sep 17 00:00:00 2001 From: Pratik Naik Date: Sun, 18 Jan 2009 18:10:58 +0000 Subject: Merge docrails --- .../assertions/selector_assertions.rb | 23 ++-- actionpack/lib/action_controller/flash.rb | 12 +- actionpack/lib/action_controller/request.rb | 12 +- actionpack/lib/action_controller/routing.rb | 5 +- .../lib/action_controller/session_management.rb | 2 +- .../lib/action_view/helpers/asset_tag_helper.rb | 124 ++++++++++++--------- 6 files changed, 106 insertions(+), 72 deletions(-) (limited to 'actionpack') diff --git a/actionpack/lib/action_controller/assertions/selector_assertions.rb b/actionpack/lib/action_controller/assertions/selector_assertions.rb index 7f8fe9ab19..0d56ea5ef7 100644 --- a/actionpack/lib/action_controller/assertions/selector_assertions.rb +++ b/actionpack/lib/action_controller/assertions/selector_assertions.rb @@ -109,20 +109,27 @@ module ActionController # starting from (and including) that element and all its children in # depth-first order. # - # If no element if specified, calling +assert_select+ will select from the - # response HTML. Calling #assert_select inside an +assert_select+ block will - # run the assertion for each element selected by the enclosing assertion. + # If no element if specified, calling +assert_select+ selects from the + # response HTML unless +assert_select+ is called from within an +assert_select+ block. + # + # When called with a block +assert_select+ passes an array of selected elements + # to the block. Calling +assert_select+ from the block, with no element specified, + # runs the assertion on the complete set of elements selected by the enclosing assertion. + # Alternatively the array may be iterated through so that +assert_select+ can be called + # separately for each element. + # # # ==== Example - # assert_select "ol>li" do |elements| + # If the response contains two ordered lists, each with four list elements then: + # assert_select "ol" do |elements| # elements.each do |element| - # assert_select element, "li" + # assert_select element, "li", 4 # end # end # - # Or for short: - # assert_select "ol>li" do - # assert_select "li" + # will pass, as will: + # assert_select "ol" do + # assert_select "li", 8 # end # # The selector may be a CSS selector expression (String), an expression diff --git a/actionpack/lib/action_controller/flash.rb b/actionpack/lib/action_controller/flash.rb index 9856dbed2a..56ee9c67e2 100644 --- a/actionpack/lib/action_controller/flash.rb +++ b/actionpack/lib/action_controller/flash.rb @@ -4,20 +4,22 @@ module ActionController #:nodoc: # action that sets flash[:notice] = "Successfully created" 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 + # class PostsController < ActionController::Base # def create # # save post # flash[:notice] = "Successfully created post" - # redirect_to :action => "display", :params => { :id => post.id } + # redirect_to posts_path(@post) # end # - # def display + # def show # # doesn't need to assign the flash notice to the template, that's done automatically # end # end # - # display.erb - # <% if flash[:notice] %>
<%= flash[:notice] %>
<% end %> + # show.html.erb + # <% if flash[:notice] %> + #
<%= flash[:notice] %>
+ # <% 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. diff --git a/actionpack/lib/action_controller/request.rb b/actionpack/lib/action_controller/request.rb index cbbfca41f6..09dcd684e8 100755 --- a/actionpack/lib/action_controller/request.rb +++ b/actionpack/lib/action_controller/request.rb @@ -29,16 +29,18 @@ module ActionController HTTP_METHODS = %w(get head put post delete options) HTTP_METHOD_LOOKUP = HTTP_METHODS.inject({}) { |h, m| h[m] = h[m.upcase] = m.to_sym; h } - # The true HTTP request \method as a lowercase symbol, such as :get. - # UnknownHttpMethod is raised for invalid methods not listed in ACCEPTED_HTTP_METHODS. + # Returns the true HTTP request \method as a lowercase symbol, such as + # :get. If the request \method is not listed in the HTTP_METHODS + # constant above, an UnknownHttpMethod exception is raised. def request_method HTTP_METHOD_LOOKUP[super] || raise(UnknownHttpMethod, "#{super}, accepted HTTP methods are #{HTTP_METHODS.to_sentence}") end memoize :request_method - # The HTTP request \method as a lowercase symbol, such as :get. - # Note, HEAD is returned as :get since the two are functionally - # equivalent from the application's perspective. + # Returns the HTTP request \method used for action processing as a + # lowercase symbol, such as :post. (Unlike #request_method, this + # method returns :get for a HEAD request because the two are + # functionally equivalent from the application's perspective.) def method request_method == :head ? :get : request_method end diff --git a/actionpack/lib/action_controller/routing.rb b/actionpack/lib/action_controller/routing.rb index da9b56fdf9..a2141a77dc 100644 --- a/actionpack/lib/action_controller/routing.rb +++ b/actionpack/lib/action_controller/routing.rb @@ -193,9 +193,8 @@ module ActionController # # map.connect '*path' , :controller => 'blog' , :action => 'unrecognized?' # - # will glob all remaining parts of the route that were not recognized earlier. This idiom - # must appear at the end of the path. The globbed values are in params[:path] in - # this case. + # will glob all remaining parts of the route that were not recognized earlier. + # The globbed values are in params[:path] as an array of path segments. # # == Route conditions # diff --git a/actionpack/lib/action_controller/session_management.rb b/actionpack/lib/action_controller/session_management.rb index f06a0da75c..b556f04649 100644 --- a/actionpack/lib/action_controller/session_management.rb +++ b/actionpack/lib/action_controller/session_management.rb @@ -37,7 +37,7 @@ module ActionController #:nodoc: # Returns the hash used to configure the session. Example use: # - # ActionController::Base.session_options[:session_secure] = true # session only available over HTTPS + # ActionController::Base.session_options[:secure] = true # session only available over HTTPS def session_options @session_options ||= {} end diff --git a/actionpack/lib/action_view/helpers/asset_tag_helper.rb b/actionpack/lib/action_view/helpers/asset_tag_helper.rb index 58f8cca6be..f6abea38ed 100644 --- a/actionpack/lib/action_view/helpers/asset_tag_helper.rb +++ b/actionpack/lib/action_view/helpers/asset_tag_helper.rb @@ -6,54 +6,70 @@ module ActionView module Helpers #:nodoc: # This module provides methods for generating HTML that links views to assets such # as images, javascripts, stylesheets, and feeds. These methods do not verify - # the assets exist before linking to them. + # the assets exist before linking to them: + # + # image_tag("rails.png") + # # => Rails src= + # stylesheet_link_tag("application") + # # => # # === Using asset hosts + # # By default, Rails links to these assets on the current host in the public - # folder, but you can direct Rails to link to assets from a dedicated assets server by - # setting ActionController::Base.asset_host in your config/environment.rb. For example, - # let's say your asset host is assets.example.com. + # folder, but you can direct Rails to link to assets from a dedicated asset + # server by setting ActionController::Base.asset_host in the application + # configuration, typically in config/environments/production.rb. + # For example, you'd define assets.example.com to be your asset + # host this way: # # ActionController::Base.asset_host = "assets.example.com" + # + # Helpers take that into account: + # # image_tag("rails.png") - # => Rails + # # => Rails # stylesheet_link_tag("application") - # => + # # => # - # This is useful since browsers typically open at most two connections to a single host, - # which means your assets often wait in single file for their turn to load. You can - # alleviate this by using a %d wildcard in asset_host (for example, "assets%d.example.com") - # to automatically distribute asset requests among four hosts (e.g., "assets0.example.com" through "assets3.example.com") - # so browsers will open eight connections rather than two. + # Browsers typically open at most two simultaneous connections to a single + # host, which means your assets often have to wait for other assets to finish + # downloading. You can alleviate this by using a %d wildcard in the + # +asset_host+. For example, "assets%d.example.com". If that wildcard is + # present Rails distributes asset requests among the corresponding four hosts + # "assets0.example.com", ..., "assets3.example.com". With this trick browsers + # will open eight simultaneous connections rather than two. # # image_tag("rails.png") - # => Rails + # # => Rails # stylesheet_link_tag("application") - # => + # # => # - # To do this, you can either setup 4 actual hosts, or you can use wildcard DNS to CNAME - # the wildcard to a single asset host. You can read more about setting up your DNS CNAME records from - # your ISP. + # To do this, you can either setup four actual hosts, or you can use wildcard + # DNS to CNAME the wildcard to a single asset host. You can read more about + # setting up your DNS CNAME records from your ISP. # # Note: This is purely a browser performance optimization and is not meant # for server load balancing. See http://www.die.net/musings/page_load_time/ # for background. # - # Alternatively, you can exert more control over the asset host by setting asset_host to a proc - # that takes a single source argument. This is useful if you are unable to setup 4 actual hosts or have - # fewer/more than 4 hosts. The example proc below generates http://assets1.example.com and - # http://assets2.example.com randomly. + # Alternatively, you can exert more control over the asset host by setting + # +asset_host+ to a proc like this: # - # ActionController::Base.asset_host = Proc.new { |source| "http://assets#{rand(2) + 1}.example.com" } + # ActionController::Base.asset_host = Proc.new { |source| + # "http://assets#{rand(2) + 1}.example.com" + # } # image_tag("rails.png") - # => Rails + # # => Rails # stylesheet_link_tag("application") - # => + # # => # - # The proc takes a source parameter (which is the path of the source asset) and an optional - # request parameter (which is an entire instance of an ActionController::AbstractRequest - # subclass). This can be used to generate a particular asset host depending on the asset path and the particular - # request. + # The example above generates "http://assets1.example.com" and + # "http://assets2.example.com" randomly. This option is useful for example if + # you need fewer/more than four hosts, custom host names, etc. + # + # As you see the proc takes a +source+ parameter. That's a string with the + # absolute path of the asset with any extensions and timestamps in place, + # for example "/images/rails.png?1230601161". # # ActionController::Base.asset_host = Proc.new { |source| # if source.starts_with?('/images') @@ -63,14 +79,16 @@ module ActionView # end # } # image_tag("rails.png") - # => Rails + # # => Rails # stylesheet_link_tag("application") - # => + # # => # - # The optional request parameter to the proc is useful in particular for serving assets from an - # SSL-protected page. The example proc below disables asset hosting for HTTPS connections, while still sending - # assets for plain HTTP requests from asset hosts. This is useful for avoiding mixed media warnings when serving - # non-HTTP assets from HTTPS web pages when you don't have an SSL certificate for each of the asset hosts. + # Alternatively you may ask for a second parameter +request+. That one is + # particularly useful for serving assets from an SSL-protected page. The + # example proc below disables asset hosting for HTTPS connections, while + # still sending assets for plain HTTP requests from asset hosts. If you don't + # have SSL certificates for each of the asset hosts this technique allows you + # to avoid warnings in the client about mixed media. # # ActionController::Base.asset_host = Proc.new { |source, request| # if request.ssl? @@ -80,7 +98,8 @@ module ActionView # end # } # - # You can also implement a custom asset host object that responds to the call method and tasks one or two parameters just like the proc. + # You can also implement a custom asset host object that responds to +call+ + # and takes either one or two parameters just like the proc. # # config.action_controller.asset_host = AssetHostingWithMinimumSsl.new( # "http://asset%d.example.com", "https://asset1.example.com" @@ -88,24 +107,29 @@ module ActionView # # === Using asset timestamps # - # By default, Rails will append all asset paths with that asset's timestamp. This allows you to set a cache-expiration date for the - # asset far into the future, but still be able to instantly invalidate it by simply updating the file (and hence updating the timestamp, - # which then updates the URL as the timestamp is part of that, which in turn busts the cache). + # By default, Rails appends asset's timestamps to all asset paths. This allows + # you to set a cache-expiration date for the asset far into the future, but + # still be able to instantly invalidate it by simply updating the file (and + # hence updating the timestamp, which then updates the URL as the timestamp + # is part of that, which in turn busts the cache). # - # It's the responsibility of the web server you use to set the far-future expiration date on cache assets that you need to take - # advantage of this feature. Here's an example for Apache: + # It's the responsibility of the web server you use to set the far-future + # expiration date on cache assets that you need to take advantage of this + # feature. Here's an example for Apache: # - # # Asset Expiration - # ExpiresActive On - # - # ExpiresDefault "access plus 1 year" - # + # # Asset Expiration + # ExpiresActive On + # + # ExpiresDefault "access plus 1 year" + # # - # Also note that in order for this to work, all your application servers must return the same timestamps. This means that they must - # have their clocks synchronized. If one of them drift out of sync, you'll see different timestamps at random and the cache won't - # work. Which means that the browser will request the same assets over and over again even thought they didn't change. You can use - # something like Live HTTP Headers for Firefox to verify that the cache is indeed working (and that the assets are not being - # requested over and over). + # Also note that in order for this to work, all your application servers must + # return the same timestamps. This means that they must have their clocks + # synchronized. If one of them drifts out of sync, you'll see different + # timestamps at random and the cache won't work. In that case the browser + # will request the same assets over and over again even thought they didn't + # change. You can use something like Live HTTP Headers for Firefox to verify + # that the cache is indeed working. module AssetTagHelper ASSETS_DIR = defined?(Rails.public_path) ? Rails.public_path : "public" JAVASCRIPTS_DIR = "#{ASSETS_DIR}/javascripts" @@ -117,7 +141,7 @@ module ActionView # :atom. Control the link options in url_for format using the # +url_options+. You can modify the LINK tag itself in +tag_options+. # - # ==== Options: + # ==== Options # * :rel - Specify the relation of this link, defaults to "alternate" # * :type - Override the auto-generated mime type # * :title - Specify the title of the link, defaults to the +type+ -- cgit v1.2.3