Merge pull request rails#51645 from notapatch/pr-guides-acion-controller-action-callbacks

carlosantoniodasilva · web-flow · commit 1d13a7c44d20 · 2024-04-23T12:09:00.000-03:00
Update guides: Replace filter with action callback [ci skip]

Rails 4.2 onwards replaced filter with action callback. However, the term has remained in the rails guides and this PR fixes this.

Types of change:

* Filter(s) =&gt; Action callback(s)
* Generalized the word "Action callbacks" as it is longer.
* actions =&gt; "controller actions" to make "controller actions" more distinct from "action callbacks".
diff --git a/guides/source/action_controller_overview.md b/guides/source/action_controller_overview.md
@@ -10,7 +10,7 @@ After reading this guide, you will know how to:
 * Follow the flow of a request through a controller.
 * Restrict parameters passed to your controller.
 * Store data in the session or cookies, and why.
-* Work with filters to execute code during request processing.
+* Work with action callbacks to execute code during request processing.
 * Use Action Controller's built-in HTTP authentication.
 * Stream data directly to the user's browser.
 * Filter sensitive parameters, so they do not appear in the application's log.
@@ -710,14 +710,14 @@ You may notice in the above code that we're using `render xml: @users`, not `ren
 You can learn more about rendering in the [Layouts and Rendering
 Guide](layouts_and_rendering.html).
 
-Filters
--------
+Action callbacks
+----------------
 
-Filters are methods that are run "before", "after" or "around" a controller action.
+Action callbacks are methods that are run "before", "after" or "around" a controller action.
 
-Filters are inherited, so if you set a filter on `ApplicationController`, it will be run on every controller in your application.
+Action callbacks are inherited, so if you set one on an `ApplicationController`, it will be run on every controller in your application.
 
-"before" filters are registered via [`before_action`][]. They may halt the request cycle. A common "before" filter is one which requires that a user is logged in for an action to be run. You can define the filter method this way:
+"before" action callbacks are registered via [`before_action`][]. They may halt the request cycle. A common "before" action callback is one which requires that a user is logged in for an action to be run. You can define the method this way:
 
 ```ruby
 class ApplicationController < ActionController::Base
@@ -733,31 +733,31 @@ class ApplicationController < ActionController::Base
 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 renders or redirects, the action will not run. If there are additional filters scheduled to run after that filter, they are also cancelled.
+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" action callback renders or redirects, the controller action will not run. If there are additional action callbacks scheduled to run after that one, they are also cancelled.
 
-In this example, the filter is added to `ApplicationController` and thus all controllers in the application inherit it. This will make everything in the application require the user to be logged in 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. You can prevent this filter from running before particular actions with [`skip_before_action`][]:
+In this example, the action callback is added to `ApplicationController` and thus all controllers in the application inherit it. This will make everything in the application require the user to be logged in 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. You can prevent this action callback from running before particular actions with [`skip_before_action`][]:
 
 ```ruby
 class LoginsController < ApplicationController
   skip_before_action :require_login, only: [:new, :create]
 end
 ```
 
-Now, the `LoginsController`'s `new` and `create` actions will work as before without requiring the user to be logged in. The `:only` option is used to skip this filter only for these actions, and there is also an `:except` option which works the other way. These options can be used when adding filters too, so you can add a filter which only runs for selected actions in the first place.
+Now, the `LoginsController`'s `new` and `create` actions will work as before without requiring the user to be logged in. The `:only` option is used to skip this action callback only for these actions, and there is also an `:except` option which works the other way. These options can be used when adding action callbacks too, so you can add a callback which only runs for selected actions in the first place.
 
-NOTE: Calling the same filter multiple times with different options will not work,
-since the last filter definition will overwrite the previous ones.
+NOTE: Calling the same action callback multiple times with different options will not work,
+since the last action callback definition will overwrite the previous ones.
 
 [`before_action`]: https://api.rubyonrails.org/classes/AbstractController/Callbacks/ClassMethods.html#method-i-before_action
 [`skip_before_action`]: https://api.rubyonrails.org/classes/AbstractController/Callbacks/ClassMethods.html#method-i-skip_before_action
 
-### After Filters and Around Filters
+### After Action and Around Action Callbacks
 
-In addition to "before" filters, you can also run filters after an action has been executed, or both before and after.
+In addition to "before" action callback, you can also run action callbacks after a controller action has been executed, or both before and after.
 
-"after" filters are registered via [`after_action`][]. They are similar to "before" filters, but because the action has already been run they have access to the response data that's about to be sent to the client. Obviously, "after" filters cannot stop the action from running. Please note that "after" filters are executed only after a successful action, but not when an exception is raised in the request cycle.
+"after" action callbacks are registered via [`after_action`][]. They are similar to "before" action callbacks, but because the controller action has already been run they have access to the response data that's about to be sent to the client. Obviously, "after" action callbacks cannot stop the action from running. Please note that "after" action callbacks are executed only after a successful controller action, but not when an exception is raised in the request cycle.
 
-"around" filters are registered via [`around_action`][]. They are responsible for running their associated actions by yielding, similar to how Rack middlewares work.
+"around" action callbacks are registered via [`around_action`][]. They are responsible for running their associated actions by yielding, similar to how Rack middlewares work.
 
 For example, in a website where changes have an approval workflow, an administrator could preview them easily by applying them within a transaction:
 
@@ -778,18 +778,18 @@ class ChangesController < ApplicationController
 end
 ```
 
