From dc4eec1129520ce9863c9373d7cb79d8636ab7ca Mon Sep 17 00:00:00 2001 From: Pratik Naik Date: Fri, 9 May 2008 10:38:02 +0100 Subject: Merge docrails: commit e6afd8b2736364322b673bbdcca3e9b38b6d3da0 Author: Xavier Noria Date: Thu May 8 23:49:36 2008 +0200 Overall documentation improvement and markup corrections. Zillion changes. commit 2fead68b3192332eee27945ed95a94a64ca73f70 Author: Austin Putman Date: Wed May 7 19:35:46 2008 -0700 Documented class methods on ActionController::Routing. These are dangerous, and mostly used for testing. commit f5b84182dbc39bea79c8ee319c688d00fa99f9d1 Author: Teflon Ted Date: Wed May 7 16:08:49 2008 -0400 Added explanation about errant inflections not being patched in the future in order to avoid breaking legacy applications. commit 370f4f51722cec49ace17093d29e9ce9e8f15cfb Author: Sunny Ripert Date: Wed May 7 14:00:59 2008 +0200 Applied list conventions in AR::Base commit 5bd18429f09d44e75191bec42a6db04bd33f3030 Author: Sunny Ripert Date: Wed May 7 13:53:35 2008 +0200 Renamed Options list to Attributes list whenever they weren't option hashes in AR::Base commit d912bd5672316454457ae83f6e9dda5197beeb6f Author: Yaroslav Markin Date: Wed May 7 13:50:28 2008 +0400 Add a filter_parameter_logging usage hint to generated ApplicationController. This may help to remind the developer to filter sensitive information from application logs. Closes #11578 commit b243de0db3c2605121e055079854af5090d06374 Author: Jack Danger Canty Date: Tue May 6 23:39:47 2008 -0700 doc: disambiguating an example ActiveRecord class commit f81d771f0657ae8375b84a77a059812cce5d6fd9 Author: Jack Danger Canty Date: Tue May 6 23:35:05 2008 -0700 doc: ActiveRecord::Reflection::AssociationReflection#through_reflection Added documentation demonstrating the use of #through_reflection for finding intervening reflection objects for HasManyThrough and HasOneThrough. commit ae6b46f00b5b8b2939c6b37ce3329c83de7e71db Author: Cheah Chu Yeow Date: Wed May 7 13:47:41 2008 +0800 Document AttributeAssignmentError and MultiparameterAssignmentErrors. commit 8f463550b597db2156b67733f31aed13487fbc3a Author: John Barnette Date: Tue May 6 22:46:44 2008 -0700 Killing/fixing a bunch of outdated language in the AR README. commit aca44bcd92ef783abdf484b58abdde6786db0f89 Author: Cheah Chu Yeow Date: Wed May 7 13:34:52 2008 +0800 Make a note about ActiveResource::Timeouterror being raised when ARes calls timeout. commit 284a930a93fbee16e25d06392779dbf2f03e9e12 Author: Jonathan Dance Date: Tue May 6 14:58:26 2008 -0400 improvements to the page caching docs commit 9482da621390c874da7c921c8bd6230caae7035a Author: Sunny Ripert Date: Mon May 5 18:13:40 2008 +0200 validates_numericality_of() "integer" option really is "only_integer" commit e9afd6790a8f530528f6597a7f59bb283be754f6 Author: Sunny Ripert Date: Mon May 5 12:11:59 2008 +0200 Harmonized hash notation in AR::Base commit 67ebf14a91ffd970b582be4ff2991d691a9cf3e1 Author: Sunny Ripert Date: Mon May 5 12:06:19 2008 +0200 Turned options into rdoc-lists in AR::Base commit 0ec7c0a41d889d4e5382b9dff72f1aaba89bf297 Author: Marshall Huss Date: Sun May 4 23:21:33 2008 -0400 Added information of how to set element_name in the case the user has a name confliction with an existing model Signed-off-by: Pratik Naik --- actionmailer/lib/action_mailer/base.rb | 25 +- .../assertions/selector_assertions.rb | 26 +- actionpack/lib/action_controller/base.rb | 52 ++-- actionpack/lib/action_controller/caching.rb | 3 +- actionpack/lib/action_controller/caching/pages.rb | 31 ++- .../lib/action_controller/polymorphic_routes.rb | 18 +- .../request_forgery_protection.rb | 4 +- actionpack/lib/action_controller/resources.rb | 34 +-- actionpack/lib/action_controller/routing.rb | 35 ++- .../session/active_record_store.rb | 21 +- actionpack/lib/action_controller/url_rewriter.rb | 14 +- actionpack/lib/action_view/base.rb | 24 +- .../lib/action_view/helpers/form_tag_helper.rb | 6 +- .../lib/action_view/helpers/prototype_helper.rb | 42 +++- actionpack/lib/action_view/helpers/url_helper.rb | 28 +-- .../lib/active_model/validations/associated.rb | 2 +- .../lib/active_model/validations/numericality.rb | 22 +- activerecord/README | 24 +- activerecord/lib/active_record/associations.rb | 275 +++++++++++---------- activerecord/lib/active_record/base.rb | 155 ++++++------ .../connection_adapters/abstract/query_cache.rb | 6 + .../connection_adapters/abstract_adapter.rb | 4 +- .../connection_adapters/mysql_adapter.rb | 24 +- .../connection_adapters/postgresql_adapter.rb | 18 +- .../connection_adapters/sqlite_adapter.rb | 2 +- activerecord/lib/active_record/fixtures.rb | 2 +- activerecord/lib/active_record/reflection.rb | 14 +- activerecord/lib/active_record/validations.rb | 8 +- activeresource/lib/active_resource/base.rb | 232 ++++++++--------- .../core_ext/hash/indifferent_access.rb | 43 ++-- activesupport/lib/active_support/inflector.rb | 5 + railties/helpers/application.rb | 5 + railties/lib/initializer.rb | 8 +- railties/lib/rails/plugin.rb | 16 +- 34 files changed, 658 insertions(+), 570 deletions(-) diff --git a/actionmailer/lib/action_mailer/base.rb b/actionmailer/lib/action_mailer/base.rb index 48e877a182..a3762bf81b 100644 --- a/actionmailer/lib/action_mailer/base.rb +++ b/actionmailer/lib/action_mailer/base.rb @@ -95,7 +95,7 @@ module ActionMailer #:nodoc: # # ActionMailer::Base.default_url_options[:host] = "example.com" # - # This can also be set as a configuration option in environment.rb: + # This can also be set as a configuration option in config/environment.rb: # # config.action_mailer.default_url_options = { :host => "example.com" } # @@ -204,22 +204,23 @@ module ActionMailer #:nodoc: # Can be set to nil for no logging. Compatible with both Ruby's own Logger and Log4r loggers. # # * smtp_settings - Allows detailed configuration for :smtp delivery method: - # * :address Allows you to use a remote mail server. Just change it from its default "localhost" setting. - # * :port On the off chance that your mail server doesn't run on port 25, you can change it. - # * :domain If you need to specify a HELO domain, you can do it here. - # * :user_name If your mail server requires authentication, set the username in this setting. - # * :password If your mail server requires authentication, set the password in this setting. - # * :authentication If your mail server requires authentication, you need to specify the authentication type here. + # * :address - Allows you to use a remote mail server. Just change it from its default "localhost" setting. + # * :port - On the off chance that your mail server doesn't run on port 25, you can change it. + # * :domain - If you need to specify a HELO domain, you can do it here. + # * :user_name - If your mail server requires authentication, set the username in this setting. + # * :password - If your mail server requires authentication, set the password in this setting. + # * :authentication - If your mail server requires authentication, you need to specify the authentication type here. # This is a symbol and one of :plain, :login, :cram_md5 # # * sendmail_settings - Allows you to override options for the :sendmail delivery method - # * :location The location of the sendmail executable, defaults to "/usr/sbin/sendmail" - # * :arguments The command line arguments - # * raise_delivery_errors - whether or not errors should be raised if the email fails to be delivered. + # * :location - The location of the sendmail executable, defaults to "/usr/sbin/sendmail" + # * :arguments - The command line arguments + # + # * raise_delivery_errors - Whether or not errors should be raised if the email fails to be delivered. # # * delivery_method - Defines a delivery method. Possible values are :smtp (default), :sendmail, and :test. # - # * perform_deliveries - Determines whether deliver_* methods are actually carried out. By default they are, + # * perform_deliveries - Determines whether deliver_* methods are actually carried out. By default they are, # but this can be turned off to help functional testing. # # * deliveries - Keeps an array of all the emails sent out through the Action Mailer with delivery_method :test. Most useful @@ -406,7 +407,7 @@ module ActionMailer #:nodoc: # templating language other than rhtml or rxml are supported. # To use this, include in your template-language plugin's init # code or on a per-application basis, this can be invoked from - # config/environment.rb: + # config/environment.rb: # # ActionMailer::Base.register_template_extension('haml') def register_template_extension(extension) 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: - # * true -- Assertion is true if at least one element selected. - # * false -- Assertion is true if no element selected. - # * String/Regexp -- Assertion is true if the text value of at least + # * true - Assertion is true if at least one element selected. + # * false - Assertion is true if no element selected. + # * String/Regexp - Assertion is true if the text value of at least # one element matches the string or regular expression. - # * Integer -- Assertion is true if exactly that number of + # * Integer - Assertion is true if exactly that number of # elements are selected. - # * Range -- Assertion is true if the number of selected + # * Range - 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: - # * :text -- Narrow the selection to elements that have this text + # * :text - Narrow the selection to elements that have this text # value (string or regexp). - # * :html -- Narrow the selection to elements that have this HTML + # * :html - Narrow the selection to elements that have this HTML # content (string or regexp). - # * :count -- Assertion is true if the number of selected elements + # * :count - Assertion is true if the number of selected elements # is equal to this value. - # * :minimum -- Assertion is true if the number of selected + # * :minimum - Assertion is true if the number of selected # elements is at least this value. - # * :maximum -- Assertion is true if the number of selected + # * :maximum - 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 session[:person] = nil, 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 environment.rb and run rake db:sessions:create. + # in your config/environment.rb and run rake db:sessions:create. # - # MemCacheStore: sessions are stored as entries in your memcached cache. Set the session store type in environment.rb: + # * MemCacheStore - Sessions are stored as entries in your memcached cache. + # Set the session store type in config/environment.rb: # - # 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: # # url_for is used to: # - # All keys given to url_for are forwarded to the Route module, save for the following: - # * :anchor -- 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: + # * :anchor - Specifies the anchor name to be appended to the path. For example, # url_for :controller => 'posts', :action => 'show', :id => 10, :anchor => 'comments' # will produce "/posts/show/10#comments". - # * :only_path -- if true, returns the relative URL (omitting the protocol, host name, and port) (false by default) - # * :trailing_slash -- if true, adds a trailing slash, as in "/archive/2005/". Note that this + # * :only_path - If true, returns the relative URL (omitting the protocol, host name, and port) (false by default). + # * :trailing_slash - If true, adds a trailing slash, as in "/archive/2005/". Note that this # is currently not recommended since it breaks caching. - # * :host -- overrides the default (current) host if provided. - # * :protocol -- overrides the default (current) protocol if provided. - # * :port -- optionally specify the port to connect to. - # * :user -- Inline HTTP authentication (only plucked out if :password is also present). - # * :password -- Inline HTTP authentication (only plucked out if :user is also present). - # * :skip_relative_url_root -- 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. + # * :host - Overrides the default (current) host if provided. + # * :protocol - Overrides the default (current) protocol if provided. + # * :port - Optionally specify the port to connect to. + # * :user - Inline HTTP authentication (only plucked out if :password is also present). + # * :password - Inline HTTP authentication (only plucked out if :user is also present). + # * :skip_relative_url_root - 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 and a query string. # Routes composes a query string as the key/value pairs not included in the . 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..a70ed72f03 100644 --- a/actionpack/lib/action_controller/caching/pages.rb +++ b/actionpack/lib/action_controller/caching/pages.rb @@ -4,23 +4,24 @@ 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 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 caches class method: + # Specifying which actions to cache is done through the caches_page class method: # # class WeblogController < ActionController::Base # 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 - # 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. + # 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 Action Pack to generate it. # # Expiration of the cache is handled by deleting the cached file, which results in a lazy regeneration approach where the cache - # is not restored before another hit is made against it. The API for doing so mimics the options from url_for and friends: + # is not restored before another hit is made against it. The API for doing so mimics the options from +url_for+ and friends: # # class WeblogController < ActionController::Base # def update @@ -35,13 +36,17 @@ 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"). + # 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"). 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 - # * :action -- specifies the action prefix for the named route: - # :new, :edit or :formatted. Default is no prefix. - # * :routing_type -- :path or :url (default :url). + # + # * :action - Specifies the action prefix for the named route: + # :new, :edit, or :formatted. Default is no prefix. + # * :routing_type - Allowed values are :path or :url. + # Default is :url. # # ==== 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: # - # * :only/:except - passed to the before_filter call. Set which actions are verified. + # * :only/:except - Passed to the before_filter call. Set which actions are verified. # * :secret - Custom salt used to generate the form_authenticity_token. # Leave this off if you are using the cookie session store. - # * :digest - Message digest used for hashing. Defaults to 'SHA1' + # * :digest - 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 @message 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: - # * :collection - add named routes for other actions that operate on the collection. + # The +resources+ method accepts the following options to customize the resulting routes: + # * :collection - Add named routes for other actions that operate on the collection. # Takes a hash of #{action} => #{method}, where method is :get/:post/:put/:delete - # or :any if the method does not matter. These routes map to a URL like /messages/rss, with a route of rss_messages_url. - # * :member - same as :collection, but for actions that operate on a specific member. - # * :new - same as :collection, but for actions that operate on the new resource action. - # * :controller - specify the controller name for the routes. - # * :singular - specify the singular name used in the member routes. - # * :requirements - set custom routing parameter requirements. - # * :conditions - specify custom routing recognition conditions. Resources sets the :method value for the method-specific routes. - # * :as - specify a different resource name to use in the URL path. For example: + # or :any if the method does not matter. These routes map to a URL like /messages/rss, with a route of +rss_messages_url+. + # * :member - Same as :collection, but for actions that operate on a specific member. + # * :new - Same as :collection, but for actions that operate on the new resource action. + # * :controller - Specify the controller name for the routes. + # * :singular - Specify the singular name used in the member routes. + # * :requirements - Set custom routing parameter requirements. + # * :conditions - Specify custom routing recognition conditions. Resources sets the :method value for the method-specific routes. + # * :as - 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 # - # * :has_one - specify nested resources, this is a shorthand for mapping singleton resources beneath the current. - # * :has_many - same has :has_one, but for plural resources. + # * :has_one - Specify nested resources, this is a shorthand for mapping singleton resources beneath the current. + # * :has_many - Same has :has_one, 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 # - # * :path_names - specify different names for the 'new' and 'edit' actions. For example: + # * :path_names - 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' } # - # * :path_prefix - set a prefix to the routes with required route variables. + # * :path_prefix - 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) # - # * :name_prefix - define a prefix for all generated routes, usually ending in an underscore. + # * :name_prefix - 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 new_message_url will raise a RoutingError exception. The default route in # config/routes.rb overrides this and allows invalid HTTP methods for resource routes. def resources(*entities, &block) diff --git a/actionpack/lib/action_controller/routing.rb b/actionpack/lib/action_controller/routing.rb index 0bffe21431..6aa266513d 100644 --- a/actionpack/lib/action_controller/routing.rb +++ b/actionpack/lib/action_controller/routing.rb @@ -15,7 +15,7 @@ module ActionController # The routing module provides URL rewriting in native Ruby. It's a way to # redirect incoming requests to controllers and actions. This replaces # mod_rewrite rules. Best of all, Rails' Routing works with any web server. - # Routes are defined in routes.rb in your RAILS_ROOT/config directory. + # Routes are defined in config/routes.rb. # # Consider the following route, installed by Rails when you generate your # application: @@ -53,7 +53,7 @@ module ActionController # == Route priority # # Not all routes are created equally. Routes have priority defined by the - # order of appearance of the routes in the routes.rb file. The priority goes + # order of appearance of the routes in the config/routes.rb file. The priority goes # from top to bottom. The last route in that file is at the lowest priority # and will be applied last. If no route matches, 404 is returned. # @@ -118,7 +118,7 @@ module ActionController # root_url # => 'http://www.example.com/' # root_path # => '' # - # You can also specify an already-defined named route in your map.root call: + # You can also specify an already-defined named route in your map.root call: # # # In routes.rb # map.new_session :controller => 'sessions', :action => 'new' @@ -217,7 +217,7 @@ module ActionController # ActionController::Routing::Routes.reload # # This will clear all named routes and reload routes.rb if the file has been modified from - # last load. To absolutely force reloading, use +reload!+. + # last load. To absolutely force reloading, use reload!. # # == Testing Routes # @@ -277,6 +277,9 @@ module ActionController end class << self + # Expects an array of controller names as the first argument. + # Executes the passed block with only the named controllers named available. + # This method is used in internal Rails testing. def with_controllers(names) prior_controllers = @possible_controllers use_controllers! names @@ -285,6 +288,10 @@ module ActionController use_controllers! prior_controllers end + # Returns an array of paths, cleaned of double-slashes and relative path references. + # * "\\\" and "//" become "\\" or "/". + # * "/foo/bar/../config" becomes "/foo/config". + # The returned array is sorted by length, descending. def normalize_paths(paths) # do the hokey-pokey of path normalization... paths = paths.collect do |path| @@ -303,6 +310,7 @@ module ActionController paths = paths.uniq.sort_by { |path| - path.length } end + # Returns the array of controller names currently available to ActionController::Routing. def possible_controllers unless @possible_controllers @possible_controllers = [] @@ -327,10 +335,28 @@ module ActionController @possible_controllers end + # Replaces the internal list of controllers available to ActionController::Routing with the passed argument. + # ActionController::Routing.use_controllers!([ "posts", "comments", "admin/comments" ]) def use_controllers!(controller_names) @possible_controllers = controller_names end + # Returns a controller path for a new +controller+ based on a +previous+ controller path. + # Handles 4 scenarios: + # + # * stay in the previous controller: + # controller_relative_to( nil, "groups/discussion" ) # => "groups/discussion" + # + # * stay in the previous namespace: + # controller_relative_to( "posts", "groups/discussion" ) # => "groups/posts" + # + # * forced move to the root namespace: + # controller_relative_to( "/posts", "groups/discussion" ) # => "posts" + # + # * previous namespace is root: + # controller_relative_to( "posts", "anything_with_no_slashes" ) # =>"posts" + # + def controller_relative_to(controller, previous) if controller.nil? then previous elsif controller[0] == ?/ then controller[1..-1] @@ -344,6 +370,7 @@ module ActionController Routes = RouteSet.new ::Inflector.module_eval do + # Ensures that routes are reloaded when Rails inflections are updated. def inflections_with_route_reloading(&block) returning(inflections_without_route_reloading(&block)) { ActionController::Routing::Routes.reload! if block_given? diff --git a/actionpack/lib/action_controller/session/active_record_store.rb b/actionpack/lib/action_controller/session/active_record_store.rb index 379fcd62b6..1e8eb57acb 100644 --- a/actionpack/lib/action_controller/session/active_record_store.rb +++ b/actionpack/lib/action_controller/session/active_record_store.rb @@ -13,7 +13,7 @@ class CGI # A session store backed by an Active Record class. A default class is - # provided, but any object duck-typing to an Active Record +Session+ class + # provided, but any object duck-typing to an Active Record Session class # with text +session_id+ and +data+ attributes is sufficient. # # The default assumes a +sessions+ tables with columns: @@ -26,13 +26,13 @@ class CGI # ActionController::SessionOverflowError will be raised. # # You may configure the table name, primary key, and data column. - # For example, at the end of config/environment.rb: + # For example, at the end of config/environment.rb: # CGI::Session::ActiveRecordStore::Session.table_name = 'legacy_session_table' # CGI::Session::ActiveRecordStore::Session.primary_key = 'session_id' # CGI::Session::ActiveRecordStore::Session.data_column_name = 'legacy_session_data' - # Note that setting the primary key to the session_id frees you from - # having a separate id column if you don't want it. However, you must - # set session.model.id = session.session_id by hand! A before_filter + # Note that setting the primary key to the +session_id+ frees you from + # having a separate +id+ column if you don't want it. However, you must + # set session.model.id = session.session_id by hand! A before filter # on ApplicationController is a good place. # # Since the default class is a simple Active Record, you get timestamps @@ -42,7 +42,7 @@ class CGI # You may provide your own session class implementation, whether a # feature-packed Active Record or a bare-metal high-performance SQL # store, by setting - # +CGI::Session::ActiveRecordStore.session_class = MySessionClass+ + # CGI::Session::ActiveRecordStore.session_class = MySessionClass # You must implement these methods: # self.find_by_session_id(session_id) # initialize(hash_of_session_id_and_data) @@ -154,8 +154,13 @@ class CGI # The database connection, table name, and session id and data columns # are configurable class attributes. Marshaling and unmarshaling # are implemented as class methods that you may override. By default, - # marshaling data is +ActiveSupport::Base64.encode64(Marshal.dump(data))+ and - # unmarshaling data is +Marshal.load(ActiveSupport::Base64.decode64(data))+. + # marshaling data is + # + # ActiveSupport::Base64.encode64(Marshal.dump(data)) + # + # and unmarshaling data is + # + # Marshal.load(ActiveSupport::Base64.decode64(data)) # # This marshaling behavior is intended to store the widest range of # binary session data in a +text+ column. For higher performance, 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: # - # * :only_path If true, the relative url is returned. Defaults to +false+. - # * :protocol The protocol to connect to. Defaults to 'http'. - # * :host Specifies the host the link should be targetted at. + # * :only_path - If true, the relative url is returned. Defaults to +false+. + # * :protocol - The protocol to connect to. Defaults to 'http'. + # * :host - Specifies the host the link should be targetted at. # If :only_path is false, this option must be # provided either explicitly, or via +default_url_options+. - # * :port Optionally specify the port to connect to. - # * :anchor An anchor name to be appended to the path. - # * :skip_relative_url_root If true, the url is not constructed using the + # * :port - Optionally specify the port to connect to. + # * :anchor - An anchor name to be appended to the path. + # * :skip_relative_url_root - If true, the url is not constructed using the # +relative_url_root+ set in ActionController::AbstractRequest.relative_url_root. - # * :trailing_slash If true, adds a trailing slash, as in "/archive/2009/" + # * :trailing_slash - If true, adds a trailing slash, as in "/archive/2009/" # # Any other key (:controller, :action, etc.) given to # +url_for+ is forwarded to the Routes module. diff --git a/actionpack/lib/action_view/base.rb b/actionpack/lib/action_view/base.rb index d32c6fbe35..4840b2526d 100644 --- a/actionpack/lib/action_view/base.rb +++ b/actionpack/lib/action_view/base.rb @@ -5,9 +5,9 @@ module ActionView #:nodoc: class MissingTemplate < ActionViewError #:nodoc: end - # Action View templates can be written in three ways. If the template file has a +.erb+ (or +.rhtml+) extension then it uses a mixture of ERb - # (included in Ruby) and HTML. If the template file has a +.builder+ (or +.rxml+) extension then Jim Weirich's Builder::XmlMarkup library is used. - # If the template file has a +.rjs+ extension then it will use ActionView::Helpers::PrototypeHelper::JavaScriptGenerator. + # Action View templates can be written in three ways. If the template file has a .erb (or .rhtml) extension then it uses a mixture of ERb + # (included in Ruby) and HTML. If the template file has a .builder (or .rxml) extension then Jim Weirich's Builder::XmlMarkup library is used. + # If the template file has a .rjs extension then it will use ActionView::Helpers::PrototypeHelper::JavaScriptGenerator. # # = ERb # @@ -24,7 +24,7 @@ module ActionView #:nodoc: # # Hi, Mr. <% puts "Frodo" %> # - # If you absolutely must write from within a function, you can use the TextHelper#concat + # If you absolutely must write from within a function, you can use the TextHelper#concat. # # <%- and -%> suppress leading and trailing whitespace, including the trailing newline, and can be used interchangeably with <% and %>. # @@ -46,7 +46,7 @@ module ActionView #:nodoc: # <% @page_title = "A Wonderful Hello" %> # <%= render "shared/header" %> # - # Now the header can pick up on the @page_title variable and use it for outputting a title tag: + # Now the header can pick up on the @page_title variable and use it for outputting a title tag: # # <%= @page_title %> # @@ -56,7 +56,7 @@ module ActionView #:nodoc: # # <%= render "shared/header", { :headline => "Welcome", :person => person } %> # - # These can now be accessed in shared/header with: + # These can now be accessed in shared/header with: # # Headline: <%= headline %> # First name: <%= person.first_name %> @@ -77,13 +77,13 @@ module ActionView #:nodoc: # # == Builder # - # Builder templates are a more programmatic alternative to ERb. They are especially useful for generating XML content. An +XmlMarkup+ object - # named +xml+ is automatically made available to templates with a +.builder+ extension. + # Builder templates are a more programmatic alternative to ERb. They are especially useful for generating XML content. An XmlMarkup object + # named +xml+ is automatically made available to templates with a .builder extension. # # Here are some basic examples: # # xml.em("emphasized") # => emphasized - # xml.em { xml.b("emph & bold") } # => emph & bold + # xml.em { xml.b("emph & bold") } # => emph & bold # xml.a("A Link", "href"=>"http://onestepback.org") # => A Link # xml.target("name"=>"compile", "option"=>"fast") # => # # NOTE: order of attributes is not specified. @@ -130,18 +130,18 @@ module ActionView #:nodoc: # # == JavaScriptGenerator # - # JavaScriptGenerator templates end in +.rjs+. Unlike conventional templates which are used to + # JavaScriptGenerator templates end in .rjs. Unlike conventional templates which are used to # render the results of an action, these templates generate instructions on how to modify an already rendered page. This makes it easy to # modify multiple elements on your page in one declarative Ajax response. Actions with these templates are called in the background with Ajax # and make updates to the page where the request originated from. # # An instance of the JavaScriptGenerator object named +page+ is automatically made available to your template, which is implicitly wrapped in an ActionView::Helpers::PrototypeHelper#update_page block. # - # When an .rjs action is called with +link_to_remote+, the generated JavaScript is automatically evaluated. Example: + # When an .rjs action is called with +link_to_remote+, the generated JavaScript is automatically evaluated. Example: # # link_to_remote :url => {:action => 'delete'} # - # The subsequently rendered +delete.rjs+ might look like: + # The subsequently rendered delete.rjs might look like: # # page.replace_html 'sidebar', :partial => 'sidebar' # page.remove "person-#{@person.id}" diff --git a/actionpack/lib/action_view/helpers/form_tag_helper.rb b/actionpack/lib/action_view/helpers/form_tag_helper.rb index f37b428b80..922a0662fe 100644 --- a/actionpack/lib/action_view/helpers/form_tag_helper.rb +++ b/actionpack/lib/action_view/helpers/form_tag_helper.rb @@ -316,12 +316,12 @@ module ActionView # Creates a submit button with the text value as the caption. # # ==== Options - # * :confirm => 'question?' -- This will add a JavaScript confirm + # * :confirm => 'question?' - This will add a JavaScript confirm # prompt with the question specified. If the user accepts, the form is # processed normally, otherwise no action is taken. - # * :disabled - If set to true, the user will not be able to use this input. + # * :disabled - If true, the user will not be able to use this input. # * :disable_with - Value of this parameter will be used as the value for a disabled version - # of the submit button when the form is submitted. + # of the submit button when the form is submitted. # * Any other key creates standard HTML options for the tag. # # ==== Examples diff --git a/actionpack/lib/action_view/helpers/prototype_helper.rb b/actionpack/lib/action_view/helpers/prototype_helper.rb index 908728c0e6..1b12aa8058 100644 --- a/actionpack/lib/action_view/helpers/prototype_helper.rb +++ b/actionpack/lib/action_view/helpers/prototype_helper.rb @@ -631,6 +631,27 @@ module ActionView # render(:update) { |page| page.update_time } # end # + # Calls to JavaScriptGenerator not matching a helper method below + # generate a proxy to the JavaScript Class named by the method called. + # + # Examples: + # + # # Generates: + # # Foo.init(); + # update_page do |page| + # page.foo.init + # end + # + # # Generates: + # # Event.observe('one', 'click', function () { + # # $('two').show(); + # # }); + # update_page do |page| + # page.event.observe('one', 'click') do |p| + # p[:two].show + # end + # end + # # You can also use PrototypeHelper#update_page_tag instead of # PrototypeHelper#update_page to wrap the generated JavaScript in a #