diff --git a/activerecord/lib/active_record/base.rb b/activerecord/lib/active_record/base.rb index 6a1a3794a2..039e14435f 100755 --- a/activerecord/lib/active_record/base.rb +++ b/activerecord/lib/active_record/base.rb @@ -514,7 +514,7 @@ module ActiveRecord #:nodoc: # # ==== Parameters # - # * :conditions - An SQL fragment like "administrator = 1" or [ "user_name = ?", username ]. See conditions in the intro. + # * :conditions - An SQL fragment like "administrator = 1", [ "user_name = ?", username ], or ["user_name = :user_name", { :user_name => user_name }]. See conditions in the intro. # * :order - An SQL fragment like "created_at DESC, name". # * :group - An attribute name by which the result should be grouped. Uses the GROUP BY SQL-clause. # * :limit - An integer determining the limit on the number of rows that should be returned. @@ -551,6 +551,7 @@ module ActiveRecord #:nodoc: # # find first # Person.find(:first) # returns the first object fetched by SELECT * FROM people # Person.find(:first, :conditions => [ "user_name = ?", user_name]) + # Person.find(:first, :conditions => [ "user_name = :u", { :u => user_name }]) # Person.find(:first, :order => "created_on DESC", :offset => 5) # # # find last diff --git a/activerecord/lib/active_record/callbacks.rb b/activerecord/lib/active_record/callbacks.rb index dd7ae51096..42bfe34505 100644 --- a/activerecord/lib/active_record/callbacks.rb +++ b/activerecord/lib/active_record/callbacks.rb @@ -5,7 +5,7 @@ module ActiveRecord # before or after an alteration of the object state. This can be used to make sure that associated and # dependent objects are deleted when +destroy+ is called (by overwriting +before_destroy+) or to massage attributes # before they're validated (by overwriting +before_validation+). As an example of the callbacks initiated, consider - # the Base#save call: + # the Base#save call for a new record: # # * (-) save # * (-) valid @@ -22,7 +22,8 @@ module ActiveRecord # * (8) after_save # # That's a total of eight callbacks, which gives you immense power to react and prepare for each state in the - # Active Record lifecycle. + # Active Record lifecycle. The sequence for calling Base#save an existing record is similar, except that each + # _on_create callback is replaced by the corresponding _on_update callback. # # Examples: # class CreditCard < ActiveRecord::Base diff --git a/railties/doc/guides/actioncontroller/actioncontroller.txt b/railties/doc/guides/actioncontroller/actioncontroller.txt index c5a594d713..0b884e590b 100644 --- a/railties/doc/guides/actioncontroller/actioncontroller.txt +++ b/railties/doc/guides/actioncontroller/actioncontroller.txt @@ -15,6 +15,8 @@ include::cookies.txt[] include::filters.txt[] +include::verification.txt[] + include::request_response_objects.txt[] include::http_auth.txt[] @@ -23,6 +25,4 @@ include::streaming.txt[] include::parameter_filtering.txt[] -include::verification.txt[] - include::rescue.txt[] diff --git a/railties/doc/guides/actioncontroller/cookies.txt b/railties/doc/guides/actioncontroller/cookies.txt index a845e452b2..d451f3f7a6 100644 --- a/railties/doc/guides/actioncontroller/cookies.txt +++ b/railties/doc/guides/actioncontroller/cookies.txt @@ -2,22 +2,30 @@ Your application can store small amounts of data on the client - called cookies - that will be persisted across requests and even sessions. Rails provides easy access to cookies via the `cookies` method, which - much like the `session` - works like a hash: -TODO: Find a real-world example where cookies are used - [source, ruby] ----------------------------------------- -class FooController < ApplicationController +class CommentsController < ApplicationController - def foo - cookies[:foo] = "bar" + def new + #Auto-fill the commenter's name if it has been stored in a cookie + @comment = Comment.new(:name => cookies[:commenter_name]) end - def display_foo - @foo = cookies[:foo] - end - - def remove_foo - cookies.delete(:foo) + def create + @comment = Comment.new(params[:comment]) + if @comment.save + flash[:notice] = "Thanks for your comment!" + if params[:remember_name] + # Remember the commenter's name + cookies[:commenter_name] = @comment.name + else + # Don't remember, and delete the name if it has been remembered before + cookies.delete(:commenter_name) + end + redirect_to @comment.article + else + render :action => "new" + end end end diff --git a/railties/doc/guides/actioncontroller/filters.txt b/railties/doc/guides/actioncontroller/filters.txt index 2baf92d6ef..a7b8d9727f 100644 --- a/railties/doc/guides/actioncontroller/filters.txt +++ b/railties/doc/guides/actioncontroller/filters.txt @@ -27,7 +27,7 @@ private end --------------------------------- -The method simply stores an error message in the flash and redirects to the login form if the user is not logged in. If a before filter (a filter which is run before the action) renders or redirects, the action will not run. If there are additional filters scheduled to run after the rendering/redirecting filter, they are also cancelled. To use this filter in a controller, use the "before_filter":http://api.rubyonrails.org/classes/ActionController/Filters/ClassMethods.html#M000704 method: +The method simply stores an error message in the flash and redirects to the login form if the user is not logged in. If a before filter (a filter which is run before the action) renders or redirects, the action will not run. If there are additional filters scheduled to run after the rendering/redirecting filter, they are also cancelled. To use this filter in a controller, use the link:http://api.rubyonrails.org/classes/ActionController/Filters/ClassMethods.html#M000704[before_filter] method: [source, ruby] --------------------------------- @@ -38,7 +38,7 @@ class ApplicationController < ActionController::Base end --------------------------------- -In this example, the filter is added to ApplicationController and thus all controllers in the application. This will make everything in the application require the user to be logged in in order to use it. For obvious reasons (the user wouldn't be able to log in in the first place!), not all controllers or actions should require this, so to prevent this filter from running you can use "skip_before_filter":http://api.rubyonrails.org/classes/ActionController/Filters/ClassMethods.html#M000711 : +In this example, the filter is added to ApplicationController and thus all controllers in the application. This will make everything in the application require the user to be logged in in order to use it. For obvious reasons (the user wouldn't be able to log in in the first place!), not all controllers or actions should require this, so to prevent this filter from running you can use link:http://api.rubyonrails.org/classes/ActionController/Filters/ClassMethods.html#M000711[skip_before_filter] : [source, ruby] --------------------------------- @@ -59,24 +59,27 @@ TODO: Find a real example for an around filter [source, ruby] --------------------------------- +# Example taken from the Rails API filter documentation: +# http://api.rubyonrails.org/classes/ActionController/Filters/ClassMethods.html class ApplicationController < Application - around_filter :foo + around_filter :catch_exceptions private - def foo - logger.debug("Action has not been run yet") - yield #Run the action - logger.debug("Action has been run") + def catch_exceptions + yield + rescue => exception + logger.debug "Caught exception! #{exception}" + raise end end --------------------------------- -=== Other types of filters === +=== Other ways to use filters === -While the most common way to use filters is by creating private methods and using *_filter to add them, there are two other ways. +While the most common way to use filters is by creating private methods and using *_filter to add them, there are two other ways to do the same thing. The first is to use a block directly with the *_filter methods. The block receives the controller as an argument, and the `require_login` filter from above could be rewritte to use a block: @@ -115,4 +118,4 @@ end Again, this is not an ideal example for this filter, because it's not run in the scope of the controller but gets it passed as an argument. The filter class has a class method `filter` which gets run before or after the action, depending on if it's a before or after filter. Classes used as around filters can also use the same `filter` method, which will get run in the same way. The method must `yield` to execute the action. Alternatively, it can have both a `before` and an `after` method that are run before and after the action. -The Rails API documentation has "more information and detail on using filters":http://api.rubyonrails.org/classes/ActionController/Filters/ClassMethods.html +The Rails API documentation has link:http://api.rubyonrails.org/classes/ActionController/Filters/ClassMethods.html[more information on using filters]. diff --git a/railties/doc/guides/actioncontroller/http_auth.txt b/railties/doc/guides/actioncontroller/http_auth.txt index 5a95de0bb3..7df0e635bf 100644 --- a/railties/doc/guides/actioncontroller/http_auth.txt +++ b/railties/doc/guides/actioncontroller/http_auth.txt @@ -1,6 +1,6 @@ == HTTP Basic Authentication == -Rails comes with built-in HTTP Basic authentication. This is an authentication scheme that is supported by the majority of browsers and other HTTP clients. As an example, we will create an administration section which will only be available by entering a username and a password into the browser's HTTP Basic dialog window. Using the built-in authentication is quite easy and only requires you to use one method, "authenticate_or_request_with_http_basic":http://api.rubyonrails.org/classes/ActionController/HttpAuthentication/Basic/ControllerMethods.html#M000610 +Rails comes with built-in HTTP Basic authentication. This is an authentication scheme that is supported by the majority of browsers and other HTTP clients. As an example, we will create an administration section which will only be available by entering a username and a password into the browser's HTTP Basic dialog window. Using the built-in authentication is quite easy and only requires you to use one method, link:http://api.rubyonrails.org/classes/ActionController/HttpAuthentication/Basic/ControllerMethods.html#M000610[authenticate_or_request_with_http_basic]. [source, ruby] ------------------------------------- diff --git a/railties/doc/guides/actioncontroller/introduction.txt b/railties/doc/guides/actioncontroller/introduction.txt index 35540bbc09..e4b0953b95 100644 --- a/railties/doc/guides/actioncontroller/introduction.txt +++ b/railties/doc/guides/actioncontroller/introduction.txt @@ -2,6 +2,6 @@ Action Controller is the C in MVC. After routing has determined which controller to use for a request, your controller is responsible for making sense of the request and producing the appropriate output. Luckily, Action Controller does most of the groundwork for you and uses smart conventions to make this as straight-forward as possible. -For most conventional RESTful applications, the controller will receive the request (this is invisible to the developer), fetch or save data from a model and use a view to create HTML output. If your controller needs to do things a little differently, that's not a problem, this is just the most common way for a controller to work. +For most conventional RESTful applications, the controller will receive the request (this is invisible to you as the developer), fetch or save data from a model and use a view to create HTML output. If your controller needs to do things a little differently, that's not a problem, this is just the most common way for a controller to work. A controller can thus be thought of as a middle man between models and views. It makes the model data available to the view so it can display it to the user, and it saves or updates data from the user to the model. diff --git a/railties/doc/guides/actioncontroller/methods.txt b/railties/doc/guides/actioncontroller/methods.txt index 0818dbb849..a1ef204adb 100644 --- a/railties/doc/guides/actioncontroller/methods.txt +++ b/railties/doc/guides/actioncontroller/methods.txt @@ -1,6 +1,6 @@ == Methods and actions == -A controller is a Ruby class which inherits from ActionController::Base and has methods just like any other class. Usually these methods correspond to actions in MVC, but they can just as well be helpful methods which can be called by actions. When your application receives a request, the routing will determine which controller and action to run. Then an instance of that controller will be created and the method corresponding to the action (the method with the same name as the action) is run. +A controller is a Ruby class which inherits from ActionController::Base and has methods just like any other class. Usually these methods correspond to actions in MVC, but they can just as well be helpful methods which can be called by actions. When your application receives a request, the routing will determine which controller and action to run. Then an instance of that controller will be created and the method corresponding to the action (the method with the same name as the action) gets run. [source, ruby] ---------------------------------------------- diff --git a/railties/doc/guides/actioncontroller/parameter_filtering.txt b/railties/doc/guides/actioncontroller/parameter_filtering.txt index dce4b252c3..c4577d4f6d 100644 --- a/railties/doc/guides/actioncontroller/parameter_filtering.txt +++ b/railties/doc/guides/actioncontroller/parameter_filtering.txt @@ -1,6 +1,6 @@ == Parameter filtering == -Rails keeps a log file for each environment (development, test and production) in the "log" folder. These are extremely useful when debugging what's actually going on in your application, but in a live application you may not want every bit of information to be stored in the log file. The "filter_parameter_logging":http://api.rubyonrails.org/classes/ActionController/Base.html#M000837 can be used to filter out sensitive information from the log. It works by replacing certain keys in the `params` hash with "[FILTERED]" before they are written to the log. As an example, let's see how to filter all parameters with keys that include "password": +Rails keeps a log file for each environment (development, test and production) in the "log" folder. These are extremely useful when debugging what's actually going on in your application, but in a live application you may not want every bit of information to be stored in the log file. The link:http://api.rubyonrails.org/classes/ActionController/Base.html#M000837[filter_parameter_logging] method can be used to filter out sensitive information from the log. It works by replacing certain keys in the `params` hash with "[FILTERED]" as they are written to the log. As an example, let's see how to filter all parameters with keys that include "password": [source, ruby] ------------------------- diff --git a/railties/doc/guides/actioncontroller/params.txt b/railties/doc/guides/actioncontroller/params.txt index 67f97b6135..7f494d7c9b 100644 --- a/railties/doc/guides/actioncontroller/params.txt +++ b/railties/doc/guides/actioncontroller/params.txt @@ -8,7 +8,7 @@ class ClientsController < ActionController::Base # This action uses query string parameters because it gets run by a HTTP GET request, # but this does not make any difference to the way in which the parameters are accessed. - # The URL for this action would look like this in order to list activated clients: /clients/?status=activated + # The URL for this action would look like this in order to list activated clients: /clients?status=activated def index if params[:status] = "activated" @clients = Client.activated @@ -47,7 +47,7 @@ The value of `params[:ids]` will now be `["1", "2", "3"]`. Note that parameter v To send a hash you include the key name inside the brackets: ------------------------------------- -