diff options
Diffstat (limited to 'actionpack/lib/action_controller')
8 files changed, 93 insertions, 79 deletions
diff --git a/actionpack/lib/action_controller/assertions/selector_assertions.rb b/actionpack/lib/action_controller/assertions/selector_assertions.rb index 272b8f6841..9ef093acfc 100644 --- a/actionpack/lib/action_controller/assertions/selector_assertions.rb +++ b/actionpack/lib/action_controller/assertions/selector_assertions.rb @@ -21,11 +21,11 @@ module ActionController # from the response HTML or elements selected by the enclosing assertion. # # In addition to HTML responses, you can make the following assertions: - # * #assert_select_rjs -- Assertions on HTML content of RJS update and + # * +assert_select_rjs+ - Assertions on HTML content of RJS update and # insertion operations. - # * #assert_select_encoded -- Assertions on HTML encoded inside XML, + # * +assert_select_encoded+ - Assertions on HTML encoded inside XML, # for example for dealing with feed item descriptions. - # * #assert_select_email -- Assertions on the HTML body of an e-mail. + # * +assert_select_email+ - Assertions on the HTML body of an e-mail. # # Also see HTML::Selector to learn how to use selectors. module SelectorAssertions @@ -136,27 +136,27 @@ module ActionController # === Equality Tests # # The equality test may be one of the following: - # * <tt>true</tt> -- Assertion is true if at least one element selected. - # * <tt>false</tt> -- Assertion is true if no element selected. - # * <tt>String/Regexp</tt> -- Assertion is true if the text value of at least + # * <tt>true</tt> - Assertion is true if at least one element selected. + # * <tt>false</tt> - Assertion is true if no element selected. + # * <tt>String/Regexp</tt> - Assertion is true if the text value of at least # one element matches the string or regular expression. - # * <tt>Integer</tt> -- Assertion is true if exactly that number of + # * <tt>Integer</tt> - Assertion is true if exactly that number of # elements are selected. - # * <tt>Range</tt> -- Assertion is true if the number of selected + # * <tt>Range</tt> - Assertion is true if the number of selected # elements fit the range. # If no equality test specified, the assertion is true if at least one # element selected. # # To perform more than one equality tests, use a hash with the following keys: - # * <tt>:text</tt> -- Narrow the selection to elements that have this text + # * <tt>:text</tt> - Narrow the selection to elements that have this text # value (string or regexp). - # * <tt>:html</tt> -- Narrow the selection to elements that have this HTML + # * <tt>:html</tt> - Narrow the selection to elements that have this HTML # content (string or regexp). - # * <tt>:count</tt> -- Assertion is true if the number of selected elements + # * <tt>:count</tt> - Assertion is true if the number of selected elements # is equal to this value. - # * <tt>:minimum</tt> -- Assertion is true if the number of selected + # * <tt>:minimum</tt> - Assertion is true if the number of selected # elements is at least this value. - # * <tt>:maximum</tt> -- Assertion is true if the number of selected + # * <tt>:maximum</tt> - Assertion is true if the number of selected # elements is at most this value. # # If the method is called with a block, once all equality tests are diff --git a/actionpack/lib/action_controller/base.rb b/actionpack/lib/action_controller/base.rb index c6d28b492a..e1bf005f39 100755 --- a/actionpack/lib/action_controller/base.rb +++ b/actionpack/lib/action_controller/base.rb @@ -159,28 +159,34 @@ module ActionController #:nodoc: # # Hello #{session[:person]} # - # For removing objects from the session, you can either assign a single key to nil, like <tt>session[:person] = nil</tt>, or you can - # remove the entire session with reset_session. + # For removing objects from the session, you can either assign a single key to +nil+: # - # Sessions are stored in a browser cookie that's cryptographically signed, but unencrypted, by default. This prevents - # the user from tampering with the session but also allows him to see its contents. + # # removes :person from session + # session[:person] = nil # - # Do not put secret information in session! + # or you can remove the entire session with +reset_session+. + # + # Sessions are stored by default in a browser cookie that's cryptographically signed, but unencrypted. + # This prevents the user from tampering with the session but also allows him to see its contents. + # + # Do not put secret information in cookie-based sessions! # # Other options for session storage are: # - # ActiveRecordStore: sessions are stored in your database, which works better than PStore with multiple app servers and, - # unlike CookieStore, hides your session contents from the user. To use ActiveRecordStore, set + # * ActiveRecordStore - Sessions are stored in your database, which works better than PStore with multiple app servers and, + # unlike CookieStore, hides your session contents from the user. To use ActiveRecordStore, set # - # config.action_controller.session_store = :active_record_store + # config.action_controller.session_store = :active_record_store # - # in your <tt>environment.rb</tt> and run <tt>rake db:sessions:create</tt>. + # in your <tt>config/environment.rb</tt> and run <tt>rake db:sessions:create</tt>. # - # MemCacheStore: sessions are stored as entries in your memcached cache. Set the session store type in <tt>environment.rb</tt>: + # * MemCacheStore - Sessions are stored as entries in your memcached cache. + # Set the session store type in <tt>config/environment.rb</tt>: # - # config.action_controller.session_store = :mem_cache_store + # config.action_controller.session_store = :mem_cache_store # - # This assumes that memcached has been installed and configured properly. See the MemCacheStore docs for more information. + # This assumes that memcached has been installed and configured properly. + # See the MemCacheStore docs for more information. # # == Responses # @@ -535,20 +541,20 @@ module ActionController #:nodoc: # # <tt>url_for</tt> is used to: # - # All keys given to url_for are forwarded to the Route module, save for the following: - # * <tt>:anchor</tt> -- specifies the anchor name to be appended to the path. For example, + # All keys given to +url_for+ are forwarded to the Route module, save for the following: + # * <tt>:anchor</tt> - Specifies the anchor name to be appended to the path. For example, # <tt>url_for :controller => 'posts', :action => 'show', :id => 10, :anchor => 'comments'</tt> # will produce "/posts/show/10#comments". - # * <tt>:only_path</tt> -- if true, returns the relative URL (omitting the protocol, host name, and port) (<tt>false</tt> by default) - # * <tt>:trailing_slash</tt> -- if true, adds a trailing slash, as in "/archive/2005/". Note that this + # * <tt>:only_path</tt> - If true, returns the relative URL (omitting the protocol, host name, and port) (<tt>false</tt> by default). + # * <tt>:trailing_slash</tt> - If true, adds a trailing slash, as in "/archive/2005/". Note that this # is currently not recommended since it breaks caching. - # * <tt>:host</tt> -- overrides the default (current) host if provided. - # * <tt>:protocol</tt> -- overrides the default (current) protocol if provided. - # * <tt>:port</tt> -- optionally specify the port to connect to. - # * <tt>:user</tt> -- Inline HTTP authentication (only plucked out if <tt>:password</tt> is also present). - # * <tt>:password</tt> -- Inline HTTP authentication (only plucked out if <tt>:user</tt> is also present). - # * <tt>:skip_relative_url_root</tt> -- if true, the url is not constructed using the relative_url_root of the request so the path - # will include the web server relative installation directory. + # * <tt>:host</tt> - Overrides the default (current) host if provided. + # * <tt>:protocol</tt> - Overrides the default (current) protocol if provided. + # * <tt>:port</tt> - Optionally specify the port to connect to. + # * <tt>:user</tt> - Inline HTTP authentication (only plucked out if <tt>:password</tt> is also present). + # * <tt>:password</tt> - Inline HTTP authentication (only plucked out if <tt>:user</tt> is also present). + # * <tt>:skip_relative_url_root</tt> - If true, the url is not constructed using the +relative_url_root+ + # of the request so the path will include the web server relative installation directory. # # The URL is generated from the remaining keys in the hash. A URL contains two key parts: the <base> and a query string. # Routes composes a query string as the key/value pairs not included in the <base>. diff --git a/actionpack/lib/action_controller/caching.rb b/actionpack/lib/action_controller/caching.rb index 08cbd13876..c4063dfb4b 100644 --- a/actionpack/lib/action_controller/caching.rb +++ b/actionpack/lib/action_controller/caching.rb @@ -20,7 +20,8 @@ module ActionController #:nodoc: # # == Caching stores # - # All the caching stores from ActiveSupport::Cache is available to be used as backends for Action Controller caching. + # All the caching stores from ActiveSupport::Cache is available to be used as backends for Action Controller caching. This setting only + # affects action and fragment caching as page caching is always written to disk. # # Configuration examples (MemoryStore is the default): # diff --git a/actionpack/lib/action_controller/caching/pages.rb b/actionpack/lib/action_controller/caching/pages.rb index 7aa6ce154b..8ceac55a91 100644 --- a/actionpack/lib/action_controller/caching/pages.rb +++ b/actionpack/lib/action_controller/caching/pages.rb @@ -4,10 +4,11 @@ require 'uri' module ActionController #:nodoc: module Caching # Page caching is an approach to caching where the entire action output of is stored as a HTML file that the web server - # can serve without going through the Action Pack. This can be as much as 100 times faster than going through the process of dynamically - # generating the content. Unfortunately, this incredible speed-up is only available to stateless pages where all visitors - # are treated the same. Content management systems -- including weblogs and wikis -- have many pages that are a great fit - # for this approach, but account-based systems where people log in and manipulate their own data are often less likely candidates. + # can serve without going through the Action Pack. This is the fastest way to cache your content as opposed to going dynamically + # through the process of generating the content. Unfortunately, this incredible speed-up is only available to stateless pages + # where all visitors are treated the same. Content management systems -- including weblogs and wikis -- have many pages that are + # a great fit for this approach, but account-based systems where people log in and manipulate their own data are often less + # likely candidates. # # Specifying which actions to cache is done through the <tt>caches</tt> class method: # @@ -15,7 +16,7 @@ module ActionController #:nodoc: # caches_page :show, :new # end # - # This will generate cache files such as weblog/show/5 and weblog/new, which match the URLs used to trigger the dynamic + # This will generate cache files such as weblog/show/5.html and weblog/new.html, which match the URLs used to trigger the dynamic # generation. This is how the web server is able pick up a cache file when it exists and otherwise let the request pass on to # the Action Pack to generate it. # @@ -36,12 +37,16 @@ module ActionController #:nodoc: # == Setting the cache directory # # The cache directory should be the document root for the web server and is set using Base.page_cache_directory = "/document/root". - # For Rails, this directory has already been set to Rails.public_path (which is usually set to RAILS_ROOT + "/public"). + # For Rails, this directory has already been set to Rails.public_path (which is usually set to RAILS_ROOT + "/public"). Changing + # this setting can be useful to avoid naming conflicts with files in public/, but doing so will likely require configuring your + # web server to look in the new location for cached files. # # == Setting the cache extension # - # By default, the cache extension is .html, which makes it easy for the cached files to be picked up by the web server. If you want - # something else, like .php or .shtml, just set Base.page_cache_extension. + # Most Rails requests do not have an extension, such as /weblog/new. In these cases, the page caching mechanism will add one in + # order to make it easy for the cached files to be picked up properly by the web server. By default, this cache extension is .html. + # If you want something else, like .php or .shtml, just set Base.page_cache_extension. In cases where a request already has an + # extension, such as .xml or .rss, page caching will not add an extension. This allows it to work well with RESTful apps. module Pages def self.included(base) #:nodoc: base.extend(ClassMethods) diff --git a/actionpack/lib/action_controller/polymorphic_routes.rb b/actionpack/lib/action_controller/polymorphic_routes.rb index aa0e05dbd7..e2b7716aa2 100644 --- a/actionpack/lib/action_controller/polymorphic_routes.rb +++ b/actionpack/lib/action_controller/polymorphic_routes.rb @@ -47,25 +47,27 @@ module ActionController # Constructs a call to a named RESTful route for the given record and returns the # resulting URL string. For example: # - # polymorphic_url(post) - # # calls post_url(post) #=> "http://example.com/posts/1" + # # calls post_url(post) + # polymorphic_url(post) # => "http://example.com/posts/1" # # ==== Options - # * <tt>:action</tt> -- specifies the action prefix for the named route: - # <tt>:new</tt>, <tt>:edit</tt> or <tt>:formatted</tt>. Default is no prefix. - # * <tt>:routing_type</tt> -- <tt>:path</tt> or <tt>:url</tt> (default <tt>:url</tt>). + # + # * <tt>:action</tt> - Specifies the action prefix for the named route: + # <tt>:new</tt>, <tt>:edit</tt>, or <tt>:formatted</tt>. Default is no prefix. + # * <tt>:routing_type</tt> - Allowed values are <tt>:path</tt> or <tt>:url</tt>. + # Default is <tt>:url</tt>. # # ==== Examples # # # an Article record - # polymorphic_url(record) #-> article_url(record) + # polymorphic_url(record) # same as article_url(record) # # # a Comment record - # polymorphic_url(record) #-> comment_url(record) + # polymorphic_url(record) # same as comment_url(record) # # # it recognizes new records and maps to the collection # record = Comment.new - # polymorphic_url(record) #-> comments_url() + # polymorphic_url(record) # same as comments_url() # def polymorphic_url(record_or_hash_or_array, options = {}) if record_or_hash_or_array.kind_of?(Array) diff --git a/actionpack/lib/action_controller/request_forgery_protection.rb b/actionpack/lib/action_controller/request_forgery_protection.rb index 7e6961d25f..5daf14eb30 100644 --- a/actionpack/lib/action_controller/request_forgery_protection.rb +++ b/actionpack/lib/action_controller/request_forgery_protection.rb @@ -69,10 +69,10 @@ module ActionController #:nodoc: # # Valid Options: # - # * <tt>:only/:except</tt> - passed to the <tt>before_filter</tt> call. Set which actions are verified. + # * <tt>:only/:except</tt> - Passed to the <tt>before_filter</tt> call. Set which actions are verified. # * <tt>:secret</tt> - Custom salt used to generate the <tt>form_authenticity_token</tt>. # Leave this off if you are using the cookie session store. - # * <tt>:digest</tt> - Message digest used for hashing. Defaults to 'SHA1' + # * <tt>:digest</tt> - Message digest used for hashing. Defaults to 'SHA1'. def protect_from_forgery(options = {}) self.request_forgery_protection_token ||= :authenticity_token before_filter :verify_authenticity_token, :only => options.delete(:only), :except => options.delete(:except) diff --git a/actionpack/lib/action_controller/resources.rb b/actionpack/lib/action_controller/resources.rb index c5e7dd7359..26f75780c1 100644 --- a/actionpack/lib/action_controller/resources.rb +++ b/actionpack/lib/action_controller/resources.rb @@ -236,27 +236,27 @@ module ActionController # which takes into account whether <tt>@message</tt> is a new record or not and generates the # path and method accordingly. # - # The #resources method accepts the following options to customize the resulting routes: - # * <tt>:collection</tt> - add named routes for other actions that operate on the collection. + # The +resources+ method accepts the following options to customize the resulting routes: + # * <tt>:collection</tt> - Add named routes for other actions that operate on the collection. # Takes a hash of <tt>#{action} => #{method}</tt>, where method is <tt>:get</tt>/<tt>:post</tt>/<tt>:put</tt>/<tt>:delete</tt> - # or <tt>:any</tt> if the method does not matter. These routes map to a URL like /messages/rss, with a route of rss_messages_url. - # * <tt>:member</tt> - same as <tt>:collection</tt>, but for actions that operate on a specific member. - # * <tt>:new</tt> - same as <tt>:collection</tt>, but for actions that operate on the new resource action. - # * <tt>:controller</tt> - specify the controller name for the routes. - # * <tt>:singular</tt> - specify the singular name used in the member routes. - # * <tt>:requirements</tt> - set custom routing parameter requirements. - # * <tt>:conditions</tt> - specify custom routing recognition conditions. Resources sets the <tt>:method</tt> value for the method-specific routes. - # * <tt>:as</tt> - specify a different resource name to use in the URL path. For example: + # or <tt>:any</tt> if the method does not matter. These routes map to a URL like /messages/rss, with a route of +rss_messages_url+. + # * <tt>:member</tt> - Same as <tt>:collection</tt>, but for actions that operate on a specific member. + # * <tt>:new</tt> - Same as <tt>:collection</tt>, but for actions that operate on the new resource action. + # * <tt>:controller</tt> - Specify the controller name for the routes. + # * <tt>:singular</tt> - Specify the singular name used in the member routes. + # * <tt>:requirements</tt> - Set custom routing parameter requirements. + # * <tt>:conditions</tt> - Specify custom routing recognition conditions. Resources sets the <tt>:method</tt> value for the method-specific routes. + # * <tt>:as</tt> - Specify a different resource name to use in the URL path. For example: # # products_path == '/productos' # map.resources :products, :as => 'productos' do |product| # # product_reviews_path(product) == '/productos/1234/comentarios' # product.resources :product_reviews, :as => 'comentarios' # end # - # * <tt>:has_one</tt> - specify nested resources, this is a shorthand for mapping singleton resources beneath the current. - # * <tt>:has_many</tt> - same has <tt>:has_one</tt>, but for plural resources. + # * <tt>:has_one</tt> - Specify nested resources, this is a shorthand for mapping singleton resources beneath the current. + # * <tt>:has_many</tt> - Same has <tt>:has_one</tt>, but for plural resources. # - # You may directly specify the routing association with has_one and has_many like: + # You may directly specify the routing association with +has_one+ and +has_many+ like: # # map.resources :notes, :has_one => :author, :has_many => [:comments, :attachments] # @@ -268,14 +268,14 @@ module ActionController # notes.resources :attachments # end # - # * <tt>:path_names</tt> - specify different names for the 'new' and 'edit' actions. For example: + # * <tt>:path_names</tt> - Specify different names for the 'new' and 'edit' actions. For example: # # new_products_path == '/productos/nuevo' # map.resources :products, :as => 'productos', :path_names => { :new => 'nuevo', :edit => 'editar' } # # You can also set default action names from an environment, like this: # config.action_controller.resources_path_names = { :new => 'nuevo', :edit => 'editar' } # - # * <tt>:path_prefix</tt> - set a prefix to the routes with required route variables. + # * <tt>:path_prefix</tt> - Set a prefix to the routes with required route variables. # # Weblog comments usually belong to a post, so you might use resources like: # @@ -296,7 +296,7 @@ module ActionController # article_comments_url(:article_id => @article) # article_comment_url(:article_id => @article, :id => @comment) # - # * <tt>:name_prefix</tt> - define a prefix for all generated routes, usually ending in an underscore. + # * <tt>:name_prefix</tt> - Define a prefix for all generated routes, usually ending in an underscore. # Use this if you have named routes that may clash. # # map.resources :tags, :path_prefix => '/books/:book_id', :name_prefix => 'book_' @@ -343,7 +343,7 @@ module ActionController # # --> GET /categories/7/messages/1 # # has named route "category_message" # - # The #resources method sets HTTP method restrictions on the routes it generates. For example, making an + # The +resources+ method sets HTTP method restrictions on the routes it generates. For example, making an # HTTP POST on <tt>new_message_url</tt> will raise a RoutingError exception. The default route in # <tt>config/routes.rb</tt> overrides this and allows invalid HTTP methods for resource routes. def resources(*entities, &block) diff --git a/actionpack/lib/action_controller/url_rewriter.rb b/actionpack/lib/action_controller/url_rewriter.rb index b143806818..3a38f23396 100644 --- a/actionpack/lib/action_controller/url_rewriter.rb +++ b/actionpack/lib/action_controller/url_rewriter.rb @@ -29,16 +29,16 @@ module ActionController # Generate a url based on the options provided, default_url_options and the # routes defined in routes.rb. The following options are supported: # - # * <tt>:only_path</tt> If true, the relative url is returned. Defaults to +false+. - # * <tt>:protocol</tt> The protocol to connect to. Defaults to 'http'. - # * <tt>:host</tt> Specifies the host the link should be targetted at. + # * <tt>:only_path</tt> - If true, the relative url is returned. Defaults to +false+. + # * <tt>:protocol</tt> - The protocol to connect to. Defaults to 'http'. + # * <tt>:host</tt> - Specifies the host the link should be targetted at. # If <tt>:only_path</tt> is false, this option must be # provided either explicitly, or via +default_url_options+. - # * <tt>:port</tt> Optionally specify the port to connect to. - # * <tt>:anchor</tt> An anchor name to be appended to the path. - # * <tt>:skip_relative_url_root</tt> If true, the url is not constructed using the + # * <tt>:port</tt> - Optionally specify the port to connect to. + # * <tt>:anchor</tt> - An anchor name to be appended to the path. + # * <tt>:skip_relative_url_root</tt> - If true, the url is not constructed using the # +relative_url_root+ set in ActionController::AbstractRequest.relative_url_root. - # * <tt>:trailing_slash</tt> If true, adds a trailing slash, as in "/archive/2009/" + # * <tt>:trailing_slash</tt> - If true, adds a trailing slash, as in "/archive/2009/" # # Any other key (<tt>:controller</tt>, <tt>:action</tt>, etc.) given to # +url_for+ is forwarded to the Routes module. |