-Note that an "around" filter also wraps rendering. In particular, in the example above, if the view itself reads from the database (e.g. via a scope), it will do so within the transaction and thus present the data to preview.
+Note that an "around" action callback also wraps rendering. In particular, in the example above, if the view itself reads from the database (e.g. via a scope), it will do so within the transaction and thus present the data to preview.
 
-You can choose not to yield and build the response yourself, in which case the action will not be run.
+You can choose not to yield and build the response yourself, in which case the controller action will not be run.
 
 [`after_action`]: https://api.rubyonrails.org/classes/AbstractController/Callbacks/ClassMethods.html#method-i-after_action
 [`around_action`]: https://api.rubyonrails.org/classes/AbstractController/Callbacks/ClassMethods.html#method-i-around_action
 
-### Other Ways to Use Filters
+### Other Ways to Use Action Callbacks
 
-While the most common way to use filters is by creating private methods and using `before_action`, `after_action`, or `around_action` to add them, there are two other ways to do the same thing.
+While the most common way to use action callbacks is by creating private methods and using `before_action`, `after_action`, or `around_action` to add them, there are two other ways to do the same thing.
 
-The first is to use a block directly with the `*_action` methods. The block receives the controller as an argument. The `require_login` filter from above could be rewritten to use a block:
+The first is to use a block directly with the `*_action` methods. The block receives the controller as an argument. The `require_login` action callback from above could be rewritten to use a block:
 
 ```ruby
 class ApplicationController < ActionController::Base
@@ -802,22 +802,22 @@ class ApplicationController < ActionController::Base
 end
 ```
 
-Note that the filter, in this case, uses `send` because the `logged_in?` method is private, and the filter does not run in the scope of the controller. This is not the recommended way to implement this particular filter, but in simpler cases, it might be useful.
+Note that the action callback, in this case, uses `send` because the `logged_in?` method is private, and the action callback does not run in the scope of the controller. This is not the recommended way to implement this particular action callback, but in simpler cases, it might be useful.
 
 Specifically for `around_action`, the block also yields in the `action`:
 
 ```ruby
 around_action { |_controller, action| time(&action) }
 ```
 
-The second way is to use a class (actually, any object that responds to the right methods will do) to handle the filtering. This is useful in cases that are more complex and cannot be implemented in a readable and reusable way using the two other methods. As an example, you could rewrite the login filter again to use a class:
+The second way is to use a class (actually, any object that responds to the right methods will do) to handle the callback action. This is useful in cases that are more complex and cannot be implemented in a readable and reusable way using the two other methods. As an example, you could rewrite the login action callback again to use a class:
 
 ```ruby
 class ApplicationController < ActionController::Base
-  before_action LoginFilter
+  before_action LoginActionCallback
 end
 
-class LoginFilter
+class LoginActionCallback
   def self.before(controller)
     unless controller.send(:logged_in?)
       controller.flash[:error] = "You must be logged in to access this section"
@@ -827,7 +827,7 @@ class LoginFilter
 end
 ```
 
-Again, this is not an ideal example for this filter, because it's not run in the scope of the controller but gets the controller passed as an argument. The filter class must implement a method with the same name as the filter, so for the `before_action` filter, the class must implement a `before` method, and so on. The `around` method must `yield` to execute the action.
+Again, this is not an ideal example for this action callback, because it's not run in the scope of the controller but gets the controller passed as an argument. The class must implement a method with the same name as the action callback, so for the `before_action` action callback, the class must implement a `before` method, and so on. The `around` method must `yield` to execute the action.
 
 Request Forgery Protection
 --------------------------
@@ -901,7 +901,7 @@ Rails collects all of the parameters sent along with the request in the `params`
 
 ### The `response` Object
 
-The response object is not usually used directly, but is built up during the execution of the action and rendering of the data that is being sent back to the user, but sometimes - like in an after filter - it can be useful to access the response directly. Some of these accessor methods also have setters, allowing you to change their values. To get a full list of the available methods, refer to the [Rails API documentation](https://api.rubyonrails.org/classes/ActionDispatch/Response.html) and [Rack Documentation](https://www.rubydoc.info/github/rack/rack/Rack/Response).
+The response object is not usually used directly, but is built up during the execution of the action and rendering of the data that is being sent back to the user, but sometimes - like in an after action callback - it can be useful to access the response directly. Some of these accessor methods also have setters, allowing you to change their values. To get a full list of the available methods, refer to the [Rails API documentation](https://api.rubyonrails.org/classes/ActionDispatch/Response.html) and [Rack Documentation](https://www.rubydoc.info/github/rack/rack/Rack/Response).
 
 | Property of `response` | Purpose                                                                                             |
 | ---------------------- | --------------------------------------------------------------------------------------------------- |
@@ -941,7 +941,7 @@ class AdminsController < ApplicationController
 end
 ```
 
-With this in place, you can create namespaced controllers that inherit from `AdminsController`. The filter will thus be run for all actions in those controllers, protecting them with HTTP basic authentication.
+With this in place, you can create namespaced controllers that inherit from `AdminsController`. The action callback will thus be run for all actions in those controllers, protecting them with HTTP basic authentication.
 
 [`http_basic_authenticate_with`]: https://api.rubyonrails.org/classes/ActionController/HttpAuthentication/Basic/ControllerMethods/ClassMethods.html#method-i-http_basic_authenticate_with
 
