diff options
Diffstat (limited to 'guides/source')
34 files changed, 3661 insertions, 3665 deletions
diff --git a/guides/source/action_controller_overview.md b/guides/source/action_controller_overview.md index 21fb11c89c..c78618c4f4 100644 --- a/guides/source/action_controller_overview.md +++ b/guides/source/action_controller_overview.md @@ -27,7 +27,7 @@ NOTE: For more details on the routing process, see "Rails Routing from the Outsi Methods and Actions ------------------- -A controller is a Ruby class which inherits from +ApplicationController+ and has methods just like any other class. When your application receives a request, the routing will determine which controller and action to run, then Rails creates an instance of that controller and runs the method with the same name as the action. +A controller is a Ruby class which inherits from `ApplicationController` and has methods just like any other class. When your application receives a request, the routing will determine which controller and action to run, then Rails creates an instance of that controller and runs the method with the same name as the action. ```ruby class ClientsController < ApplicationController @@ -36,7 +36,7 @@ class ClientsController < ApplicationController end ``` -As an example, if a user goes to +/clients/new+ in your application to add a new client, Rails will create an instance of +ClientsController+ and run the +new+ method. Note that the empty method from the example above could work just fine because Rails will by default render the +new.html.erb+ view unless the action says otherwise. The +new+ method could make available to the view a +@client+ instance variable by creating a new +Client+: +As an example, if a user goes to `/clients/new` in your application to add a new client, Rails will create an instance of `ClientsController` and run the `new` method. Note that the empty method from the example above could work just fine because Rails will by default render the `new.html.erb` view unless the action says otherwise. The `new` method could make available to the view a `@client` instance variable by creating a new `Client`: ```ruby def new @@ -46,14 +46,14 @@ end The "Layouts & Rendering Guide":layouts_and_rendering.html explains this in more detail. -+ApplicationController+ inherits from +ActionController::Base+, which defines a number of helpful methods. This guide will cover some of these, but if you're curious to see what's in there, you can see all of them in the API documentation or in the source itself. +`ApplicationController` inherits from `ActionController::Base`, which defines a number of helpful methods. This guide will cover some of these, but if you're curious to see what's in there, you can see all of them in the API documentation or in the source itself. Only public methods are callable as actions. It is a best practice to lower the visibility of methods which are not intended to be actions, like auxiliary methods or filters. Parameters ---------- -You will probably want to access data sent in by the user or other parameters in your controller actions. There are two kinds of parameters possible in a web application. The first are parameters that are sent as part of the URL, called query string parameters. The query string is everything after "?" in the URL. The second type of parameter is usually referred to as POST data. This information usually comes from an HTML form which has been filled in by the user. It's called POST data because it can only be sent as part of an HTTP POST request. Rails does not make any distinction between query string parameters and POST parameters, and both are available in the +params+ hash in your controller: +You will probably want to access data sent in by the user or other parameters in your controller actions. There are two kinds of parameters possible in a web application. The first are parameters that are sent as part of the URL, called query string parameters. The query string is everything after "?" in the URL. The second type of parameter is usually referred to as POST data. This information usually comes from an HTML form which has been filled in by the user. It's called POST data because it can only be sent as part of an HTTP POST request. Rails does not make any distinction between query string parameters and POST parameters, and both are available in the `params` hash in your controller: ```ruby class ClientsController < ActionController::Base @@ -89,7 +89,7 @@ end ### Hash and Array Parameters -The +params+ hash is not limited to one-dimensional keys and values. It can contain arrays and (nested) hashes. To send an array of values, append an empty pair of square brackets "[]" to the key name: +The `params` hash is not limited to one-dimensional keys and values. It can contain arrays and (nested) hashes. To send an array of values, append an empty pair of square brackets "[]" to the key name: ``` GET /clients?ids[]=1&ids[]=2&ids[]=3 @@ -97,7 +97,7 @@ GET /clients?ids[]=1&ids[]=2&ids[]=3 NOTE: The actual URL in this example will be encoded as "/clients?ids%5b%5d=1&ids%5b%5d=2&ids%5b%5d=3" as "[" and "]" are not allowed in URLs. Most of the time you don't have to worry about this because the browser will take care of it for you, and Rails will decode it back when it receives it, but if you ever find yourself having to send those requests to the server manually you have to keep this in mind. -The value of +params[:ids]+ will now be +["1", "2", "3"]+. Note that parameter values are always strings; Rails makes no attempt to guess or cast the type. +The value of `params[:ids]` will now be `["1", "2", "3"]`. Note that parameter values are always strings; Rails makes no attempt to guess or cast the type. To send a hash you include the key name inside the brackets: @@ -110,13 +110,13 @@ To send a hash you include the key name inside the brackets: </form> ``` -When this form is submitted, the value of +params[:client]+ will be `{"name" => "Acme", "phone" => "12345", "address" => {"postcode" => "12345", "city" => "Carrot City"}}`. Note the nested hash in +params[:client][:address]+. +When this form is submitted, the value of `params[:client]` will be `{"name" => "Acme", "phone" => "12345", "address" => {"postcode" => "12345", "city" => "Carrot City"}}`. Note the nested hash in `params[:client][:address]`. -Note that the +params+ hash is actually an instance of +HashWithIndifferentAccess+ from Active Support, which acts like a hash that lets you use symbols and strings interchangeably as keys. +Note that the `params` hash is actually an instance of `HashWithIndifferentAccess` from Active Support, which acts like a hash that lets you use symbols and strings interchangeably as keys. ### JSON/XML parameters -If you're writing a web service application, you might find yourself more comfortable on accepting parameters in JSON or XML format. Rails will automatically convert your parameters into +params+ hash, which you'll be able to access like you would normally do with form data. +If you're writing a web service application, you might find yourself more comfortable on accepting parameters in JSON or XML format. Rails will automatically convert your parameters into `params` hash, which you'll be able to access like you would normally do with form data. So for example, if you are sending this JSON parameter: @@ -126,13 +126,13 @@ So for example, if you are sending this JSON parameter: You'll get `params[:company]` as `{ :name => "acme", "address" => "123 Carrot Street" }`. -Also, if you've turned on +config.wrap_parameters+ in your initializer or calling +wrap_parameters+ in your controller, you can safely omit the root element in the JSON/XML parameter. The parameters will be cloned and wrapped in the key according to your controller's name by default. So the above parameter can be written as: +Also, if you've turned on `config.wrap_parameters` in your initializer or calling `wrap_parameters` in your controller, you can safely omit the root element in the JSON/XML parameter. The parameters will be cloned and wrapped in the key according to your controller's name by default. So the above parameter can be written as: ``` { "name": "acme", "address": "123 Carrot Street" } ``` -And assume that you're sending the data to +CompaniesController+, it would then be wrapped in +:company+ key like this: +And assume that you're sending the data to `CompaniesController`, it would then be wrapped in `:company` key like this: ```ruby { :name => "acme", :address => "123 Carrot Street", :company => { :name => "acme", :address => "123 Carrot Street" }} @@ -142,17 +142,17 @@ You can customize the name of the key or specific parameters you want to wrap by ### Routing Parameters -The +params+ hash will always contain the +:controller+ and +:action+ keys, but you should use the methods +controller_name+ and +action_name+ instead to access these values. Any other parameters defined by the routing, such as +:id+ will also be available. As an example, consider a listing of clients where the list can show either active or inactive clients. We can add a route which captures the +:status+ parameter in a "pretty" URL: +The `params` hash will always contain the `:controller` and `:action` keys, but you should use the methods `controller_name` and `action_name` instead to access these values. Any other parameters defined by the routing, such as `:id` will also be available. As an example, consider a listing of clients where the list can show either active or inactive clients. We can add a route which captures the `:status` parameter in a "pretty" URL: ```ruby match '/clients/:status' => 'clients#index', :foo => "bar" ``` -In this case, when a user opens the URL +/clients/active+, +params[:status]+ will be set to "active". When this route is used, +params[:foo]+ will also be set to "bar" just like it was passed in the query string. In the same way +params[:action]+ will contain "index". +In this case, when a user opens the URL `/clients/active`, `params[:status]` will be set to "active". When this route is used, `params[:foo]` will also be set to "bar" just like it was passed in the query string. In the same way `params[:action]` will contain "index". -### +default_url_options+ +### `default_url_options` -You can set global default parameters for URL generation by defining a method called +default_url_options+ in your controller. Such a method must return a hash with the desired defaults, whose keys must be symbols: +You can set global default parameters for URL generation by defining a method called `default_url_options` in your controller. Such a method must return a hash with the desired defaults, whose keys must be symbols: ```ruby class ApplicationController < ActionController::Base @@ -162,9 +162,9 @@ class ApplicationController < ActionController::Base end ``` -These options will be used as a starting point when generating URLs, so it's possible they'll be overridden by the options passed in +url_for+ calls. +These options will be used as a starting point when generating URLs, so it's possible they'll be overridden by the options passed in `url_for` calls. -If you define +default_url_options+ in +ApplicationController+, as in the example above, it would be used for all URL generation. The method can also be defined in one specific controller, in which case it only affects URLs generated there. +If you define `default_url_options` in `ApplicationController`, as in the example above, it would be used for all URL generation. The method can also be defined in one specific controller, in which case it only affects URLs generated there. Session @@ -187,7 +187,7 @@ If your user sessions don't store critical data or don't need to be around for l Read more about session storage in the "Security Guide":security.html. -If you need a different session storage mechanism, you can change it in the +config/initializers/session_store.rb+ file: +If you need a different session storage mechanism, you can change it in the `config/initializers/session_store.rb` file: ```ruby # Use the database for sessions instead of the cookie-based default, @@ -196,7 +196,7 @@ If you need a different session storage mechanism, you can change it in the +con # YourApp::Application.config.session_store :active_record_store ``` -Rails sets up a session key (the name of the cookie) when signing the session data. These can also be changed in +config/initializers/session_store.rb+: +Rails sets up a session key (the name of the cookie) when signing the session data. These can also be changed in `config/initializers/session_store.rb`: ```ruby # Be sure to restart your server when you modify this file. @@ -204,7 +204,7 @@ Rails sets up a session key (the name of the cookie) when signing the session da YourApp::Application.config.session_store :cookie_store, :key => '_your_app_session' ``` -You can also pass a +:domain+ key and specify the domain name for the cookie: +You can also pass a `:domain` key and specify the domain name for the cookie: ```ruby # Be sure to restart your server when you modify this file. @@ -212,7 +212,7 @@ You can also pass a +:domain+ key and specify the domain name for the cookie: YourApp::Application.config.session_store :cookie_store, :key => '_your_app_session', :domain => ".example.com" ``` -Rails sets up (for the CookieStore) a secret key used for signing the session data. This can be changed in +config/initializers/secret_token.rb+ +Rails sets up (for the CookieStore) a secret key used for signing the session data. This can be changed in `config/initializers/secret_token.rb` ```ruby # Be sure to restart your server when you modify this file. @@ -224,11 +224,11 @@ Rails sets up (for the CookieStore) a secret key used for signing the session da YourApp::Application.config.secret_token = '49d3f3de9ed86c74b94ad6bd0...' ``` -NOTE: Changing the secret when using the +CookieStore+ will invalidate all existing sessions. +NOTE: Changing the secret when using the `CookieStore` will invalidate all existing sessions. ### Accessing the Session -In your controller you can access the session through the +session+ instance method. +In your controller you can access the session through the `session` instance method. NOTE: Sessions are lazily loaded. If you don't access sessions in your action's code, they will not be loaded. Hence you will never need to disable sessions, just not accessing them will do the job. @@ -266,7 +266,7 @@ class LoginsController < ApplicationController end ``` -To remove something from the session, assign that key to be +nil+: +To remove something from the session, assign that key to be `nil`: ```ruby class LoginsController < ApplicationController @@ -279,7 +279,7 @@ class LoginsController < ApplicationController end ``` -To reset the entire session, use +reset_session+. +To reset the entire session, use `reset_session`. ### The Flash @@ -299,7 +299,7 @@ class LoginsController < ApplicationController end ``` -Note that it is also possible to assign a flash message as part of the redirection. You can assign +:notice+, +:alert+ or the general purpose +:flash+: +Note that it is also possible to assign a flash message as part of the redirection. You can assign `:notice`, `:alert` or the general purpose `:flash`: ```ruby redirect_to root_url, :notice => "You have successfully logged out." @@ -307,7 +307,7 @@ redirect_to root_url, :alert => "You're stuck here!" redirect_to root_url, :flash => { :referral_code => 1234 } ``` -The +destroy+ action redirects to the application's +root_url+, where the message will be displayed. Note that it's entirely up to the next action to decide what, if anything, it will do with what the previous action put in the flash. It's conventional to display any error alerts or notices from the flash in the application's layout: +The `destroy` action redirects to the application's `root_url`, where the message will be displayed. Note that it's entirely up to the next action to decide what, if anything, it will do with what the previous action put in the flash. It's conventional to display any error alerts or notices from the flash in the application's layout: ```ruby <html> @@ -334,7 +334,7 @@ You can pass anything that the session can store; you're not limited to notices <% end %> ``` -If you want a flash value to be carried over to another request, use the +keep+ method: +If you want a flash value to be carried over to another request, use the `keep` method: ```ruby class MainController < ApplicationController @@ -354,9 +354,9 @@ class MainController < ApplicationController end ``` -#### +flash.now+ +#### `flash.now` -By default, adding values to the flash will make them available to the next request, but sometimes you may want to access those values in the same request. For example, if the +create+ action fails to save a resource and you render the +new+ template directly, that's not going to result in a new request, but you may still want to display a message using the flash. To do this, you can use +flash.now+ in the same way you use the normal +flash+: +By default, adding values to the flash will make them available to the next request, but sometimes you may want to access those values in the same request. For example, if the `create` action fails to save a resource and you render the `new` template directly, that's not going to result in a new request, but you may still want to display a message using the flash. To do this, you can use `flash.now` in the same way you use the normal `flash`: ```ruby class ClientsController < ApplicationController @@ -375,7 +375,7 @@ end Cookies ------- -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: +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: ```ruby class CommentsController < ApplicationController @@ -403,12 +403,12 @@ class CommentsController < ApplicationController end ``` -Note that while for session values you set the key to +nil+, to delete a cookie value you should use +cookies.delete(:key)+. +Note that while for session values you set the key to `nil`, to delete a cookie value you should use `cookies.delete(:key)`. Rendering xml and json data --------------------------- -ActionController makes it extremely easy to render +xml+ or +json+ data. If you generate a controller using scaffold then your controller would look something like this. +ActionController makes it extremely easy to render `xml` or `json` data. If you generate a controller using scaffold then your controller would look something like this. ```ruby class UsersController < ApplicationController @@ -423,7 +423,7 @@ class UsersController < ApplicationController end ``` -Notice that in the above case code is `render :xml => @users` and not `render :xml => @users.to_xml`. That is because if the input is not string then rails automatically invokes +to_xml+ . +Notice that in the above case code is `render :xml => @users` and not `render :xml => @users.to_xml`. That is because if the input is not string then rails automatically invokes `to_xml` . Filters @@ -431,7 +431,7 @@ Filters Filters 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. +Filters are inherited, so if you set a filter on `ApplicationController`, it will be run on every controller in your application. Before filters 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: @@ -461,7 +461,7 @@ 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. -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 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. You can prevent this filter from running before particular actions with +skip_before_filter+: +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 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. You can prevent this filter from running before particular actions with `skip_before_filter`: ```ruby class LoginsController < ApplicationController @@ -469,7 +469,7 @@ class LoginsController < ApplicationController 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 only skip this filter 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 only skip this filter 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. ### After Filters and Around Filters @@ -507,7 +507,7 @@ You can choose not to yield and build the response yourself, in which case the a 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 rewritten to use a block: +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 rewritten to use a block: ```ruby class ApplicationController < ActionController::Base @@ -517,7 +517,7 @@ class ApplicationController < ActionController::Base end ``` -Note that the filter in this case uses +send+ because the +logged_in?+ method is private and the filter is not run in the scope of the controller. This is not the recommended way to implement this particular filter, but in more simple cases it might be useful. +Note that the filter in this case uses `send` because the `logged_in?` method is private and the filter is not run in the scope of the controller. This is not the recommended way to implement this particular filter, but in more simple cases it might be useful. 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 can not 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: @@ -536,7 +536,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 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. +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 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. Request Forgery Protection -------------------------- @@ -567,24 +567,24 @@ You will see how the token gets added as a hidden field: </form> ``` -Rails adds this token to every form that's generated using the "form helpers":form_helpers.html, so most of the time you don't have to worry about it. If you're writing a form manually or need to add the token for another reason, it's available through the method +form_authenticity_token+: +Rails adds this token to every form that's generated using the "form helpers":form_helpers.html, so most of the time you don't have to worry about it. If you're writing a form manually or need to add the token for another reason, it's available through the method `form_authenticity_token`: -The +form_authenticity_token+ generates a valid authentication token. That's useful in places where Rails does not add it automatically, like in custom Ajax calls. +The `form_authenticity_token` generates a valid authentication token. That's useful in places where Rails does not add it automatically, like in custom Ajax calls. The "Security Guide":security.html has more about this and a lot of other security-related issues that you should be aware of when developing a web application. The Request and Response Objects -------------------------------- -In every controller there are two accessor methods pointing to the request and the response objects associated with the request cycle that is currently in execution. The +request+ method contains an instance of +AbstractRequest+ and the +response+ method returns a response object representing what is going to be sent back to the client. +In every controller there are two accessor methods pointing to the request and the response objects associated with the request cycle that is currently in execution. The `request` method contains an instance of `AbstractRequest` and the `response` method returns a response object representing what is going to be sent back to the client. -### The +request+ Object +### The `request` Object The request object contains a lot of useful information about the request coming in from the client. To get a full list of the available methods, refer to the "API documentation":http://api.rubyonrails.org/classes/ActionDispatch/Request.html. Among the properties that you can access on this object are: -|_.Property of +request+|_.Purpose| +|_.Property of `request`|_.Purpose| |host|The hostname used for this request.| -|domain(n=2)|The hostname's first +n+ segments, starting from the right (the TLD).| +|domain(n=2)|The hostname's first `n` segments, starting from the right (the TLD).| |format|The content type requested by the client.| |method|The HTTP method used for the request.| |get?, post?, patch?, put?, delete?, head?|Returns true if the HTTP method is GET/POST/PATCH/PUT/DELETE/HEAD.| @@ -595,15 +595,15 @@ The request object contains a lot of useful information about the request coming |remote_ip|The IP address of the client.| |url|The entire URL used for the request.| -#### +path_parameters+, +query_parameters+, and +request_parameters+ +#### `path_parameters`, `query_parameters`, and `request_parameters` -Rails collects all of the parameters sent along with the request in the +params+ hash, whether they are sent as part of the query string or the post body. The request object has three accessors that give you access to these parameters depending on where they came from. The +query_parameters+ hash contains parameters that were sent as part of the query string while the +request_parameters+ hash contains parameters sent as part of the post body. The +path_parameters+ hash contains parameters that were recognized by the routing as being part of the path leading to this particular controller and action. +Rails collects all of the parameters sent along with the request in the `params` hash, whether they are sent as part of the query string or the post body. The request object has three accessors that give you access to these parameters depending on where they came from. The `query_parameters` hash contains parameters that were sent as part of the query string while the `request_parameters` hash contains parameters sent as part of the post body. The `path_parameters` hash contains parameters that were recognized by the routing as being part of the path leading to this particular controller and action. -### The +response+ Object +### 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. -|_.Property of +response+|_.Purpose| +|_.Property of `response`|_.Purpose| |body|This is the string of data being sent back to the client. This is most often HTML.| |status|The HTTP status code for the response, like 200 for a successful request or 404 for file not found.| |location|The URL the client is being redirected to, if any.| @@ -613,7 +613,7 @@ The response object is not usually used directly, but is built up during the exe #### Setting Custom Headers -If you want to set custom headers for a response then +response.headers+ is the place to do it. The headers attribute is a hash which maps header names to their values, and Rails will set some of them automatically. If you want to add or change a header, just assign it to +response.headers+ this way: +If you want to set custom headers for a response then `response.headers` is the place to do it. The headers attribute is a hash which maps header names to their values, and Rails will set some of them automatically. If you want to add or change a header, just assign it to `response.headers` this way: ```ruby response.headers["Content-Type"] = "application/pdf" @@ -629,7 +629,7 @@ Rails comes with two built-in HTTP authentication mechanisms: ### HTTP Basic Authentication -HTTP basic authentication is an authentication scheme that is supported by the majority of browsers and other HTTP clients. As an example, consider 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, +http_basic_authenticate_with+. +HTTP basic authentication is an authentication scheme that is supported by the majority of browsers and other HTTP clients. As an example, consider 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, `http_basic_authenticate_with`. ```ruby class AdminController < ApplicationController @@ -637,11 +637,11 @@ class AdminController < ApplicationController end ``` -With this in place, you can create namespaced controllers that inherit from +AdminController+. 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 `AdminController`. The filter will thus be run for all actions in those controllers, protecting them with HTTP basic authentication. ### HTTP Digest Authentication -HTTP digest authentication is superior to the basic authentication as it does not require the client to send an unencrypted password over the network (though HTTP basic authentication is safe over HTTPS). Using digest authentication with Rails is quite easy and only requires using one method, +authenticate_or_request_with_http_digest+. +HTTP digest authentication is superior to the basic authentication as it does not require the client to send an unencrypted password over the network (though HTTP basic authentication is safe over HTTPS). Using digest authentication with Rails is quite easy and only requires using one method, `authenticate_or_request_with_http_digest`. ```ruby class AdminController < ApplicationController @@ -659,14 +659,14 @@ class AdminController < ApplicationController end ``` -As seen in the example above, the +authenticate_or_request_with_http_digest+ block takes only one argument - the username. And the block returns the password. Returning +false+ or +nil+ from the +authenticate_or_request_with_http_digest+ will cause authentication failure. +As seen in the example above, the `authenticate_or_request_with_http_digest` block takes only one argument - the username. And the block returns the password. Returning `false` or `nil` from the `authenticate_or_request_with_http_digest` will cause authentication failure. Streaming and File Downloads ---------------------------- -Sometimes you may want to send a file to the user instead of rendering an HTML page. All controllers in Rails have the +send_data+ and the +send_file+ methods, which will both stream data to the client. +send_file+ is a convenience method that lets you provide the name of a file on the disk and it will stream the contents of that file for you. +Sometimes you may want to send a file to the user instead of rendering an HTML page. All controllers in Rails have the `send_data` and the `send_file` methods, which will both stream data to the client. `send_file` is a convenience method that lets you provide the name of a file on the disk and it will stream the contents of that file for you. -To stream data to the client, use +send_data+: +To stream data to the client, use `send_data`: ```ruby require "prawn" @@ -692,11 +692,11 @@ class ClientsController < ApplicationController end ``` -The +download_pdf+ action in the example above will call a private method which actually generates the PDF document and returns it as a string. This string will then be streamed to the client as a file download and a filename will be suggested to the user. Sometimes when streaming files to the user, you may not want them to download the file. Take images, for example, which can be embedded into HTML pages. To tell the browser a file is not meant to be downloaded, you can set the +:disposition+ option to "inline". The opposite and default value for this option is "attachment". +The `download_pdf` action in the example above will call a private method which actually generates the PDF document and returns it as a string. This string will then be streamed to the client as a file download and a filename will be suggested to the user. Sometimes when streaming files to the user, you may not want them to download the file. Take images, for example, which can be embedded into HTML pages. To tell the browser a file is not meant to be downloaded, you can set the `:disposition` option to "inline". The opposite and default value for this option is "attachment". ### Sending Files -If you want to send a file that already exists on disk, use the +send_file+ method. +If you want to send a file that already exists on disk, use the `send_file` method. ```ruby class ClientsController < ApplicationController @@ -710,9 +710,9 @@ class ClientsController < ApplicationController end ``` -This will read and stream the file 4kB at the time, avoiding loading the entire file into memory at once. You can turn off streaming with the +:stream+ option or adjust the block size with the +:buffer_size+ option. +This will read and stream the file 4kB at the time, avoiding loading the entire file into memory at once. You can turn off streaming with the `:stream` option or adjust the block size with the `:buffer_size` option. -If +:type+ is not specified, it will be guessed from the file extension specified in +:filename+. If the content type is not registered for the extension, `application/octet-stream` will be used. +If `:type` is not specified, it will be guessed from the file extension specified in `:filename`. If the content type is not registered for the extension, `application/octet-stream` will be used. WARNING: Be careful when using data coming from the client (params, cookies, etc.) to locate the file on disk, as this is a security risk that might allow someone to gain access to files they are not meant to see. @@ -720,7 +720,7 @@ TIP: It is not recommended that you stream static files through Rails if you can ### RESTful Downloads -While +send_data+ works just fine, if you are creating a RESTful application having separate actions for file downloads is usually not necessary. In REST terminology, the PDF file from the example above can be considered just another representation of the client resource. Rails provides an easy and quite sleek way of doing "RESTful downloads". Here's how you can rewrite the example so that the PDF download is a part of the +show+ action, without any streaming: +While `send_data` works just fine, if you are creating a RESTful application having separate actions for file downloads is usually not necessary. In REST terminology, the PDF file from the example above can be considered just another representation of the client resource. Rails provides an easy and quite sleek way of doing "RESTful downloads". Here's how you can rewrite the example so that the PDF download is a part of the `show` action, without any streaming: ```ruby class ClientsController < ApplicationController @@ -736,7 +736,7 @@ class ClientsController < ApplicationController end ``` -In order for this example to work, you have to add the PDF MIME type to Rails. This can be done by adding the following line to the file +config/initializers/mime_types.rb+: +In order for this example to work, you have to add the PDF MIME type to Rails. This can be done by adding the following line to the file `config/initializers/mime_types.rb`: ```ruby Mime::Type.register "application/pdf", :pdf @@ -753,7 +753,7 @@ GET /clients/1.pdf Parameter Filtering ------------------- -Rails keeps a log file for each environment 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. You can filter certain request parameters from your log files by appending them to `config.filter_parameters` in the application configuration. These parameters will be marked [FILTERED] in the log. +Rails keeps a log file for each environment 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. You can filter certain request parameters from your log files by appending them to `config.filter_parameters` in the application configuration. These parameters will be marked [FILTERED] in the log. ```ruby config.filter_parameters << :password @@ -762,21 +762,21 @@ config.filter_parameters << :password Rescue ------ -Most likely your application is going to contain bugs or otherwise throw an exception that needs to be handled. For example, if the user follows a link to a resource that no longer exists in the database, Active Record will throw the +ActiveRecord::RecordNotFound+ exception. +Most likely your application is going to contain bugs or otherwise throw an exception that needs to be handled. For example, if the user follows a link to a resource that no longer exists in the database, Active Record will throw the `ActiveRecord::RecordNotFound` exception. Rails' default exception handling displays a "500 Server Error" message for all exceptions. If the request was made locally, a nice traceback and some added information gets displayed so you can figure out what went wrong and deal with it. If the request was remote Rails will just display a simple "500 Server Error" message to the user, or a "404 Not Found" if there was a routing error or a record could not be found. Sometimes you might want to customize how these errors are caught and how they're displayed to the user. There are several levels of exception handling available in a Rails application: ### The Default 500 and 404 Templates -By default a production application will render either a 404 or a 500 error message. These messages are contained in static HTML files in the +public+ folder, in +404.html+ and +500.html+ respectively. You can customize these files to add some extra information and layout, but remember that they are static; i.e. you can't use RHTML or layouts in them, just plain HTML. +By default a production application will render either a 404 or a 500 error message. These messages are contained in static HTML files in the `public` folder, in `404.html` and `500.html` respectively. You can customize these files to add some extra information and layout, but remember that they are static; i.e. you can't use RHTML or layouts in them, just plain HTML. -### +rescue_from+ +### `rescue_from` -If you want to do something a bit more elaborate when catching errors, you can use +rescue_from+, which handles exceptions of a certain type (or multiple types) in an entire controller and its subclasses. +If you want to do something a bit more elaborate when catching errors, you can use `rescue_from`, which handles exceptions of a certain type (or multiple types) in an entire controller and its subclasses. -When an exception occurs which is caught by a +rescue_from+ directive, the exception object is passed to the handler. The handler can be a method or a +Proc+ object passed to the +:with+ option. You can also use a block directly instead of an explicit +Proc+ object. +When an exception occurs which is caught by a `rescue_from` directive, the exception object is passed to the handler. The handler can be a method or a `Proc` object passed to the `:with` option. You can also use a block directly instead of an explicit `Proc` object. -Here's how you can use +rescue_from+ to intercept all +ActiveRecord::RecordNotFound+ errors and do something with them. +Here's how you can use `rescue_from` to intercept all `ActiveRecord::RecordNotFound` errors and do something with them. ```ruby class ApplicationController < ActionController::Base @@ -822,12 +822,12 @@ class ClientsController < ApplicationController end ``` -NOTE: Certain exceptions are only rescuable from the +ApplicationController+ class, as they are raised before the controller gets initialized and the action gets executed. See Pratik Naik's "article":http://m.onkey.org/2008/7/20/rescue-from-dispatching on the subject for more information. +NOTE: Certain exceptions are only rescuable from the `ApplicationController` class, as they are raised before the controller gets initialized and the action gets executed. See Pratik Naik's "article":http://m.onkey.org/2008/7/20/rescue-from-dispatching on the subject for more information. Force HTTPS protocol -------------------- -Sometime you might want to force a particular controller to only be accessible via an HTTPS protocol for security reasons. Since Rails 3.1 you can now use +force_ssl+ method in your controller to enforce that: +Sometime you might want to force a particular controller to only be accessible via an HTTPS protocol for security reasons. Since Rails 3.1 you can now use `force_ssl` method in your controller to enforce that: ```ruby class DinnerController @@ -835,7 +835,7 @@ class DinnerController end ``` -Just like the filter, you could also passing +:only+ and +:except+ to enforce the secure connection only to specific actions. +Just like the filter, you could also passing `:only` and `:except` to enforce the secure connection only to specific actions. ```ruby class DinnerController @@ -845,4 +845,4 @@ class DinnerController end ``` -Please note that if you found yourself adding +force_ssl+ to many controllers, you may found yourself wanting to force the whole application to use HTTPS instead. In that case, you can set the +config.force_ssl+ in your environment file. +Please note that if you found yourself adding `force_ssl` to many controllers, you may found yourself wanting to force the whole application to use HTTPS instead. In that case, you can set the `config.force_ssl` in your environment file. diff --git a/guides/source/action_view_overview.md b/guides/source/action_view_overview.md index a4fd80d59c..0cb5a56a54 100644 --- a/guides/source/action_view_overview.md +++ b/guides/source/action_view_overview.md @@ -58,7 +58,7 @@ $ gem install actionpack $ gem install rack ``` -Now we'll create a simple "Hello World" application that uses the +titleize+ method provided by Active Support. +Now we'll create a simple "Hello World" application that uses the `titleize` method provided by Active Support. *hello_world.rb:* @@ -73,7 +73,7 @@ end Rack::Handler::Mongrel.run method(:hello_world), :Port => 4567 ``` -We can see this all come together by starting up the application and then visiting +http://localhost:4567/+ +We can see this all come together by starting up the application and then visiting `http://localhost:4567/` ```bash $ ruby hello_world.rb @@ -81,7 +81,7 @@ $ ruby hello_world.rb TODO needs a screenshot? I have one - not sure where to put it. -Notice how 'hello world' has been converted into 'Hello World' by the +titleize+ helper method. +Notice how 'hello world' has been converted into 'Hello World' by the `titleize` helper method. Action View can also be used with "Sinatra":http://www.sinatrarb.com/ in the same way. @@ -111,14 +111,14 @@ Then, we can run the application: $ ruby hello_world.rb ``` -Once the application is running, you can see Sinatra and Action View working together by visiting +http://localhost:4567/+ +Once the application is running, you can see Sinatra and Action View working together by visiting `http://localhost:4567/` TODO needs a screenshot? I have one - not sure where to put it. Templates, Partials and Layouts ------------------------------- -As mentioned before, the final HTML output is a composition of three Rails elements: +Templates+, +Partials+ and +Layouts+. +As mentioned before, the final HTML output is a composition of three Rails elements: `Templates`, `Partials` and `Layouts`. Find below a brief overview of each one of them. ### Templates @@ -129,7 +129,7 @@ Rails supports multiple template systems and uses a file extension to distinguis #### ERB -Within an ERB template Ruby code can be included using both +<% %>+ and +<%= %>+ tags. The +<% %>+ are used to execute Ruby code that does not return anything, such as conditions, loops or blocks, and the +<%= %>+ tags are used when you want output. +Within an ERB template Ruby code can be included using both `<% %>` and `<%= %>` tags. The `<% %>` are used to execute Ruby code that does not return anything, such as conditions, loops or blocks, and the `<%= %>` tags are used when you want output. Consider the following loop for names: @@ -140,18 +140,18 @@ Consider the following loop for names: <% end %> ``` -The loop is setup in regular embedding tags +<% %>+ and the name is written using the output embedding tag +<%= %>+. Note that this is not just a usage suggestion, for Regular output functions like print or puts won't work with ERB templates. So this would be wrong: +The loop is setup in regular embedding tags `<% %>` and the name is written using the output embedding tag `<%= %>`. Note that this is not just a usage suggestion, for Regular output functions like print or puts won't work with ERB templates. So this would be wrong: ```erb <%# WRONG %> Hi, Mr. <% puts "Frodo" %> ``` -To suppress leading and trailing whitespaces, you can use +<%-+ +-%>+ interchangeably with +<%+ and +%>+. +To suppress leading and trailing whitespaces, you can use `<%-` `-%>` interchangeably with `<%` and `%>`. #### 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: @@ -224,19 +224,19 @@ Partial templates – usually just called "partials" – are another device for #### Naming Partials -To render a partial as part of a view, you use the +render+ method within the view: +To render a partial as part of a view, you use the `render` method within the view: ```ruby <%= render "menu" %> ``` -This will render a file named +_menu.html.erb+ at that point within the view is being rendered. Note the leading underscore character: partials are named with a leading underscore to distinguish them from regular views, even though they are referred to without the underscore. This holds true even when you're pulling in a partial from another folder: +This will render a file named `_menu.html.erb` at that point within the view is being rendered. Note the leading underscore character: partials are named with a leading underscore to distinguish them from regular views, even though they are referred to without the underscore. This holds true even when you're pulling in a partial from another folder: ```ruby <%= render "shared/menu" %> ``` -That code will pull in the partial from +app/views/shared/_menu.html.erb+. +That code will pull in the partial from `app/views/shared/_menu.html.erb`. #### Using Partials to simplify Views @@ -255,7 +255,7 @@ One way to use partials is to treat them as the equivalent of subroutines: as a <%= render "shared/footer" %> ``` -Here, the +_ad_banner.html.erb+ and +_footer.html.erb+ partials could contain content that is shared among many pages in your application. You don't need to see the details of these sections when you're concentrating on a particular page. +Here, the `_ad_banner.html.erb` and `_footer.html.erb` partials could contain content that is shared among many pages in your application. You don't need to see the details of these sections when you're concentrating on a particular page. #### The :as and :object options @@ -265,13 +265,13 @@ By default `ActionView::Partials::PartialRenderer` has its object in a local var <%= render :partial => "product" %> ``` -within product we'll get `@product` in the local variable +product+, as if we had written: +within product we'll get `@product` in the local variable `product`, as if we had written: ```erb <%= render :partial => "product", :locals => { :product => @product } %> ``` -With the `:as` option we can specify a different name for said local variable. For example, if we wanted it to be +item+ instead of product+ we'd do: +With the `:as` option we can specify a different name for said local variable. For example, if we wanted it to be `item` instead of product+ we'd do: ```erb <%= render :partial => "product", :as => 'item' %> @@ -302,9 +302,9 @@ So the three-lined example for rendering all the products can be rewritten with <%= render :partial => "product", :collection => @products %> ``` -When a partial is called with a pluralized collection, then the individual instances of the partial have access to the member of the collection being rendered via a variable named after the partial. In this case, the partial is +_product+ , and within the +_product+ partial, you can refer to +product+ to get the instance that is being rendered. +When a partial is called with a pluralized collection, then the individual instances of the partial have access to the member of the collection being rendered via a variable named after the partial. In this case, the partial is `_product` , and within the `_product` partial, you can refer to `product` to get the instance that is being rendered. -You can use a shorthand syntax for rendering collections. Assuming @products is a collection of +Product+ instances, you can simply write the following to produce the same result: +You can use a shorthand syntax for rendering collections. Assuming @products is a collection of `Product` instances, you can simply write the following to produce the same result: ```erb <%= render @products %> @@ -314,13 +314,13 @@ Rails determines the name of the partial to use by looking at the model name in #### Spacer Templates -You can also specify a second partial to be rendered between instances of the main partial by using the +:spacer_template+ option: +You can also specify a second partial to be rendered between instances of the main partial by using the `:spacer_template` option: ```erb <%= render @products, :spacer_template => "product_ruler" %> ``` -Rails will render the +_product_ruler+ partial (with no data passed in to it) between each pair of +_product+ partials. +Rails will render the `_product_ruler` partial (with no data passed in to it) between each pair of `_product` partials. ### Layouts @@ -336,13 +336,13 @@ Partial Layouts Partials can have their own layouts applied to them. These layouts are different than the ones that are specified globally for the entire action, but they work in a similar fashion. -Let's say we're displaying a post on a page where it should be wrapped in a +div+ for display purposes. First, we'll create a new +Post+: +Let's say we're displaying a post on a page where it should be wrapped in a `div` for display purposes. First, we'll create a new `Post`: ```ruby Post.create(:body => 'Partial Layouts are cool!') ``` -In the +show+ template, we'll render the +post+ partial wrapped in the +box+ layout: +In the `show` template, we'll render the `post` partial wrapped in the `box` layout: *posts/show.html.erb* @@ -350,7 +350,7 @@ In the +show+ template, we'll render the +post+ partial wrapped in the +box+ lay <%= render :partial => 'post', :layout => 'box', :locals => {:post => @post} %> ``` -The +box+ layout simply wraps the +post+ partial in a +div+: +The `box` layout simply wraps the `post` partial in a `div`: *posts/_box.html.erb* @@ -360,7 +360,7 @@ The +box+ layout simply wraps the +post+ partial in a +div+: </div> ``` -The +post+ partial wraps the post's +body+ in a +div+ with the +id+ of the post using the +div_for+ helper: +The `post` partial wraps the post's `body` in a `div` with the `id` of the post using the `div_for` helper: *posts/_post.html.erb* @@ -380,9 +380,9 @@ This example would output the following: </div> ``` -Note that the partial layout has access to the local +post+ variable that was passed into the +render+ call. However, unlike application-wide layouts, partial layouts still have the underscore prefix. +Note that the partial layout has access to the local `post` variable that was passed into the `render` call. However, unlike application-wide layouts, partial layouts still have the underscore prefix. -You can also render a block of code within a partial layout instead of calling +yield+. For example, if we didn't have the +post+ partial, we could do this instead: +You can also render a block of code within a partial layout instead of calling `yield`. For example, if we didn't have the `post` partial, we could do this instead: *posts/show.html.erb* @@ -394,7 +394,7 @@ You can also render a block of code within a partial layout instead of calling + <% end %> ``` -If we're using the same +box+ partial from above, his would produce the same output as the previous example. +If we're using the same `box` partial from above, his would produce the same output as the previous example. View Paths ---------- @@ -428,7 +428,7 @@ error_messages_for "post" #### form -Returns a form with inputs for all attributes of the specified Active Record object. For example, let's say we have a +@post+ with attributes named +title+ of type +String+ and +body+ of type +Text+. Calling +form+ would produce a form to creating a new post with inputs for those attributes. +Returns a form with inputs for all attributes of the specified Active Record object. For example, let's say we have a `@post` with attributes named `title` of type `String` and `body` of type `Text`. Calling `form` would produce a form to creating a new post with inputs for those attributes. ```ruby form("post") @@ -448,13 +448,13 @@ form("post") </form> ``` -Typically, +form_for+ is used instead of +form+ because it doesn't automatically include all of the model's attributes. +Typically, `form_for` is used instead of `form` because it doesn't automatically include all of the model's attributes. #### input Returns a default input tag for the type of object returned by the method. -For example, if +@post+ has an attribute +title+ mapped to a +String+ column that holds "Hello World": +For example, if `@post` has an attribute `title` mapped to a `String` column that holds "Hello World": ```ruby input("post", "title") # => @@ -463,13 +463,13 @@ input("post", "title") # => ### RecordTagHelper -This module provides methods for generating container tags, such as +div+, for your record. This is the recommended way of creating a container for render your Active Record object, as it adds an appropriate class and id attributes to that container. You can then refer to those containers easily by following the convention, instead of having to think about which class or id attribute you should use. +This module provides methods for generating container tags, such as `div`, for your record. This is the recommended way of creating a container for render your Active Record object, as it adds an appropriate class and id attributes to that container. You can then refer to those containers easily by following the convention, instead of having to think about which class or id attribute you should use. #### content_tag_for Renders a container tag that relates to your Active Record Object. -For example, given +@post+ is the object of +Post+ class, you can do: +For example, given `@post` is the object of `Post` class, you can do: ```ruby <%= content_tag_for(:tr, @post) do %> @@ -501,7 +501,7 @@ Will generate this HTML output: </tr> ``` -You can pass a collection of Active Record objects. This method will loop through your objects and create a container for each of them. For example, given +@posts+ is an array of two +Post+ objects: +You can pass a collection of Active Record objects. This method will loop through your objects and create a container for each of them. For example, given `@posts` is an array of two `Post` objects: ```ruby <%= content_tag_for(:tr, @posts) do |post| %> @@ -522,7 +522,7 @@ Will generate this HTML output: #### div_for -This is actually a convenient method which calls +content_tag_for+ internally with +:div+ as the tag name. You can pass either an Active Record object or a collection of objects. For example: +This is actually a convenient method which calls `content_tag_for` internally with `:div` as the tag name. You can pass either an Active Record object or a collection of objects. For example: ```ruby <%= div_for(@post, :class => "frontpage") do %> @@ -542,7 +542,7 @@ Will generate this HTML output: This module provides methods for generating HTML that links views to assets such as images, JavaScript files, stylesheets, and feeds. -By default, Rails links to these assets on the current host in the public folder, but you can direct Rails to link to assets from a dedicated assets server by setting +config.action_controller.asset_host+ in the application configuration, typically in +config/environments/production.rb+. For example, let's say your asset host is +assets.example.com+: +By default, Rails links to these assets on the current host in the public folder, but you can direct Rails to link to assets from a dedicated assets server by setting `config.action_controller.asset_host` in the application configuration, typically in `config/environments/production.rb`. For example, let's say your asset host is `assets.example.com`: ```ruby config.action_controller.asset_host = "assets.example.com" @@ -551,7 +551,7 @@ image_tag("rails.png") # => <img src="http://assets.example.com/images/rails.png #### register_javascript_expansion -Register one or more JavaScript files to be included when symbol is passed to javascript_include_tag. This method is typically intended to be called from plugin initialization to register JavaScript files that the plugin installed in +vendor/assets/javascripts+. +Register one or more JavaScript files to be included when symbol is passed to javascript_include_tag. This method is typically intended to be called from plugin initialization to register JavaScript files that the plugin installed in `vendor/assets/javascripts`. ```ruby ActionView::Helpers::AssetTagHelper.register_javascript_expansion :monkey => ["head", "body", "tail"] @@ -564,7 +564,7 @@ javascript_include_tag :monkey # => #### register_stylesheet_expansion -Register one or more stylesheet files to be included when symbol is passed to +stylesheet_link_tag+. This method is typically intended to be called from plugin initialization to register stylesheet files that the plugin installed in +vendor/assets/stylesheets+. +Register one or more stylesheet files to be included when symbol is passed to `stylesheet_link_tag`. This method is typically intended to be called from plugin initialization to register stylesheet files that the plugin installed in `vendor/assets/stylesheets`. ```ruby ActionView::Helpers::AssetTagHelper.register_stylesheet_expansion :monkey => ["head", "body", "tail"] @@ -586,7 +586,7 @@ auto_discovery_link_tag(:rss, "http://www.example.com/feed.rss", {:title => "RSS #### image_path -Computes the path to an image asset in the +app/assets/images+ directory. Full paths from the document root will be passed through. Used internally by +image_tag+ to build the image path. +Computes the path to an image asset in the `app/assets/images` directory. Full paths from the document root will be passed through. Used internally by `image_tag` to build the image path. ```ruby image_path("edit.png") # => /assets/edit.png @@ -600,7 +600,7 @@ image_path("edit.png") # => /assets/edit-2d1a2db63fc738690021fedb5a65b68e.png #### image_url -Computes the url to an image asset in the +app/asset/images+ directory. This will call +image_path+ internally and merge with your current host or your asset host. +Computes the url to an image asset in the `app/asset/images` directory. This will call `image_path` internally and merge with your current host or your asset host. ```ruby image_url("edit.png") # => http://www.example.com/assets/edit.png @@ -608,7 +608,7 @@ image_url("edit.png") # => http://www.example.com/assets/edit.png #### image_tag -Returns an html image tag for the source. The source can be a full path or a file that exists in your +app/assets/images+ directory. +Returns an html image tag for the source. The source can be a full path or a file that exists in your `app/assets/images` directory. ```ruby image_tag("icon.png") # => <img src="/assets/icon.png" alt="Icon" /> @@ -616,25 +616,25 @@ image_tag("icon.png") # => <img src="/assets/icon.png" alt="Icon" /> #### javascript_include_tag -Returns an html script tag for each of the sources provided. You can pass in the filename (+.js+ extension is optional) of JavaScript files that exist in your +app/assets/javascripts+ directory for inclusion into the current page or you can pass the full path relative to your document root. +Returns an html script tag for each of the sources provided. You can pass in the filename (`.js` extension is optional) of JavaScript files that exist in your `app/assets/javascripts` directory for inclusion into the current page or you can pass the full path relative to your document root. ```ruby javascript_include_tag "common" # => <script src="/assets/common.js"></script> ``` -If the application does not use the asset pipeline, to include the jQuery JavaScript library in your application, pass +:defaults+ as the source. When using +:defaults+, if an +application.js+ file exists in your +app/assets/javascripts+ directory, it will be included as well. +If the application does not use the asset pipeline, to include the jQuery JavaScript library in your application, pass `:defaults` as the source. When using `:defaults`, if an `application.js` file exists in your `app/assets/javascripts` directory, it will be included as well. ```ruby javascript_include_tag :defaults ``` -You can also include all JavaScript files in the +app/assets/javascripts+ directory using +:all+ as the source. +You can also include all JavaScript files in the `app/assets/javascripts` directory using `:all` as the source. ```ruby javascript_include_tag :all ``` -You can also cache multiple JavaScript files into one file, which requires less HTTP connections to download and can better be compressed by gzip (leading to faster transfers). Caching will only happen if +ActionController::Base.perform_caching+ is set to true (which is the case by default for the Rails production environment, but not for the development environment). +You can also cache multiple JavaScript files into one file, which requires less HTTP connections to download and can better be compressed by gzip (leading to faster transfers). Caching will only happen if `ActionController::Base.perform_caching` is set to true (which is the case by default for the Rails production environment, but not for the development environment). ```ruby javascript_include_tag :all, :cache => true # => @@ -643,7 +643,7 @@ javascript_include_tag :all, :cache => true # => #### javascript_path -Computes the path to a JavaScript asset in the +app/assets/javascripts+ directory. If the source filename has no extension, +.js+ will be appended. Full paths from the document root will be passed through. Used internally by +javascript_include_tag+ to build the script path. +Computes the path to a JavaScript asset in the `app/assets/javascripts` directory. If the source filename has no extension, `.js` will be appended. Full paths from the document root will be passed through. Used internally by `javascript_include_tag` to build the script path. ```ruby javascript_path "common" # => /assets/common.js @@ -651,7 +651,7 @@ javascript_path "common" # => /assets/common.js #### javascript_url -Computes the url to a JavaScript asset in the +app/assets/javascripts+ directory. This will call +javascript_path+ internally and merge with your current host or your asset host. +Computes the url to a JavaScript asset in the `app/assets/javascripts` directory. This will call `javascript_path` internally and merge with your current host or your asset host. ```ruby javascript_url "common" # => http://www.example.com/assets/common.js @@ -659,7 +659,7 @@ javascript_url "common" # => http://www.example.com/assets/common.js #### stylesheet_link_tag -Returns a stylesheet link tag for the sources specified as arguments. If you don't specify an extension, +.css+ will be appended automatically. +Returns a stylesheet link tag for the sources specified as arguments. If you don't specify an extension, `.css` will be appended automatically. ```ruby stylesheet_link_tag "application" # => <link href="/assets/application.css" media="screen" rel="stylesheet" /> @@ -680,7 +680,7 @@ stylesheet_link_tag :all, :cache => true #### stylesheet_path -Computes the path to a stylesheet asset in the +app/assets/stylesheets+ directory. If the source filename has no extension, .css will be appended. Full paths from the document root will be passed through. Used internally by stylesheet_link_tag to build the stylesheet path. +Computes the path to a stylesheet asset in the `app/assets/stylesheets` directory. If the source filename has no extension, .css will be appended. Full paths from the document root will be passed through. Used internally by stylesheet_link_tag to build the stylesheet path. ```ruby stylesheet_path "application" # => /assets/application.css @@ -688,7 +688,7 @@ stylesheet_path "application" # => /assets/application.css #### stylesheet_url -Computes the url to a stylesheet asset in the +app/assets/stylesheets+ directory. This will call +stylesheet_path+ internally and merge with your current host or your asset host. +Computes the url to a stylesheet asset in the `app/assets/stylesheets` directory. This will call `stylesheet_path` internally and merge with your current host or your asset host. ```ruby stylesheet_url "application" # => http://www.example.com/assets/application.css @@ -757,7 +757,7 @@ This would add something like "Process data files (0.34523)" to the log, which y #### cache -A method for caching fragments of a view rather than an entire action or page. This technique is useful caching pieces like menus, lists of news topics, static HTML fragments, and so on. This method takes a block that contains the content you wish to cache. See +ActionController::Caching::Fragments+ for more information. +A method for caching fragments of a view rather than an entire action or page. This technique is useful caching pieces like menus, lists of news topics, static HTML fragments, and so on. This method takes a block that contains the content you wish to cache. See `ActionController::Caching::Fragments` for more information. ```ruby <% cache do %> @@ -769,7 +769,7 @@ A method for caching fragments of a view rather than an entire action or page. T #### capture -The +capture+ method allows you to extract part of a template into a variable. You can then use this variable anywhere in your templates or layout. +The `capture` method allows you to extract part of a template into a variable. You can then use this variable anywhere in your templates or layout. ```ruby <% @greeting = capture do %> @@ -792,9 +792,9 @@ The captured variable can then be used anywhere else. #### content_for -Calling +content_for+ stores a block of markup in an identifier for later use. You can make subsequent calls to the stored content in other templates or the layout by passing the identifier as an argument to +yield+. +Calling `content_for` stores a block of markup in an identifier for later use. You can make subsequent calls to the stored content in other templates or the layout by passing the identifier as an argument to `yield`. -For example, let's say we have a standard application layout, but also a special page that requires certain JavaScript that the rest of the site doesn't need. We can use +content_for+ to include this JavaScript on our special page without fattening up the rest of the site. +For example, let's say we have a standard application layout, but also a special page that requires certain JavaScript that the rest of the site doesn't need. We can use `content_for` to include this JavaScript on our special page without fattening up the rest of the site. *app/views/layouts/application.html.erb* @@ -840,7 +840,7 @@ datetime_select("post", "published_on") #### distance_of_time_in_words -Reports the approximate distance in time between two Time or Date objects or integers as seconds. Set +include_seconds+ to true if you want more detailed approximations. +Reports the approximate distance in time between two Time or Date objects or integers as seconds. Set `include_seconds` to true if you want more detailed approximations. ```ruby distance_of_time_in_words(Time.now, Time.now + 15.seconds) # => less than a minute @@ -849,7 +849,7 @@ distance_of_time_in_words(Time.now, Time.now + 15.seconds, :include_seconds => t #### select_date -Returns a set of html select-tags (one for year, month, and day) pre-selected with the +date+ provided. +Returns a set of html select-tags (one for year, month, and day) pre-selected with the `date` provided. ```ruby # Generates a date select that defaults to the date provided (six days after today) @@ -861,7 +861,7 @@ select_date() #### select_datetime -Returns a set of html select-tags (one for year, month, day, hour, and minute) pre-selected with the +datetime+ provided. +Returns a set of html select-tags (one for year, month, day, hour, and minute) pre-selected with the `datetime` provided. ```ruby # Generates a datetime select that defaults to the datetime provided (four days after today) @@ -930,7 +930,7 @@ select_time(Time.now) #### select_year -Returns a select tag with options for each of the five years on each side of the current, which is selected. The five year radius can be changed using the +:start_year+ and +:end_year+ keys in the +options+. +Returns a select tag with options for each of the five years on each side of the current, which is selected. The five year radius can be changed using the `:start_year` and `:end_year` keys in the `options`. ```ruby # Generates a select field for five years on either side of Date.today that defaults to the current year @@ -942,7 +942,7 @@ select_year(Date.today, :start_year => 1900, :end_year => 2009) #### time_ago_in_words -Like +distance_of_time_in_words+, but where +to_time+ is fixed to +Time.now+. +Like `distance_of_time_in_words`, but where `to_time` is fixed to `Time.now`. ```ruby time_ago_in_words(3.minutes.from_now) # => 3 minutes @@ -959,7 +959,7 @@ time_select("order", "submitted") ### DebugHelper -Returns a +pre+ tag that has object dumped by YAML. This creates a very readable way to inspect an object. +Returns a `pre` tag that has object dumped by YAML. This creates a very readable way to inspect an object. ```ruby my_hash = {'first' => 1, 'second' => 'two', 'third' => [1,2,3]} @@ -1125,7 +1125,7 @@ Provides a number of methods for turning different kinds of containers into a se #### collection_select -Returns +select+ and +option+ tags for the collection of existing return values of +method+ for +object+'s class. +Returns `select` and `option` tags for the collection of existing return values of `method` for `object`'s class. Example object structure for use with this method: @@ -1142,7 +1142,7 @@ class Author < ActiveRecord::Base end ``` -Sample usage (selecting the associated Author for an instance of Post, +@post+): +Sample usage (selecting the associated Author for an instance of Post, `@post`): ```ruby collection_select(:post, :author_id, Author.all, :id, :name_with_initial, {:prompt => true}) @@ -1161,7 +1161,7 @@ If `@post.author_id` is 1, this would return: #### collection_radio_buttons -Returns +radio_button+ tags for the collection of existing return values of +method+ for +object+'s class. +Returns `radio_button` tags for the collection of existing return values of `method` for `object`'s class. Example object structure for use with this method: @@ -1178,7 +1178,7 @@ class Author < ActiveRecord::Base end ``` -Sample usage (selecting the associated Author for an instance of Post, +@post+): +Sample usage (selecting the associated Author for an instance of Post, `@post`): ```ruby collection_radio_buttons(:post, :author_id, Author.all, :id, :name_with_initial) @@ -1197,7 +1197,7 @@ If `@post.author_id` is 1, this would return: #### collection_check_boxes -Returns +check_box+ tags for the collection of existing return values of +method+ for +object+'s class. +Returns `check_box` tags for the collection of existing return values of `method` for `object`'s class. Example object structure for use with this method: @@ -1214,7 +1214,7 @@ class Author < ActiveRecord::Base end ``` -Sample usage (selecting the associated Authors for an instance of Post, +@post+): +Sample usage (selecting the associated Authors for an instance of Post, `@post`): ```ruby collection_check_boxes(:post, :author_ids, Author.all, :id, :name_with_initial) @@ -1242,7 +1242,7 @@ Return select and option tags for the given object and method, using country_opt #### option_groups_from_collection_for_select -Returns a string of +option+ tags, like +options_from_collection_for_select+, but groups them by +optgroup+ tags based on the object relationships of the arguments. +Returns a string of `option` tags, like `options_from_collection_for_select`, but groups them by `optgroup` tags based on the object relationships of the arguments. Example object structure for use with this method: @@ -1280,7 +1280,7 @@ Possible output: </optgroup> ``` -Note: Only the +optgroup+ and +option+ tags are returned, so you still have to wrap the output in an appropriate +select+ tag. +Note: Only the `optgroup` and `option` tags are returned, so you still have to wrap the output in an appropriate `select` tag. #### options_for_select @@ -1291,11 +1291,11 @@ options_for_select([ "VISA", "MasterCard" ]) # => <option>VISA</option> <option>MasterCard</option> ``` -Note: Only the +option+ tags are returned, you have to wrap this call in a regular HTML +select+ tag. +Note: Only the `option` tags are returned, you have to wrap this call in a regular HTML `select` tag. #### options_from_collection_for_select -Returns a string of option tags that have been compiled by iterating over the +collection+ and assigning the result of a call to the +value_method+ as the option value and the +text_method+ as the option text. +Returns a string of option tags that have been compiled by iterating over the `collection` and assigning the result of a call to the `value_method` as the option value and the `text_method` as the option text. ```ruby # options_from_collection_for_select(collection, value_method, text_method, selected = nil) @@ -1308,7 +1308,7 @@ options_from_collection_for_select(@project.people, "id", "name") # => <option value="#{person.id}">#{person.name}</option> ``` -Note: Only the +option+ tags are returned, you have to wrap this call in a regular HTML +select+ tag. +Note: Only the `option` tags are returned, you have to wrap this call in a regular HTML `select` tag. #### select @@ -1337,7 +1337,7 @@ Returns a string of option tags for pretty much any time zone in the world. #### time_zone_select -Return select and option tags for the given object and method, using +time_zone_options_for_select+ to generate the list of option tags. +Return select and option tags for the given object and method, using `time_zone_options_for_select` to generate the list of option tags. ```ruby time_zone_select( "user", "time_zone") @@ -1389,7 +1389,7 @@ file_field_tag 'attachment' #### form_tag -Starts a form tag that points the action to an url configured with +url_for_options+ just like +ActionController::Base#url_for+. +Starts a form tag that points the action to an url configured with `url_for_options` just like `ActionController::Base#url_for`. ```ruby <%= form_tag '/posts' do %> @@ -1497,7 +1497,7 @@ end #### define_javascript_functions -Includes the Action Pack JavaScript libraries inside a single +script+ tag. +Includes the Action Pack JavaScript libraries inside a single `script` tag. #### escape_javascript @@ -1575,7 +1575,7 @@ number_with_delimiter(12345678) # => 12,345,678 #### number_with_precision -Formats a number with the specified level of +precision+, which defaults to 3. +Formats a number with the specified level of `precision`, which defaults to 3. ```ruby number_with_precision(111.2345) # => 111.235 @@ -1587,11 +1587,11 @@ Localized Views Action View has the ability render different templates depending on the current locale. -For example, suppose you have a Posts controller with a show action. By default, calling this action will render +app/views/posts/show.html.erb+. But if you set +I18n.locale = :de+, then +app/views/posts/show.de.html.erb+ will be rendered instead. If the localized template isn't present, the undecorated version will be used. This means you're not required to provide localized views for all cases, but they will be preferred and used if available. +For example, suppose you have a Posts controller with a show action. By default, calling this action will render `app/views/posts/show.html.erb`. But if you set `I18n.locale = :de`, then `app/views/posts/show.de.html.erb` will be rendered instead. If the localized template isn't present, the undecorated version will be used. This means you're not required to provide localized views for all cases, but they will be preferred and used if available. -You can use the same technique to localize the rescue files in your public directory. For example, setting +I18n.locale = :de+ and creating +public/500.de.html+ and +public/404.de.html+ would allow you to have localized rescue pages. +You can use the same technique to localize the rescue files in your public directory. For example, setting `I18n.locale = :de` and creating `public/500.de.html` and `public/404.de.html` would allow you to have localized rescue pages. -Since Rails doesn't restrict the symbols that you use to set I18n.locale, you can leverage this system to display different content depending on anything you like. For example, suppose you have some "expert" users that should see different pages from "normal" users. You could add the following to +app/controllers/application.rb+: +Since Rails doesn't restrict the symbols that you use to set I18n.locale, you can leverage this system to display different content depending on anything you like. For example, suppose you have some "expert" users that should see different pages from "normal" users. You could add the following to `app/controllers/application.rb`: ```ruby before_filter :set_expert_locale @@ -1601,6 +1601,6 @@ def set_expert_locale end ``` -Then you could create special views like +app/views/posts/show.expert.html.erb+ that would only be displayed to expert users. +Then you could create special views like `app/views/posts/show.expert.html.erb` that would only be displayed to expert users. You can read more about the Rails Internationalization (I18n) API "here":i18n.html. diff --git a/guides/source/active_record_basics.md b/guides/source/active_record_basics.md index 69f8eace41..e1e010e905 100644 --- a/guides/source/active_record_basics.md +++ b/guides/source/active_record_basics.md @@ -41,49 +41,49 @@ When writing applications using other programming languages or frameworks, it ma ### Naming Conventions -By default, Active Record uses some naming conventions to find out how the mapping between models and database tables should be created. Rails will pluralize your class names to find the respective database table. So, for a class +Book+, you should have a database table called *books*. The Rails pluralization mechanisms are very powerful, being capable to pluralize (and singularize) both regular and irregular words. When using class names composed of two or more words, the model class name should follow the Ruby conventions, using the CamelCase form, while the table name must contain the words separated by underscores. Examples: +By default, Active Record uses some naming conventions to find out how the mapping between models and database tables should be created. Rails will pluralize your class names to find the respective database table. So, for a class `Book`, you should have a database table called *books*. The Rails pluralization mechanisms are very powerful, being capable to pluralize (and singularize) both regular and irregular words. When using class names composed of two or more words, the model class name should follow the Ruby conventions, using the CamelCase form, while the table name must contain the words separated by underscores. Examples: -* Database Table - Plural with underscores separating words (e.g., +book_clubs+) -* Model Class - Singular with the first letter of each word capitalized (e.g., +BookClub+) +* Database Table - Plural with underscores separating words (e.g., `book_clubs`) +* Model Class - Singular with the first letter of each word capitalized (e.g., `BookClub`) |_.Model / Class |_.Table / Schema | -|+Post+ |+posts+| -|+LineItem+ |+line_items+| -|+Deer+ |+deer+| -|+Mouse+ |+mice+| -|+Person+ |+people+| +|`Post` |`posts`| +|`LineItem` |`line_items`| +|`Deer` |`deer`| +|`Mouse` |`mice`| +|`Person` |`people`| ### Schema Conventions Active Record uses naming conventions for the columns in database tables, depending on the purpose of these columns. -* *Foreign keys* - These fields should be named following the pattern +singularized_table_name_id+ (e.g., +item_id+, +order_id+). These are the fields that Active Record will look for when you create associations between your models. -* *Primary keys* - By default, Active Record will use an integer column named +id+ as the table's primary key. When using "Rails Migrations":migrations.html to create your tables, this column will be automatically created. +* *Foreign keys* - These fields should be named following the pattern `singularized_table_name_id` (e.g., `item_id`, `order_id`). These are the fields that Active Record will look for when you create associations between your models. +* *Primary keys* - By default, Active Record will use an integer column named `id` as the table's primary key. When using "Rails Migrations":migrations.html to create your tables, this column will be automatically created. There are also some optional column names that will create additional features to Active Record instances: -* +created_at+ - Automatically gets set to the current date and time when the record is first created. -* +created_on+ - Automatically gets set to the current date when the record is first created. -* +updated_at+ - Automatically gets set to the current date and time whenever the record is updated. -* +updated_on+ - Automatically gets set to the current date whenever the record is updated. -* +lock_version+ - Adds "optimistic locking":http://api.rubyonrails.org/classes/ActiveRecord/Locking.html to a model. -* +type+ - Specifies that the model uses "Single Table Inheritance":http://api.rubyonrails.org/classes/ActiveRecord/Base.html -* +(table_name)_count+ - Used to cache the number of belonging objects on associations. For example, a +comments_count+ column in a +Post+ class that has many instances of +Comment+ will cache the number of existent comments for each post. +* `created_at` - Automatically gets set to the current date and time when the record is first created. +* `created_on` - Automatically gets set to the current date when the record is first created. +* `updated_at` - Automatically gets set to the current date and time whenever the record is updated. +* `updated_on` - Automatically gets set to the current date whenever the record is updated. +* `lock_version` - Adds "optimistic locking":http://api.rubyonrails.org/classes/ActiveRecord/Locking.html to a model. +* `type` - Specifies that the model uses "Single Table Inheritance":http://api.rubyonrails.org/classes/ActiveRecord/Base.html +* `(table_name)_count` - Used to cache the number of belonging objects on associations. For example, a `comments_count` column in a `Post` class that has many instances of `Comment` will cache the number of existent comments for each post. -NOTE: While these column names are optional, they are in fact reserved by Active Record. Steer clear of reserved keywords unless you want the extra functionality. For example, +type+ is a reserved keyword used to designate a table using Single Table Inheritance (STI). If you are not using STI, try an analogous keyword like "context", that may still accurately describe the data you are modeling. +NOTE: While these column names are optional, they are in fact reserved by Active Record. Steer clear of reserved keywords unless you want the extra functionality. For example, `type` is a reserved keyword used to designate a table using Single Table Inheritance (STI). If you are not using STI, try an analogous keyword like "context", that may still accurately describe the data you are modeling. Creating Active Record Models ----------------------------- -It is very easy to create Active Record models. All you have to do is to subclass the +ActiveRecord::Base+ class and you're good to go: +It is very easy to create Active Record models. All you have to do is to subclass the `ActiveRecord::Base` class and you're good to go: ```ruby class Product < ActiveRecord::Base end ``` -This will create a +Product+ model, mapped to a +products+ table at the database. By doing this you'll also have the ability to map the columns of each row in that table with the attributes of the instances of your model. Suppose that the +products+ table was created using an SQL sentence like: +This will create a `Product` model, mapped to a `products` table at the database. By doing this you'll also have the ability to map the columns of each row in that table with the attributes of the instances of your model. Suppose that the `products` table was created using an SQL sentence like: ```sql CREATE TABLE products ( @@ -106,7 +106,7 @@ Overriding the Naming Conventions What if you need to follow a different naming convention or need to use your Rails application with a legacy database? No problem, you can easily override the default conventions. -You can use the +ActiveRecord::Base.table_name=+ method to specify the table name that should be used: +You can use the `ActiveRecord::Base.table_name=` method to specify the table name that should be used: ```ruby class Product < ActiveRecord::Base @@ -114,7 +114,7 @@ class Product < ActiveRecord::Base end ``` -If you do so, you will have to define manually the class name that is hosting the fixtures (class_name.yml) using the +set_fixture_class+ method in your test definition: +If you do so, you will have to define manually the class name that is hosting the fixtures (class_name.yml) using the `set_fixture_class` method in your test definition: ```ruby class FunnyJoke < ActiveSupport::TestCase @@ -124,7 +124,7 @@ class FunnyJoke < ActiveSupport::TestCase end ``` -It's also possible to override the column that should be used as the table's primary key using the +ActiveRecord::Base.set_primary_key+ method: +It's also possible to override the column that should be used as the table's primary key using the `ActiveRecord::Base.set_primary_key` method: ```ruby class Product < ActiveRecord::Base @@ -139,15 +139,15 @@ CRUD is an acronym for the four verbs we use to operate on data: *C*reate, *R*ea ### Create -Active Record objects can be created from a hash, a block or have their attributes manually set after creation. The +new+ method will return a new object while +create+ will return the object and save it to the database. +Active Record objects can be created from a hash, a block or have their attributes manually set after creation. The `new` method will return a new object while `create` will return the object and save it to the database. -For example, given a model +User+ with attributes of +name+ and +occupation+, the +create+ method call will create and save a new record into the database: +For example, given a model `User` with attributes of `name` and `occupation`, the `create` method call will create and save a new record into the database: ```ruby user = User.create(:name => "David", :occupation => "Code Artist") ``` -Using the +new+ method, an object can be created without being saved: +Using the `new` method, an object can be created without being saved: ```ruby user = User.new @@ -155,9 +155,9 @@ Using the +new+ method, an object can be created without being saved: user.occupation = "Code Artist" ``` -A call to +user.save+ will commit the record to the database. +A call to `user.save` will commit the record to the database. -Finally, if a block is provided, both +create+ and +new+ will yield the new object to that block for initialization: +Finally, if a block is provided, both `create` and `new` will yield the new object to that block for initialization: ```ruby user = User.new do |u| diff --git a/guides/source/active_record_querying.md b/guides/source/active_record_querying.md index bad38e3841..96b49aebdb 100644 --- a/guides/source/active_record_querying.md +++ b/guides/source/active_record_querying.md @@ -17,7 +17,7 @@ If you're used to using raw SQL to find database records, then you will generall Code examples throughout this guide will refer to one or more of the following models: -TIP: All of the following models use +id+ as the primary key, unless specified otherwise. +TIP: All of the following models use `id` as the primary key, unless specified otherwise. ```ruby class Client < ActiveRecord::Base @@ -53,29 +53,29 @@ Retrieving Objects from the Database To retrieve objects from the database, Active Record provides several finder methods. Each finder method allows you to pass arguments into it to perform certain queries on your database without writing raw SQL. The methods are: -* +bind+ -* +create_with+ -* +eager_load+ -* +extending+ -* +from+ -* +group+ -* +having+ -* +includes+ -* +joins+ -* +limit+ -* +lock+ -* +none+ -* +offset+ -* +order+ -* +none+ -* +preload+ -* +readonly+ -* +references+ -* +reorder+ -* +reverse_order+ -* +select+ -* +uniq+ -* +where+ +* `bind` +* `create_with` +* `eager_load` +* `extending` +* `from` +* `group` +* `having` +* `includes` +* `joins` +* `limit` +* `lock` +* `none` +* `offset` +* `order` +* `none` +* `preload` +* `readonly` +* `references` +* `reorder` +* `reverse_order` +* `select` +* `uniq` +* `where` All of the above methods return an instance of `ActiveRecord::Relation`. @@ -84,7 +84,7 @@ The primary operation of `Model.find(options)` can be summarized as: * Convert the supplied options to an equivalent SQL query. * Fire the SQL query and retrieve the corresponding results from the database. * Instantiate the equivalent Ruby object of the appropriate model for every resulting row. -* Run +after_find+ callbacks, if any. +* Run `after_find` callbacks, if any. ### Retrieving a Single Object @@ -106,9 +106,9 @@ The SQL equivalent of the above is: SELECT * FROM clients WHERE (clients.id = 10) LIMIT 1 ``` -`Model.find(primary_key)` will raise an +ActiveRecord::RecordNotFound+ exception if no matching record is found. +`Model.find(primary_key)` will raise an `ActiveRecord::RecordNotFound` exception if no matching record is found. -#### +take+ +#### `take` `Model.take` retrieves a record without any implicit ordering. For example: @@ -123,11 +123,11 @@ The SQL equivalent of the above is: SELECT * FROM clients LIMIT 1 ``` -`Model.take` returns +nil+ if no record is found and no exception will be raised. +`Model.take` returns `nil` if no record is found and no exception will be raised. TIP: The retrieved record may vary depending on the database engine. -#### +first+ +#### `first` `Model.first` finds the first record ordered by the primary key. For example: @@ -142,9 +142,9 @@ The SQL equivalent of the above is: SELECT * FROM clients ORDER BY clients.id ASC LIMIT 1 ``` -`Model.first` returns +nil+ if no matching record is found and no exception will be raised. +`Model.first` returns `nil` if no matching record is found and no exception will be raised. -#### +last+ +#### `last` `Model.last` finds the last record ordered by the primary key. For example: @@ -159,9 +159,9 @@ The SQL equivalent of the above is: SELECT * FROM clients ORDER BY clients.id DESC LIMIT 1 ``` -`Model.last` returns +nil+ if no matching record is found and no exception will be raised. +`Model.last` returns `nil` if no matching record is found and no exception will be raised. -#### +find_by+ +#### `find_by` `Model.find_by` finds the first record matching some conditions. For example: @@ -179,7 +179,7 @@ It is equivalent to writing: Client.where(first_name: 'Lifo').take ``` -#### +take!+ +#### `take!` `Model.take!` retrieves a record without any implicit ordering. For example: @@ -194,9 +194,9 @@ The SQL equivalent of the above is: SELECT * FROM clients LIMIT 1 ``` -`Model.take!` raises +ActiveRecord::RecordNotFound+ if no matching record is found. +`Model.take!` raises `ActiveRecord::RecordNotFound` if no matching record is found. -#### +first!+ +#### `first!` `Model.first!` finds the first record ordered by the primary key. For example: @@ -211,9 +211,9 @@ The SQL equivalent of the above is: SELECT * FROM clients ORDER BY clients.id ASC LIMIT 1 ``` -`Model.first!` raises +ActiveRecord::RecordNotFound+ if no matching record is found. +`Model.first!` raises `ActiveRecord::RecordNotFound` if no matching record is found. -#### +last!+ +#### `last!` `Model.last!` finds the last record ordered by the primary key. For example: @@ -228,11 +228,11 @@ The SQL equivalent of the above is: SELECT * FROM clients ORDER BY clients.id DESC LIMIT 1 ``` -`Model.last!` raises +ActiveRecord::RecordNotFound+ if no matching record is found. +`Model.last!` raises `ActiveRecord::RecordNotFound` if no matching record is found. -#### +find_by!+ +#### `find_by!` -`Model.find_by!` finds the first record matching some conditions. It raises +ActiveRecord::RecordNotFound+ if no matching record is found. For example: +`Model.find_by!` finds the first record matching some conditions. It raises `ActiveRecord::RecordNotFound` if no matching record is found. For example: ```ruby Client.find_by! first_name: 'Lifo' @@ -266,11 +266,11 @@ The SQL equivalent of the above is: SELECT * FROM clients WHERE (clients.id IN (1,10)) ``` -WARNING: `Model.find(array_of_primary_key)` will raise an +ActiveRecord::RecordNotFound+ exception unless a matching record is found for <strong>all</strong> of the supplied primary keys. +WARNING: `Model.find(array_of_primary_key)` will raise an `ActiveRecord::RecordNotFound` exception unless a matching record is found for <strong>all</strong> of the supplied primary keys. #### take -`Model.take(limit)` retrieves the first number of records specified by +limit+ without any explicit ordering: +`Model.take(limit)` retrieves the first number of records specified by `limit` without any explicit ordering: ```ruby Client.take(2) @@ -286,7 +286,7 @@ SELECT * FROM clients LIMIT 2 #### first -`Model.first(limit)` finds the first number of records specified by +limit+ ordered by primary key: +`Model.first(limit)` finds the first number of records specified by `limit` ordered by primary key: ```ruby Client.first(2) @@ -302,7 +302,7 @@ SELECT * FROM clients LIMIT 2 #### last -`Model.last(limit)` finds the number of records specified by +limit+ ordered by primary key in descending order: +`Model.last(limit)` finds the number of records specified by `limit` ordered by primary key in descending order: ```ruby Client.last(2) @@ -329,15 +329,15 @@ User.all.each do |user| end ``` -But this approach becomes increasingly impractical as the table size increases, since +User.all.each+ instructs Active Record to fetch _the entire table_ in a single pass, build a model object per row, and then keep the entire array of model objects in memory. Indeed, if we have a large number of records, the entire collection may exceed the amount of memory available. +But this approach becomes increasingly impractical as the table size increases, since `User.all.each` instructs Active Record to fetch _the entire table_ in a single pass, build a model object per row, and then keep the entire array of model objects in memory. Indeed, if we have a large number of records, the entire collection may exceed the amount of memory available. -Rails provides two methods that address this problem by dividing records into memory-friendly batches for processing. The first method, +find_each+, retrieves a batch of records and then yields _each_ record to the block individually as a model. The second method, +find_in_batches+, retrieves a batch of records and then yields _the entire batch_ to the block as an array of models. +Rails provides two methods that address this problem by dividing records into memory-friendly batches for processing. The first method, `find_each`, retrieves a batch of records and then yields _each_ record to the block individually as a model. The second method, `find_in_batches`, retrieves a batch of records and then yields _the entire batch_ to the block as an array of models. -TIP: The +find_each+ and +find_in_batches+ methods are intended for use in the batch processing of a large number of records that wouldn't fit in memory all at once. If you just need to loop over a thousand records the regular find methods are the preferred option. +TIP: The `find_each` and `find_in_batches` methods are intended for use in the batch processing of a large number of records that wouldn't fit in memory all at once. If you just need to loop over a thousand records the regular find methods are the preferred option. -#### +find_each+ +#### `find_each` -The +find_each+ method retrieves a batch of records and then yields _each_ record to the block individually as a model. In the following example, +find_each+ will retrieve 1000 records (the current default for both +find_each+ and +find_in_batches+) and then yield each record individually to the block as a model. This process is repeated until all of the records have been processed: +The `find_each` method retrieves a batch of records and then yields _each_ record to the block individually as a model. In the following example, `find_each` will retrieve 1000 records (the current default for both `find_each` and `find_in_batches`) and then yield each record individually to the block as a model. This process is repeated until all of the records have been processed: ```ruby User.find_each do |user| @@ -345,15 +345,15 @@ User.find_each do |user| end ``` -##### Options for +find_each+ +##### Options for `find_each` -The +find_each+ method accepts most of the options allowed by the regular +find+ method, except for +:order+ and +:limit+, which are reserved for internal use by +find_each+. +The `find_each` method accepts most of the options allowed by the regular `find` method, except for `:order` and `:limit`, which are reserved for internal use by `find_each`. -Two additional options, +:batch_size+ and +:start+, are available as well. +Two additional options, `:batch_size` and `:start`, are available as well. -*+:batch_size+* +*`:batch_size`* -The +:batch_size+ option allows you to specify the number of records to be retrieved in each batch, before being passed individually to the block. For example, to retrieve records in batches of 5000: +The `:batch_size` option allows you to specify the number of records to be retrieved in each batch, before being passed individually to the block. For example, to retrieve records in batches of 5000: ```ruby User.find_each(:batch_size => 5000) do |user| @@ -361,9 +361,9 @@ User.find_each(:batch_size => 5000) do |user| end ``` -*+:start+* +*`:start`* -By default, records are fetched in ascending order of the primary key, which must be an integer. The +:start+ option allows you to configure the first ID of the sequence whenever the lowest ID is not the one you need. This would be useful, for example, if you wanted to resume an interrupted batch process, provided you saved the last processed ID as a checkpoint. +By default, records are fetched in ascending order of the primary key, which must be an integer. The `:start` option allows you to configure the first ID of the sequence whenever the lowest ID is not the one you need. This would be useful, for example, if you wanted to resume an interrupted batch process, provided you saved the last processed ID as a checkpoint. For example, to send newsletters only to users with the primary key starting from 2000, and to retrieve them in batches of 5000: @@ -375,11 +375,11 @@ end Another example would be if you wanted multiple workers handling the same processing queue. You could have each worker handle 10000 records by setting the appropriate `:start` option on each worker. -NOTE: The +:include+ option allows you to name associations that should be loaded alongside with the models. +NOTE: The `:include` option allows you to name associations that should be loaded alongside with the models. -#### +find_in_batches+ +#### `find_in_batches` -The +find_in_batches+ method is similar to +find_each+, since both retrieve batches of records. The difference is that +find_in_batches+ yields _batches_ to the block as an array of models, instead of individually. The following example will yield to the supplied block an array of up to 1000 invoices at a time, with the final block containing any remaining invoices: +The `find_in_batches` method is similar to `find_each`, since both retrieve batches of records. The difference is that `find_in_batches` yields _batches_ to the block as an array of models, instead of individually. The following example will yield to the supplied block an array of up to 1000 invoices at a time, with the final block containing any remaining invoices: ```ruby # Give add_invoices an array of 1000 invoices at a time @@ -388,22 +388,22 @@ Invoice.find_in_batches(:include => :invoice_lines) do |invoices| end ``` -NOTE: The +:include+ option allows you to name associations that should be loaded alongside with the models. +NOTE: The `:include` option allows you to name associations that should be loaded alongside with the models. -##### Options for +find_in_batches+ +##### Options for `find_in_batches` -The +find_in_batches+ method accepts the same +:batch_size+ and +:start+ options as +find_each+, as well as most of the options allowed by the regular +find+ method, except for +:order+ and +:limit+, which are reserved for internal use by +find_in_batches+. +The `find_in_batches` method accepts the same `:batch_size` and `:start` options as `find_each`, as well as most of the options allowed by the regular `find` method, except for `:order` and `:limit`, which are reserved for internal use by `find_in_batches`. Conditions ---------- -The +where+ method allows you to specify conditions to limit the records returned, representing the +WHERE+-part of the SQL statement. Conditions can either be specified as a string, array, or hash. +The `where` method allows you to specify conditions to limit the records returned, representing the `WHERE`-part of the SQL statement. Conditions can either be specified as a string, array, or hash. ### Pure String Conditions -If you'd like to add conditions to your find, you could just specify them in there, just like +Client.where("orders_count = '2'")+. This will find all clients where the +orders_count+ field's value is 2. +If you'd like to add conditions to your find, you could just specify them in there, just like `Client.where("orders_count = '2'")`. This will find all clients where the `orders_count` field's value is 2. -WARNING: Building your own conditions as pure strings can leave you vulnerable to SQL injection exploits. For example, +Client.where("first_name LIKE '%#{params[:first_name]}%'")+ is not safe. See the next section for the preferred way to handle conditions using an array. +WARNING: Building your own conditions as pure strings can leave you vulnerable to SQL injection exploits. For example, `Client.where("first_name LIKE '%#{params[:first_name]}%'")` is not safe. See the next section for the preferred way to handle conditions using an array. ### Array Conditions @@ -413,7 +413,7 @@ Now what if that number could vary, say as an argument from somewhere? The find Client.where("orders_count = ?", params[:orders]) ``` -Active Record will go through the first element in the conditions value and any additional elements will replace the question marks +(?)+ in the first element. +Active Record will go through the first element in the conditions value and any additional elements will replace the question marks `(?)` in the first element. If you want to specify multiple conditions: @@ -421,7 +421,7 @@ If you want to specify multiple conditions: Client.where("orders_count = ? AND locked = ?", params[:orders], false) ``` -In this example, the first question mark will be replaced with the value in +params[:orders]+ and the second will be replaced with the SQL representation of +false+, which depends on the adapter. +In this example, the first question mark will be replaced with the value in `params[:orders]` and the second will be replaced with the SQL representation of `false`, which depends on the adapter. This code is highly preferable: @@ -441,7 +441,7 @@ TIP: For more information on the dangers of SQL injection, see the "Ruby on Rail #### Placeholder Conditions -Similar to the +(?)+ replacement style of params, you can also specify keys/values hash in your array conditions: +Similar to the `(?)` replacement style of params, you can also specify keys/values hash in your array conditions: ```ruby Client.where("created_at >= :start_date AND created_at <= :end_date", @@ -470,12 +470,12 @@ Client.where('locked' => true) In the case of a belongs_to relationship, an association key can be used to specify the model if an ActiveRecord object is used as the value. This method works with polymorphic relationships as well. -<ruby> +```ruby Post.where(:author => author) Author.joins(:posts).where(:posts => {:author => author}) -</ruby> +``` -NOTE: The values cannot be symbols. For example, you cannot do +Client.where(:status => :active)+. +NOTE: The values cannot be symbols. For example, you cannot do `Client.where(:status => :active)`. #### Range Conditions @@ -483,7 +483,7 @@ NOTE: The values cannot be symbols. For example, you cannot do +Client.where(:st Client.where(:created_at => (Time.now.midnight - 1.day)..Time.now.midnight) ``` -This will find all clients created yesterday by using a +BETWEEN+ SQL statement: +This will find all clients created yesterday by using a `BETWEEN` SQL statement: ```sql SELECT * FROM clients WHERE (clients.created_at BETWEEN '2008-12-21 00:00:00' AND '2008-12-22 00:00:00') @@ -493,7 +493,7 @@ This demonstrates a shorter syntax for the examples in "Array Conditions":#array #### Subset Conditions -If you want to find records using the +IN+ expression you can pass an array to the conditions hash: +If you want to find records using the `IN` expression you can pass an array to the conditions hash: ```ruby Client.where(:orders_count => [1,3,5]) @@ -508,15 +508,15 @@ SELECT * FROM clients WHERE (clients.orders_count IN (1,3,5)) Ordering -------- -To retrieve records from the database in a specific order, you can use the +order+ method. +To retrieve records from the database in a specific order, you can use the `order` method. -For example, if you're getting a set of records and want to order them in ascending order by the +created_at+ field in your table: +For example, if you're getting a set of records and want to order them in ascending order by the `created_at` field in your table: ```ruby Client.order("created_at") ``` -You could specify +ASC+ or +DESC+ as well: +You could specify `ASC` or `DESC` as well: ```ruby Client.order("created_at DESC") @@ -532,7 +532,7 @@ Client.order("orders_count ASC, created_at DESC") Client.order("orders_count ASC", "created_at DESC") ``` -If you want to call +order+ multiple times e.g. in different context, new order will prepend previous one +If you want to call `order` multiple times e.g. in different context, new order will prepend previous one ```ruby Client.order("orders_count ASC").order("created_at DESC") @@ -542,15 +542,15 @@ Client.order("orders_count ASC").order("created_at DESC") Selecting Specific Fields ------------------------- -By default, `Model.find` selects all the fields from the result set using +select *+. +By default, `Model.find` selects all the fields from the result set using `select *`. -To select only a subset of fields from the result set, you can specify the subset via the +select+ method. +To select only a subset of fields from the result set, you can specify the subset via the `select` method. -NOTE: If the +select+ method is used, all the returning objects will be "read only":#readonly-objects. +NOTE: If the `select` method is used, all the returning objects will be "read only":#readonly-objects. <br /> -For example, to select only +viewable_by+ and +locked+ columns: +For example, to select only `viewable_by` and `locked` columns: ```ruby Client.select("viewable_by, locked") @@ -568,9 +568,9 @@ Be careful because this also means you're initializing a model object with only ActiveModel::MissingAttributeError: missing attribute: <attribute> ``` -Where +<attribute>+ is the attribute you asked for. The +id+ method will not raise the +ActiveRecord::MissingAttributeError+, so just be careful when working with associations because they need the +id+ method to function properly. +Where `<attribute>` is the attribute you asked for. The `id` method will not raise the `ActiveRecord::MissingAttributeError`, so just be careful when working with associations because they need the `id` method to function properly. -If you would like to only grab a single record per unique value in a certain field, you can use +uniq+: +If you would like to only grab a single record per unique value in a certain field, you can use `uniq`: ```ruby Client.select(:name).uniq @@ -595,9 +595,9 @@ query.uniq(false) Limit and Offset ---------------- -To apply +LIMIT+ to the SQL fired by the +Model.find+, you can specify the +LIMIT+ using +limit+ and +offset+ methods on the relation. +To apply `LIMIT` to the SQL fired by the `Model.find`, you can specify the `LIMIT` using `limit` and `offset` methods on the relation. -You can use +limit+ to specify the number of records to be retrieved, and use +offset+ to specify the number of records to skip before starting to return the records. For example +You can use `limit` to specify the number of records to be retrieved, and use `offset` to specify the number of records to skip before starting to return the records. For example ```ruby Client.limit(5) @@ -609,7 +609,7 @@ will return a maximum of 5 clients and because it specifies no offset it will re SELECT * FROM clients LIMIT 5 ``` -Adding +offset+ to that +Adding `offset` to that ```ruby Client.limit(5).offset(30) @@ -624,7 +624,7 @@ SELECT * FROM clients LIMIT 5 OFFSET 30 Group ----- -To apply a +GROUP BY+ clause to the SQL fired by the finder, you can specify the +group+ method on the find. +To apply a `GROUP BY` clause to the SQL fired by the finder, you can specify the `group` method on the find. For example, if you want to find a collection of the dates orders were created on: @@ -632,7 +632,7 @@ For example, if you want to find a collection of the dates orders were created o Order.select("date(created_at) as ordered_date, sum(price) as total_price").group("date(created_at)") ``` -And this will give you a single +Order+ object for each date where there are orders in the database. +And this will give you a single `Order` object for each date where there are orders in the database. The SQL that would be executed would be something like this: @@ -645,7 +645,7 @@ GROUP BY date(created_at) Having ------ -SQL uses the +HAVING+ clause to specify conditions on the +GROUP BY+ fields. You can add the +HAVING+ clause to the SQL fired by the +Model.find+ by adding the +:having+ option to the find. +SQL uses the `HAVING` clause to specify conditions on the `GROUP BY` fields. You can add the `HAVING` clause to the SQL fired by the `Model.find` by adding the `:having` option to the find. For example: @@ -667,9 +667,9 @@ This will return single order objects for each day, but only those that are orde Overriding Conditions --------------------- -### +except+ +### `except` -You can specify certain conditions to be excepted by using the +except+ method. For example: +You can specify certain conditions to be excepted by using the `except` method. For example: ```ruby Post.where('id > 10').limit(20).order('id asc').except(:order) @@ -681,9 +681,9 @@ The SQL that would be executed: SELECT * FROM posts WHERE id > 10 LIMIT 20 ``` -### +only+ +### `only` -You can also override conditions using the +only+ method. For example: +You can also override conditions using the `only` method. For example: ```ruby Post.where('id > 10').limit(20).order('id desc').only(:order, :where) @@ -695,9 +695,9 @@ The SQL that would be executed: SELECT * FROM posts WHERE id > 10 ORDER BY id DESC ``` -### +reorder+ +### `reorder` -The +reorder+ method overrides the default scope order. For example: +The `reorder` method overrides the default scope order. For example: ```ruby class Post < ActiveRecord::Base @@ -715,15 +715,15 @@ The SQL that would be executed: SELECT * FROM posts WHERE id = 10 ORDER BY name ``` -In case the +reorder+ clause is not used, the SQL executed would be: +In case the `reorder` clause is not used, the SQL executed would be: ```sql SELECT * FROM posts WHERE id = 10 ORDER BY posted_at DESC ``` -### +reverse_order+ +### `reverse_order` -The +reverse_order+ method reverses the ordering clause if specified. +The `reverse_order` method reverses the ordering clause if specified. ```ruby Client.where("orders_count > 10").order(:name).reverse_order @@ -735,7 +735,7 @@ The SQL that would be executed: SELECT * FROM clients WHERE orders_count > 10 ORDER BY name DESC ``` -If no ordering clause is specified in the query, the +reverse_order+ orders by the primary key in reverse order. +If no ordering clause is specified in the query, the `reverse_order` orders by the primary key in reverse order. ```ruby Client.where("orders_count > 10").reverse_order @@ -752,7 +752,7 @@ This method accepts *no* arguments. Null Relation ------------- -The +none+ method returns a chainable relation with no records. Any subsequent conditions chained to the returned relation will continue generating empty relations. This is useful in scenarios where you need a chainable response to a method or a scope that could return zero results. +The `none` method returns a chainable relation with no records. Any subsequent conditions chained to the returned relation will continue generating empty relations. This is useful in scenarios where you need a chainable response to a method or a scope that could return zero results. ```ruby Post.none # returns an empty Relation and fires no queries. @@ -777,7 +777,7 @@ end Readonly Objects ---------------- -Active Record provides +readonly+ method on a relation to explicitly disallow modification of any of the returned objects. Any attempt to alter a readonly record will not succeed, raising an +ActiveRecord::ReadOnlyRecord+ exception. +Active Record provides `readonly` method on a relation to explicitly disallow modification of any of the returned objects. Any attempt to alter a readonly record will not succeed, raising an `ActiveRecord::ReadOnlyRecord` exception. ```ruby client = Client.readonly.first @@ -785,7 +785,7 @@ client.visits += 1 client.save ``` -As +client+ is explicitly set to be a readonly object, the above code will raise an +ActiveRecord::ReadOnlyRecord+ exception when calling +client.save+ with an updated value of _visits_. +As `client` is explicitly set to be a readonly object, the above code will raise an `ActiveRecord::ReadOnlyRecord` exception when calling `client.save` with an updated value of _visits_. Locking Records for Update -------------------------- @@ -799,11 +799,11 @@ Active Record provides two locking mechanisms: ### Optimistic Locking -Optimistic locking allows multiple users to access the same record for edits, and assumes a minimum of conflicts with the data. It does this by checking whether another process has made changes to a record since it was opened. An +ActiveRecord::StaleObjectError+ exception is thrown if that has occurred and the update is ignored. +Optimistic locking allows multiple users to access the same record for edits, and assumes a minimum of conflicts with the data. It does this by checking whether another process has made changes to a record since it was opened. An `ActiveRecord::StaleObjectError` exception is thrown if that has occurred and the update is ignored. <strong>Optimistic locking column</strong> -In order to use optimistic locking, the table needs to have a column called +lock_version+ of type integer. Each time the record is updated, Active Record increments the +lock_version+ column. If an update request is made with a lower value in the +lock_version+ field than is currently in the +lock_version+ column in the database, the update request will fail with an +ActiveRecord::StaleObjectError+. Example: +In order to use optimistic locking, the table needs to have a column called `lock_version` of type integer. Each time the record is updated, Active Record increments the `lock_version` column. If an update request is made with a lower value in the `lock_version` field than is currently in the `lock_version` column in the database, the update request will fail with an `ActiveRecord::StaleObjectError`. Example: ```ruby c1 = Client.find(1) @@ -820,7 +820,7 @@ You're then responsible for dealing with the conflict by rescuing the exception This behavior can be turned off by setting `ActiveRecord::Base.lock_optimistically = false`. -To override the name of the +lock_version+ column, +ActiveRecord::Base+ provides a class attribute called +locking_column+: +To override the name of the `lock_version` column, `ActiveRecord::Base` provides a class attribute called `locking_column`: ```ruby class Client < ActiveRecord::Base @@ -830,7 +830,7 @@ end ### Pessimistic Locking -Pessimistic locking uses a locking mechanism provided by the underlying database. Using +lock+ when building a relation obtains an exclusive lock on the selected rows. Relations using +lock+ are usually wrapped inside a transaction for preventing deadlock conditions. +Pessimistic locking uses a locking mechanism provided by the underlying database. Using `lock` when building a relation obtains an exclusive lock on the selected rows. Relations using `lock` are usually wrapped inside a transaction for preventing deadlock conditions. For example: @@ -851,7 +851,7 @@ Item Update (0.4ms) UPDATE `items` SET `updated_at` = '2009-02-07 18:05:56', ` SQL (0.8ms) COMMIT ``` -You can also pass raw SQL to the +lock+ method for allowing different types of locks. For example, MySQL has an expression called +LOCK IN SHARE MODE+ where you can lock a record but still allow other queries to read it. To specify this expression just pass it in as the lock option: +You can also pass raw SQL to the `lock` method for allowing different types of locks. For example, MySQL has an expression called `LOCK IN SHARE MODE` where you can lock a record but still allow other queries to read it. To specify this expression just pass it in as the lock option: ```ruby Item.transaction do @@ -874,11 +874,11 @@ end Joining Tables -------------- -Active Record provides a finder method called +joins+ for specifying +JOIN+ clauses on the resulting SQL. There are multiple ways to use the +joins+ method. +Active Record provides a finder method called `joins` for specifying `JOIN` clauses on the resulting SQL. There are multiple ways to use the `joins` method. ### Using a String SQL Fragment -You can just supply the raw SQL specifying the +JOIN+ clause to +joins+: +You can just supply the raw SQL specifying the `JOIN` clause to `joins`: ```ruby Client.joins('LEFT OUTER JOIN addresses ON addresses.client_id = clients.id') @@ -892,11 +892,11 @@ SELECT clients.* FROM clients LEFT OUTER JOIN addresses ON addresses.client_id = ### Using Array/Hash of Named Associations -WARNING: This method only works with +INNER JOIN+. +WARNING: This method only works with `INNER JOIN`. -Active Record lets you use the names of the "associations":association_basics.html defined on the model as a shortcut for specifying +JOIN+ clause for those associations when using the +joins+ method. +Active Record lets you use the names of the "associations":association_basics.html defined on the model as a shortcut for specifying `JOIN` clause for those associations when using the `joins` method. -For example, consider the following +Category+, +Post+, +Comments+ and +Guest+ models: +For example, consider the following `Category`, `Post`, `Comments` and `Guest` models: ```ruby class Category < ActiveRecord::Base @@ -923,7 +923,7 @@ class Tag < ActiveRecord::Base end ``` -Now all of the following will produce the expected join queries using +INNER JOIN+: +Now all of the following will produce the expected join queries using `INNER JOIN`: #### Joining a Single Association @@ -1004,12 +1004,12 @@ time_range = (Time.now.midnight - 1.day)..Time.now.midnight Client.joins(:orders).where(:orders => {:created_at => time_range}) ``` -This will find all clients who have orders that were created yesterday, again using a +BETWEEN+ SQL expression. +This will find all clients who have orders that were created yesterday, again using a `BETWEEN` SQL expression. Eager Loading Associations -------------------------- -Eager loading is the mechanism for loading the associated records of the objects returned by +Model.find+ using as few queries as possible. +Eager loading is the mechanism for loading the associated records of the objects returned by `Model.find` using as few queries as possible. <strong>N <plus> 1 queries problem</strong> @@ -1027,9 +1027,9 @@ This code looks fine at the first sight. But the problem lies within the total n <strong>Solution to N <plus> 1 queries problem</strong> -Active Record lets you specify in advance all the associations that are going to be loaded. This is possible by specifying the +includes+ method of the +Model.find+ call. With +includes+, Active Record ensures that all of the specified associations are loaded using the minimum possible number of queries. +Active Record lets you specify in advance all the associations that are going to be loaded. This is possible by specifying the `includes` method of the `Model.find` call. With `includes`, Active Record ensures that all of the specified associations are loaded using the minimum possible number of queries. -Revisiting the above case, we could rewrite +Client.limit(10)+ to use eager load addresses: +Revisiting the above case, we could rewrite `Client.limit(10)` to use eager load addresses: ```ruby clients = Client.includes(:address).limit(10) @@ -1049,7 +1049,7 @@ SELECT addresses.* FROM addresses ### Eager Loading Multiple Associations -Active Record lets you eager load any number of associations with a single +Model.find+ call by using an array, hash, or a nested hash of array/hash with the +includes+ method. +Active Record lets you eager load any number of associations with a single `Model.find` call by using an array, hash, or a nested hash of array/hash with the `includes` method. #### Array of Multiple Associations @@ -1069,30 +1069,30 @@ This will find the category with id 1 and eager load all of the associated posts ### Specifying Conditions on Eager Loaded Associations -Even though Active Record lets you specify conditions on the eager loaded associations just like +joins+, the recommended way is to use "joins":#joining-tables instead. +Even though Active Record lets you specify conditions on the eager loaded associations just like `joins`, the recommended way is to use "joins":#joining-tables instead. -However if you must do this, you may use +where+ as you would normally. +However if you must do this, you may use `where` as you would normally. ```ruby Post.includes(:comments).where("comments.visible" => true) ``` -This would generate a query which contains a +LEFT OUTER JOIN+ whereas the +joins+ method would generate one using the +INNER JOIN+ function instead. +This would generate a query which contains a `LEFT OUTER JOIN` whereas the `joins` method would generate one using the `INNER JOIN` function instead. ```ruby SELECT "posts"."id" AS t0_r0, ... "comments"."updated_at" AS t1_r5 FROM "posts" LEFT OUTER JOIN "comments" ON "comments"."post_id" = "posts"."id" WHERE (comments.visible = 1) ``` -If there was no +where+ condition, this would generate the normal set of two queries. +If there was no `where` condition, this would generate the normal set of two queries. -If, in the case of this +includes+ query, there were no comments for any posts, all the posts would still be loaded. By using +joins+ (an INNER JOIN), the join conditions *must* match, otherwise no records will be returned. +If, in the case of this `includes` query, there were no comments for any posts, all the posts would still be loaded. By using `joins` (an INNER JOIN), the join conditions *must* match, otherwise no records will be returned. Scopes ------ -Scoping allows you to specify commonly-used queries which can be referenced as method calls on the association objects or models. With these scopes, you can use every method previously covered such as +where+, +joins+ and +includes+. All scope methods will return an +ActiveRecord::Relation+ object which will allow for further methods (such as other scopes) to be called on it. +Scoping allows you to specify commonly-used queries which can be referenced as method calls on the association objects or models. With these scopes, you can use every method previously covered such as `where`, `joins` and `includes`. All scope methods will return an `ActiveRecord::Relation` object which will allow for further methods (such as other scopes) to be called on it. -To define a simple scope, we use the +scope+ method inside the class, passing the query that we'd like run when this scope is called: +To define a simple scope, we use the `scope` method inside the class, passing the query that we'd like run when this scope is called: ```ruby class Post < ActiveRecord::Base @@ -1119,13 +1119,13 @@ class Post < ActiveRecord::Base end ``` -To call this +published+ scope we can call it on either the class: +To call this `published` scope we can call it on either the class: ```ruby Post.published # => [published posts] ``` -Or on an association consisting of +Post+ objects: +Or on an association consisting of `Post` objects: ```ruby category = Category.first @@ -1167,7 +1167,7 @@ category.posts.created_before(time) ### Applying a default scope If we wish for a scope to be applied across all queries to the model we can use the -+default_scope+ method within the model itself. +`default_scope` method within the model itself. ```ruby class Client < ActiveRecord::Base @@ -1195,8 +1195,8 @@ end ### Removing all scoping -If we wish to remove scoping for any reason we can use the +unscoped+ method. This is -especially useful if a +default_scope+ is specified in the model and should not be +If we wish to remove scoping for any reason we can use the `unscoped` method. This is +especially useful if a `default_scope` is specified in the model and should not be applied for this particular query. ```ruby @@ -1205,8 +1205,8 @@ Client.unscoped.all This method removes all scoping and will do a normal query on the table. -Note that chaining +unscoped+ with a +scope+ does not work. In these cases, it is -recommended that you use the block form of +unscoped+: +Note that chaining `unscoped` with a `scope` does not work. In these cases, it is +recommended that you use the block form of `unscoped`: ```ruby Client.unscoped { @@ -1217,26 +1217,26 @@ Client.unscoped { Dynamic Finders --------------- -For every field (also known as an attribute) you define in your table, Active Record provides a finder method. If you have a field called +first_name+ on your +Client+ model for example, you get +find_by_first_name+ and +find_all_by_first_name+ for free from Active Record. If you have a +locked+ field on the +Client+ model, you also get +find_by_locked+ and +find_all_by_locked+ methods. +For every field (also known as an attribute) you define in your table, Active Record provides a finder method. If you have a field called `first_name` on your `Client` model for example, you get `find_by_first_name` and `find_all_by_first_name` for free from Active Record. If you have a `locked` field on the `Client` model, you also get `find_by_locked` and `find_all_by_locked` methods. -You can also use +find_last_by_*+ methods which will find the last record matching your argument. +You can also use `find_last_by_*` methods which will find the last record matching your argument. -You can specify an exclamation point (`!`) on the end of the dynamic finders to get them to raise an +ActiveRecord::RecordNotFound+ error if they do not return any records, like +Client.find_by_name!("Ryan")+ +You can specify an exclamation point (`!`) on the end of the dynamic finders to get them to raise an `ActiveRecord::RecordNotFound` error if they do not return any records, like `Client.find_by_name!("Ryan")` -If you want to find both by name and locked, you can chain these finders together by simply typing "+and+" between the fields. For example, +Client.find_by_first_name_and_locked("Ryan", true)+. +If you want to find both by name and locked, you can chain these finders together by simply typing "`and`" between the fields. For example, `Client.find_by_first_name_and_locked("Ryan", true)`. -WARNING: Up to and including Rails 3.1, when the number of arguments passed to a dynamic finder method is lesser than the number of fields, say `Client.find_by_name_and_locked("Ryan")`, the behavior is to pass +nil+ as the missing argument. This is *unintentional* and this behavior will be changed in Rails 3.2 to throw an +ArgumentError+. +WARNING: Up to and including Rails 3.1, when the number of arguments passed to a dynamic finder method is lesser than the number of fields, say `Client.find_by_name_and_locked("Ryan")`, the behavior is to pass `nil` as the missing argument. This is *unintentional* and this behavior will be changed in Rails 3.2 to throw an `ArgumentError`. Find or build a new object -------------------------- -It's common that you need to find a record or create it if it doesn't exist. You can do that with the +first_or_create+ and +first_or_create!+ methods. +It's common that you need to find a record or create it if it doesn't exist. You can do that with the `first_or_create` and `first_or_create!` methods. -### +first_or_create+ +### `first_or_create` -The +first_or_create+ method checks whether +first+ returns +nil+ or not. If it does return +nil+, then +create+ is called. This is very powerful when coupled with the +where+ method. Let's see an example. +The `first_or_create` method checks whether `first` returns `nil` or not. If it does return `nil`, then `create` is called. This is very powerful when coupled with the `where` method. Let's see an example. -Suppose you want to find a client named 'Andy', and if there's none, create one and additionally set his +locked+ attribute to false. You can do so by running: +Suppose you want to find a client named 'Andy', and if there's none, create one and additionally set his `locked` attribute to false. You can do so by running: ```ruby Client.where(:first_name => 'Andy').first_or_create(:locked => false) @@ -1252,40 +1252,40 @@ INSERT INTO clients (created_at, first_name, locked, orders_count, updated_at) V COMMIT ``` -+first_or_create+ returns either the record that already exists or the new record. In our case, we didn't already have a client named Andy so the record is created and returned. +`first_or_create` returns either the record that already exists or the new record. In our case, we didn't already have a client named Andy so the record is created and returned. -The new record might not be saved to the database; that depends on whether validations passed or not (just like +create+). +The new record might not be saved to the database; that depends on whether validations passed or not (just like `create`). -It's also worth noting that +first_or_create+ takes into account the arguments of the +where+ method. In the example above we didn't explicitly pass a +:first_name => 'Andy'+ argument to +first_or_create+. However, that was used when creating the new record because it was already passed before to the +where+ method. +It's also worth noting that `first_or_create` takes into account the arguments of the `where` method. In the example above we didn't explicitly pass a `:first_name => 'Andy'` argument to `first_or_create`. However, that was used when creating the new record because it was already passed before to the `where` method. -You can do the same with the +find_or_create_by+ method: +You can do the same with the `find_or_create_by` method: ```ruby Client.find_or_create_by_first_name(:first_name => "Andy", :locked => false) ``` -This method still works, but it's encouraged to use +first_or_create+ because it's more explicit on which arguments are used to _find_ the record and which are used to _create_, resulting in less confusion overall. +This method still works, but it's encouraged to use `first_or_create` because it's more explicit on which arguments are used to _find_ the record and which are used to _create_, resulting in less confusion overall. -### +first_or_create!+ +### `first_or_create!` -You can also use +first_or_create!+ to raise an exception if the new record is invalid. Validations are not covered on this guide, but let's assume for a moment that you temporarily add +You can also use `first_or_create!` to raise an exception if the new record is invalid. Validations are not covered on this guide, but let's assume for a moment that you temporarily add ```ruby validates :orders_count, :presence => true ``` -to your +Client+ model. If you try to create a new +Client+ without passing an +orders_count+, the record will be invalid and an exception will be raised: +to your `Client` model. If you try to create a new `Client` without passing an `orders_count`, the record will be invalid and an exception will be raised: ```ruby Client.where(:first_name => 'Andy').first_or_create!(:locked => false) # => ActiveRecord::RecordInvalid: Validation failed: Orders count can't be blank ``` -As with +first_or_create+ there is a +find_or_create_by!+ method but the +first_or_create!+ method is preferred for clarity. +As with `first_or_create` there is a `find_or_create_by!` method but the `first_or_create!` method is preferred for clarity. -### +first_or_initialize+ +### `first_or_initialize` -The +first_or_initialize+ method will work just like +first_or_create+ but it will not call +create+ but +new+. This means that a new model instance will be created in memory but won't be saved to the database. Continuing with the +first_or_create+ example, we now want the client named 'Nick': +The `first_or_initialize` method will work just like `first_or_create` but it will not call `create` but `new`. This means that a new model instance will be created in memory but won't be saved to the database. Continuing with the `first_or_create` example, we now want the client named 'Nick': ```ruby nick = Client.where(:first_name => 'Nick').first_or_initialize(:locked => false) @@ -1304,7 +1304,7 @@ Because the object is not yet stored in the database, the SQL generated looks li SELECT * FROM clients WHERE (clients.first_name = 'Nick') LIMIT 1 ``` -When you want to save it to the database, just call +save+: +When you want to save it to the database, just call `save`: ```ruby nick.save @@ -1314,7 +1314,7 @@ nick.save Finding by SQL -------------- -If you'd like to use your own SQL to find records in a table you can use +find_by_sql+. The +find_by_sql+ method will return an array of objects even if the underlying query returns just a single record. For example you could run this query: +If you'd like to use your own SQL to find records in a table you can use `find_by_sql`. The `find_by_sql` method will return an array of objects even if the underlying query returns just a single record. For example you could run this query: ```ruby Client.find_by_sql("SELECT * FROM clients @@ -1322,18 +1322,18 @@ Client.find_by_sql("SELECT * FROM clients ORDER clients.created_at desc") ``` -+find_by_sql+ provides you with a simple way of making custom calls to the database and retrieving instantiated objects. +`find_by_sql` provides you with a simple way of making custom calls to the database and retrieving instantiated objects. -+select_all+ +`select_all` ------------ -`find_by_sql` has a close relative called +connection#select_all+. +select_all+ will retrieve objects from the database using custom SQL just like +find_by_sql+ but will not instantiate them. Instead, you will get an array of hashes where each hash indicates a record. +`find_by_sql` has a close relative called `connection#select_all`. `select_all` will retrieve objects from the database using custom SQL just like `find_by_sql` but will not instantiate them. Instead, you will get an array of hashes where each hash indicates a record. ```ruby Client.connection.select_all("SELECT * FROM clients WHERE id = '1'") ``` -+pluck+ +`pluck` ------- `pluck` can be used to query a single or multiple columns from the underlying table of a model. It accepts a list of column names as argument and returns an array of values of the specified columns with the corresponding data type. @@ -1352,7 +1352,7 @@ Client.pluck(:id, :name) # => [[1, 'David'], [2, 'Jeremy'], [3, 'Jose']] ``` -+pluck+ makes it possible to replace code like +`pluck` makes it possible to replace code like ```ruby Client.select(:id).map { |c| c.id } @@ -1368,10 +1368,10 @@ Client.pluck(:id) Client.pluck(:id, :name) ``` -+ids+ +`ids` ----- -+ids+ can be used to pluck all the IDs for the relation using the table's primary key. +`ids` can be used to pluck all the IDs for the relation using the table's primary key. ```ruby Person.ids @@ -1390,13 +1390,13 @@ Person.ids Existence of Objects -------------------- -If you simply want to check for the existence of the object there's a method called +exists?+. This method will query the database using the same query as +find+, but instead of returning an object or collection of objects it will return either +true+ or +false+. +If you simply want to check for the existence of the object there's a method called `exists?`. This method will query the database using the same query as `find`, but instead of returning an object or collection of objects it will return either `true` or `false`. ```ruby Client.exists?(1) ``` -The +exists?+ method also takes multiple ids, but the catch is that it will return true if any one of those records exists. +The `exists?` method also takes multiple ids, but the catch is that it will return true if any one of those records exists. ```ruby Client.exists?(1,2,3) @@ -1404,21 +1404,21 @@ Client.exists?(1,2,3) Client.exists?([1,2,3]) ``` -It's even possible to use +exists?+ without any arguments on a model or a relation. +It's even possible to use `exists?` without any arguments on a model or a relation. ```ruby Client.where(:first_name => 'Ryan').exists? ``` -The above returns +true+ if there is at least one client with the +first_name+ 'Ryan' and +false+ otherwise. +The above returns `true` if there is at least one client with the `first_name` 'Ryan' and `false` otherwise. ```ruby Client.exists? ``` -The above returns +false+ if the +clients+ table is empty and +true+ otherwise. +The above returns `false` if the `clients` table is empty and `true` otherwise. -You can also use +any?+ and +many?+ to check for existence on a model or relation. +You can also use `any?` and `many?` to check for existence on a model or relation. ```ruby # via a model @@ -1473,13 +1473,13 @@ SELECT count(DISTINCT clients.id) AS count_all FROM clients ### Count -If you want to see how many records are in your model's table you could call +Client.count+ and that will return the number. If you want to be more specific and find all the clients with their age present in the database you can use +Client.count(:age)+. +If you want to see how many records are in your model's table you could call `Client.count` and that will return the number. If you want to be more specific and find all the clients with their age present in the database you can use `Client.count(:age)`. For options, please see the parent section, "Calculations":#calculations. ### Average -If you want to see the average of a certain number in one of your tables you can call the +average+ method on the class that relates to the table. This method call will look something like this: +If you want to see the average of a certain number in one of your tables you can call the `average` method on the class that relates to the table. This method call will look something like this: ```ruby Client.average("orders_count") @@ -1491,7 +1491,7 @@ For options, please see the parent section, "Calculations":#calculations. ### Minimum -If you want to find the minimum value of a field in your table you can call the +minimum+ method on the class that relates to the table. This method call will look something like this: +If you want to find the minimum value of a field in your table you can call the `minimum` method on the class that relates to the table. This method call will look something like this: ```ruby Client.minimum("age") @@ -1501,7 +1501,7 @@ For options, please see the parent section, "Calculations":#calculations. ### Maximum -If you want to find the maximum value of a field in your table you can call the +maximum+ method on the class that relates to the table. This method call will look something like this: +If you want to find the maximum value of a field in your table you can call the `maximum` method on the class that relates to the table. This method call will look something like this: ```ruby Client.maximum("age") @@ -1511,7 +1511,7 @@ For options, please see the parent section, "Calculations":#calculations. ### Sum -If you want to find the sum of a field for all records in your table you can call the +sum+ method on the class that relates to the table. This method call will look something like this: +If you want to find the sum of a field for all records in your table you can call the `sum` method on the class that relates to the table. This method call will look something like this: ```ruby Client.sum("orders_count") @@ -1560,7 +1560,7 @@ EXPLAIN for: SELECT "users".* FROM "users" INNER JOIN "posts" ON "posts"."user_i ``` Eager loading may trigger more than one query under the hood, and some queries -may need the results of previous ones. Because of that, +explain+ actually +may need the results of previous ones. Because of that, `explain` actually executes the query, and then asks for the query plans. For example, ```ruby @@ -1604,9 +1604,9 @@ compared to the total time needed to fetch records. So, a relation is seen as a unit of work, no matter whether the implementation of eager loading involves several queries under the hood. -A threshold of +nil+ disables automatic EXPLAINs. +A threshold of `nil` disables automatic EXPLAINs. -The default threshold in development mode is 0.5 seconds, and +nil+ in test and +The default threshold in development mode is 0.5 seconds, and `nil` in test and production modes. INFO. Automatic EXPLAIN gets disabled if Active Record has no logger, regardless @@ -1614,7 +1614,7 @@ of the value of the threshold. #### Disabling Automatic EXPLAIN -Automatic EXPLAIN can be selectively silenced with +ActiveRecord::Base.silence_auto_explain+: +Automatic EXPLAIN can be selectively silenced with `ActiveRecord::Base.silence_auto_explain`: ```ruby ActiveRecord::Base.silence_auto_explain do @@ -1625,8 +1625,8 @@ end That may be useful for queries you know are slow but fine, like a heavyweight report of an admin interface. -As its name suggests, +silence_auto_explain+ only silences automatic EXPLAINs. -Explicit calls to +ActiveRecord::Relation#explain+ run. +As its name suggests, `silence_auto_explain` only silences automatic EXPLAINs. +Explicit calls to `ActiveRecord::Relation#explain` run. ### Interpreting EXPLAIN diff --git a/guides/source/active_record_validations_callbacks.md b/guides/source/active_record_validations_callbacks.md index 551cd983e9..bf75f27d0c 100644 --- a/guides/source/active_record_validations_callbacks.md +++ b/guides/source/active_record_validations_callbacks.md @@ -40,14 +40,14 @@ There are several ways to validate data before it is saved into your database, i ### When Does Validation Happen? -There are two kinds of Active Record objects: those that correspond to a row inside your database and those that do not. When you create a fresh object, for example using the +new+ method, that object does not belong to the database yet. Once you call +save+ upon that object it will be saved into the appropriate database table. Active Record uses the +new_record?+ instance method to determine whether an object is already in the database or not. Consider the following simple Active Record class: +There are two kinds of Active Record objects: those that correspond to a row inside your database and those that do not. When you create a fresh object, for example using the `new` method, that object does not belong to the database yet. Once you call `save` upon that object it will be saved into the appropriate database table. Active Record uses the `new_record?` instance method to determine whether an object is already in the database or not. Consider the following simple Active Record class: ```ruby class Person < ActiveRecord::Base end ``` -We can see how it works by looking at some +rails console+ output: +We can see how it works by looking at some `rails console` output: ```ruby >> p = Person.new(:name => "John Doe") @@ -60,45 +60,45 @@ We can see how it works by looking at some +rails console+ output: => false ``` -Creating and saving a new record will send an SQL +INSERT+ operation to the database. Updating an existing record will send an SQL +UPDATE+ operation instead. Validations are typically run before these commands are sent to the database. If any validations fail, the object will be marked as invalid and Active Record will not perform the +INSERT+ or +UPDATE+ operation. This helps to avoid storing an invalid object in the database. You can choose to have specific validations run when an object is created, saved, or updated. +Creating and saving a new record will send an SQL `INSERT` operation to the database. Updating an existing record will send an SQL `UPDATE` operation instead. Validations are typically run before these commands are sent to the database. If any validations fail, the object will be marked as invalid and Active Record will not perform the `INSERT` or `UPDATE` operation. This helps to avoid storing an invalid object in the database. You can choose to have specific validations run when an object is created, saved, or updated. CAUTION: There are many ways to change the state of an object in the database. Some methods will trigger validations, but some will not. This means that it's possible to save an object in the database in an invalid state if you aren't careful. The following methods trigger validations, and will save the object to the database only if the object is valid: -* +create+ -* +create!+ -* +save+ -* +save!+ -* +update+ -* +update_attributes+ -* +update_attributes!+ +* `create` +* `create!` +* `save` +* `save!` +* `update` +* `update_attributes` +* `update_attributes!` -The bang versions (e.g. +save!+) raise an exception if the record is invalid. The non-bang versions don't: +save+ and +update_attributes+ return +false+, +create+ and +update+ just return the objects. +The bang versions (e.g. `save!`) raise an exception if the record is invalid. The non-bang versions don't: `save` and `update_attributes` return `false`, `create` and `update` just return the objects. ### Skipping Validations The following methods skip validations, and will save the object to the database regardless of its validity. They should be used with caution. -* +decrement!+ -* +decrement_counter+ -* +increment!+ -* +increment_counter+ -* +toggle!+ -* +touch+ -* +update_all+ -* +update_attribute+ -* +update_column+ -* +update_columns+ -* +update_counters+ +* `decrement!` +* `decrement_counter` +* `increment!` +* `increment_counter` +* `toggle!` +* `touch` +* `update_all` +* `update_attribute` +* `update_column` +* `update_columns` +* `update_counters` -Note that +save+ also has the ability to skip validations if passed +:validate => false+ as argument. This technique should be used with caution. +Note that `save` also has the ability to skip validations if passed `:validate => false` as argument. This technique should be used with caution. -* +save(:validate => false)+ +* `save(:validate => false)` -### +valid?+ and +invalid?+ +### `valid?` and `invalid?` -To verify whether or not an object is valid, Rails uses the +valid?+ method. You can also use this method on your own. +valid?+ triggers your validations and returns true if no errors were found in the object, and false otherwise. +To verify whether or not an object is valid, Rails uses the `valid?` method. You can also use this method on your own. `valid?` triggers your validations and returns true if no errors were found in the object, and false otherwise. ```ruby class Person < ActiveRecord::Base @@ -109,9 +109,9 @@ Person.create(:name => "John Doe").valid? # => true Person.create(:name => nil).valid? # => false ``` -After Active Record has performed validations, any errors found can be accessed through the +errors+ instance method, which returns a collection of errors. By definition, an object is valid if this collection is empty after running validations. +After Active Record has performed validations, any errors found can be accessed through the `errors` instance method, which returns a collection of errors. By definition, an object is valid if this collection is empty after running validations. -Note that an object instantiated with +new+ will not report errors even if it's technically invalid, because validations are not run when using +new+. +Note that an object instantiated with `new` will not report errors even if it's technically invalid, because validations are not run when using `new`. ```ruby class Person < ActiveRecord::Base @@ -143,13 +143,13 @@ end => ActiveRecord::RecordInvalid: Validation failed: Name can't be blank ``` -+invalid?+ is simply the inverse of +valid?+. +invalid?+ triggers your validations, returning true if any errors were found in the object, and false otherwise. +`invalid?` is simply the inverse of `valid?`. `invalid?` triggers your validations, returning true if any errors were found in the object, and false otherwise. -### +errors[]+ +### `errors[]` -To verify whether or not a particular attribute of an object is valid, you can use +errors[:attribute]+. It returns an array of all the errors for +:attribute+. If there are no errors on the specified attribute, an empty array is returned. +To verify whether or not a particular attribute of an object is valid, you can use `errors[:attribute]`. It returns an array of all the errors for `:attribute`. If there are no errors on the specified attribute, an empty array is returned. -This method is only useful _after_ validations have been run, because it only inspects the errors collection and does not trigger validations itself. It's different from the +ActiveRecord::Base#invalid?+ method explained above because it doesn't verify the validity of the object as a whole. It only checks to see whether there are errors found on an individual attribute of the object. +This method is only useful _after_ validations have been run, because it only inspects the errors collection and does not trigger validations itself. It's different from the `ActiveRecord::Base#invalid?` method explained above because it doesn't verify the validity of the object as a whole. It only checks to see whether there are errors found on an individual attribute of the object. ```ruby class Person < ActiveRecord::Base @@ -165,13 +165,13 @@ We'll cover validation errors in greater depth in the "Working with Validation E Validation Helpers ------------------ -Active Record offers many pre-defined validation helpers that you can use directly inside your class definitions. These helpers provide common validation rules. Every time a validation fails, an error message is added to the object's +errors+ collection, and this message is associated with the attribute being validated. +Active Record offers many pre-defined validation helpers that you can use directly inside your class definitions. These helpers provide common validation rules. Every time a validation fails, an error message is added to the object's `errors` collection, and this message is associated with the attribute being validated. Each helper accepts an arbitrary number of attribute names, so with a single line of code you can add the same kind of validation to several attributes. -All of them accept the +:on+ and +:message+ options, which define when the validation should be run and what message should be added to the +errors+ collection if it fails, respectively. The +:on+ option takes one of the values +:save+ (the default), +:create+ or +:update+. There is a default error message for each one of the validation helpers. These messages are used when the +:message+ option isn't specified. Let's take a look at each one of the available helpers. +All of them accept the `:on` and `:message` options, which define when the validation should be run and what message should be added to the `errors` collection if it fails, respectively. The `:on` option takes one of the values `:save` (the default), `:create` or `:update`. There is a default error message for each one of the validation helpers. These messages are used when the `:message` option isn't specified. Let's take a look at each one of the available helpers. -### +acceptance+ +### `acceptance` Validates that a checkbox on the user interface was checked when a form was submitted. This is typically used when the user needs to agree to your application's terms of service, confirm reading some text, or any similar concept. This validation is very specific to web applications and this 'acceptance' does not need to be recorded anywhere in your database (if you don't have a field for it, the helper will just create a virtual attribute). @@ -183,7 +183,7 @@ end The default error message for this helper is "_must be accepted_". -It can receive an +:accept+ option, which determines the value that will be considered acceptance. It defaults to "1" and can be easily changed. +It can receive an `:accept` option, which determines the value that will be considered acceptance. It defaults to "1" and can be easily changed. ```ruby class Person < ActiveRecord::Base @@ -191,9 +191,9 @@ class Person < ActiveRecord::Base end ``` -### +validates_associated+ +### `validates_associated` -You should use this helper when your model has associations with other models and they also need to be validated. When you try to save your object, +valid?+ will be called upon each one of the associated objects. +You should use this helper when your model has associations with other models and they also need to be validated. When you try to save your object, `valid?` will be called upon each one of the associated objects. ```ruby class Library < ActiveRecord::Base @@ -204,11 +204,11 @@ end This validation will work with all of the association types. -CAUTION: Don't use +validates_associated+ on both ends of your associations. They would call each other in an infinite loop. +CAUTION: Don't use `validates_associated` on both ends of your associations. They would call each other in an infinite loop. -The default error message for +validates_associated+ is "_is invalid_". Note that each associated object will contain its own +errors+ collection; errors do not bubble up to the calling model. +The default error message for `validates_associated` is "_is invalid_". Note that each associated object will contain its own `errors` collection; errors do not bubble up to the calling model. -### +confirmation+ +### `confirmation` You should use this helper when you have two text fields that should receive exactly the same content. For example, you may want to confirm an email address or a password. This validation creates a virtual attribute whose name is the name of the field that has to be confirmed with "_confirmation" appended. @@ -225,7 +225,7 @@ In your view template you could use something like <%= text_field :person, :email_confirmation %> ``` -This check is performed only if +email_confirmation+ is not +nil+. To require confirmation, make sure to add a presence check for the confirmation attribute (we'll take a look at +presence+ later on this guide): +This check is performed only if `email_confirmation` is not `nil`. To require confirmation, make sure to add a presence check for the confirmation attribute (we'll take a look at `presence` later on this guide): ```ruby class Person < ActiveRecord::Base @@ -236,7 +236,7 @@ end The default error message for this helper is "_doesn't match confirmation_". -### +exclusion+ +### `exclusion` This helper validates that the attributes' values are not included in a given set. In fact, this set can be any enumerable object. @@ -247,13 +247,13 @@ class Account < ActiveRecord::Base end ``` -The +exclusion+ helper has an option +:in+ that receives the set of values that will not be accepted for the validated attributes. The +:in+ option has an alias called +:within+ that you can use for the same purpose, if you'd like to. This example uses the +:message+ option to show how you can include the attribute's value. +The `exclusion` helper has an option `:in` that receives the set of values that will not be accepted for the validated attributes. The `:in` option has an alias called `:within` that you can use for the same purpose, if you'd like to. This example uses the `:message` option to show how you can include the attribute's value. The default error message is "_is reserved_". -### +format+ +### `format` -This helper validates the attributes' values by testing whether they match a given regular expression, which is specified using the +:with+ option. +This helper validates the attributes' values by testing whether they match a given regular expression, which is specified using the `:with` option. ```ruby class Product < ActiveRecord::Base @@ -264,7 +264,7 @@ end The default error message is "_is invalid_". -### +inclusion+ +### `inclusion` This helper validates that the attributes' values are included in a given set. In fact, this set can be any enumerable object. @@ -275,11 +275,11 @@ class Coffee < ActiveRecord::Base end ``` -The +inclusion+ helper has an option +:in+ that receives the set of values that will be accepted. The +:in+ option has an alias called +:within+ that you can use for the same purpose, if you'd like to. The previous example uses the +:message+ option to show how you can include the attribute's value. +The `inclusion` helper has an option `:in` that receives the set of values that will be accepted. The `:in` option has an alias called `:within` that you can use for the same purpose, if you'd like to. The previous example uses the `:message` option to show how you can include the attribute's value. The default error message for this helper is "_is not included in the list_". -### +length+ +### `length` This helper validates the length of the attributes' values. It provides a variety of options, so you can specify length constraints in different ways: @@ -294,12 +294,12 @@ end The possible length constraint options are: -* +:minimum+ - The attribute cannot have less than the specified length. -* +:maximum+ - The attribute cannot have more than the specified length. -* +:in+ (or +:within+) - The attribute length must be included in a given interval. The value for this option must be a range. -* +:is+ - The attribute length must be equal to the given value. +* `:minimum` - The attribute cannot have less than the specified length. +* `:maximum` - The attribute cannot have more than the specified length. +* `:in` (or `:within`) - The attribute length must be included in a given interval. The value for this option must be a range. +* `:is` - The attribute length must be equal to the given value. -The default error messages depend on the type of length validation being performed. You can personalize these messages using the +:wrong_length+, +:too_long+, and +:too_short+ options and `%{count}` as a placeholder for the number corresponding to the length constraint being used. You can still use the +:message+ option to specify an error message. +The default error messages depend on the type of length validation being performed. You can personalize these messages using the `:wrong_length`, `:too_long`, and `:too_short` options and `%{count}` as a placeholder for the number corresponding to the length constraint being used. You can still use the `:message` option to specify an error message. ```ruby class Person < ActiveRecord::Base @@ -308,7 +308,7 @@ class Person < ActiveRecord::Base end ``` -This helper counts characters by default, but you can split the value in a different way using the +:tokenizer+ option: +This helper counts characters by default, but you can split the value in a different way using the `:tokenizer` option: ```ruby class Essay < ActiveRecord::Base @@ -322,21 +322,21 @@ class Essay < ActiveRecord::Base end ``` -Note that the default error messages are plural (e.g., "is too short (minimum is %{count} characters)"). For this reason, when +:minimum+ is 1 you should provide a personalized message or use +validates_presence_of+ instead. When +:in+ or +:within+ have a lower limit of 1, you should either provide a personalized message or call +presence+ prior to +length+. +Note that the default error messages are plural (e.g., "is too short (minimum is %{count} characters)"). For this reason, when `:minimum` is 1 you should provide a personalized message or use `validates_presence_of` instead. When `:in` or `:within` have a lower limit of 1, you should either provide a personalized message or call `presence` prior to `length`. -The +size+ helper is an alias for +length+. +The `size` helper is an alias for `length`. -### +numericality+ +### `numericality` -This helper validates that your attributes have only numeric values. By default, it will match an optional sign followed by an integral or floating point number. To specify that only integral numbers are allowed set +:only_integer+ to true. +This helper validates that your attributes have only numeric values. By default, it will match an optional sign followed by an integral or floating point number. To specify that only integral numbers are allowed set `:only_integer` to true. -If you set +:only_integer+ to +true+, then it will use the +If you set `:only_integer` to `true`, then it will use the ```ruby /\A[<plus>-]?\d<plus>\Z/ ``` -regular expression to validate the attribute's value. Otherwise, it will try to convert the value to a number using +Float+. +regular expression to validate the attribute's value. Otherwise, it will try to convert the value to a number using `Float`. WARNING. Note that the regular expression above allows a trailing newline character. @@ -347,21 +347,21 @@ class Player < ActiveRecord::Base end ``` -Besides +:only_integer+, this helper also accepts the following options to add constraints to acceptable values: +Besides `:only_integer`, this helper also accepts the following options to add constraints to acceptable values: -* +:greater_than+ - Specifies the value must be greater than the supplied value. The default error message for this option is "_must be greater than %{count}_". -* +:greater_than_or_equal_to+ - Specifies the value must be greater than or equal to the supplied value. The default error message for this option is "_must be greater than or equal to %{count}_". -* +:equal_to+ - Specifies the value must be equal to the supplied value. The default error message for this option is "_must be equal to %{count}_". -* +:less_than+ - Specifies the value must be less than the supplied value. The default error message for this option is "_must be less than %{count}_". -* +:less_than_or_equal_to+ - Specifies the value must be less than or equal the supplied value. The default error message for this option is "_must be less than or equal to %{count}_". -* +:odd+ - Specifies the value must be an odd number if set to true. The default error message for this option is "_must be odd_". -* +:even+ - Specifies the value must be an even number if set to true. The default error message for this option is "_must be even_". +* `:greater_than` - Specifies the value must be greater than the supplied value. The default error message for this option is "_must be greater than %{count}_". +* `:greater_than_or_equal_to` - Specifies the value must be greater than or equal to the supplied value. The default error message for this option is "_must be greater than or equal to %{count}_". +* `:equal_to` - Specifies the value must be equal to the supplied value. The default error message for this option is "_must be equal to %{count}_". +* `:less_than` - Specifies the value must be less than the supplied value. The default error message for this option is "_must be less than %{count}_". +* `:less_than_or_equal_to` - Specifies the value must be less than or equal the supplied value. The default error message for this option is "_must be less than or equal to %{count}_". +* `:odd` - Specifies the value must be an odd number if set to true. The default error message for this option is "_must be odd_". +* `:even` - Specifies the value must be an even number if set to true. The default error message for this option is "_must be even_". The default error message is "_is not a number_". -### +presence+ +### `presence` -This helper validates that the specified attributes are not empty. It uses the +blank?+ method to check if the value is either +nil+ or a blank string, that is, a string that is either empty or consists of whitespace. +This helper validates that the specified attributes are not empty. It uses the `blank?` method to check if the value is either `nil` or a blank string, that is, a string that is either empty or consists of whitespace. ```ruby class Person < ActiveRecord::Base @@ -378,13 +378,13 @@ class LineItem < ActiveRecord::Base end ``` -If you validate the presence of an object associated via a +has_one+ or +has_many+ relationship, it will check that the object is neither +blank?+ nor +marked_for_destruction?+. +If you validate the presence of an object associated via a `has_one` or `has_many` relationship, it will check that the object is neither `blank?` nor `marked_for_destruction?`. -Since +false.blank?+ is true, if you want to validate the presence of a boolean field you should use `validates :field_name, :inclusion => { :in => [true, false] }`. +Since `false.blank?` is true, if you want to validate the presence of a boolean field you should use `validates :field_name, :inclusion => { :in => [true, false] }`. The default error message is "_can't be empty_". -### +uniqueness+ +### `uniqueness` This helper validates that the attribute's value is unique right before the object gets saved. It does not create a uniqueness constraint in the database, so it may happen that two different database connections create two records with the same value for a column that you intend to be unique. To avoid that, you must create a unique index in your database. @@ -396,7 +396,7 @@ end The validation happens by performing an SQL query into the model's table, searching for an existing record with the same value in that attribute. -There is a +:scope+ option that you can use to specify other attributes that are used to limit the uniqueness check: +There is a `:scope` option that you can use to specify other attributes that are used to limit the uniqueness check: ```ruby class Holiday < ActiveRecord::Base @@ -405,7 +405,7 @@ class Holiday < ActiveRecord::Base end ``` -There is also a +:case_sensitive+ option that you can use to define whether the uniqueness constraint will be case sensitive or not. This option defaults to true. +There is also a `:case_sensitive` option that you can use to define whether the uniqueness constraint will be case sensitive or not. This option defaults to true. ```ruby class Person < ActiveRecord::Base @@ -417,7 +417,7 @@ WARNING. Note that some databases are configured to perform case-insensitive sea The default error message is "_has already been taken_". -### +validates_with+ +### `validates_with` This helper passes the record to a separate class for validation. @@ -435,13 +435,13 @@ class GoodnessValidator < ActiveModel::Validator end ``` -NOTE: Errors added to +record.errors[:base]+ relate to the state of the record as a whole, and not to a specific attribute. +NOTE: Errors added to `record.errors[:base]` relate to the state of the record as a whole, and not to a specific attribute. -The +validates_with+ helper takes a class, or a list of classes to use for validation. There is no default error message for +validates_with+. You must manually add errors to the record's errors collection in the validator class. +The `validates_with` helper takes a class, or a list of classes to use for validation. There is no default error message for `validates_with`. You must manually add errors to the record's errors collection in the validator class. -To implement the validate method, you must have a +record+ parameter defined, which is the record to be validated. +To implement the validate method, you must have a `record` parameter defined, which is the record to be validated. -Like all other validations, +validates_with+ takes the +:if+, +:unless+ and +:on+ options. If you pass any other options, it will send those options to the validator class as +options+: +Like all other validations, `validates_with` takes the `:if`, `:unless` and `:on` options. If you pass any other options, it will send those options to the validator class as `options`: ```ruby class Person < ActiveRecord::Base @@ -457,9 +457,9 @@ class GoodnessValidator < ActiveModel::Validator end ``` -### +validates_each+ +### `validates_each` -This helper validates attributes against a block. It doesn't have a predefined validation function. You should create one using a block, and every attribute passed to +validates_each+ will be tested against it. In the following example, we don't want names and surnames to begin with lower case. +This helper validates attributes against a block. It doesn't have a predefined validation function. You should create one using a block, and every attribute passed to `validates_each` will be tested against it. In the following example, we don't want names and surnames to begin with lower case. ```ruby class Person < ActiveRecord::Base @@ -476,9 +476,9 @@ Common Validation Options These are common validation options: -### +:allow_nil+ +### `:allow_nil` -The +:allow_nil+ option skips the validation when the value being validated is +nil+. +The `:allow_nil` option skips the validation when the value being validated is `nil`. ```ruby class Coffee < ActiveRecord::Base @@ -487,11 +487,11 @@ class Coffee < ActiveRecord::Base end ``` -TIP: +:allow_nil+ is ignored by the presence validator. +TIP: `:allow_nil` is ignored by the presence validator. -### +:allow_blank+ +### `:allow_blank` -The +:allow_blank+ option is similar to the +:allow_nil+ option. This option will let validation pass if the attribute's value is +blank?+, like +nil+ or an empty string for example. +The `:allow_blank` option is similar to the `:allow_nil` option. This option will let validation pass if the attribute's value is `blank?`, like `nil` or an empty string for example. ```ruby class Topic < ActiveRecord::Base @@ -502,15 +502,15 @@ Topic.create("title" => "").valid? # => true Topic.create("title" => nil).valid? # => true ``` -TIP: +:allow_blank+ is ignored by the presence validator. +TIP: `:allow_blank` is ignored by the presence validator. -### +:message+ +### `:message` -As you've already seen, the +:message+ option lets you specify the message that will be added to the +errors+ collection when validation fails. When this option is not used, Active Record will use the respective default error message for each validation helper. +As you've already seen, the `:message` option lets you specify the message that will be added to the `errors` collection when validation fails. When this option is not used, Active Record will use the respective default error message for each validation helper. -### +:on+ +### `:on` -The +:on+ option lets you specify when the validation should happen. The default behavior for all the built-in validation helpers is to be run on save (both when you're creating a new record and when you're updating it). If you want to change it, you can use +:on => :create+ to run the validation only when a new record is created or +:on => :update+ to run the validation only when a record is updated. +The `:on` option lets you specify when the validation should happen. The default behavior for all the built-in validation helpers is to be run on save (both when you're creating a new record and when you're updating it). If you want to change it, you can use `:on => :create` to run the validation only when a new record is created or `:on => :update` to run the validation only when a record is updated. ```ruby class Person < ActiveRecord::Base @@ -528,7 +528,7 @@ end Strict Validations ------------------ -You can also specify validations to be strict and raise +ActiveModel::StrictValidationFailed+ when the object is invalid. +You can also specify validations to be strict and raise `ActiveModel::StrictValidationFailed` when the object is invalid. ```ruby class Person < ActiveRecord::Base @@ -538,7 +538,7 @@ end Person.new.valid? => ActiveModel::StrictValidationFailed: Name can't be blank ``` -There is also an ability to pass custom exception to +:strict+ option +There is also an ability to pass custom exception to `:strict` option ```ruby class Person < ActiveRecord::Base @@ -551,11 +551,11 @@ Person.new.valid? => TokenGenerationException: Token can't be blank Conditional Validation ---------------------- -Sometimes it will make sense to validate an object just when a given predicate is satisfied. You can do that by using the +:if+ and +:unless+ options, which can take a symbol, a string, a +Proc+ or an +Array+. You may use the +:if+ option when you want to specify when the validation *should* happen. If you want to specify when the validation *should not* happen, then you may use the +:unless+ option. +Sometimes it will make sense to validate an object just when a given predicate is satisfied. You can do that by using the `:if` and `:unless` options, which can take a symbol, a string, a `Proc` or an `Array`. You may use the `:if` option when you want to specify when the validation *should* happen. If you want to specify when the validation *should not* happen, then you may use the `:unless` option. -### Using a Symbol with +:if+ and +:unless+ +### Using a Symbol with `:if` and `:unless` -You can associate the +:if+ and +:unless+ options with a symbol corresponding to the name of a method that will get called right before validation happens. This is the most commonly used option. +You can associate the `:if` and `:unless` options with a symbol corresponding to the name of a method that will get called right before validation happens. This is the most commonly used option. ```ruby class Order < ActiveRecord::Base @@ -567,9 +567,9 @@ class Order < ActiveRecord::Base end ``` -### Using a String with +:if+ and +:unless+ +### Using a String with `:if` and `:unless` -You can also use a string that will be evaluated using +eval+ and needs to contain valid Ruby code. You should use this option only when the string represents a really short condition. +You can also use a string that will be evaluated using `eval` and needs to contain valid Ruby code. You should use this option only when the string represents a really short condition. ```ruby class Person < ActiveRecord::Base @@ -577,9 +577,9 @@ class Person < ActiveRecord::Base end ``` -### Using a Proc with +:if+ and +:unless+ +### Using a Proc with `:if` and `:unless` -Finally, it's possible to associate +:if+ and +:unless+ with a +Proc+ object which will be called. Using a +Proc+ object gives you the ability to write an inline condition instead of a separate method. This option is best suited for one-liners. +Finally, it's possible to associate `:if` and `:unless` with a `Proc` object which will be called. Using a `Proc` object gives you the ability to write an inline condition instead of a separate method. This option is best suited for one-liners. ```ruby class Account < ActiveRecord::Base @@ -590,7 +590,7 @@ end ### Grouping conditional validations -Sometimes it is useful to have multiple validations use one condition, it can be easily achieved using +with_options+. +Sometimes it is useful to have multiple validations use one condition, it can be easily achieved using `with_options`. ```ruby class User < ActiveRecord::Base @@ -601,11 +601,11 @@ class User < ActiveRecord::Base end ``` -All validations inside of +with_options+ block will have automatically passed the condition +:if => :is_admin?+ +All validations inside of `with_options` block will have automatically passed the condition `:if => :is_admin?` ### Combining validation conditions -On the other hand, when multiple conditions define whether or not a validation should happen, an +Array+ can be used. Moreover, you can apply both +:if:+ and +:unless+ to the same validation. +On the other hand, when multiple conditions define whether or not a validation should happen, an `Array` can be used. Moreover, you can apply both `:if:` and `:unless` to the same validation. ```ruby class Computer < ActiveRecord::Base @@ -615,7 +615,7 @@ class Computer < ActiveRecord::Base end ``` -The validation only runs when all the +:if+ conditions and none of the +:unless+ conditions are evaluated to +true+. +The validation only runs when all the `:if` conditions and none of the `:unless` conditions are evaluated to `true`. Performing Custom Validations ----------------------------- @@ -624,7 +624,7 @@ When the built-in validation helpers are not enough for your needs, you can writ ### Custom Validators -Custom validators are classes that extend `ActiveModel::Validator`. These classes must implement a +validate+ method which takes a record as an argument and performs the validation on it. The custom validator is called using the +validates_with+ method. +Custom validators are classes that extend `ActiveModel::Validator`. These classes must implement a `validate` method which takes a record as an argument and performs the validation on it. The custom validator is called using the `validates_with` method. ```ruby class MyValidator < ActiveModel::Validator @@ -641,7 +641,7 @@ class Person end ``` -The easiest way to add custom validators for validating individual attributes is with the convenient `ActiveModel::EachValidator`. In this case, the custom validator class must implement a +validate_each+ method which takes three arguments: record, attribute and value which correspond to the instance, the attribute to be validated and the value of the attribute in the passed instance. +The easiest way to add custom validators for validating individual attributes is with the convenient `ActiveModel::EachValidator`. In this case, the custom validator class must implement a `validate_each` method which takes three arguments: record, attribute and value which correspond to the instance, the attribute to be validated and the value of the attribute in the passed instance. ```ruby class EmailValidator < ActiveModel::EachValidator @@ -661,7 +661,7 @@ As shown in the example, you can also combine standard validations with your own ### Custom Methods -You can also create methods that verify the state of your models and add messages to the +errors+ collection when they are invalid. You must then register these methods by using the +validate+ class method, passing in the symbols for the validation methods' names. +You can also create methods that verify the state of your models and add messages to the `errors` collection when they are invalid. You must then register these methods by using the `validate` class method, passing in the symbols for the validation methods' names. You can pass more than one symbol for each class method and the respective validations will be run in the same order as they were registered. @@ -684,7 +684,7 @@ class Invoice < ActiveRecord::Base end ``` -By default such validations will run every time you call +valid?+. It is also possible to control when to run these custom validations by giving an +:on+ option to the +validate+ method, with either: +:create+ or +:update+. +By default such validations will run every time you call `valid?`. It is also possible to control when to run these custom validations by giving an `:on` option to the `validate` method, with either: `:create` or `:update`. ```ruby class Invoice < ActiveRecord::Base @@ -706,7 +706,7 @@ ActiveRecord::Base.class_eval do end ``` -Simply reopen +ActiveRecord::Base+ and define a class method like that. You'd typically put this code somewhere in +config/initializers+. You can use this helper like this: +Simply reopen `ActiveRecord::Base` and define a class method like that. You'd typically put this code somewhere in `config/initializers`. You can use this helper like this: ```ruby class Movie < ActiveRecord::Base @@ -717,13 +717,13 @@ end Working with Validation Errors ------------------------------ -In addition to the +valid?+ and +invalid?+ methods covered earlier, Rails provides a number of methods for working with the +errors+ collection and inquiring about the validity of objects. +In addition to the `valid?` and `invalid?` methods covered earlier, Rails provides a number of methods for working with the `errors` collection and inquiring about the validity of objects. -The following is a list of the most commonly used methods. Please refer to the +ActiveModel::Errors+ documentation for a list of all the available methods. +The following is a list of the most commonly used methods. Please refer to the `ActiveModel::Errors` documentation for a list of all the available methods. -### +errors+ +### `errors` -Returns an instance of the class +ActiveModel::Errors+ containing all errors. Each key is the attribute name and the value is an array of strings with all errors. +Returns an instance of the class `ActiveModel::Errors` containing all errors. Each key is the attribute name and the value is an array of strings with all errors. ```ruby class Person < ActiveRecord::Base @@ -740,9 +740,9 @@ person.valid? # => true person.errors # => [] ``` -### +errors[]+ +### `errors[]` -+errors[]+ is used when you want to check the error messages for a specific attribute. It returns an array of strings with all error messages for the given attribute, each string with one error message. If there are no errors related to the attribute, it returns an empty array. +`errors[]` is used when you want to check the error messages for a specific attribute. It returns an array of strings with all error messages for the given attribute, each string with one error message. If there are no errors related to the attribute, it returns an empty array. ```ruby class Person < ActiveRecord::Base @@ -763,9 +763,9 @@ person.errors[:name] # => ["can't be blank", "is too short (minimum is 3 characters)"] ``` -### +errors.add+ +### `errors.add` -The +add+ method lets you manually add messages that are related to particular attributes. You can use the +errors.full_messages+ or +errors.to_a+ methods to view the messages in the form they might be displayed to a user. Those particular messages get the attribute name prepended (and capitalized). +add+ receives the name of the attribute you want to add the message to, and the message itself. +The `add` method lets you manually add messages that are related to particular attributes. You can use the `errors.full_messages` or `errors.to_a` methods to view the messages in the form they might be displayed to a user. Those particular messages get the attribute name prepended (and capitalized). `add` receives the name of the attribute you want to add the message to, and the message itself. ```ruby class Person < ActiveRecord::Base @@ -783,7 +783,7 @@ person.errors.full_messages # => ["Name cannot contain the characters !@#%*()_-+="] ``` -Another way to do this is using +[]=+ setter +Another way to do this is using `[]=` setter ```ruby class Person < ActiveRecord::Base @@ -801,9 +801,9 @@ Another way to do this is using +[]=+ setter # => ["Name cannot contain the characters !@#%*()_-+="] ``` -### +errors[:base]+ +### `errors[:base]` -You can add error messages that are related to the object's state as a whole, instead of being related to a specific attribute. You can use this method when you want to say that the object is invalid, no matter the values of its attributes. Since +errors[:base]+ is an array, you can simply add a string to it and it will be used as an error message. +You can add error messages that are related to the object's state as a whole, instead of being related to a specific attribute. You can use this method when you want to say that the object is invalid, no matter the values of its attributes. Since `errors[:base]` is an array, you can simply add a string to it and it will be used as an error message. ```ruby class Person < ActiveRecord::Base @@ -813,9 +813,9 @@ class Person < ActiveRecord::Base end ``` -### +errors.clear+ +### `errors.clear` -The +clear+ method is used when you intentionally want to clear all the messages in the +errors+ collection. Of course, calling +errors.clear+ upon an invalid object won't actually make it valid: the +errors+ collection will now be empty, but the next time you call +valid?+ or any method that tries to save this object to the database, the validations will run again. If any of the validations fail, the +errors+ collection will be filled again. +The `clear` method is used when you intentionally want to clear all the messages in the `errors` collection. Of course, calling `errors.clear` upon an invalid object won't actually make it valid: the `errors` collection will now be empty, but the next time you call `valid?` or any method that tries to save this object to the database, the validations will run again. If any of the validations fail, the `errors` collection will be filled again. ```ruby class Person < ActiveRecord::Base @@ -836,9 +836,9 @@ p.errors[:name] # => ["can't be blank", "is too short (minimum is 3 characters)"] ``` -### +errors.size+ +### `errors.size` -The +size+ method returns the total number of error messages for the object. +The `size` method returns the total number of error messages for the object. ```ruby class Person < ActiveRecord::Base @@ -865,11 +865,11 @@ You can install it as a gem by adding this line to your Gemfile: gem "dynamic_form" ``` -Now you will have access to the two helper methods +error_messages+ and +error_messages_for+ in your view templates. +Now you will have access to the two helper methods `error_messages` and `error_messages_for` in your view templates. -### +error_messages+ and +error_messages_for+ +### `error_messages` and `error_messages_for` -When creating a form with the +form_for+ helper, you can use the +error_messages+ method on the form builder to render all failed validation messages for the current model instance. +When creating a form with the `form_for` helper, you can use the `error_messages` method on the form builder to render all failed validation messages for the current model instance. ```ruby class Product < ActiveRecord::Base @@ -901,7 +901,7 @@ If you submit the form with empty fields, the result will be similar to the one NOTE: The appearance of the generated HTML will be different from the one shown, unless you have used scaffolding. See "Customizing the Error Messages CSS":#customizing-error-messages-css. -You can also use the +error_messages_for+ helper to display the error messages of a model assigned to a view template. It is very similar to the previous example and will achieve exactly the same result. +You can also use the `error_messages_for` helper to display the error messages of a model assigned to a view template. It is very similar to the previous example and will achieve exactly the same result. ```erb <%= error_messages_for :product %> @@ -909,7 +909,7 @@ You can also use the +error_messages_for+ helper to display the error messages o The displayed text for each error message will always be formed by the capitalized name of the attribute that holds the error, followed by the error message itself. -Both the +form.error_messages+ and the +error_messages_for+ helpers accept options that let you customize the +div+ element that holds the messages, change the header text, change the message below the header, and specify the tag used for the header element. For example, +Both the `form.error_messages` and the `error_messages_for` helpers accept options that let you customize the `div` element that holds the messages, change the header text, change the message below the header, and specify the tag used for the header element. For example, ```erb <%= f.error_messages :header_message => "Invalid product!", @@ -921,32 +921,32 @@ results in: !images/customized_error_messages.png(Customized error messages)! -If you pass +nil+ in any of these options, the corresponding section of the +div+ will be discarded. +If you pass `nil` in any of these options, the corresponding section of the `div` will be discarded. ### Customizing the Error Messages CSS The selectors used to customize the style of error messages are: -* +.field_with_errors+ - Style for the form fields and labels with errors. -* +#error_explanation+ - Style for the +div+ element with the error messages. -* +#error_explanation h2+ - Style for the header of the +div+ element. -* +#error_explanation p+ - Style for the paragraph holding the message that appears right below the header of the +div+ element. -* +#error_explanation ul li+ - Style for the list items with individual error messages. +* `.field_with_errors` - Style for the form fields and labels with errors. +* `#error_explanation` - Style for the `div` element with the error messages. +* `#error_explanation h2` - Style for the header of the `div` element. +* `#error_explanation p` - Style for the paragraph holding the message that appears right below the header of the `div` element. +* `#error_explanation ul li` - Style for the list items with individual error messages. -If scaffolding was used, file +app/assets/stylesheets/scaffolds.css.scss+ will have been generated automatically. This file defines the red-based styles you saw in the examples above. +If scaffolding was used, file `app/assets/stylesheets/scaffolds.css.scss` will have been generated automatically. This file defines the red-based styles you saw in the examples above. -The name of the class and the id can be changed with the +:class+ and +:id+ options, accepted by both helpers. +The name of the class and the id can be changed with the `:class` and `:id` options, accepted by both helpers. ### Customizing the Error Messages HTML -By default, form fields with errors are displayed enclosed by a +div+ element with the +field_with_errors+ CSS class. However, it's possible to override that. +By default, form fields with errors are displayed enclosed by a `div` element with the `field_with_errors` CSS class. However, it's possible to override that. -The way form fields with errors are treated is defined by +ActionView::Base.field_error_proc+. This is a +Proc+ that receives two parameters: +The way form fields with errors are treated is defined by `ActionView::Base.field_error_proc`. This is a `Proc` that receives two parameters: * A string with the HTML tag -* An instance of +ActionView::Helpers::InstanceTag+. +* An instance of `ActionView::Helpers::InstanceTag`. -Below is a simple example where we change the Rails behavior to always display the error messages in front of each of the form fields in error. The error messages will be enclosed by a +span+ element with a +validation-error+ CSS class. There will be no +div+ element enclosing the +input+ element, so we get rid of that red border around the text field. You can use the +validation-error+ CSS class to style it anyway you want. +Below is a simple example where we change the Rails behavior to always display the error messages in front of each of the form fields in error. The error messages will be enclosed by a `span` element with a `validation-error` CSS class. There will be no `div` element enclosing the `input` element, so we get rid of that red border around the text field. You can use the `validation-error` CSS class to style it anyway you want. ```ruby ActionView::Base.field_error_proc = Proc.new do |html_tag, instance| @@ -1004,41 +1004,41 @@ Here is a list with all the available Active Record callbacks, listed in the sam ### Creating an Object -* +before_validation+ -* +after_validation+ -* +before_save+ -* +around_save+ -* +before_create+ -* +around_create+ -* +after_create+ -* +after_save+ +* `before_validation` +* `after_validation` +* `before_save` +* `around_save` +* `before_create` +* `around_create` +* `after_create` +* `after_save` ### Updating an Object -* +before_validation+ -* +after_validation+ -* +before_save+ -* +around_save+ -* +before_update+ -* +around_update+ -* +after_update+ -* +after_save+ +* `before_validation` +* `after_validation` +* `before_save` +* `around_save` +* `before_update` +* `around_update` +* `after_update` +* `after_save` ### Destroying an Object -* +before_destroy+ -* +around_destroy+ -* +after_destroy+ +* `before_destroy` +* `around_destroy` +* `after_destroy` -WARNING. +after_save+ runs both on create and update, but always _after_ the more specific callbacks +after_create+ and +after_update+, no matter the order in which the macro calls were executed. +WARNING. `after_save` runs both on create and update, but always _after_ the more specific callbacks `after_create` and `after_update`, no matter the order in which the macro calls were executed. -### +after_initialize+ and +after_find+ +### `after_initialize` and `after_find` -The +after_initialize+ callback will be called whenever an Active Record object is instantiated, either by directly using +new+ or when a record is loaded from the database. It can be useful to avoid the need to directly override your Active Record +initialize+ method. +The `after_initialize` callback will be called whenever an Active Record object is instantiated, either by directly using `new` or when a record is loaded from the database. It can be useful to avoid the need to directly override your Active Record `initialize` method. -The +after_find+ callback will be called whenever Active Record loads a record from the database. +after_find+ is called before +after_initialize+ if both are defined. +The `after_find` callback will be called whenever Active Record loads a record from the database. `after_find` is called before `after_initialize` if both are defined. -The +after_initialize+ and +after_find+ callbacks have no +before_*+ counterparts, but they can be registered just like the other Active Record callbacks. +The `after_initialize` and `after_find` callbacks have no `before_*` counterparts, but they can be registered just like the other Active Record callbacks. ```ruby class User < ActiveRecord::Base @@ -1066,66 +1066,66 @@ Running Callbacks The following methods trigger callbacks: -* +create+ -* +create!+ -* +decrement!+ -* +destroy+ -* +destroy_all+ -* +increment!+ -* +save+ -* +save!+ -* +save(:validate => false)+ -* +toggle!+ -* +update+ -* +update_attribute+ -* +update_attributes+ -* +update_attributes!+ -* +valid?+ - -Additionally, the +after_find+ callback is triggered by the following finder methods: - -* +all+ -* +first+ -* +find+ -* +find_all_by_<em>attribute</em>+ -* +find_by_<em>attribute</em>+ -* +find_by_<em>attribute</em>!+ -* +find_by_sql+ -* +last+ - -The +after_initialize+ callback is triggered every time a new object of the class is initialized. +* `create` +* `create!` +* `decrement!` +* `destroy` +* `destroy_all` +* `increment!` +* `save` +* `save!` +* `save(:validate => false)` +* `toggle!` +* `update` +* `update_attribute` +* `update_attributes` +* `update_attributes!` +* `valid?` + +Additionally, the `after_find` callback is triggered by the following finder methods: + +* `all` +* `first` +* `find` +* `find_all_by_<em>attribute</em>` +* `find_by_<em>attribute</em>` +* `find_by_<em>attribute</em>!` +* `find_by_sql` +* `last` + +The `after_initialize` callback is triggered every time a new object of the class is initialized. Skipping Callbacks ------------------ Just as with validations, it is also possible to skip callbacks. These methods should be used with caution, however, because important business rules and application logic may be kept in callbacks. Bypassing them without understanding the potential implications may lead to invalid data. -* +decrement+ -* +decrement_counter+ -* +delete+ -* +delete_all+ -* +increment+ -* +increment_counter+ -* +toggle+ -* +touch+ -* +update_column+ -* +update_columns+ -* +update_all+ -* +update_counters+ +* `decrement` +* `decrement_counter` +* `delete` +* `delete_all` +* `increment` +* `increment_counter` +* `toggle` +* `touch` +* `update_column` +* `update_columns` +* `update_all` +* `update_counters` Halting Execution ----------------- As you start registering new callbacks for your models, they will be queued for execution. This queue will include all your model's validations, the registered callbacks, and the database operation to be executed. -The whole callback chain is wrapped in a transaction. If any <em>before</em> callback method returns exactly +false+ or raises an exception, the execution chain gets halted and a ROLLBACK is issued; <em>after</em> callbacks can only accomplish that by raising an exception. +The whole callback chain is wrapped in a transaction. If any <em>before</em> callback method returns exactly `false` or raises an exception, the execution chain gets halted and a ROLLBACK is issued; <em>after</em> callbacks can only accomplish that by raising an exception. -WARNING. Raising an arbitrary exception may break code that expects +save+ and its friends not to fail like that. The +ActiveRecord::Rollback+ exception is thought precisely to tell Active Record a rollback is going on. That one is internally captured but not reraised. +WARNING. Raising an arbitrary exception may break code that expects `save` and its friends not to fail like that. The `ActiveRecord::Rollback` exception is thought precisely to tell Active Record a rollback is going on. That one is internally captured but not reraised. Relational Callbacks -------------------- -Callbacks work through model relationships, and can even be defined by them. Suppose an example where a user has many posts. A user's posts should be destroyed if the user is destroyed. Let's add an +after_destroy+ callback to the +User+ model by way of its relationship to the +Post+ model: +Callbacks work through model relationships, and can even be defined by them. Suppose an example where a user has many posts. A user's posts should be destroyed if the user is destroyed. Let's add an `after_destroy` callback to the `User` model by way of its relationship to the `Post` model: ```ruby class User < ActiveRecord::Base @@ -1152,11 +1152,11 @@ Post destroyed Conditional Callbacks --------------------- -As with validations, we can also make the calling of a callback method conditional on the satisfaction of a given predicate. We can do this using the +:if+ and +:unless+ options, which can take a symbol, a string, a +Proc+ or an +Array+. You may use the +:if+ option when you want to specify under which conditions the callback *should* be called. If you want to specify the conditions under which the callback *should not* be called, then you may use the +:unless+ option. +As with validations, we can also make the calling of a callback method conditional on the satisfaction of a given predicate. We can do this using the `:if` and `:unless` options, which can take a symbol, a string, a `Proc` or an `Array`. You may use the `:if` option when you want to specify under which conditions the callback *should* be called. If you want to specify the conditions under which the callback *should not* be called, then you may use the `:unless` option. -### Using +:if+ and +:unless+ with a +Symbol+ +### Using `:if` and `:unless` with a `Symbol` -You can associate the +:if+ and +:unless+ options with a symbol corresponding to the name of a predicate method that will get called right before the callback. When using the +:if+ option, the callback won't be executed if the predicate method returns false; when using the +:unless+ option, the callback won't be executed if the predicate method returns true. This is the most common option. Using this form of registration it is also possible to register several different predicates that should be called to check if the callback should be executed. +You can associate the `:if` and `:unless` options with a symbol corresponding to the name of a predicate method that will get called right before the callback. When using the `:if` option, the callback won't be executed if the predicate method returns false; when using the `:unless` option, the callback won't be executed if the predicate method returns true. This is the most common option. Using this form of registration it is also possible to register several different predicates that should be called to check if the callback should be executed. ```ruby class Order < ActiveRecord::Base @@ -1164,9 +1164,9 @@ class Order < ActiveRecord::Base end ``` -### Using +:if+ and +:unless+ with a String +### Using `:if` and `:unless` with a String -You can also use a string that will be evaluated using +eval+ and hence needs to contain valid Ruby code. You should use this option only when the string represents a really short condition: +You can also use a string that will be evaluated using `eval` and hence needs to contain valid Ruby code. You should use this option only when the string represents a really short condition: ```ruby class Order < ActiveRecord::Base @@ -1174,9 +1174,9 @@ class Order < ActiveRecord::Base end ``` -### Using +:if+ and +:unless+ with a +Proc+ +### Using `:if` and `:unless` with a `Proc` -Finally, it is possible to associate +:if+ and +:unless+ with a +Proc+ object. This option is best suited when writing short validation methods, usually one-liners: +Finally, it is possible to associate `:if` and `:unless` with a `Proc` object. This option is best suited when writing short validation methods, usually one-liners: ```ruby class Order < ActiveRecord::Base @@ -1187,7 +1187,7 @@ end ### Multiple Conditions for Callbacks -When writing conditional callbacks, it is possible to mix both +:if+ and +:unless+ in the same callback declaration: +When writing conditional callbacks, it is possible to mix both `:if` and `:unless` in the same callback declaration: ```ruby class Comment < ActiveRecord::Base @@ -1201,7 +1201,7 @@ Callback Classes Sometimes the callback methods that you'll write will be useful enough to be reused by other models. Active Record makes it possible to create classes that encapsulate the callback methods, so it becomes very easy to reuse them. -Here's an example where we create a class with an +after_destroy+ callback for a +PictureFile+ model: +Here's an example where we create a class with an `after_destroy` callback for a `PictureFile` model: ```ruby class PictureFileCallbacks @@ -1221,7 +1221,7 @@ class PictureFile < ActiveRecord::Base end ``` -Note that we needed to instantiate a new +PictureFileCallbacks+ object, since we declared our callback as an instance method. This is particularly useful if the callbacks make use of the state of the instantiated object. Often, however, it will make more sense to declare the callbacks as class methods: +Note that we needed to instantiate a new `PictureFileCallbacks` object, since we declared our callback as an instance method. This is particularly useful if the callbacks make use of the state of the instantiated object. Often, however, it will make more sense to declare the callbacks as class methods: ```ruby class PictureFileCallbacks @@ -1233,7 +1233,7 @@ class PictureFileCallbacks end ``` -If the callback method is declared this way, it won't be necessary to instantiate a +PictureFileCallbacks+ object. +If the callback method is declared this way, it won't be necessary to instantiate a `PictureFileCallbacks` object. ```ruby class PictureFile < ActiveRecord::Base @@ -1246,17 +1246,17 @@ You can declare as many callbacks as you want inside your callback classes. Observers --------- -Observers are similar to callbacks, but with important differences. Whereas callbacks can pollute a model with code that isn't directly related to its purpose, observers allow you to add the same functionality without changing the code of the model. For example, it could be argued that a +User+ model should not include code to send registration confirmation emails. Whenever you use callbacks with code that isn't directly related to your model, you may want to consider creating an observer instead. +Observers are similar to callbacks, but with important differences. Whereas callbacks can pollute a model with code that isn't directly related to its purpose, observers allow you to add the same functionality without changing the code of the model. For example, it could be argued that a `User` model should not include code to send registration confirmation emails. Whenever you use callbacks with code that isn't directly related to your model, you may want to consider creating an observer instead. ### Creating Observers -For example, imagine a +User+ model where we want to send an email every time a new user is created. Because sending emails is not directly related to our model's purpose, we should create an observer to contain the code implementing this functionality. +For example, imagine a `User` model where we want to send an email every time a new user is created. Because sending emails is not directly related to our model's purpose, we should create an observer to contain the code implementing this functionality. ```bash $ rails generate observer User ``` -generates +app/models/user_observer.rb+ containing the observer class +UserObserver+: +generates `app/models/user_observer.rb` containing the observer class `UserObserver`: ```ruby class UserObserver < ActiveRecord::Observer @@ -1277,14 +1277,14 @@ As with callback classes, the observer's methods receive the observed model as a ### Registering Observers -Observers are conventionally placed inside of your +app/models+ directory and registered in your application's +config/application.rb+ file. For example, the +UserObserver+ above would be saved as +app/models/user_observer.rb+ and registered in +config/application.rb+ this way: +Observers are conventionally placed inside of your `app/models` directory and registered in your application's `config/application.rb` file. For example, the `UserObserver` above would be saved as `app/models/user_observer.rb` and registered in `config/application.rb` this way: ```ruby # Activate observers that should always be running. config.active_record.observers = :user_observer ``` -As usual, settings in +config/environments+ take precedence over those in +config/application.rb+. So, if you prefer that an observer doesn't run in all environments, you can simply register it in a specific environment instead. +As usual, settings in `config/environments` take precedence over those in `config/application.rb`. So, if you prefer that an observer doesn't run in all environments, you can simply register it in a specific environment instead. ### Sharing Observers @@ -1300,7 +1300,7 @@ class MailerObserver < ActiveRecord::Observer end ``` -In this example, the +after_create+ method will be called whenever a +Registration+ or +User+ is created. Note that this new +MailerObserver+ would also need to be registered in +config/application.rb+ in order to take effect: +In this example, the `after_create` method will be called whenever a `Registration` or `User` is created. Note that this new `MailerObserver` would also need to be registered in `config/application.rb` in order to take effect: ```ruby # Activate observers that should always be running. @@ -1310,9 +1310,9 @@ config.active_record.observers = :mailer_observer Transaction Callbacks --------------------- -There are two additional callbacks that are triggered by the completion of a database transaction: +after_commit+ and +after_rollback+. These callbacks are very similar to the +after_save+ callback except that they don't execute until after database changes have either been committed or rolled back. They are most useful when your active record models need to interact with external systems which are not part of the database transaction. +There are two additional callbacks that are triggered by the completion of a database transaction: `after_commit` and `after_rollback`. These callbacks are very similar to the `after_save` callback except that they don't execute until after database changes have either been committed or rolled back. They are most useful when your active record models need to interact with external systems which are not part of the database transaction. -Consider, for example, the previous example where the +PictureFile+ model needs to delete a file after the corresponding record is destroyed. If anything raises an exception after the +after_destroy+ callback is called and the transaction rolls back, the file will have been deleted and the model will be left in an inconsistent state. For example, suppose that +picture_file_2+ in the code below is not valid and the +save!+ method raises an error. +Consider, for example, the previous example where the `PictureFile` model needs to delete a file after the corresponding record is destroyed. If anything raises an exception after the `after_destroy` callback is called and the transaction rolls back, the file will have been deleted and the model will be left in an inconsistent state. For example, suppose that `picture_file_2` in the code below is not valid and the `save!` method raises an error. ```ruby PictureFile.transaction do @@ -1321,7 +1321,7 @@ PictureFile.transaction do end ``` -By using the +after_commit+ callback we can account for this case. +By using the `after_commit` callback we can account for this case. ```ruby class PictureFile < ActiveRecord::Base @@ -1340,4 +1340,4 @@ class PictureFile < ActiveRecord::Base end ``` -The +after_commit+ and +after_rollback+ callbacks are guaranteed to be called for all models created, updated, or destroyed within a transaction block. If any exceptions are raised within one of these callbacks, they will be ignored so that they don't interfere with the other callbacks. As such, if your callback code could raise an exception, you'll need to rescue it and handle it appropriately within the callback. +The `after_commit` and `after_rollback` callbacks are guaranteed to be called for all models created, updated, or destroyed within a transaction block. If any exceptions are raised within one of these callbacks, they will be ignored so that they don't interfere with the other callbacks. As such, if your callback code could raise an exception, you'll need to rescue it and handle it appropriately within the callback. diff --git a/guides/source/active_support_core_extensions.md b/guides/source/active_support_core_extensions.md index 06edaa29f2..226ff67ff7 100644 --- a/guides/source/active_support_core_extensions.md +++ b/guides/source/active_support_core_extensions.md @@ -22,15 +22,15 @@ Thus, after a simple require like: require 'active_support' ``` -objects do not even respond to +blank?+. Let's see how to load its definition. +objects do not even respond to `blank?`. Let's see how to load its definition. #### Cherry-picking a Definition -The most lightweight way to get +blank?+ is to cherry-pick the file that defines it. +The most lightweight way to get `blank?` is to cherry-pick the file that defines it. -For every single method defined as a core extension this guide has a note that says where such a method is defined. In the case of +blank?+ the note reads: +For every single method defined as a core extension this guide has a note that says where such a method is defined. In the case of `blank?` the note reads: -NOTE: Defined in +active_support/core_ext/object/blank.rb+. +NOTE: Defined in `active_support/core_ext/object/blank.rb`. That means that this single call is enough: @@ -42,9 +42,9 @@ Active Support has been carefully revised so that cherry-picking a file loads on #### Loading Grouped Core Extensions -The next level is to simply load all extensions to +Object+. As a rule of thumb, extensions to +SomeClass+ are available in one shot by loading +active_support/core_ext/some_class+. +The next level is to simply load all extensions to `Object`. As a rule of thumb, extensions to `SomeClass` are available in one shot by loading `active_support/core_ext/some_class`. -Thus, to load all extensions to +Object+ (including +blank?+): +Thus, to load all extensions to `Object` (including `blank?`): ```ruby require 'active_support/core_ext/object' @@ -66,32 +66,32 @@ And finally, if you want to have all Active Support available just issue: require 'active_support/all' ``` -That does not even put the entire Active Support in memory upfront indeed, some stuff is configured via +autoload+, so it is only loaded if used. +That does not even put the entire Active Support in memory upfront indeed, some stuff is configured via `autoload`, so it is only loaded if used. ### Active Support Within a Ruby on Rails Application -A Ruby on Rails application loads all Active Support unless +config.active_support.bare+ is true. In that case, the application will only load what the framework itself cherry-picks for its own needs, and can still cherry-pick itself at any granularity level, as explained in the previous section. +A Ruby on Rails application loads all Active Support unless `config.active_support.bare` is true. In that case, the application will only load what the framework itself cherry-picks for its own needs, and can still cherry-pick itself at any granularity level, as explained in the previous section. Extensions to All Objects ------------------------- -### +blank?+ and +present?+ +### `blank?` and `present?` The following values are considered to be blank in a Rails application: -* +nil+ and +false+, +* `nil` and `false`, * strings composed only of whitespace (see note below), * empty arrays and hashes, and -* any other object that responds to +empty?+ and it is empty. +* any other object that responds to `empty?` and it is empty. INFO: The predicate for strings uses the Unicode-aware character class `[:space:]`, so for example U+2029 (paragraph separator) is considered to be whitespace. WARNING: Note that numbers are not mentioned, in particular 0 and 0.0 are *not* blank. -For example, this method from +ActionDispatch::Session::AbstractStore+ uses +blank?+ for checking whether a session key is present: +For example, this method from `ActionDispatch::Session::AbstractStore` uses `blank?` for checking whether a session key is present: ```ruby def ensure_session_key! @@ -101,7 +101,7 @@ def ensure_session_key! end ``` -The method +present?+ is equivalent to +!blank?+. This example is taken from +ActionDispatch::Http::Cache::Response+: +The method `present?` is equivalent to `!blank?`. This example is taken from `ActionDispatch::Http::Cache::Response`: ```ruby def set_conditional_cache_control! @@ -110,19 +110,19 @@ def set_conditional_cache_control! end ``` -NOTE: Defined in +active_support/core_ext/object/blank.rb+. +NOTE: Defined in `active_support/core_ext/object/blank.rb`. -### +presence+ +### `presence` -The +presence+ method returns its receiver if +present?+, and +nil+ otherwise. It is useful for idioms like this: +The `presence` method returns its receiver if `present?`, and `nil` otherwise. It is useful for idioms like this: ```ruby host = config[:host].presence || 'localhost' ``` -NOTE: Defined in +active_support/core_ext/object/blank.rb+. +NOTE: Defined in `active_support/core_ext/object/blank.rb`. -### +duplicable?+ +### `duplicable?` A few fundamental objects in Ruby are singletons. For example, in the whole life of a program the integer 1 refers always to the same instance: @@ -131,7 +131,7 @@ A few fundamental objects in Ruby are singletons. For example, in the whole life Math.cos(0).to_i.object_id # => 3 ``` -Hence, there's no way these objects can be duplicated through +dup+ or +clone+: +Hence, there's no way these objects can be duplicated through `dup` or `clone`: ```ruby true.dup # => TypeError: can't dup TrueClass @@ -144,22 +144,22 @@ Some numbers which are not singletons are not duplicable either: (2**1024).clone # => allocator undefined for Bignum ``` -Active Support provides +duplicable?+ to programmatically query an object about this property: +Active Support provides `duplicable?` to programmatically query an object about this property: ```ruby "".duplicable? # => true false.duplicable? # => false ``` -By definition all objects are +duplicable?+ except +nil+, +false+, +true+, symbols, numbers, and class and module objects. +By definition all objects are `duplicable?` except `nil`, `false`, `true`, symbols, numbers, and class and module objects. -WARNING. Any class can disallow duplication removing +dup+ and +clone+ or raising exceptions from them, only +rescue+ can tell whether a given arbitrary object is duplicable. +duplicable?+ depends on the hard-coded list above, but it is much faster than +rescue+. Use it only if you know the hard-coded list is enough in your use case. +WARNING. Any class can disallow duplication removing `dup` and `clone` or raising exceptions from them, only `rescue` can tell whether a given arbitrary object is duplicable. `duplicable?` depends on the hard-coded list above, but it is much faster than `rescue`. Use it only if you know the hard-coded list is enough in your use case. -NOTE: Defined in +active_support/core_ext/object/duplicable.rb+. +NOTE: Defined in `active_support/core_ext/object/duplicable.rb`. -### +deep_dup+ +### `deep_dup` -The +deep_dup+ method returns deep copy of a given object. Normally, when you +dup+ an object that contains other objects, ruby does not +dup+ them. If you have an array with a string, for example, it will look like this: +The `deep_dup` method returns deep copy of a given object. Normally, when you `dup` an object that contains other objects, ruby does not `dup` them. If you have an array with a string, for example, it will look like this: ```ruby array = ['string'] @@ -178,9 +178,9 @@ array #=> ['foo'] duplicate #=> ['foo', 'another-string'] ``` -As you can see, after duplicating +Array+ instance, we got another object, therefore we can modify it and the original object will stay unchanged. This is not true for array's elements, however. Since +dup+ does not make deep copy, the string inside array is still the same object. +As you can see, after duplicating `Array` instance, we got another object, therefore we can modify it and the original object will stay unchanged. This is not true for array's elements, however. Since `dup` does not make deep copy, the string inside array is still the same object. -If you need a deep copy of an object, you should use +deep_dup+. Here is an example: +If you need a deep copy of an object, you should use `deep_dup`. Here is an example: ```ruby array = ['string'] @@ -192,7 +192,7 @@ array #=> ['string'] duplicate #=> ['foo'] ``` -If object is not duplicable, +deep_dup+ will just return this object: +If object is not duplicable, `deep_dup` will just return this object: ```ruby number = 1 @@ -200,11 +200,11 @@ dup = number.deep_dup number.object_id == dup.object_id # => true ``` -NOTE: Defined in +active_support/core_ext/object/deep_dup.rb+. +NOTE: Defined in `active_support/core_ext/object/deep_dup.rb`. -### +try+ +### `try` -When you want to call a method on an object only if it is not +nil+, the simplest way to achieve it is with conditional statements, adding unnecessary clutter. The alternative is to use +try+. +try+ is like +Object#send+ except that it returns +nil+ if sent to +nil+. +When you want to call a method on an object only if it is not `nil`, the simplest way to achieve it is with conditional statements, adding unnecessary clutter. The alternative is to use `try`. `try` is like `Object#send` except that it returns `nil` if sent to `nil`. Here is an example: @@ -218,7 +218,7 @@ end @number.try(:next) ``` -Another example is this code from +ActiveRecord::ConnectionAdapters::AbstractAdapter+ where +@logger+ could be +nil+. You can see that the code uses +try+ and avoids an unnecessary check. +Another example is this code from `ActiveRecord::ConnectionAdapters::AbstractAdapter` where `@logger` could be `nil`. You can see that the code uses `try` and avoids an unnecessary check. ```ruby def log_info(sql, name, ms) @@ -229,17 +229,17 @@ def log_info(sql, name, ms) end ``` -+try+ can also be called without arguments but a block, which will only be executed if the object is not nil: +`try` can also be called without arguments but a block, which will only be executed if the object is not nil: ```ruby @person.try { |p| "#{p.first_name} #{p.last_name}" } ``` -NOTE: Defined in +active_support/core_ext/object/try.rb+. +NOTE: Defined in `active_support/core_ext/object/try.rb`. -### +class_eval(*args, &block)+ +### `class_eval(*args, &block)` -You can evaluate code in the context of any object's singleton class using +class_eval+: +You can evaluate code in the context of any object's singleton class using `class_eval`: ```ruby class Proc @@ -256,11 +256,11 @@ class Proc end ``` -NOTE: Defined in +active_support/core_ext/kernel/singleton_class.rb+. +NOTE: Defined in `active_support/core_ext/kernel/singleton_class.rb`. -### +acts_like?(duck)+ +### `acts_like?(duck)` -The method +acts_like?+ provides a way to check whether some class acts like some other class based on a simple convention: a class that provides the same interface as +String+ defines +The method `acts_like?` provides a way to check whether some class acts like some other class based on a simple convention: a class that provides the same interface as `String` defines ```ruby def acts_like_string? @@ -273,21 +273,21 @@ which is only a marker, its body or return value are irrelevant. Then, client co some_klass.acts_like?(:string) ``` -Rails has classes that act like +Date+ or +Time+ and follow this contract. +Rails has classes that act like `Date` or `Time` and follow this contract. -NOTE: Defined in +active_support/core_ext/object/acts_like.rb+. +NOTE: Defined in `active_support/core_ext/object/acts_like.rb`. -### +to_param+ +### `to_param` -All objects in Rails respond to the method +to_param+, which is meant to return something that represents them as values in a query string, or as URL fragments. +All objects in Rails respond to the method `to_param`, which is meant to return something that represents them as values in a query string, or as URL fragments. -By default +to_param+ just calls +to_s+: +By default `to_param` just calls `to_s`: ```ruby 7.to_param # => "7" ``` -The return value of +to_param+ should *not* be escaped: +The return value of `to_param` should *not* be escaped: ```ruby "Tom & Jerry".to_param # => "Tom & Jerry" @@ -295,13 +295,13 @@ The return value of +to_param+ should *not* be escaped: Several classes in Rails overwrite this method. -For example +nil+, +true+, and +false+ return themselves. +Array#to_param+ calls +to_param+ on the elements and joins the result with "/": +For example `nil`, `true`, and `false` return themselves. `Array#to_param` calls `to_param` on the elements and joins the result with "/": ```ruby [0, true, String].to_param # => "0/true/String" ``` -Notably, the Rails routing system calls +to_param+ on models to get a value for the +:id+ placeholder. +ActiveRecord::Base#to_param+ returns the +id+ of a model, but you can redefine that method in your models. For example, given +Notably, the Rails routing system calls `to_param` on models to get a value for the `:id` placeholder. `ActiveRecord::Base#to_param` returns the `id` of a model, but you can redefine that method in your models. For example, given ```ruby class User @@ -317,13 +317,13 @@ we get: user_path(@user) # => "/users/357-john-smith" ``` -WARNING. Controllers need to be aware of any redefinition of +to_param+ because when a request like that comes in "357-john-smith" is the value of +params[:id]+. +WARNING. Controllers need to be aware of any redefinition of `to_param` because when a request like that comes in "357-john-smith" is the value of `params[:id]`. -NOTE: Defined in +active_support/core_ext/object/to_param.rb+. +NOTE: Defined in `active_support/core_ext/object/to_param.rb`. -### +to_query+ +### `to_query` -Except for hashes, given an unescaped +key+ this method constructs the part of a query string that would map such key to what +to_param+ returns. For example, given +Except for hashes, given an unescaped `key` this method constructs the part of a query string that would map such key to what `to_param` returns. For example, given ```ruby class User @@ -348,33 +348,33 @@ account.to_query('company[name]') so its output is ready to be used in a query string. -Arrays return the result of applying +to_query+ to each element with `_key_[]` as key, and join the result with "&": +Arrays return the result of applying `to_query` to each element with `_key_[]` as key, and join the result with "&": ```ruby [3.4, -45.6].to_query('sample') # => "sample%5B%5D=3.4&sample%5B%5D=-45.6" ``` -Hashes also respond to +to_query+ but with a different signature. If no argument is passed a call generates a sorted series of key/value assignments calling +to_query(key)+ on its values. Then it joins the result with "&": +Hashes also respond to `to_query` but with a different signature. If no argument is passed a call generates a sorted series of key/value assignments calling `to_query(key)` on its values. Then it joins the result with "&": ```ruby {:c => 3, :b => 2, :a => 1}.to_query # => "a=1&b=2&c=3" ``` -The method +Hash#to_query+ accepts an optional namespace for the keys: +The method `Hash#to_query` accepts an optional namespace for the keys: ```ruby {:id => 89, :name => "John Smith"}.to_query('user') # => "user%5Bid%5D=89&user%5Bname%5D=John+Smith" ``` -NOTE: Defined in +active_support/core_ext/object/to_query.rb+. +NOTE: Defined in `active_support/core_ext/object/to_query.rb`. -### +with_options+ +### `with_options` -The method +with_options+ provides a way to factor out common options in a series of method calls. +The method `with_options` provides a way to factor out common options in a series of method calls. -Given a default options hash, +with_options+ yields a proxy object to a block. Within the block, methods called on the proxy are forwarded to the receiver with their options merged. For example, you get rid of the duplication in: +Given a default options hash, `with_options` yields a proxy object to a block. Within the block, methods called on the proxy are forwarded to the receiver with their options merged. For example, you get rid of the duplication in: ```ruby class Account < ActiveRecord::Base @@ -407,17 +407,17 @@ I18n.with_options :locale => user.locale, :scope => "newsletter" do |i18n| end ``` -TIP: Since +with_options+ forwards calls to its receiver they can be nested. Each nesting level will merge inherited defaults in addition to their own. +TIP: Since `with_options` forwards calls to its receiver they can be nested. Each nesting level will merge inherited defaults in addition to their own. -NOTE: Defined in +active_support/core_ext/object/with_options.rb+. +NOTE: Defined in `active_support/core_ext/object/with_options.rb`. ### Instance Variables Active Support provides several methods to ease access to instance variables. -#### +instance_variable_names+ +#### `instance_variable_names` -Ruby 1.8 and 1.9 have a method called +instance_variables+ that returns the names of the defined instance variables. But they behave differently, in 1.8 it returns strings whereas in 1.9 it returns symbols. Active Support defines +instance_variable_names+ as a portable way to obtain them as strings: +Ruby 1.8 and 1.9 have a method called `instance_variables` that returns the names of the defined instance variables. But they behave differently, in 1.8 it returns strings whereas in 1.9 it returns symbols. Active Support defines `instance_variable_names` as a portable way to obtain them as strings: ```ruby class C @@ -431,11 +431,11 @@ C.new(0, 1).instance_variable_names # => ["@y", "@x"] WARNING: The order in which the names are returned is unspecified, and it indeed depends on the version of the interpreter. -NOTE: Defined in +active_support/core_ext/object/instance_variables.rb+. +NOTE: Defined in `active_support/core_ext/object/instance_variables.rb`. -#### +instance_values+ +#### `instance_values` -The method +instance_values+ returns a hash that maps instance variable names without "@" to their +The method `instance_values` returns a hash that maps instance variable names without "@" to their corresponding values. Keys are strings: ```ruby @@ -448,17 +448,17 @@ end C.new(0, 1).instance_values # => {"x" => 0, "y" => 1} ``` -NOTE: Defined in +active_support/core_ext/object/instance_variables.rb+. +NOTE: Defined in `active_support/core_ext/object/instance_variables.rb`. ### Silencing Warnings, Streams, and Exceptions -The methods +silence_warnings+ and +enable_warnings+ change the value of +$VERBOSE+ accordingly for the duration of their block, and reset it afterwards: +The methods `silence_warnings` and `enable_warnings` change the value of `$VERBOSE` accordingly for the duration of their block, and reset it afterwards: ```ruby silence_warnings { Object.const_set "RAILS_DEFAULT_LOGGER", logger } ``` -You can silence any stream while a block runs with +silence_stream+: +You can silence any stream while a block runs with `silence_stream`: ```ruby silence_stream(STDOUT) do @@ -466,7 +466,7 @@ silence_stream(STDOUT) do end ``` -The +quietly+ method addresses the common use case where you want to silence STDOUT and STDERR, even in subprocesses: +The `quietly` method addresses the common use case where you want to silence STDOUT and STDERR, even in subprocesses: ```ruby quietly { system 'bundle install' } @@ -474,7 +474,7 @@ quietly { system 'bundle install' } For example, the railties test suite uses that one in a few places to prevent command messages from being echoed intermixed with the progress status. -Silencing exceptions is also possible with +suppress+. This method receives an arbitrary number of exception classes. If an exception is raised during the execution of the block and is +kind_of?+ any of the arguments, +suppress+ captures it and returns silently. Otherwise the exception is reraised: +Silencing exceptions is also possible with `suppress`. This method receives an arbitrary number of exception classes. If an exception is raised during the execution of the block and is `kind_of?` any of the arguments, `suppress` captures it and returns silently. Otherwise the exception is reraised: ```ruby # If the user is locked the increment is lost, no big deal. @@ -483,13 +483,13 @@ suppress(ActiveRecord::StaleObjectError) do end ``` -NOTE: Defined in +active_support/core_ext/kernel/reporting.rb+. +NOTE: Defined in `active_support/core_ext/kernel/reporting.rb`. -### +in?+ +### `in?` -The predicate +in?+ tests if an object is included in another object or a list of objects. An +ArgumentError+ exception will be raised if a single argument is passed and it does not respond to +include?+. +The predicate `in?` tests if an object is included in another object or a list of objects. An `ArgumentError` exception will be raised if a single argument is passed and it does not respond to `include?`. -Examples of +in?+: +Examples of `in?`: ```ruby 1.in?(1,2) # => true @@ -499,16 +499,16 @@ Examples of +in?+: 1.in?(1) # => ArgumentError ``` -NOTE: Defined in +active_support/core_ext/object/inclusion.rb+. +NOTE: Defined in `active_support/core_ext/object/inclusion.rb`. -Extensions to +Module+ +Extensions to `Module` ---------------------- -### +alias_method_chain+ +### `alias_method_chain` Using plain Ruby you can wrap methods with other methods, that's called _alias chaining_. -For example, let's say you'd like params to be strings in functional tests, as they are in real requests, but still want the convenience of assigning integers and other kind of values. To accomplish that you could wrap +ActionController::TestCase#process+ this way in +test/test_helper.rb+: +For example, let's say you'd like params to be strings in functional tests, as they are in real requests, but still want the convenience of assigning integers and other kind of values. To accomplish that you could wrap `ActionController::TestCase#process` this way in `test/test_helper.rb`: ```ruby ActionController::TestCase.class_eval do @@ -523,9 +523,9 @@ ActionController::TestCase.class_eval do end ``` -That's the method +get+, +post+, etc., delegate the work to. +That's the method `get`, `post`, etc., delegate the work to. -That technique has a risk, it could be the case that +:original_process+ was taken. To try to avoid collisions people choose some label that characterizes what the chaining is about: +That technique has a risk, it could be the case that `:original_process` was taken. To try to avoid collisions people choose some label that characterizes what the chaining is about: ```ruby ActionController::TestCase.class_eval do @@ -538,7 +538,7 @@ ActionController::TestCase.class_eval do end ``` -The method +alias_method_chain+ provides a shortcut for that pattern: +The method `alias_method_chain` provides a shortcut for that pattern: ```ruby ActionController::TestCase.class_eval do @@ -550,13 +550,13 @@ ActionController::TestCase.class_eval do end ``` -Rails uses +alias_method_chain+ all over the code base. For example validations are added to +ActiveRecord::Base#save+ by wrapping the method that way in a separate module specialized in validations. +Rails uses `alias_method_chain` all over the code base. For example validations are added to `ActiveRecord::Base#save` by wrapping the method that way in a separate module specialized in validations. -NOTE: Defined in +active_support/core_ext/module/aliasing.rb+. +NOTE: Defined in `active_support/core_ext/module/aliasing.rb`. ### Attributes -#### +alias_attribute+ +#### `alias_attribute` Model attributes have a reader, a writer, and a predicate. You can alias a model attribute having the corresponding three methods defined for you in one shot. As in other aliasing methods, the new name is the first argument, and the old name is the second (my mnemonic is they go in the same order as if you did an assignment): @@ -568,15 +568,15 @@ class User < ActiveRecord::Base end ``` -NOTE: Defined in +active_support/core_ext/module/aliasing.rb+. +NOTE: Defined in `active_support/core_ext/module/aliasing.rb`. #### Internal Attributes When you are defining an attribute in a class that is meant to be subclassed, name collisions are a risk. That's remarkably important for libraries. -Active Support defines the macros +attr_internal_reader+, +attr_internal_writer+, and +attr_internal_accessor+. They behave like their Ruby built-in +attr_*+ counterparts, except they name the underlying instance variable in a way that makes collisions less likely. +Active Support defines the macros `attr_internal_reader`, `attr_internal_writer`, and `attr_internal_accessor`. They behave like their Ruby built-in `attr_*` counterparts, except they name the underlying instance variable in a way that makes collisions less likely. -The macro +attr_internal+ is a synonym for +attr_internal_accessor+: +The macro `attr_internal` is a synonym for `attr_internal_accessor`: ```ruby # library @@ -590,9 +590,9 @@ class MyCrawler < ThirdPartyLibrary::Crawler end ``` -In the previous example it could be the case that +:log_level+ does not belong to the public interface of the library and it is only used for development. The client code, unaware of the potential conflict, subclasses and defines its own +:log_level+. Thanks to +attr_internal+ there's no collision. +In the previous example it could be the case that `:log_level` does not belong to the public interface of the library and it is only used for development. The client code, unaware of the potential conflict, subclasses and defines its own `:log_level`. Thanks to `attr_internal` there's no collision. -By default the internal instance variable is named with a leading underscore, +@_log_level+ in the example above. That's configurable via +Module.attr_internal_naming_format+ though, you can pass any +sprintf+-like format string with a leading +@+ and a +%s+ somewhere, which is where the name will be placed. The default is +"@_%s"+. +By default the internal instance variable is named with a leading underscore, `@_log_level` in the example above. That's configurable via `Module.attr_internal_naming_format` though, you can pass any `sprintf`-like format string with a leading `@` and a `%s` somewhere, which is where the name will be placed. The default is `"@_%s"`. Rails uses internal attributes in a few spots, for examples for views: @@ -606,11 +606,11 @@ module ActionView end ``` -NOTE: Defined in +active_support/core_ext/module/attr_internal.rb+. +NOTE: Defined in `active_support/core_ext/module/attr_internal.rb`. #### Module Attributes -The macros +mattr_reader+, +mattr_writer+, and +mattr_accessor+ are analogous to the +cattr_*+ macros defined for class. Check "Class Attributes":#class-attributes. +The macros `mattr_reader`, `mattr_writer`, and `mattr_accessor` are analogous to the `cattr_*` macros defined for class. Check "Class Attributes":#class-attributes. For example, the dependencies mechanism uses them: @@ -633,13 +633,13 @@ module ActiveSupport end ``` -NOTE: Defined in +active_support/core_ext/module/attribute_accessors.rb+. +NOTE: Defined in `active_support/core_ext/module/attribute_accessors.rb`. ### Parents -#### +parent+ +#### `parent` -The +parent+ method on a nested named module returns the module that contains its corresponding constant: +The `parent` method on a nested named module returns the module that contains its corresponding constant: ```ruby module X @@ -654,15 +654,15 @@ X::Y::Z.parent # => X::Y M.parent # => X::Y ``` -If the module is anonymous or belongs to the top-level, +parent+ returns +Object+. +If the module is anonymous or belongs to the top-level, `parent` returns `Object`. -WARNING: Note that in that case +parent_name+ returns +nil+. +WARNING: Note that in that case `parent_name` returns `nil`. -NOTE: Defined in +active_support/core_ext/module/introspection.rb+. +NOTE: Defined in `active_support/core_ext/module/introspection.rb`. -#### +parent_name+ +#### `parent_name` -The +parent_name+ method on a nested named module returns the fully-qualified name of the module that contains its corresponding constant: +The `parent_name` method on a nested named module returns the fully-qualified name of the module that contains its corresponding constant: ```ruby module X @@ -677,15 +677,15 @@ X::Y::Z.parent_name # => "X::Y" M.parent_name # => "X::Y" ``` -For top-level or anonymous modules +parent_name+ returns +nil+. +For top-level or anonymous modules `parent_name` returns `nil`. -WARNING: Note that in that case +parent+ returns +Object+. +WARNING: Note that in that case `parent` returns `Object`. -NOTE: Defined in +active_support/core_ext/module/introspection.rb+. +NOTE: Defined in `active_support/core_ext/module/introspection.rb`. -#### +parents+ +#### `parents` -The method +parents+ calls +parent+ on the receiver and upwards until +Object+ is reached. The chain is returned in an array, from bottom to top: +The method `parents` calls `parent` on the receiver and upwards until `Object` is reached. The chain is returned in an array, from bottom to top: ```ruby module X @@ -700,11 +700,11 @@ X::Y::Z.parents # => [X::Y, X, Object] M.parents # => [X::Y, X, Object] ``` -NOTE: Defined in +active_support/core_ext/module/introspection.rb+. +NOTE: Defined in `active_support/core_ext/module/introspection.rb`. ### Constants -The method +local_constants+ returns the names of the constants that have been +The method `local_constants` returns the names of the constants that have been defined in the receiver module: ```ruby @@ -721,18 +721,18 @@ X.local_constants # => [:X1, :X2, :Y] X::Y.local_constants # => [:Y1, :X1] ``` -The names are returned as symbols. (The deprecated method +local_constant_names+ returns strings.) +The names are returned as symbols. (The deprecated method `local_constant_names` returns strings.) -NOTE: Defined in +active_support/core_ext/module/introspection.rb+. +NOTE: Defined in `active_support/core_ext/module/introspection.rb`. #### Qualified Constant Names -The standard methods +const_defined?+, +const_get+ , and +const_set+ accept +The standard methods `const_defined?`, `const_get` , and `const_set` accept bare constant names. Active Support extends this API to be able to pass relative qualified constant names. -The new methods are +qualified_const_defined?+, +qualified_const_get+, and -+qualified_const_set+. Their arguments are assumed to be qualified constant +The new methods are `qualified_const_defined?`, `qualified_const_get`, and +`qualified_const_set`. Their arguments are assumed to be qualified constant names relative to their receiver: ```ruby @@ -748,7 +748,7 @@ Math.qualified_const_get("E") # => 2.718281828459045 ``` These methods are analogous to their builtin counterparts. In particular, -+qualified_constant_defined?+ accepts an optional second argument to be +`qualified_constant_defined?` accepts an optional second argument to be able to say whether you want the predicate to look in the ancestors. This flag is taken into account for each constant in the expression while walking down the path. @@ -767,7 +767,7 @@ module N end ``` -+qualified_const_defined?+ behaves this way: +`qualified_const_defined?` behaves this way: ```ruby N.qualified_const_defined?("C::X", false) # => false @@ -776,18 +776,18 @@ N.qualified_const_defined?("C::X") # => true ``` As the last example implies, the second argument defaults to true, -as in +const_defined?+. +as in `const_defined?`. For coherence with the builtin methods only relative paths are accepted. -Absolute qualified constant names like +::Math::PI+ raise +NameError+. +Absolute qualified constant names like `::Math::PI` raise `NameError`. -NOTE: Defined in +active_support/core_ext/module/qualified_const.rb+. +NOTE: Defined in `active_support/core_ext/module/qualified_const.rb`. ### Reachable A named module is reachable if it is stored in its corresponding constant. It means you can reach the module object via the constant. -That is what ordinarily happens, if a module is called "M", the +M+ constant exists and holds it: +That is what ordinarily happens, if a module is called "M", the `M` constant exists and holds it: ```ruby module M @@ -819,7 +819,7 @@ end orphan.reachable? # => false ``` -NOTE: Defined in +active_support/core_ext/module/reachable.rb+. +NOTE: Defined in `active_support/core_ext/module/reachable.rb`. ### Anonymous @@ -836,7 +836,7 @@ N.name # => "N" Module.new.name # => nil ``` -You can check whether a module has a name with the predicate +anonymous?+: +You can check whether a module has a name with the predicate `anonymous?`: ```ruby module M @@ -860,13 +860,13 @@ m.anonymous? # => false though an anonymous module is unreachable by definition. -NOTE: Defined in +active_support/core_ext/module/anonymous.rb+. +NOTE: Defined in `active_support/core_ext/module/anonymous.rb`. ### Method Delegation -The macro +delegate+ offers an easy way to forward methods. +The macro `delegate` offers an easy way to forward methods. -Let's imagine that users in some application have login information in the +User+ model but name and other data in a separate +Profile+ model: +Let's imagine that users in some application have login information in the `User` model but name and other data in a separate `Profile` model: ```ruby class User < ActiveRecord::Base @@ -874,7 +874,7 @@ class User < ActiveRecord::Base end ``` -With that configuration you get a user's name via his profile, +user.profile.name+, but it could be handy to still be able to access such attribute directly: +With that configuration you get a user's name via his profile, `user.profile.name`, but it could be handy to still be able to access such attribute directly: ```ruby class User < ActiveRecord::Base @@ -886,7 +886,7 @@ class User < ActiveRecord::Base end ``` -That is what +delegate+ does for you: +That is what `delegate` does for you: ```ruby class User < ActiveRecord::Base @@ -900,13 +900,13 @@ It is shorter, and the intention more obvious. The method must be public in the target. -The +delegate+ macro accepts several methods: +The `delegate` macro accepts several methods: ```ruby delegate :name, :age, :address, :twitter, :to => :profile ``` -When interpolated into a string, the +:to+ option should become an expression that evaluates to the object the method is delegated to. Typically a string or symbol. Such an expression is evaluated in the context of the receiver: +When interpolated into a string, the `:to` option should become an expression that evaluates to the object the method is delegated to. Typically a string or symbol. Such an expression is evaluated in the context of the receiver: ```ruby # delegates to the Rails constant @@ -916,25 +916,25 @@ delegate :logger, :to => :Rails delegate :table_name, :to => 'self.class' ``` -WARNING: If the +:prefix+ option is +true+ this is less generic, see below. +WARNING: If the `:prefix` option is `true` this is less generic, see below. -By default, if the delegation raises +NoMethodError+ and the target is +nil+ the exception is propagated. You can ask that +nil+ is returned instead with the +:allow_nil+ option: +By default, if the delegation raises `NoMethodError` and the target is `nil` the exception is propagated. You can ask that `nil` is returned instead with the `:allow_nil` option: ```ruby delegate :name, :to => :profile, :allow_nil => true ``` -With +:allow_nil+ the call +user.name+ returns +nil+ if the user has no profile. +With `:allow_nil` the call `user.name` returns `nil` if the user has no profile. -The option +:prefix+ adds a prefix to the name of the generated method. This may be handy for example to get a better name: +The option `:prefix` adds a prefix to the name of the generated method. This may be handy for example to get a better name: ```ruby delegate :street, :to => :address, :prefix => true ``` -The previous example generates +address_street+ rather than +street+. +The previous example generates `address_street` rather than `street`. -WARNING: Since in this case the name of the generated method is composed of the target object and target method names, the +:to+ option must be a method name. +WARNING: Since in this case the name of the generated method is composed of the target object and target method names, the `:to` option must be a method name. A custom prefix may also be configured: @@ -942,15 +942,15 @@ A custom prefix may also be configured: delegate :size, :to => :attachment, :prefix => :avatar ``` -In the previous example the macro generates +avatar_size+ rather than +size+. +In the previous example the macro generates `avatar_size` rather than `size`. -NOTE: Defined in +active_support/core_ext/module/delegation.rb+ +NOTE: Defined in `active_support/core_ext/module/delegation.rb` ### Redefining Methods -There are cases where you need to define a method with +define_method+, but don't know whether a method with that name already exists. If it does, a warning is issued if they are enabled. No big deal, but not clean either. +There are cases where you need to define a method with `define_method`, but don't know whether a method with that name already exists. If it does, a warning is issued if they are enabled. No big deal, but not clean either. -The method +redefine_method+ prevents such a potential warning, removing the existing method before if needed. Rails uses it in a few places, for instance when it generates an association's API: +The method `redefine_method` prevents such a potential warning, removing the existing method before if needed. Rails uses it in a few places, for instance when it generates an association's API: ```ruby redefine_method("#{reflection.name}=") do |new_value| @@ -965,16 +965,16 @@ redefine_method("#{reflection.name}=") do |new_value| end ``` -NOTE: Defined in +active_support/core_ext/module/remove_method.rb+ +NOTE: Defined in `active_support/core_ext/module/remove_method.rb` -Extensions to +Class+ +Extensions to `Class` --------------------- ### Class Attributes -#### +class_attribute+ +#### `class_attribute` -The method +class_attribute+ declares one or more inheritable class attributes that can be overridden at any level down the hierarchy. +The method `class_attribute` declares one or more inheritable class attributes that can be overridden at any level down the hierarchy. ```ruby class A @@ -998,7 +998,7 @@ A.x # => :a B.x # => :b ``` -For example +ActionMailer::Base+ defines: +For example `ActionMailer::Base` defines: ```ruby class_attribute :default_params @@ -1023,7 +1023,7 @@ a1.x # => 1, comes from A a2.x # => 2, overridden in a2 ``` -The generation of the writer instance method can be prevented by setting the option +:instance_writer+ to +false+. +The generation of the writer instance method can be prevented by setting the option `:instance_writer` to `false`. ```ruby module ActiveRecord @@ -1036,7 +1036,7 @@ end A model may find that option useful as a way to prevent mass-assignment from setting the attribute. -The generation of the reader instance method can be prevented by setting the option +:instance_reader+ to +false+. +The generation of the reader instance method can be prevented by setting the option `:instance_reader` to `false`. ```ruby class A @@ -1046,15 +1046,15 @@ end A.new.x = 1 # NoMethodError ``` -For convenience +class_attribute+ also defines an instance predicate which is the double negation of what the instance reader returns. In the examples above it would be called +x?+. +For convenience `class_attribute` also defines an instance predicate which is the double negation of what the instance reader returns. In the examples above it would be called `x?`. -When +:instance_reader+ is +false+, the instance predicate returns a +NoMethodError+ just like the reader method. +When `:instance_reader` is `false`, the instance predicate returns a `NoMethodError` just like the reader method. -NOTE: Defined in +active_support/core_ext/class/attribute.rb+ +NOTE: Defined in `active_support/core_ext/class/attribute.rb` -#### +cattr_reader+, +cattr_writer+, and +cattr_accessor+ +#### `cattr_reader`, `cattr_writer`, and `cattr_accessor` -The macros +cattr_reader+, +cattr_writer+, and +cattr_accessor+ are analogous to their +attr_*+ counterparts but for classes. They initialize a class variable to +nil+ unless it already exists, and generate the corresponding class methods to access it: +The macros `cattr_reader`, `cattr_writer`, and `cattr_accessor` are analogous to their `attr_*` counterparts but for classes. They initialize a class variable to `nil` unless it already exists, and generate the corresponding class methods to access it: ```ruby class MysqlAdapter < AbstractAdapter @@ -1064,7 +1064,7 @@ class MysqlAdapter < AbstractAdapter end ``` -Instance methods are created as well for convenience, they are just proxies to the class attribute. So, instances can change the class attribute, but cannot override it as it happens with +class_attribute+ (see above). For example given +Instance methods are created as well for convenience, they are just proxies to the class attribute. So, instances can change the class attribute, but cannot override it as it happens with `class_attribute` (see above). For example given ```ruby module ActionView @@ -1075,9 +1075,9 @@ module ActionView end ``` -we can access +field_error_proc+ in views. +we can access `field_error_proc` in views. -The generation of the reader instance method can be prevented by setting +:instance_reader+ to +false+ and the generation of the writer instance method can be prevented by setting +:instance_writer+ to +false+. Generation of both methods can be prevented by setting +:instance_accessor+ to +false+. In all cases, the value must be exactly +false+ and not any false value. +The generation of the reader instance method can be prevented by setting `:instance_reader` to `false` and the generation of the writer instance method can be prevented by setting `:instance_writer` to `false`. Generation of both methods can be prevented by setting `:instance_accessor` to `false`. In all cases, the value must be exactly `false` and not any false value. ```ruby module A @@ -1092,15 +1092,15 @@ module A end ``` -A model may find it useful to set +:instance_accessor+ to +false+ as a way to prevent mass-assignment from setting the attribute. +A model may find it useful to set `:instance_accessor` to `false` as a way to prevent mass-assignment from setting the attribute. -NOTE: Defined in +active_support/core_ext/class/attribute_accessors.rb+. +NOTE: Defined in `active_support/core_ext/class/attribute_accessors.rb`. ### Subclasses & Descendants -#### +subclasses+ +#### `subclasses` -The +subclasses+ method returns the subclasses of the receiver: +The `subclasses` method returns the subclasses of the receiver: ```ruby class C; end @@ -1120,11 +1120,11 @@ The order in which these classes are returned is unspecified. WARNING: This method is redefined in some Rails core classes but should be all compatible in Rails 3.1. -NOTE: Defined in +active_support/core_ext/class/subclasses.rb+. +NOTE: Defined in `active_support/core_ext/class/subclasses.rb`. -#### +descendants+ +#### `descendants` -The +descendants+ method returns all classes that are `<` than its receiver: +The `descendants` method returns all classes that are `<` than its receiver: ```ruby class C; end @@ -1142,16 +1142,16 @@ C.descendants # => [B, A, D] The order in which these classes are returned is unspecified. -NOTE: Defined in +active_support/core_ext/class/subclasses.rb+. +NOTE: Defined in `active_support/core_ext/class/subclasses.rb`. -Extensions to +String+ +Extensions to `String` ---------------------- ### Output Safety #### Motivation -Inserting data into HTML templates needs extra care. For example, you can't just interpolate +@review.title+ verbatim into an HTML page. For one thing, if the review title is "Flanagan & Matz rules!" the output won't be well-formed because an ampersand has to be escaped as "&amp;". What's more, depending on the application, that may be a big security hole because users can inject malicious HTML setting a hand-crafted review title. Check out the "section about cross-site scripting in the Security guide":security.html#cross-site-scripting-xss for further information about the risks. +Inserting data into HTML templates needs extra care. For example, you can't just interpolate `@review.title` verbatim into an HTML page. For one thing, if the review title is "Flanagan & Matz rules!" the output won't be well-formed because an ampersand has to be escaped as "&amp;". What's more, depending on the application, that may be a big security hole because users can inject malicious HTML setting a hand-crafted review title. Check out the "section about cross-site scripting in the Security guide":security.html#cross-site-scripting-xss for further information about the risks. #### Safe Strings @@ -1163,14 +1163,14 @@ Strings are considered to be <i>unsafe</i> by default: "".html_safe? # => false ``` -You can obtain a safe string from a given one with the +html_safe+ method: +You can obtain a safe string from a given one with the `html_safe` method: ```ruby s = "".html_safe s.html_safe? # => true ``` -It is important to understand that +html_safe+ performs no escaping whatsoever, it is just an assertion: +It is important to understand that `html_safe` performs no escaping whatsoever, it is just an assertion: ```ruby s = "<script>...</script>".html_safe @@ -1178,9 +1178,9 @@ s.html_safe? # => true s # => "<script>...</script>" ``` -It is your responsibility to ensure calling +html_safe+ on a particular string is fine. +It is your responsibility to ensure calling `html_safe` on a particular string is fine. -If you append onto a safe string, either in-place with +concat+/`<<`, or with `+`, the result is a safe string. Unsafe arguments are escaped: +If you append onto a safe string, either in-place with `concat`/`<<`, or with `+`, the result is a safe string. Unsafe arguments are escaped: ```ruby "".html_safe + "<" # => "<" @@ -1198,7 +1198,7 @@ These methods should not be used in ordinary views. In Rails 3 unsafe values are <%= @review.title %> <%# fine in Rails 3, escaped if needed %> ``` -To insert something verbatim use the +raw+ helper rather than calling +html_safe+: +To insert something verbatim use the `raw` helper rather than calling `html_safe`: ```erb <%= raw @cms.current_template %> <%# inserts @cms.current_template as is %> @@ -1210,7 +1210,7 @@ or, equivalently, use `<%==`: <%== @cms.current_template %> <%# inserts @cms.current_template as is %> ``` -The +raw+ helper calls +html_safe+ for you: +The `raw` helper calls `html_safe` for you: ```ruby def raw(stringish) @@ -1218,46 +1218,46 @@ def raw(stringish) end ``` -NOTE: Defined in +active_support/core_ext/string/output_safety.rb+. +NOTE: Defined in `active_support/core_ext/string/output_safety.rb`. #### Transformation -As a rule of thumb, except perhaps for concatenation as explained above, any method that may change a string gives you an unsafe string. These are +downcase+, +gsub+, +strip+, +chomp+, +underscore+, etc. +As a rule of thumb, except perhaps for concatenation as explained above, any method that may change a string gives you an unsafe string. These are `downcase`, `gsub`, `strip`, `chomp`, `underscore`, etc. -In the case of in-place transformations like +gsub!+ the receiver itself becomes unsafe. +In the case of in-place transformations like `gsub!` the receiver itself becomes unsafe. INFO: The safety bit is lost always, no matter whether the transformation actually changed something. #### Conversion and Coercion -Calling +to_s+ on a safe string returns a safe string, but coercion with +to_str+ returns an unsafe string. +Calling `to_s` on a safe string returns a safe string, but coercion with `to_str` returns an unsafe string. #### Copying -Calling +dup+ or +clone+ on safe strings yields safe strings. +Calling `dup` or `clone` on safe strings yields safe strings. -### +squish+ +### `squish` -The method +squish+ strips leading and trailing whitespace, and substitutes runs of whitespace with a single space each: +The method `squish` strips leading and trailing whitespace, and substitutes runs of whitespace with a single space each: ```ruby " \n foo\n\r \t bar \n".squish # => "foo bar" ``` -There's also the destructive version +String#squish!+. +There's also the destructive version `String#squish!`. -NOTE: Defined in +active_support/core_ext/string/filters.rb+. +NOTE: Defined in `active_support/core_ext/string/filters.rb`. -### +truncate+ +### `truncate` -The method +truncate+ returns a copy of its receiver truncated after a given +length+: +The method `truncate` returns a copy of its receiver truncated after a given `length`: ```ruby "Oh dear! Oh dear! I shall be late!".truncate(20) # => "Oh dear! Oh dear!..." ``` -Ellipsis can be customized with the +:omission+ option: +Ellipsis can be customized with the `:omission` option: ```ruby "Oh dear! Oh dear! I shall be late!".truncate(20, :omission => '…') @@ -1266,7 +1266,7 @@ Ellipsis can be customized with the +:omission+ option: Note in particular that truncation takes into account the length of the omission string. -Pass a +:separator+ to truncate the string at a natural break: +Pass a `:separator` to truncate the string at a natural break: ```ruby "Oh dear! Oh dear! I shall be late!".truncate(18) @@ -1275,40 +1275,40 @@ Pass a +:separator+ to truncate the string at a natural break: # => "Oh dear! Oh..." ``` -The option +:separator+ can be a regexp: +The option `:separator` can be a regexp: ```ruby "Oh dear! Oh dear! I shall be late!".truncate(18, :separator => /\s/) # => "Oh dear! Oh..." ``` -In above examples "dear" gets cut first, but then +:separator+ prevents it. +In above examples "dear" gets cut first, but then `:separator` prevents it. -NOTE: Defined in +active_support/core_ext/string/filters.rb+. +NOTE: Defined in `active_support/core_ext/string/filters.rb`. -### +inquiry+ +### `inquiry` -The `inquiry` method converts a string into a +StringInquirer+ object making equality checks prettier. +The `inquiry` method converts a string into a `StringInquirer` object making equality checks prettier. ```ruby "production".inquiry.production? # => true "active".inquiry.inactive? # => false ``` -### +starts_with?+ and +ends_with?+ +### `starts_with?` and `ends_with?` -Active Support defines 3rd person aliases of +String#start_with?+ and +String#end_with?+: +Active Support defines 3rd person aliases of `String#start_with?` and `String#end_with?`: ```ruby "foo".starts_with?("f") # => true "foo".ends_with?("o") # => true ``` -NOTE: Defined in +active_support/core_ext/string/starts_ends_with.rb+. +NOTE: Defined in `active_support/core_ext/string/starts_ends_with.rb`. -### +strip_heredoc+ +### `strip_heredoc` -The method +strip_heredoc+ strips indentation in heredocs. +The method `strip_heredoc` strips indentation in heredocs. For example in @@ -1329,9 +1329,9 @@ the user would see the usage message aligned against the left margin. Technically, it looks for the least indented line in the whole string, and removes that amount of leading whitespace. -NOTE: Defined in +active_support/core_ext/string/strip.rb+. +NOTE: Defined in `active_support/core_ext/string/strip.rb`. -### +indent+ +### `indent` Indents the lines in the receiver: @@ -1347,7 +1347,7 @@ EOS end ``` -The second argument, +indent_string+, specifies which indent string to use. The default is +nil+, which tells the method to make an educated guess peeking at the first indented line, and fallback to a space if there is none. +The second argument, `indent_string`, specifies which indent string to use. The default is `nil`, which tells the method to make an educated guess peeking at the first indented line, and fallback to a space if there is none. ```ruby " foo".indent(2) # => " foo" @@ -1355,22 +1355,22 @@ The second argument, +indent_string+, specifies which indent string to use. The "foo".indent(2, "\t") # => "\t\tfoo" ``` -While +indent_string+ is tipically one space or tab, it may be any string. +While `indent_string` is tipically one space or tab, it may be any string. -The third argument, +indent_empty_lines+, is a flag that says whether empty lines should be indented. Default is false. +The third argument, `indent_empty_lines`, is a flag that says whether empty lines should be indented. Default is false. ```ruby "foo\n\nbar".indent(2) # => " foo\n\n bar" "foo\n\nbar".indent(2, nil, true) # => " foo\n \n bar" ``` -The +indent!+ method performs indentation in-place. +The `indent!` method performs indentation in-place. ### Access -#### +at(position)+ +#### `at(position)` -Returns the character of the string at position +position+: +Returns the character of the string at position `position`: ```ruby "hello".at(0) # => "h" @@ -1379,11 +1379,11 @@ Returns the character of the string at position +position+: "hello".at(10) # => nil ``` -NOTE: Defined in +active_support/core_ext/string/access.rb+. +NOTE: Defined in `active_support/core_ext/string/access.rb`. -#### +from(position)+ +#### `from(position)` -Returns the substring of the string starting at position +position+: +Returns the substring of the string starting at position `position`: ```ruby "hello".from(0) # => "hello" @@ -1392,11 +1392,11 @@ Returns the substring of the string starting at position +position+: "hello".from(10) # => "" if < 1.9, nil in 1.9 ``` -NOTE: Defined in +active_support/core_ext/string/access.rb+. +NOTE: Defined in `active_support/core_ext/string/access.rb`. -#### +to(position)+ +#### `to(position)` -Returns the substring of the string up to position +position+: +Returns the substring of the string up to position `position`: ```ruby "hello".to(0) # => "h" @@ -1405,25 +1405,25 @@ Returns the substring of the string up to position +position+: "hello".to(10) # => "hello" ``` -NOTE: Defined in +active_support/core_ext/string/access.rb+. +NOTE: Defined in `active_support/core_ext/string/access.rb`. -#### +first(limit = 1)+ +#### `first(limit = 1)` -The call +str.first(n)+ is equivalent to +str.to(n-1)+ if +n+ > 0, and returns an empty string for +n+ == 0. +The call `str.first(n)` is equivalent to `str.to(n-1)` if `n` > 0, and returns an empty string for `n` == 0. -NOTE: Defined in +active_support/core_ext/string/access.rb+. +NOTE: Defined in `active_support/core_ext/string/access.rb`. -#### +last(limit = 1)+ +#### `last(limit = 1)` -The call +str.last(n)+ is equivalent to +str.from(-n)+ if +n+ > 0, and returns an empty string for +n+ == 0. +The call `str.last(n)` is equivalent to `str.from(-n)` if `n` > 0, and returns an empty string for `n` == 0. -NOTE: Defined in +active_support/core_ext/string/access.rb+. +NOTE: Defined in `active_support/core_ext/string/access.rb`. ### Inflections -#### +pluralize+ +#### `pluralize` -The method +pluralize+ returns the plural of its receiver: +The method `pluralize` returns the plural of its receiver: ```ruby "table".pluralize # => "tables" @@ -1431,9 +1431,9 @@ The method +pluralize+ returns the plural of its receiver: "equipment".pluralize # => "equipment" ``` -As the previous example shows, Active Support knows some irregular plurals and uncountable nouns. Built-in rules can be extended in +config/initializers/inflections.rb+. That file is generated by the +rails+ command and has instructions in comments. +As the previous example shows, Active Support knows some irregular plurals and uncountable nouns. Built-in rules can be extended in `config/initializers/inflections.rb`. That file is generated by the `rails` command and has instructions in comments. -+pluralize+ can also take an optional +count+ parameter. If `count == 1` the singular form will be returned. For any other value of +count+ the plural form will be returned: +`pluralize` can also take an optional `count` parameter. If `count == 1` the singular form will be returned. For any other value of `count` the plural form will be returned: ```ruby "dude".pluralize(0) # => "dudes" @@ -1452,11 +1452,11 @@ def undecorated_table_name(class_name = base_class.name) end ``` -NOTE: Defined in +active_support/core_ext/string/inflections.rb+. +NOTE: Defined in `active_support/core_ext/string/inflections.rb`. -#### +singularize+ +#### `singularize` -The inverse of +pluralize+: +The inverse of `pluralize`: ```ruby "tables".singularize # => "table" @@ -1475,11 +1475,11 @@ def derive_class_name end ``` -NOTE: Defined in +active_support/core_ext/string/inflections.rb+. +NOTE: Defined in `active_support/core_ext/string/inflections.rb`. -#### +camelize+ +#### `camelize` -The method +camelize+ returns its receiver in camel case: +The method `camelize` returns its receiver in camel case: ```ruby "product".camelize # => "Product" @@ -1503,7 +1503,7 @@ def session_store=(store) end ``` -+camelize+ accepts an optional argument, it can be +:upper+ (default), or +:lower+. With the latter the first letter becomes lowercase: +`camelize` accepts an optional argument, it can be `:upper` (default), or `:lower`. With the latter the first letter becomes lowercase: ```ruby "visual_effect".camelize(:lower) # => "visualEffect" @@ -1511,7 +1511,7 @@ end That may be handy to compute method names in a language that follows that convention, for example JavaScript. -INFO: As a rule of thumb you can think of +camelize+ as the inverse of +underscore+, though there are cases where that does not hold: `"SSLError".underscore.camelize` gives back `"SslError"`. To support cases such as this, Active Support allows you to specify acronyms in +config/initializers/inflections.rb+: +INFO: As a rule of thumb you can think of `camelize` as the inverse of `underscore`, though there are cases where that does not hold: `"SSLError".underscore.camelize` gives back `"SslError"`. To support cases such as this, Active Support allows you to specify acronyms in `config/initializers/inflections.rb`: ```ruby ActiveSupport::Inflector.inflections do |inflect| @@ -1521,13 +1521,13 @@ end "SSLError".underscore.camelize #=> "SSLError" ``` -+camelize+ is aliased to +camelcase+. +`camelize` is aliased to `camelcase`. -NOTE: Defined in +active_support/core_ext/string/inflections.rb+. +NOTE: Defined in `active_support/core_ext/string/inflections.rb`. -#### +underscore+ +#### `underscore` -The method +underscore+ goes the other way around, from camel case to paths: +The method `underscore` goes the other way around, from camel case to paths: ```ruby "Product".underscore # => "product" @@ -1546,9 +1546,9 @@ and understands strings that start with lowercase: "visualEffect".underscore # => "visual_effect" ``` -+underscore+ accepts no argument though. +`underscore` accepts no argument though. -Rails class and module autoloading uses +underscore+ to infer the relative path without extension of a file that would define a given missing constant: +Rails class and module autoloading uses `underscore` to infer the relative path without extension of a file that would define a given missing constant: ```ruby # active_support/dependencies.rb @@ -1560,26 +1560,26 @@ def load_missing_constant(from_mod, const_name) end ``` -INFO: As a rule of thumb you can think of +underscore+ as the inverse of +camelize+, though there are cases where that does not hold. For example, `"SSLError".underscore.camelize` gives back `"SslError"`. +INFO: As a rule of thumb you can think of `underscore` as the inverse of `camelize`, though there are cases where that does not hold. For example, `"SSLError".underscore.camelize` gives back `"SslError"`. -NOTE: Defined in +active_support/core_ext/string/inflections.rb+. +NOTE: Defined in `active_support/core_ext/string/inflections.rb`. -#### +titleize+ +#### `titleize` -The method +titleize+ capitalizes the words in the receiver: +The method `titleize` capitalizes the words in the receiver: ```ruby "alice in wonderland".titleize # => "Alice In Wonderland" "fermat's enigma".titleize # => "Fermat's Enigma" ``` -+titleize+ is aliased to +titlecase+. +`titleize` is aliased to `titlecase`. -NOTE: Defined in +active_support/core_ext/string/inflections.rb+. +NOTE: Defined in `active_support/core_ext/string/inflections.rb`. -#### +dasherize+ +#### `dasherize` -The method +dasherize+ replaces the underscores in the receiver with dashes: +The method `dasherize` replaces the underscores in the receiver with dashes: ```ruby "name".dasherize # => "name" @@ -1596,11 +1596,11 @@ def reformat_name(name) end ``` -NOTE: Defined in +active_support/core_ext/string/inflections.rb+. +NOTE: Defined in `active_support/core_ext/string/inflections.rb`. -#### +demodulize+ +#### `demodulize` -Given a string with a qualified constant name, +demodulize+ returns the very constant name, that is, the rightmost part of it: +Given a string with a qualified constant name, `demodulize` returns the very constant name, that is, the rightmost part of it: ```ruby "Product".demodulize # => "Product" @@ -1621,11 +1621,11 @@ def counter_cache_column end ``` -NOTE: Defined in +active_support/core_ext/string/inflections.rb+. +NOTE: Defined in `active_support/core_ext/string/inflections.rb`. -#### +deconstantize+ +#### `deconstantize` -Given a string with a qualified constant reference expression, +deconstantize+ removes the rightmost segment, generally leaving the name of the constant's container: +Given a string with a qualified constant reference expression, `deconstantize` removes the rightmost segment, generally leaving the name of the constant's container: ```ruby "Product".deconstantize # => "" @@ -1633,7 +1633,7 @@ Given a string with a qualified constant reference expression, +deconstantize+ r "Admin::Hotel::ReservationUtils".deconstantize # => "Admin::Hotel" ``` -Active Support for example uses this method in +Module#qualified_const_set+: +Active Support for example uses this method in `Module#qualified_const_set`: ```ruby def qualified_const_set(path, value) @@ -1646,24 +1646,24 @@ def qualified_const_set(path, value) end ``` -NOTE: Defined in +active_support/core_ext/string/inflections.rb+. +NOTE: Defined in `active_support/core_ext/string/inflections.rb`. -#### +parameterize+ +#### `parameterize` -The method +parameterize+ normalizes its receiver in a way that can be used in pretty URLs. +The method `parameterize` normalizes its receiver in a way that can be used in pretty URLs. ```ruby "John Smith".parameterize # => "john-smith" "Kurt Gödel".parameterize # => "kurt-godel" ``` -In fact, the result string is wrapped in an instance of +ActiveSupport::Multibyte::Chars+. +In fact, the result string is wrapped in an instance of `ActiveSupport::Multibyte::Chars`. -NOTE: Defined in +active_support/core_ext/string/inflections.rb+. +NOTE: Defined in `active_support/core_ext/string/inflections.rb`. -#### +tableize+ +#### `tableize` -The method +tableize+ is +underscore+ followed by +pluralize+. +The method `tableize` is `underscore` followed by `pluralize`. ```ruby "Person".tableize # => "people" @@ -1671,13 +1671,13 @@ The method +tableize+ is +underscore+ followed by +pluralize+. "InvoiceLine".tableize # => "invoice_lines" ``` -As a rule of thumb, +tableize+ returns the table name that corresponds to a given model for simple cases. The actual implementation in Active Record is not straight +tableize+ indeed, because it also demodulizes the class name and checks a few options that may affect the returned string. +As a rule of thumb, `tableize` returns the table name that corresponds to a given model for simple cases. The actual implementation in Active Record is not straight `tableize` indeed, because it also demodulizes the class name and checks a few options that may affect the returned string. -NOTE: Defined in +active_support/core_ext/string/inflections.rb+. +NOTE: Defined in `active_support/core_ext/string/inflections.rb`. -#### +classify+ +#### `classify` -The method +classify+ is the inverse of +tableize+. It gives you the class name corresponding to a table name: +The method `classify` is the inverse of `tableize`. It gives you the class name corresponding to a table name: ```ruby "people".classify # => "Person" @@ -1691,13 +1691,13 @@ The method understands qualified table names: "highrise_production.companies".classify # => "Company" ``` -Note that +classify+ returns a class name as a string. You can get the actual class object invoking +constantize+ on it, explained next. +Note that `classify` returns a class name as a string. You can get the actual class object invoking `constantize` on it, explained next. -NOTE: Defined in +active_support/core_ext/string/inflections.rb+. +NOTE: Defined in `active_support/core_ext/string/inflections.rb`. -#### +constantize+ +#### `constantize` -The method +constantize+ resolves the constant reference expression in its receiver: +The method `constantize` resolves the constant reference expression in its receiver: ```ruby "Fixnum".constantize # => Fixnum @@ -1708,9 +1708,9 @@ end "M::X".constantize # => 1 ``` -If the string evaluates to no known constant, or its content is not even a valid constant name, +constantize+ raises +NameError+. +If the string evaluates to no known constant, or its content is not even a valid constant name, `constantize` raises `NameError`. -Constant name resolution by +constantize+ starts always at the top-level +Object+ even if there is no leading "::". +Constant name resolution by `constantize` starts always at the top-level `Object` even if there is no leading "::". ```ruby X = :in_Object @@ -1725,7 +1725,7 @@ end So, it is in general not equivalent to what Ruby would do in the same spot, had a real constant be evaluated. -Mailer test cases obtain the mailer being tested from the name of the test class using +constantize+: +Mailer test cases obtain the mailer being tested from the name of the test class using `constantize`: ```ruby # action_mailer/test_case.rb @@ -1736,11 +1736,11 @@ rescue NameError => e end ``` -NOTE: Defined in +active_support/core_ext/string/inflections.rb+. +NOTE: Defined in `active_support/core_ext/string/inflections.rb`. -#### +humanize+ +#### `humanize` -The method +humanize+ gives you a sensible name for display out of an attribute name. To do so it replaces underscores with spaces, removes any "_id" suffix, and capitalizes the first word: +The method `humanize` gives you a sensible name for display out of an attribute name. To do so it replaces underscores with spaces, removes any "_id" suffix, and capitalizes the first word: ```ruby "name".humanize # => "Name" @@ -1748,7 +1748,7 @@ The method +humanize+ gives you a sensible name for display out of an attribute "comments_count".humanize # => "Comments count" ``` -The helper method +full_messages+ uses +humanize+ as a fallback to include attribute names: +The helper method `full_messages` uses `humanize` as a fallback to include attribute names: ```ruby def full_messages @@ -1765,11 +1765,11 @@ def full_messages end ``` -NOTE: Defined in +active_support/core_ext/string/inflections.rb+. +NOTE: Defined in `active_support/core_ext/string/inflections.rb`. -#### +foreign_key+ +#### `foreign_key` -The method +foreign_key+ gives a foreign key column name from a class name. To do so it demodulizes, underscores, and adds "_id": +The method `foreign_key` gives a foreign key column name from a class name. To do so it demodulizes, underscores, and adds "_id": ```ruby "User".foreign_key # => "user_id" @@ -1783,20 +1783,20 @@ Pass a false argument if you do not want the underscore in "_id": "User".foreign_key(false) # => "userid" ``` -Associations use this method to infer foreign keys, for example +has_one+ and +has_many+ do this: +Associations use this method to infer foreign keys, for example `has_one` and `has_many` do this: ```ruby # active_record/associations.rb foreign_key = options[:foreign_key] || reflection.active_record.name.foreign_key ``` -NOTE: Defined in +active_support/core_ext/string/inflections.rb+. +NOTE: Defined in `active_support/core_ext/string/inflections.rb`. ### Conversions -#### +to_date+, +to_time+, +to_datetime+ +#### `to_date`, `to_time`, `to_datetime` -The methods +to_date+, +to_time+, and +to_datetime+ are basically convenience wrappers around +Date._parse+: +The methods `to_date`, `to_time`, and `to_datetime` are basically convenience wrappers around `Date._parse`: ```ruby "2010-07-27".to_date # => Tue, 27 Jul 2010 @@ -1804,22 +1804,22 @@ The methods +to_date+, +to_time+, and +to_datetime+ are basically convenience wr "2010-07-27 23:37:00".to_datetime # => Tue, 27 Jul 2010 23:37:00 +0000 ``` -+to_time+ receives an optional argument +:utc+ or +:local+, to indicate which time zone you want the time in: +`to_time` receives an optional argument `:utc` or `:local`, to indicate which time zone you want the time in: ```ruby "2010-07-27 23:42:00".to_time(:utc) # => Tue Jul 27 23:42:00 UTC 2010 "2010-07-27 23:42:00".to_time(:local) # => Tue Jul 27 23:42:00 +0200 2010 ``` -Default is +:utc+. +Default is `:utc`. -Please refer to the documentation of +Date._parse+ for further details. +Please refer to the documentation of `Date._parse` for further details. -INFO: The three of them return +nil+ for blank receivers. +INFO: The three of them return `nil` for blank receivers. -NOTE: Defined in +active_support/core_ext/string/conversions.rb+. +NOTE: Defined in `active_support/core_ext/string/conversions.rb`. -Extensions to +Numeric+ +Extensions to `Numeric` ----------------------- ### Bytes @@ -1851,7 +1851,7 @@ Singular forms are aliased so you are able to say: 1.megabyte # => 1048576 ``` -NOTE: Defined in +active_support/core_ext/numeric/bytes.rb+. +NOTE: Defined in `active_support/core_ext/numeric/bytes.rb`. ### Time @@ -1888,7 +1888,7 @@ Date[http://ruby-doc.org/stdlib/libdoc/date/rdoc/Date.html] and Time[http://ruby-doc.org/stdlib/libdoc/time/rdoc/Time.html] should be used for precision date and time arithmetic. -NOTE: Defined in +active_support/core_ext/numeric/time.rb+. +NOTE: Defined in `active_support/core_ext/numeric/time.rb`. ### Formatting @@ -1975,25 +1975,25 @@ Produce a string representation of a number in human-readable words: 1234567890123456.to_s(:human) # => "1.23 Quadrillion" ``` -NOTE: Defined in +active_support/core_ext/numeric/formatting.rb+. +NOTE: Defined in `active_support/core_ext/numeric/formatting.rb`. -Extensions to +Integer+ +Extensions to `Integer` ----------------------- -### +multiple_of?+ +### `multiple_of?` -The method +multiple_of?+ tests whether an integer is multiple of the argument: +The method `multiple_of?` tests whether an integer is multiple of the argument: ```ruby 2.multiple_of?(1) # => true 1.multiple_of?(2) # => false ``` -NOTE: Defined in +active_support/core_ext/integer/multiple.rb+. +NOTE: Defined in `active_support/core_ext/integer/multiple.rb`. -### +ordinal+ +### `ordinal` -The method +ordinal+ returns the ordinal suffix string corresponding to the receiver integer: +The method `ordinal` returns the ordinal suffix string corresponding to the receiver integer: ```ruby 1.ordinal # => "st" @@ -2004,11 +2004,11 @@ The method +ordinal+ returns the ordinal suffix string corresponding to the rece -134.ordinal # => "th" ``` -NOTE: Defined in +active_support/core_ext/integer/inflections.rb+. +NOTE: Defined in `active_support/core_ext/integer/inflections.rb`. -### +ordinalize+ +### `ordinalize` -The method +ordinalize+ returns the ordinal string corresponding to the receiver integer. In comparison, note that the +ordinal+ method returns *only* the suffix string. +The method `ordinalize` returns the ordinal string corresponding to the receiver integer. In comparison, note that the `ordinal` method returns *only* the suffix string. ```ruby 1.ordinalize # => "1st" @@ -2019,19 +2019,19 @@ The method +ordinalize+ returns the ordinal string corresponding to the receiver -134.ordinalize # => "-134th" ``` -NOTE: Defined in +active_support/core_ext/integer/inflections.rb+. +NOTE: Defined in `active_support/core_ext/integer/inflections.rb`. -Extensions to +BigDecimal+ +Extensions to `BigDecimal` -------------------------- ... -Extensions to +Enumerable+ +Extensions to `Enumerable` -------------------------- -### +sum+ +### `sum` -The method +sum+ adds the elements of an enumerable: +The method `sum` adds the elements of an enumerable: ```ruby [1, 2, 3].sum # => 6 @@ -2053,7 +2053,7 @@ The sum of an empty collection is zero by default, but this is customizable: [].sum(1) # => 1 ``` -If a block is given, +sum+ becomes an iterator that yields the elements of the collection and sums the returned values: +If a block is given, `sum` becomes an iterator that yields the elements of the collection and sums the returned values: ```ruby (1..5).sum {|n| n * 2 } # => 30 @@ -2066,7 +2066,7 @@ The sum of an empty receiver can be customized in this form as well: [].sum(1) {|n| n**3} # => 1 ``` -The method +ActiveRecord::Observer#observed_subclasses+ for example is implemented this way: +The method `ActiveRecord::Observer#observed_subclasses` for example is implemented this way: ```ruby def observed_subclasses @@ -2074,11 +2074,11 @@ def observed_subclasses end ``` -NOTE: Defined in +active_support/core_ext/enumerable.rb+. +NOTE: Defined in `active_support/core_ext/enumerable.rb`. -### +index_by+ +### `index_by` -The method +index_by+ generates a hash with the elements of an enumerable indexed by some key. +The method `index_by` generates a hash with the elements of an enumerable indexed by some key. It iterates through the collection and passes each element to a block. The element will be keyed by the value returned by the block: @@ -2089,11 +2089,11 @@ invoices.index_by(&:number) WARNING. Keys should normally be unique. If the block returns the same value for different elements no collection is built for that key. The last item will win. -NOTE: Defined in +active_support/core_ext/enumerable.rb+. +NOTE: Defined in `active_support/core_ext/enumerable.rb`. -### +many?+ +### `many?` -The method +many?+ is shorthand for +collection.size > 1+: +The method `many?` is shorthand for `collection.size > 1`: ```erb <% if pages.many? %> @@ -2101,37 +2101,37 @@ The method +many?+ is shorthand for +collection.size > 1+: <% end %> ``` -If an optional block is given, +many?+ only takes into account those elements that return true: +If an optional block is given, `many?` only takes into account those elements that return true: ```ruby @see_more = videos.many? {|video| video.category == params[:category]} ``` -NOTE: Defined in +active_support/core_ext/enumerable.rb+. +NOTE: Defined in `active_support/core_ext/enumerable.rb`. -### +exclude?+ +### `exclude?` -The predicate +exclude?+ tests whether a given object does *not* belong to the collection. It is the negation of the built-in +include?+: +The predicate `exclude?` tests whether a given object does *not* belong to the collection. It is the negation of the built-in `include?`: ```ruby to_visit << node if visited.exclude?(node) ``` -NOTE: Defined in +active_support/core_ext/enumerable.rb+. +NOTE: Defined in `active_support/core_ext/enumerable.rb`. -Extensions to +Array+ +Extensions to `Array` --------------------- ### Accessing -Active Support augments the API of arrays to ease certain ways of accessing them. For example, +to+ returns the subarray of elements up to the one at the passed index: +Active Support augments the API of arrays to ease certain ways of accessing them. For example, `to` returns the subarray of elements up to the one at the passed index: ```ruby %w(a b c d).to(2) # => %w(a b c) [].to(7) # => [] ``` -Similarly, +from+ returns the tail from the element at the passed index to the end. If the index is greater than the length of the array, it returns an empty array. +Similarly, `from` returns the tail from the element at the passed index to the end. If the index is greater than the length of the array, it returns an empty array. ```ruby %w(a b c d).from(2) # => %w(c d) @@ -2139,18 +2139,18 @@ Similarly, +from+ returns the tail from the element at the passed index to the e [].from(0) # => [] ``` -The methods +second+, +third+, +fourth+, and +fifth+ return the corresponding element (+first+ is built-in). Thanks to social wisdom and positive constructiveness all around, +forty_two+ is also available. +The methods `second`, `third`, `fourth`, and `fifth` return the corresponding element (`first` is built-in). Thanks to social wisdom and positive constructiveness all around, `forty_two` is also available. ```ruby %w(a b c d).third # => c %w(a b c d).fifth # => nil ``` -NOTE: Defined in +active_support/core_ext/array/access.rb+. +NOTE: Defined in `active_support/core_ext/array/access.rb`. ### Adding Elements -#### +prepend+ +#### `prepend` This method is an alias of `Array#unshift`. @@ -2159,9 +2159,9 @@ This method is an alias of `Array#unshift`. [].prepend(10) # => [10] ``` -NOTE: Defined in +active_support/core_ext/array/prepend_and_append.rb+. +NOTE: Defined in `active_support/core_ext/array/prepend_and_append.rb`. -#### +append+ +#### `append` This method is an alias of `Array#<<`. @@ -2170,11 +2170,11 @@ This method is an alias of `Array#<<`. [].append([1,2]) # => [[1,2]] ``` -NOTE: Defined in +active_support/core_ext/array/prepend_and_append.rb+. +NOTE: Defined in `active_support/core_ext/array/prepend_and_append.rb`. ### Options Extraction -When the last argument in a method call is a hash, except perhaps for a +&block+ argument, Ruby allows you to omit the brackets: +When the last argument in a method call is a hash, except perhaps for a `&block` argument, Ruby allows you to omit the brackets: ```ruby User.exists?(:email => params[:email]) @@ -2184,9 +2184,9 @@ That syntactic sugar is used a lot in Rails to avoid positional arguments where If a method expects a variable number of arguments and uses `*` in its declaration, however, such an options hash ends up being an item of the array of arguments, where it loses its role. -In those cases, you may give an options hash a distinguished treatment with +extract_options!+. This method checks the type of the last item of an array. If it is a hash it pops it and returns it, otherwise it returns an empty hash. +In those cases, you may give an options hash a distinguished treatment with `extract_options!`. This method checks the type of the last item of an array. If it is a hash it pops it and returns it, otherwise it returns an empty hash. -Let's see for example the definition of the +caches_action+ controller macro: +Let's see for example the definition of the `caches_action` controller macro: ```ruby def caches_action(*actions) @@ -2196,15 +2196,15 @@ def caches_action(*actions) end ``` -This method receives an arbitrary number of action names, and an optional hash of options as last argument. With the call to +extract_options!+ you obtain the options hash and remove it from +actions+ in a simple and explicit way. +This method receives an arbitrary number of action names, and an optional hash of options as last argument. With the call to `extract_options!` you obtain the options hash and remove it from `actions` in a simple and explicit way. -NOTE: Defined in +active_support/core_ext/array/extract_options.rb+. +NOTE: Defined in `active_support/core_ext/array/extract_options.rb`. ### Conversions -#### +to_sentence+ +#### `to_sentence` -The method +to_sentence+ turns an array into a string containing a sentence that enumerates its items: +The method `to_sentence` turns an array into a string containing a sentence that enumerates its items: ```ruby %w().to_sentence # => "" @@ -2228,13 +2228,13 @@ The defaults for these options can be localised, their keys are: Options `:connector` and `:skip_last_comma` are deprecated. -NOTE: Defined in +active_support/core_ext/array/conversions.rb+. +NOTE: Defined in `active_support/core_ext/array/conversions.rb`. -#### +to_formatted_s+ +#### `to_formatted_s` -The method +to_formatted_s+ acts like +to_s+ by default. +The method `to_formatted_s` acts like `to_s` by default. -If the array contains items that respond to +id+, however, it may be passed the symbol `:db` as argument. That's typically used with collections of ARs. Returned strings are: +If the array contains items that respond to `id`, however, it may be passed the symbol `:db` as argument. That's typically used with collections of ARs. Returned strings are: ```ruby [].to_formatted_s(:db) # => "null" @@ -2242,13 +2242,13 @@ If the array contains items that respond to +id+, however, it may be passed the invoice.lines.to_formatted_s(:db) # => "23,567,556,12" ``` -Integers in the example above are supposed to come from the respective calls to +id+. +Integers in the example above are supposed to come from the respective calls to `id`. -NOTE: Defined in +active_support/core_ext/array/conversions.rb+. +NOTE: Defined in `active_support/core_ext/array/conversions.rb`. -#### +to_xml+ +#### `to_xml` -The method +to_xml+ returns a string containing an XML representation of its receiver: +The method `to_xml` returns a string containing an XML representation of its receiver: ```ruby Contributor.limit(2).order(:rank).to_xml @@ -2270,7 +2270,7 @@ Contributor.limit(2).order(:rank).to_xml # </contributors> ``` -To do so it sends +to_xml+ to every item in turn, and collects the results under a root node. All items must respond to +to_xml+, an exception is raised otherwise. +To do so it sends `to_xml` to every item in turn, and collects the results under a root node. All items must respond to `to_xml`, an exception is raised otherwise. By default, the name of the root element is the underscorized and dasherized plural of the name of the class of the first item, provided the rest of elements belong to that type (checked with `is_a?`) and they are not hashes. In the example above that's "contributors". @@ -2345,16 +2345,16 @@ Contributor.limit(2).order(:rank).to_xml(:skip_types => true) # </contributors> ``` -NOTE: Defined in +active_support/core_ext/array/conversions.rb+. +NOTE: Defined in `active_support/core_ext/array/conversions.rb`. ### Wrapping -The method +Array.wrap+ wraps its argument in an array unless it is already an array (or array-like). +The method `Array.wrap` wraps its argument in an array unless it is already an array (or array-like). Specifically: -* If the argument is +nil+ an empty list is returned. -* Otherwise, if the argument responds to +to_ary+ it is invoked, and if the value of +to_ary+ is not +nil+, it is returned. +* If the argument is `nil` an empty list is returned. +* Otherwise, if the argument responds to `to_ary` it is invoked, and if the value of `to_ary` is not `nil`, it is returned. * Otherwise, an array with the argument as its single element is returned. ```ruby @@ -2365,9 +2365,9 @@ Array.wrap(0) # => [0] This method is similar in purpose to `Kernel#Array`, but there are some differences: -* If the argument responds to +to_ary+ the method is invoked. `Kernel#Array` moves on to try +to_a+ if the returned value is +nil+, but `Array.wrap` returns +nil+ right away. -* If the returned value from +to_ary+ is neither +nil+ nor an +Array+ object, `Kernel#Array` raises an exception, while `Array.wrap` does not, it just returns the value. -* It does not call +to_a+ on the argument, though special-cases +nil+ to return an empty array. +* If the argument responds to `to_ary` the method is invoked. `Kernel#Array` moves on to try `to_a` if the returned value is `nil`, but `Array.wrap` returns `nil` right away. +* If the returned value from `to_ary` is neither `nil` nor an `Array` object, `Kernel#Array` raises an exception, while `Array.wrap` does not, it just returns the value. +* It does not call `to_a` on the argument, though special-cases `nil` to return an empty array. The last point is particularly worth comparing for some enumerables: @@ -2382,15 +2382,15 @@ There's also a related idiom that uses the splat operator: [*object] ``` -which in Ruby 1.8 returns +[nil]+ for +nil+, and calls to `Array(object)` otherwise. (Please if you know the exact behavior in 1.9 contact fxn.) +which in Ruby 1.8 returns `[nil]` for `nil`, and calls to `Array(object)` otherwise. (Please if you know the exact behavior in 1.9 contact fxn.) -Thus, in this case the behavior is different for +nil+, and the differences with `Kernel#Array` explained above apply to the rest of +object+s. +Thus, in this case the behavior is different for `nil`, and the differences with `Kernel#Array` explained above apply to the rest of `object`s. -NOTE: Defined in +active_support/core_ext/array/wrap.rb+. +NOTE: Defined in `active_support/core_ext/array/wrap.rb`. ### Duplicating -The method +Array.deep_dup+ duplicates itself and all objects inside recursively with ActiveSupport method +Object#deep_dup+. It works like +Array#map+ with sending +deep_dup+ method to each object inside. +The method `Array.deep_dup` duplicates itself and all objects inside recursively with ActiveSupport method `Object#deep_dup`. It works like `Array#map` with sending `deep_dup` method to each object inside. ```ruby array = [1, [2, 3]] @@ -2399,13 +2399,13 @@ dup[1][2] = 4 array[1][2] == nil # => true ``` -NOTE: Defined in +active_support/core_ext/array/deep_dup.rb+. +NOTE: Defined in `active_support/core_ext/array/deep_dup.rb`. ### Grouping -#### +in_groups_of(number, fill_with = nil)+ +#### `in_groups_of(number, fill_with = nil)` -The method +in_groups_of+ splits an array into consecutive groups of a certain size. It returns an array with the groups: +The method `in_groups_of` splits an array into consecutive groups of a certain size. It returns an array with the groups: ```ruby [1, 2, 3].in_groups_of(2) # => [[1, 2], [3, nil]] @@ -2423,25 +2423,25 @@ or yields them in turn if a block is passed: <% end %> ``` -The first example shows +in_groups_of+ fills the last group with as many +nil+ elements as needed to have the requested size. You can change this padding value using the second optional argument: +The first example shows `in_groups_of` fills the last group with as many `nil` elements as needed to have the requested size. You can change this padding value using the second optional argument: ```ruby [1, 2, 3].in_groups_of(2, 0) # => [[1, 2], [3, 0]] ``` -And you can tell the method not to fill the last group passing +false+: +And you can tell the method not to fill the last group passing `false`: ```ruby [1, 2, 3].in_groups_of(2, false) # => [[1, 2], [3]] ``` -As a consequence +false+ can't be a used as a padding value. +As a consequence `false` can't be a used as a padding value. -NOTE: Defined in +active_support/core_ext/array/grouping.rb+. +NOTE: Defined in `active_support/core_ext/array/grouping.rb`. -#### +in_groups(number, fill_with = nil)+ +#### `in_groups(number, fill_with = nil)` -The method +in_groups+ splits an array into a certain number of groups. The method returns an array with the groups: +The method `in_groups` splits an array into a certain number of groups. The method returns an array with the groups: ```ruby %w(1 2 3 4 5 6 7).in_groups(3) @@ -2457,7 +2457,7 @@ or yields them in turn if a block is passed: ["6", "7", nil] ``` -The examples above show that +in_groups+ fills some groups with a trailing +nil+ element as needed. A group can get at most one of these extra elements, the rightmost one if any. And the groups that have them are always the last ones. +The examples above show that `in_groups` fills some groups with a trailing `nil` element as needed. A group can get at most one of these extra elements, the rightmost one if any. And the groups that have them are always the last ones. You can change this padding value using the second optional argument: @@ -2466,20 +2466,20 @@ You can change this padding value using the second optional argument: # => [["1", "2", "3"], ["4", "5", "0"], ["6", "7", "0"]] ``` -And you can tell the method not to fill the smaller groups passing +false+: +And you can tell the method not to fill the smaller groups passing `false`: ```ruby %w(1 2 3 4 5 6 7).in_groups(3, false) # => [["1", "2", "3"], ["4", "5"], ["6", "7"]] ``` -As a consequence +false+ can't be a used as a padding value. +As a consequence `false` can't be a used as a padding value. -NOTE: Defined in +active_support/core_ext/array/grouping.rb+. +NOTE: Defined in `active_support/core_ext/array/grouping.rb`. -#### +split(value = nil)+ +#### `split(value = nil)` -The method +split+ divides an array by a separator and returns the resulting chunks. +The method `split` divides an array by a separator and returns the resulting chunks. If a block is passed the separators are those elements of the array for which the block returns true: @@ -2488,7 +2488,7 @@ If a block is passed the separators are those elements of the array for which th # => [[-5], [-3, -2, -1], [1, 2, 3], [5]] ``` -Otherwise, the value received as argument, which defaults to +nil+, is the separator: +Otherwise, the value received as argument, which defaults to `nil`, is the separator: ```ruby [0, 1, -5, 1, 1, "foo", "bar"].split(1) @@ -2497,16 +2497,16 @@ Otherwise, the value received as argument, which defaults to +nil+, is the separ TIP: Observe in the previous example that consecutive separators result in empty arrays. -NOTE: Defined in +active_support/core_ext/array/grouping.rb+. +NOTE: Defined in `active_support/core_ext/array/grouping.rb`. -Extensions to +Hash+ +Extensions to `Hash` -------------------- ### Conversions -#### +to_xml+ +#### `to_xml` -The method +to_xml+ returns a string containing an XML representation of its receiver: +The method `to_xml` returns a string containing an XML representation of its receiver: ```ruby {"foo" => 1, "bar" => 2}.to_xml @@ -2518,17 +2518,17 @@ The method +to_xml+ returns a string containing an XML representation of its rec # </hash> ``` -To do so, the method loops over the pairs and builds nodes that depend on the _values_. Given a pair +key+, +value+: +To do so, the method loops over the pairs and builds nodes that depend on the _values_. Given a pair `key`, `value`: -* If +value+ is a hash there's a recursive call with +key+ as `:root`. +* If `value` is a hash there's a recursive call with `key` as `:root`. -* If +value+ is an array there's a recursive call with +key+ as `:root`, and +key+ singularized as `:children`. +* If `value` is an array there's a recursive call with `key` as `:root`, and `key` singularized as `:children`. -* If +value+ is a callable object it must expect one or two arguments. Depending on the arity, the callable is invoked with the +options+ hash as first argument with +key+ as `:root`, and +key+ singularized as second argument. Its return value becomes a new node. +* If `value` is a callable object it must expect one or two arguments. Depending on the arity, the callable is invoked with the `options` hash as first argument with `key` as `:root`, and `key` singularized as second argument. Its return value becomes a new node. -* If +value+ responds to +to_xml+ the method is invoked with +key+ as `:root`. +* If `value` responds to `to_xml` the method is invoked with `key` as `:root`. -* Otherwise, a node with +key+ as tag is created with a string representation of +value+ as text node. If +value+ is +nil+ an attribute "nil" set to "true" is added. Unless the option `:skip_types` exists and is true, an attribute "type" is added as well according to the following mapping: +* Otherwise, a node with `key` as tag is created with a string representation of `value` as text node. If `value` is `nil` an attribute "nil" set to "true" is added. Unless the option `:skip_types` exists and is true, an attribute "type" is added as well according to the following mapping: ```ruby XML_TYPE_NAMES = { @@ -2549,11 +2549,11 @@ By default the root node is "hash", but that's configurable via the `:root` opti The default XML builder is a fresh instance of `Builder::XmlMarkup`. You can configure your own builder with the `:builder` option. The method also accepts options like `:dasherize` and friends, they are forwarded to the builder. -NOTE: Defined in +active_support/core_ext/hash/conversions.rb+. +NOTE: Defined in `active_support/core_ext/hash/conversions.rb`. ### Merging -Ruby has a built-in method +Hash#merge+ that merges two hashes: +Ruby has a built-in method `Hash#merge` that merges two hashes: ```ruby {:a => 1, :b => 1}.merge(:a => 0, :c => 2) @@ -2562,56 +2562,56 @@ Ruby has a built-in method +Hash#merge+ that merges two hashes: Active Support defines a few more ways of merging hashes that may be convenient. -#### +reverse_merge+ and +reverse_merge!+ +#### `reverse_merge` and `reverse_merge!` -In case of collision the key in the hash of the argument wins in +merge+. You can support option hashes with default values in a compact way with this idiom: +In case of collision the key in the hash of the argument wins in `merge`. You can support option hashes with default values in a compact way with this idiom: ```ruby options = {:length => 30, :omission => "..."}.merge(options) ``` -Active Support defines +reverse_merge+ in case you prefer this alternative notation: +Active Support defines `reverse_merge` in case you prefer this alternative notation: ```ruby options = options.reverse_merge(:length => 30, :omission => "...") ``` -And a bang version +reverse_merge!+ that performs the merge in place: +And a bang version `reverse_merge!` that performs the merge in place: ```ruby options.reverse_merge!(:length => 30, :omission => "...") ``` -WARNING. Take into account that +reverse_merge!+ may change the hash in the caller, which may or may not be a good idea. +WARNING. Take into account that `reverse_merge!` may change the hash in the caller, which may or may not be a good idea. -NOTE: Defined in +active_support/core_ext/hash/reverse_merge.rb+. +NOTE: Defined in `active_support/core_ext/hash/reverse_merge.rb`. -#### +reverse_update+ +#### `reverse_update` -The method +reverse_update+ is an alias for +reverse_merge!+, explained above. +The method `reverse_update` is an alias for `reverse_merge!`, explained above. -WARNING. Note that +reverse_update+ has no bang. +WARNING. Note that `reverse_update` has no bang. -NOTE: Defined in +active_support/core_ext/hash/reverse_merge.rb+. +NOTE: Defined in `active_support/core_ext/hash/reverse_merge.rb`. -#### +deep_merge+ and +deep_merge!+ +#### `deep_merge` and `deep_merge!` As you can see in the previous example if a key is found in both hashes the value in the one in the argument wins. -Active Support defines +Hash#deep_merge+. In a deep merge, if a key is found in both hashes and their values are hashes in turn, then their _merge_ becomes the value in the resulting hash: +Active Support defines `Hash#deep_merge`. In a deep merge, if a key is found in both hashes and their values are hashes in turn, then their _merge_ becomes the value in the resulting hash: ```ruby {:a => {:b => 1}}.deep_merge(:a => {:c => 2}) # => {:a => {:b => 1, :c => 2}} ``` -The method +deep_merge!+ performs a deep merge in place. +The method `deep_merge!` performs a deep merge in place. -NOTE: Defined in +active_support/core_ext/hash/deep_merge.rb+. +NOTE: Defined in `active_support/core_ext/hash/deep_merge.rb`. ### Deep duplicating -The method +Hash.deep_dup+ duplicates itself and all keys and values inside recursively with ActiveSupport method +Object#deep_dup+. It works like +Enumerator#each_with_object+ with sending +deep_dup+ method to each pair inside. +The method `Hash.deep_dup` duplicates itself and all keys and values inside recursively with ActiveSupport method `Object#deep_dup`. It works like `Enumerator#each_with_object` with sending `deep_dup` method to each pair inside. ```ruby hash = { :a => 1, :b => { :c => 2, :d => [3, 4] } } @@ -2624,15 +2624,15 @@ hash[:b][:e] == nil # => true hash[:b][:d] == [3, 4] # => true ``` -NOTE: Defined in +active_support/core_ext/hash/deep_dup.rb+. +NOTE: Defined in `active_support/core_ext/hash/deep_dup.rb`. ### Diffing -The method +diff+ returns a hash that represents a diff of the receiver and the argument with the following logic: +The method `diff` returns a hash that represents a diff of the receiver and the argument with the following logic: -* Pairs +key+, +value+ that exist in both hashes do not belong to the diff hash. +* Pairs `key`, `value` that exist in both hashes do not belong to the diff hash. -* If both hashes have +key+, but with different values, the pair in the receiver wins. +* If both hashes have `key`, but with different values, the pair in the receiver wins. * The rest is just merged. @@ -2654,7 +2654,7 @@ The method +diff+ returns a hash that represents a diff of the receiver and the {}.diff(:a => 1) # => {:a => 1} ``` -An important property of this diff hash is that you can retrieve the original hash by applying +diff+ twice: +An important property of this diff hash is that you can retrieve the original hash by applying `diff` twice: ```ruby hash.diff(hash2).diff(hash2) == hash @@ -2662,39 +2662,39 @@ hash.diff(hash2).diff(hash2) == hash Diffing hashes may be useful for error messages related to expected option hashes for example. -NOTE: Defined in +active_support/core_ext/hash/diff.rb+. +NOTE: Defined in `active_support/core_ext/hash/diff.rb`. ### Working with Keys -#### +except+ and +except!+ +#### `except` and `except!` -The method +except+ returns a hash with the keys in the argument list removed, if present: +The method `except` returns a hash with the keys in the argument list removed, if present: ```ruby {:a => 1, :b => 2}.except(:a) # => {:b => 2} ``` -If the receiver responds to +convert_key+, the method is called on each of the arguments. This allows +except+ to play nice with hashes with indifferent access for instance: +If the receiver responds to `convert_key`, the method is called on each of the arguments. This allows `except` to play nice with hashes with indifferent access for instance: ```ruby {:a => 1}.with_indifferent_access.except(:a) # => {} {:a => 1}.with_indifferent_access.except("a") # => {} ``` -The method +except+ may come in handy for example when you want to protect some parameter that can't be globally protected with +attr_protected+: +The method `except` may come in handy for example when you want to protect some parameter that can't be globally protected with `attr_protected`: ```ruby params[:account] = params[:account].except(:plan_id) unless admin? @account.update_attributes(params[:account]) ``` -There's also the bang variant +except!+ that removes keys in the very receiver. +There's also the bang variant `except!` that removes keys in the very receiver. -NOTE: Defined in +active_support/core_ext/hash/except.rb+. +NOTE: Defined in `active_support/core_ext/hash/except.rb`. -#### +transform_keys+ and +transform_keys!+ +#### `transform_keys` and `transform_keys!` -The method +transform_keys+ accepts a block and returns a hash that has applied the block operations to each of the keys in the receiver: +The method `transform_keys` accepts a block and returns a hash that has applied the block operations to each of the keys in the receiver: ```ruby {nil => nil, 1 => 1, :a => :a}.transform_keys{ |key| key.to_s.upcase } @@ -2708,7 +2708,7 @@ The result in case of collision is undefined: # => {"A" => 2}, in my test, can't rely on this result though ``` -This method may be useful for example to build specialized conversions. For instance +stringify_keys+ and +symbolize_keys+ use +transform_keys+ to perform their key conversions: +This method may be useful for example to build specialized conversions. For instance `stringify_keys` and `symbolize_keys` use `transform_keys` to perform their key conversions: ```ruby def stringify_keys @@ -2720,20 +2720,20 @@ def symbolize_keys end ``` -There's also the bang variant +transform_keys!+ that applies the block operations to keys in the very receiver. +There's also the bang variant `transform_keys!` that applies the block operations to keys in the very receiver. -Besides that, one can use +deep_transform_keys+ and +deep_transform_keys!+ to perform the block operation on all the keys in the given hash and all the hashes nested into it. An example of the result is: +Besides that, one can use `deep_transform_keys` and `deep_transform_keys!` to perform the block operation on all the keys in the given hash and all the hashes nested into it. An example of the result is: ```ruby {nil => nil, 1 => 1, :nested => {:a => 3, 5 => 5}}.deep_transform_keys{ |key| key.to_s.upcase } # => {""=>nil, "1"=>1, "NESTED"=>{"A"=>3, "5"=>5}} ``` -NOTE: Defined in +active_support/core_ext/hash/keys.rb+. +NOTE: Defined in `active_support/core_ext/hash/keys.rb`. -#### +stringify_keys+ and +stringify_keys!+ +#### `stringify_keys` and `stringify_keys!` -The method +stringify_keys+ returns a hash that has a stringified version of the keys in the receiver. It does so by sending +to_s+ to them: +The method `stringify_keys` returns a hash that has a stringified version of the keys in the receiver. It does so by sending `to_s` to them: ```ruby {nil => nil, 1 => 1, :a => :a}.stringify_keys @@ -2747,7 +2747,7 @@ The result in case of collision is undefined: # => {"a" => 2}, in my test, can't rely on this result though ``` -This method may be useful for example to easily accept both symbols and strings as options. For instance +ActionView::Helpers::FormHelper+ defines: +This method may be useful for example to easily accept both symbols and strings as options. For instance `ActionView::Helpers::FormHelper` defines: ```ruby def to_check_box_tag(options = {}, checked_value = "1", unchecked_value = "0") @@ -2757,22 +2757,22 @@ def to_check_box_tag(options = {}, checked_value = "1", unchecked_value = "0") end ``` -The second line can safely access the "type" key, and let the user to pass either +:type+ or "type". +The second line can safely access the "type" key, and let the user to pass either `:type` or "type". -There's also the bang variant +stringify_keys!+ that stringifies keys in the very receiver. +There's also the bang variant `stringify_keys!` that stringifies keys in the very receiver. -Besides that, one can use +deep_stringify_keys+ and +deep_stringify_keys!+ to stringify all the keys in the given hash and all the hashes nested into it. An example of the result is: +Besides that, one can use `deep_stringify_keys` and `deep_stringify_keys!` to stringify all the keys in the given hash and all the hashes nested into it. An example of the result is: ```ruby {nil => nil, 1 => 1, :nested => {:a => 3, 5 => 5}}.deep_stringify_keys # => {""=>nil, "1"=>1, "nested"=>{"a"=>3, "5"=>5}} ``` -NOTE: Defined in +active_support/core_ext/hash/keys.rb+. +NOTE: Defined in `active_support/core_ext/hash/keys.rb`. -#### +symbolize_keys+ and +symbolize_keys!+ +#### `symbolize_keys` and `symbolize_keys!` -The method +symbolize_keys+ returns a hash that has a symbolized version of the keys in the receiver, where possible. It does so by sending +to_sym+ to them: +The method `symbolize_keys` returns a hash that has a symbolized version of the keys in the receiver, where possible. It does so by sending `to_sym` to them: ```ruby {nil => nil, 1 => 1, "a" => "a"}.symbolize_keys @@ -2788,7 +2788,7 @@ The result in case of collision is undefined: # => {:a => 2}, in my test, can't rely on this result though ``` -This method may be useful for example to easily accept both symbols and strings as options. For instance +ActionController::UrlRewriter+ defines +This method may be useful for example to easily accept both symbols and strings as options. For instance `ActionController::UrlRewriter` defines ```ruby def rewrite_path(options) @@ -2798,37 +2798,37 @@ def rewrite_path(options) end ``` -The second line can safely access the +:params+ key, and let the user to pass either +:params+ or "params". +The second line can safely access the `:params` key, and let the user to pass either `:params` or "params". -There's also the bang variant +symbolize_keys!+ that symbolizes keys in the very receiver. +There's also the bang variant `symbolize_keys!` that symbolizes keys in the very receiver. -Besides that, one can use +deep_symbolize_keys+ and +deep_symbolize_keys!+ to symbolize all the keys in the given hash and all the hashes nested into it. An example of the result is: +Besides that, one can use `deep_symbolize_keys` and `deep_symbolize_keys!` to symbolize all the keys in the given hash and all the hashes nested into it. An example of the result is: ```ruby {nil => nil, 1 => 1, "nested" => {"a" => 3, 5 => 5}}.deep_symbolize_keys # => {nil=>nil, 1=>1, :nested=>{:a=>3, 5=>5}} ``` -NOTE: Defined in +active_support/core_ext/hash/keys.rb+. +NOTE: Defined in `active_support/core_ext/hash/keys.rb`. -#### +to_options+ and +to_options!+ +#### `to_options` and `to_options!` -The methods +to_options+ and +to_options!+ are respectively aliases of +symbolize_keys+ and +symbolize_keys!+. +The methods `to_options` and `to_options!` are respectively aliases of `symbolize_keys` and `symbolize_keys!`. -NOTE: Defined in +active_support/core_ext/hash/keys.rb+. +NOTE: Defined in `active_support/core_ext/hash/keys.rb`. -#### +assert_valid_keys+ +#### `assert_valid_keys` -The method +assert_valid_keys+ receives an arbitrary number of arguments, and checks whether the receiver has any key outside that white list. If it does +ArgumentError+ is raised. +The method `assert_valid_keys` receives an arbitrary number of arguments, and checks whether the receiver has any key outside that white list. If it does `ArgumentError` is raised. ```ruby {:a => 1}.assert_valid_keys(:a) # passes {:a => 1}.assert_valid_keys("a") # ArgumentError ``` -Active Record does not accept unknown options when building associations, for example. It implements that control via +assert_valid_keys+. +Active Record does not accept unknown options when building associations, for example. It implements that control via `assert_valid_keys`. -NOTE: Defined in +active_support/core_ext/hash/keys.rb+. +NOTE: Defined in `active_support/core_ext/hash/keys.rb`. ### Slicing @@ -2842,7 +2842,7 @@ Ruby has built-in support for taking slices out of strings and arrays. Active Su # => {:b => 2} # non-existing keys are ignored ``` -If the receiver responds to +convert_key+ keys are normalized: +If the receiver responds to `convert_key` keys are normalized: ```ruby {:a => 1, :b => 2}.with_indifferent_access.slice("a") @@ -2851,7 +2851,7 @@ If the receiver responds to +convert_key+ keys are normalized: NOTE. Slicing may come in handy for sanitizing option hashes with a white list of keys. -There's also +slice!+ which in addition to perform a slice in place returns what's removed: +There's also `slice!` which in addition to perform a slice in place returns what's removed: ```ruby hash = {:a => 1, :b => 2} @@ -2859,11 +2859,11 @@ rest = hash.slice!(:a) # => {:b => 2} hash # => {:a => 1} ``` -NOTE: Defined in +active_support/core_ext/hash/slice.rb+. +NOTE: Defined in `active_support/core_ext/hash/slice.rb`. ### Extracting -The method +extract!+ removes and returns the key/value pairs matching the given keys. +The method `extract!` removes and returns the key/value pairs matching the given keys. ```ruby hash = {:a => 1, :b => 2} @@ -2871,24 +2871,24 @@ rest = hash.extract!(:a) # => {:a => 1} hash # => {:b => 2} ``` -NOTE: Defined in +active_support/core_ext/hash/slice.rb+. +NOTE: Defined in `active_support/core_ext/hash/slice.rb`. ### Indifferent Access -The method +with_indifferent_access+ returns an +ActiveSupport::HashWithIndifferentAccess+ out of its receiver: +The method `with_indifferent_access` returns an `ActiveSupport::HashWithIndifferentAccess` out of its receiver: ```ruby {:a => 1}.with_indifferent_access["a"] # => 1 ``` -NOTE: Defined in +active_support/core_ext/hash/indifferent_access.rb+. +NOTE: Defined in `active_support/core_ext/hash/indifferent_access.rb`. -Extensions to +Regexp+ +Extensions to `Regexp` ---------------------- -### +multiline?+ +### `multiline?` -The method +multiline?+ says whether a regexp has the +/m+ flag set, that is, whether the dot matches newlines. +The method `multiline?` says whether a regexp has the `/m` flag set, that is, whether the dot matches newlines. ```ruby %r{.}.multiline? # => false @@ -2910,14 +2910,14 @@ def assign_route_options(segments, defaults, requirements) end ``` -NOTE: Defined in +active_support/core_ext/regexp.rb+. +NOTE: Defined in `active_support/core_ext/regexp.rb`. -Extensions to +Range+ +Extensions to `Range` --------------------- -### +to_s+ +### `to_s` -Active Support extends the method +Range#to_s+ so that it understands an optional format argument. As of this writing the only supported non-default format is +:db+: +Active Support extends the method `Range#to_s` so that it understands an optional format argument. As of this writing the only supported non-default format is `:db`: ```ruby (Date.today..Date.tomorrow).to_s @@ -2927,13 +2927,13 @@ Active Support extends the method +Range#to_s+ so that it understands an optiona # => "BETWEEN '2009-10-25' AND '2009-10-26'" ``` -As the example depicts, the +:db+ format generates a +BETWEEN+ SQL clause. That is used by Active Record in its support for range values in conditions. +As the example depicts, the `:db` format generates a `BETWEEN` SQL clause. That is used by Active Record in its support for range values in conditions. -NOTE: Defined in +active_support/core_ext/range/conversions.rb+. +NOTE: Defined in `active_support/core_ext/range/conversions.rb`. -### +include?+ +### `include?` -The methods +Range#include?+ and +Range#===+ say whether some value falls between the ends of a given instance: +The methods `Range#include?` and `Range#===` say whether some value falls between the ends of a given instance: ```ruby (2..3).include?(Math::E) # => true @@ -2953,11 +2953,11 @@ Active Support extends these methods so that the argument may be another range i (1...9) === (3..9) # => false ``` -NOTE: Defined in +active_support/core_ext/range/include_range.rb+. +NOTE: Defined in `active_support/core_ext/range/include_range.rb`. -### +overlaps?+ +### `overlaps?` -The method +Range#overlaps?+ says whether any two given ranges have non-void intersection: +The method `Range#overlaps?` says whether any two given ranges have non-void intersection: ```ruby (1..10).overlaps?(7..11) # => true @@ -2965,37 +2965,37 @@ The method +Range#overlaps?+ says whether any two given ranges have non-void int (1..10).overlaps?(11..27) # => false ``` -NOTE: Defined in +active_support/core_ext/range/overlaps.rb+. +NOTE: Defined in `active_support/core_ext/range/overlaps.rb`. -Extensions to +Proc+ +Extensions to `Proc` -------------------- -### +bind+ +### `bind` -As you surely know Ruby has an +UnboundMethod+ class whose instances are methods that belong to the limbo of methods without a self. The method +Module#instance_method+ returns an unbound method for example: +As you surely know Ruby has an `UnboundMethod` class whose instances are methods that belong to the limbo of methods without a self. The method `Module#instance_method` returns an unbound method for example: ```ruby Hash.instance_method(:delete) # => #<UnboundMethod: Hash#delete> ``` -An unbound method is not callable as is, you need to bind it first to an object with +bind+: +An unbound method is not callable as is, you need to bind it first to an object with `bind`: ```ruby clear = Hash.instance_method(:clear) clear.bind({:a => 1}).call # => {} ``` -Active Support defines +Proc#bind+ with an analogous purpose: +Active Support defines `Proc#bind` with an analogous purpose: ```ruby Proc.new { size }.bind([]).call # => 0 ``` -As you see that's callable and bound to the argument, the return value is indeed a +Method+. +As you see that's callable and bound to the argument, the return value is indeed a `Method`. -NOTE: To do so +Proc#bind+ actually creates a method under the hood. If you ever see a method with a weird name like +__bind_1256598120_237302+ in a stack trace you know now where it comes from. +NOTE: To do so `Proc#bind` actually creates a method under the hood. If you ever see a method with a weird name like `__bind_1256598120_237302` in a stack trace you know now where it comes from. -Action Pack uses this trick in +rescue_from+ for example, which accepts the name of a method and also a proc as callbacks for a given rescued exception. It has to call them in either case, so a bound method is returned by +handler_for_rescue+, thus simplifying the code in the caller: +Action Pack uses this trick in `rescue_from` for example, which accepts the name of a method and also a proc as callbacks for a given rescued exception. It has to call them in either case, so a bound method is returned by `handler_for_rescue`, thus simplifying the code in the caller: ```ruby def handler_for_rescue(exception) @@ -3012,28 +3012,28 @@ def handler_for_rescue(exception) end ``` -NOTE: Defined in +active_support/core_ext/proc.rb+. +NOTE: Defined in `active_support/core_ext/proc.rb`. -Extensions to +Date+ +Extensions to `Date` -------------------- ### Calculations -NOTE: All the following methods are defined in +active_support/core_ext/date/calculations.rb+. +NOTE: All the following methods are defined in `active_support/core_ext/date/calculations.rb`. -INFO: The following calculation methods have edge cases in October 1582, since days 5..14 just do not exist. This guide does not document their behavior around those days for brevity, but it is enough to say that they do what you would expect. That is, +Date.new(1582, 10, 4).tomorrow+ returns +Date.new(1582, 10, 15)+ and so on. Please check +test/core_ext/date_ext_test.rb+ in the Active Support test suite for expected behavior. +INFO: The following calculation methods have edge cases in October 1582, since days 5..14 just do not exist. This guide does not document their behavior around those days for brevity, but it is enough to say that they do what you would expect. That is, `Date.new(1582, 10, 4).tomorrow` returns `Date.new(1582, 10, 15)` and so on. Please check `test/core_ext/date_ext_test.rb` in the Active Support test suite for expected behavior. -#### +Date.current+ +#### `Date.current` -Active Support defines +Date.current+ to be today in the current time zone. That's like +Date.today+, except that it honors the user time zone, if defined. It also defines +Date.yesterday+ and +Date.tomorrow+, and the instance predicates +past?+, +today?+, and +future?+, all of them relative to +Date.current+. +Active Support defines `Date.current` to be today in the current time zone. That's like `Date.today`, except that it honors the user time zone, if defined. It also defines `Date.yesterday` and `Date.tomorrow`, and the instance predicates `past?`, `today?`, and `future?`, all of them relative to `Date.current`. -When making Date comparisons using methods which honor the user time zone, make sure to use +Date.current+ and not +Date.today+. There are cases where the user time zone might be in the future compared to the system time zone, which +Date.today+ uses by default. This means +Date.today+ may equal +Date.yesterday+. +When making Date comparisons using methods which honor the user time zone, make sure to use `Date.current` and not `Date.today`. There are cases where the user time zone might be in the future compared to the system time zone, which `Date.today` uses by default. This means `Date.today` may equal `Date.yesterday`. #### Named dates -##### +prev_year+, +next_year+ +##### `prev_year`, `next_year` -In Ruby 1.9 +prev_year+ and +next_year+ return a date with the same day/month in the last or next year: +In Ruby 1.9 `prev_year` and `next_year` return a date with the same day/month in the last or next year: ```ruby d = Date.new(2010, 5, 8) # => Sat, 08 May 2010 @@ -3049,11 +3049,11 @@ d.prev_year # => Sun, 28 Feb 1999 d.next_year # => Wed, 28 Feb 2001 ``` -+prev_year+ is aliased to +last_year+. +`prev_year` is aliased to `last_year`. -##### +prev_month+, +next_month+ +##### `prev_month`, `next_month` -In Ruby 1.9 +prev_month+ and +next_month+ return the date with the same day in the last or next month: +In Ruby 1.9 `prev_month` and `next_month` return the date with the same day in the last or next month: ```ruby d = Date.new(2010, 5, 8) # => Sat, 08 May 2010 @@ -3070,11 +3070,11 @@ Date.new(2000, 5, 31).next_month # => Fri, 30 Jun 2000 Date.new(2000, 1, 31).next_month # => Tue, 29 Feb 2000 ``` -+prev_month+ is aliased to +last_month+. +`prev_month` is aliased to `last_month`. -##### +prev_quarter+, +next_quarter+ +##### `prev_quarter`, `next_quarter` -Same as +prev_month+ and +next_month+. It returns the date with the same day in the previous or next quarter: +Same as `prev_month` and `next_month`. It returns the date with the same day in the previous or next quarter: ```ruby t = Time.local(2010, 5, 8) # => Sat, 08 May 2010 @@ -3091,11 +3091,11 @@ Time.local(2000, 10, 31).prev_quarter # => Mon, 30 Oct 2000 Time.local(2000, 11, 31).next_quarter # => Wed, 28 Feb 2001 ``` -+prev_quarter+ is aliased to +last_quarter+. +`prev_quarter` is aliased to `last_quarter`. -##### +beginning_of_week+, +end_of_week+ +##### `beginning_of_week`, `end_of_week` -The methods +beginning_of_week+ and +end_of_week+ return the dates for the +The methods `beginning_of_week` and `end_of_week` return the dates for the beginning and end of the week, respectively. Weeks are assumed to start on Monday, but that can be changed passing an argument. @@ -3107,11 +3107,11 @@ d.end_of_week # => Sun, 09 May 2010 d.end_of_week(:sunday) # => Sat, 08 May 2010 ``` -+beginning_of_week+ is aliased to +at_beginning_of_week+ and +end_of_week+ is aliased to +at_end_of_week+. +`beginning_of_week` is aliased to `at_beginning_of_week` and `end_of_week` is aliased to `at_end_of_week`. -##### +monday+, +sunday+ +##### `monday`, `sunday` -The methods +monday+ and +sunday+ return the dates for the beginning and +The methods `monday` and `sunday` return the dates for the beginning and end of the week, respectively. Weeks are assumed to start on Monday. ```ruby @@ -3120,9 +3120,9 @@ d.monday # => Mon, 03 May 2010 d.sunday # => Sun, 09 May 2010 ``` -##### +prev_week+, +next_week+ +##### `prev_week`, `next_week` -The method +next_week+ receives a symbol with a day name in English (in lowercase, default is +:monday+) and it returns the date corresponding to that day: +The method `next_week` receives a symbol with a day name in English (in lowercase, default is `:monday`) and it returns the date corresponding to that day: ```ruby d = Date.new(2010, 5, 9) # => Sun, 09 May 2010 @@ -3130,7 +3130,7 @@ d.next_week # => Mon, 10 May 2010 d.next_week(:saturday) # => Sat, 15 May 2010 ``` -The method +prev_week+ is analogous: +The method `prev_week` is analogous: ```ruby d.prev_week # => Mon, 26 Apr 2010 @@ -3138,11 +3138,11 @@ d.prev_week(:saturday) # => Sat, 01 May 2010 d.prev_week(:friday) # => Fri, 30 Apr 2010 ``` -+prev_week+ is aliased to +last_week+. +`prev_week` is aliased to `last_week`. -##### +beginning_of_month+, +end_of_month+ +##### `beginning_of_month`, `end_of_month` -The methods +beginning_of_month+ and +end_of_month+ return the dates for the beginning and end of the month: +The methods `beginning_of_month` and `end_of_month` return the dates for the beginning and end of the month: ```ruby d = Date.new(2010, 5, 9) # => Sun, 09 May 2010 @@ -3150,11 +3150,11 @@ d.beginning_of_month # => Sat, 01 May 2010 d.end_of_month # => Mon, 31 May 2010 ``` -+beginning_of_month+ is aliased to +at_beginning_of_month+, and +end_of_month+ is aliased to +at_end_of_month+. +`beginning_of_month` is aliased to `at_beginning_of_month`, and `end_of_month` is aliased to `at_end_of_month`. -##### +beginning_of_quarter+, +end_of_quarter+ +##### `beginning_of_quarter`, `end_of_quarter` -The methods +beginning_of_quarter+ and +end_of_quarter+ return the dates for the beginning and end of the quarter of the receiver's calendar year: +The methods `beginning_of_quarter` and `end_of_quarter` return the dates for the beginning and end of the quarter of the receiver's calendar year: ```ruby d = Date.new(2010, 5, 9) # => Sun, 09 May 2010 @@ -3162,11 +3162,11 @@ d.beginning_of_quarter # => Thu, 01 Apr 2010 d.end_of_quarter # => Wed, 30 Jun 2010 ``` -+beginning_of_quarter+ is aliased to +at_beginning_of_quarter+, and +end_of_quarter+ is aliased to +at_end_of_quarter+. +`beginning_of_quarter` is aliased to `at_beginning_of_quarter`, and `end_of_quarter` is aliased to `at_end_of_quarter`. -##### +beginning_of_year+, +end_of_year+ +##### `beginning_of_year`, `end_of_year` -The methods +beginning_of_year+ and +end_of_year+ return the dates for the beginning and end of the year: +The methods `beginning_of_year` and `end_of_year` return the dates for the beginning and end of the year: ```ruby d = Date.new(2010, 5, 9) # => Sun, 09 May 2010 @@ -3174,20 +3174,20 @@ d.beginning_of_year # => Fri, 01 Jan 2010 d.end_of_year # => Fri, 31 Dec 2010 ``` -+beginning_of_year+ is aliased to +at_beginning_of_year+, and +end_of_year+ is aliased to +at_end_of_year+. +`beginning_of_year` is aliased to `at_beginning_of_year`, and `end_of_year` is aliased to `at_end_of_year`. #### Other Date Computations -##### +years_ago+, +years_since+ +##### `years_ago`, `years_since` -The method +years_ago+ receives a number of years and returns the same date those many years ago: +The method `years_ago` receives a number of years and returns the same date those many years ago: ```ruby date = Date.new(2010, 6, 7) date.years_ago(10) # => Wed, 07 Jun 2000 ``` -+years_since+ moves forward in time: +`years_since` moves forward in time: ```ruby date = Date.new(2010, 6, 7) @@ -3201,9 +3201,9 @@ Date.new(2012, 2, 29).years_ago(3) # => Sat, 28 Feb 2009 Date.new(2012, 2, 29).years_since(3) # => Sat, 28 Feb 2015 ``` -##### +months_ago+, +months_since+ +##### `months_ago`, `months_since` -The methods +months_ago+ and +months_since+ work analogously for months: +The methods `months_ago` and `months_since` work analogously for months: ```ruby Date.new(2010, 4, 30).months_ago(2) # => Sun, 28 Feb 2010 @@ -3217,18 +3217,18 @@ Date.new(2010, 4, 30).months_ago(2) # => Sun, 28 Feb 2010 Date.new(2009, 12, 31).months_since(2) # => Sun, 28 Feb 2010 ``` -##### +weeks_ago+ +##### `weeks_ago` -The method +weeks_ago+ works analogously for weeks: +The method `weeks_ago` works analogously for weeks: ```ruby Date.new(2010, 5, 24).weeks_ago(1) # => Mon, 17 May 2010 Date.new(2010, 5, 24).weeks_ago(2) # => Mon, 10 May 2010 ``` -##### +advance+ +##### `advance` -The most generic way to jump to other days is +advance+. This method receives a hash with keys +:years+, +:months+, +:weeks+, +:days+, and returns a date advanced as much as the present keys indicate: +The most generic way to jump to other days is `advance`. This method receives a hash with keys `:years`, `:months`, `:weeks`, `:days`, and returns a date advanced as much as the present keys indicate: ```ruby date = Date.new(2010, 6, 6) @@ -3240,7 +3240,7 @@ Note in the previous example that increments may be negative. To perform the computation the method first increments years, then months, then weeks, and finally days. This order is important towards the end of months. Say for example we are at the end of February of 2010, and we want to move one month and one day forward. -The method +advance+ advances first one month, and then one day, the result is: +The method `advance` advances first one month, and then one day, the result is: ```ruby Date.new(2010, 2, 28).advance(:months => 1, :days => 1) @@ -3256,14 +3256,14 @@ Date.new(2010, 2, 28).advance(:days => 1).advance(:months => 1) #### Changing Components -The method +change+ allows you to get a new date which is the same as the receiver except for the given year, month, or day: +The method `change` allows you to get a new date which is the same as the receiver except for the given year, month, or day: ```ruby Date.new(2010, 12, 23).change(:year => 2011, :month => 11) # => Wed, 23 Nov 2011 ``` -This method is not tolerant to non-existing dates, if the change is invalid +ArgumentError+ is raised: +This method is not tolerant to non-existing dates, if the change is invalid `ArgumentError` is raised: ```ruby Date.new(2010, 1, 31).change(:month => 2) @@ -3283,7 +3283,7 @@ d - 3.hours # => Sun, 08 Aug 2010 21:00:00 UTC +00:00 ``` -They translate to calls to +since+ or +advance+. For example here we get the correct jump in the calendar reform: +They translate to calls to `since` or `advance`. For example here we get the correct jump in the calendar reform: ```ruby Date.new(1582, 10, 4) + 1.day @@ -3292,56 +3292,56 @@ Date.new(1582, 10, 4) + 1.day #### Timestamps -INFO: The following methods return a +Time+ object if possible, otherwise a +DateTime+. If set, they honor the user time zone. +INFO: The following methods return a `Time` object if possible, otherwise a `DateTime`. If set, they honor the user time zone. -##### +beginning_of_day+, +end_of_day+ +##### `beginning_of_day`, `end_of_day` -The method +beginning_of_day+ returns a timestamp at the beginning of the day (00:00:00): +The method `beginning_of_day` returns a timestamp at the beginning of the day (00:00:00): ```ruby date = Date.new(2010, 6, 7) date.beginning_of_day # => Mon Jun 07 00:00:00 +0200 2010 ``` -The method +end_of_day+ returns a timestamp at the end of the day (23:59:59): +The method `end_of_day` returns a timestamp at the end of the day (23:59:59): ```ruby date = Date.new(2010, 6, 7) date.end_of_day # => Mon Jun 07 23:59:59 +0200 2010 ``` -+beginning_of_day+ is aliased to +at_beginning_of_day+, +midnight+, +at_midnight+. +`beginning_of_day` is aliased to `at_beginning_of_day`, `midnight`, `at_midnight`. -##### +beginning_of_hour+, +end_of_hour+ +##### `beginning_of_hour`, `end_of_hour` -The method +beginning_of_hour+ returns a timestamp at the beginning of the hour (hh:00:00): +The method `beginning_of_hour` returns a timestamp at the beginning of the hour (hh:00:00): ```ruby date = DateTime.new(2010, 6, 7, 19, 55, 25) date.beginning_of_hour # => Mon Jun 07 19:00:00 +0200 2010 ``` -The method +end_of_hour+ returns a timestamp at the end of the hour (hh:59:59): +The method `end_of_hour` returns a timestamp at the end of the hour (hh:59:59): ```ruby date = DateTime.new(2010, 6, 7, 19, 55, 25) date.end_of_hour # => Mon Jun 07 19:59:59 +0200 2010 ``` -+beginning_of_hour+ is aliased to +at_beginning_of_hour+. +`beginning_of_hour` is aliased to `at_beginning_of_hour`. -INFO: +beginning_of_hour+ and +end_of_hour+ are implemented for +Time+ and +DateTime+ but *not* +Date+ as it does not make sense to request the beginning or end of an hour on a +Date+ instance. +INFO: `beginning_of_hour` and `end_of_hour` are implemented for `Time` and `DateTime` but *not* `Date` as it does not make sense to request the beginning or end of an hour on a `Date` instance. -##### +ago+, +since+ +##### `ago`, `since` -The method +ago+ receives a number of seconds as argument and returns a timestamp those many seconds ago from midnight: +The method `ago` receives a number of seconds as argument and returns a timestamp those many seconds ago from midnight: ```ruby date = Date.current # => Fri, 11 Jun 2010 date.ago(1) # => Thu, 10 Jun 2010 23:59:59 EDT -04:00 ``` -Similarly, +since+ moves forward: +Similarly, `since` moves forward: ```ruby date = Date.current # => Fri, 11 Jun 2010 @@ -3352,16 +3352,16 @@ date.since(1) # => Fri, 11 Jun 2010 00:00:01 EDT -04:00 ### Conversions -Extensions to +DateTime+ +Extensions to `DateTime` ------------------------ -WARNING: +DateTime+ is not aware of DST rules and so some of these methods have edge cases when a DST change is going on. For example +seconds_since_midnight+ might not return the real amount in such a day. +WARNING: `DateTime` is not aware of DST rules and so some of these methods have edge cases when a DST change is going on. For example `seconds_since_midnight` might not return the real amount in such a day. ### Calculations -NOTE: All the following methods are defined in +active_support/core_ext/date_time/calculations.rb+. +NOTE: All the following methods are defined in `active_support/core_ext/date_time/calculations.rb`. -The class +DateTime+ is a subclass of +Date+ so by loading +active_support/core_ext/date/calculations.rb+ you inherit these methods and their aliases, except that they will always return datetimes: +The class `DateTime` is a subclass of `Date` so by loading `active_support/core_ext/date/calculations.rb` you inherit these methods and their aliases, except that they will always return datetimes: ```ruby yesterday @@ -3389,7 +3389,7 @@ prev_year (last_year) next_year ``` -The following methods are reimplemented so you do *not* need to load +active_support/core_ext/date/calculations.rb+ for these ones: +The following methods are reimplemented so you do *not* need to load `active_support/core_ext/date/calculations.rb` for these ones: ```ruby beginning_of_day (midnight, at_midnight, at_beginning_of_day) @@ -3398,9 +3398,9 @@ ago since (in) ``` -On the other hand, +advance+ and +change+ are also defined and support more options, they are documented below. +On the other hand, `advance` and `change` are also defined and support more options, they are documented below. -The following methods are only implemented in +active_support/core_ext/date_time/calculations.rb+ as they only make sense when used with a +DateTime+ instance: +The following methods are only implemented in `active_support/core_ext/date_time/calculations.rb` as they only make sense when used with a `DateTime` instance: ```ruby beginning_of_hour (at_beginning_of_hour) @@ -3409,35 +3409,35 @@ end_of_hour #### Named Datetimes -##### +DateTime.current+ +##### `DateTime.current` -Active Support defines +DateTime.current+ to be like +Time.now.to_datetime+, except that it honors the user time zone, if defined. It also defines +DateTime.yesterday+ and +DateTime.tomorrow+, and the instance predicates +past?+, and +future?+ relative to +DateTime.current+. +Active Support defines `DateTime.current` to be like `Time.now.to_datetime`, except that it honors the user time zone, if defined. It also defines `DateTime.yesterday` and `DateTime.tomorrow`, and the instance predicates `past?`, and `future?` relative to `DateTime.current`. #### Other Extensions -##### +seconds_since_midnight+ +##### `seconds_since_midnight` -The method +seconds_since_midnight+ returns the number of seconds since midnight: +The method `seconds_since_midnight` returns the number of seconds since midnight: ```ruby now = DateTime.current # => Mon, 07 Jun 2010 20:26:36 +0000 now.seconds_since_midnight # => 73596 ``` -##### +utc+ +##### `utc` -The method +utc+ gives you the same datetime in the receiver expressed in UTC. +The method `utc` gives you the same datetime in the receiver expressed in UTC. ```ruby now = DateTime.current # => Mon, 07 Jun 2010 19:27:52 -0400 now.utc # => Mon, 07 Jun 2010 23:27:52 +0000 ``` -This method is also aliased as +getutc+. +This method is also aliased as `getutc`. -##### +utc?+ +##### `utc?` -The predicate +utc?+ says whether the receiver has UTC as its time zone: +The predicate `utc?` says whether the receiver has UTC as its time zone: ```ruby now = DateTime.now # => Mon, 07 Jun 2010 19:30:47 -0400 @@ -3445,9 +3445,9 @@ now.utc? # => false now.utc.utc? # => true ``` -##### +advance+ +##### `advance` -The most generic way to jump to another datetime is +advance+. This method receives a hash with keys +:years+, +:months+, +:weeks+, +:days+, +:hours+, +:minutes+, and +:seconds+, and returns a datetime advanced as much as the present keys indicate. +The most generic way to jump to another datetime is `advance`. This method receives a hash with keys `:years`, `:months`, `:weeks`, `:days`, `:hours`, `:minutes`, and `:seconds`, and returns a datetime advanced as much as the present keys indicate. ```ruby d = DateTime.current @@ -3456,7 +3456,7 @@ d.advance(:years => 1, :months => 1, :days => 1, :hours => 1, :minutes => 1, :se # => Tue, 06 Sep 2011 12:34:32 +0000 ``` -This method first computes the destination date passing +:years+, +:months+, +:weeks+, and +:days+ to +Date#advance+ documented above. After that, it adjusts the time calling +since+ with the number of seconds to advance. This order is relevant, a different ordering would give different datetimes in some edge-cases. The example in +Date#advance+ applies, and we can extend it to show order relevance related to the time bits. +This method first computes the destination date passing `:years`, `:months`, `:weeks`, and `:days` to `Date#advance` documented above. After that, it adjusts the time calling `since` with the number of seconds to advance. This order is relevant, a different ordering would give different datetimes in some edge-cases. The example in `Date#advance` applies, and we can extend it to show order relevance related to the time bits. If we first move the date bits (that have also a relative order of processing, as documented before), and then the time bits we get for example the following computation: @@ -3474,11 +3474,11 @@ d.advance(:seconds => 1).advance(:months => 1) # => Thu, 01 Apr 2010 00:00:00 +0000 ``` -WARNING: Since +DateTime+ is not DST-aware you can end up in a non-existing point in time with no warning or error telling you so. +WARNING: Since `DateTime` is not DST-aware you can end up in a non-existing point in time with no warning or error telling you so. #### Changing Components -The method +change+ allows you to get a new datetime which is the same as the receiver except for the given options, which may include +:year+, +:month+, +:day+, +:hour+, +:min+, +:sec+, +:offset+, +:start+: +The method `change` allows you to get a new datetime which is the same as the receiver except for the given options, which may include `:year`, `:month`, `:day`, `:hour`, `:min`, `:sec`, `:offset`, `:start`: ```ruby now = DateTime.current @@ -3501,7 +3501,7 @@ now.change(:min => 0) # => Tue, 08 Jun 2010 01:00:00 +0000 ``` -This method is not tolerant to non-existing dates, if the change is invalid +ArgumentError+ is raised: +This method is not tolerant to non-existing dates, if the change is invalid `ArgumentError` is raised: ```ruby DateTime.current.change(:month => 2, :day => 30) @@ -3521,21 +3521,21 @@ now - 1.week # => Mon, 02 Aug 2010 23:15:17 +0000 ``` -They translate to calls to +since+ or +advance+. For example here we get the correct jump in the calendar reform: +They translate to calls to `since` or `advance`. For example here we get the correct jump in the calendar reform: ```ruby DateTime.new(1582, 10, 4, 23) + 1.hour # => Fri, 15 Oct 1582 00:00:00 +0000 ``` -Extensions to +Time+ +Extensions to `Time` -------------------- ### Calculations -NOTE: All the following methods are defined in +active_support/core_ext/time/calculations.rb+. +NOTE: All the following methods are defined in `active_support/core_ext/time/calculations.rb`. -Active Support adds to +Time+ many of the methods available for +DateTime+: +Active Support adds to `Time` many of the methods available for `DateTime`: ```ruby past? @@ -3577,8 +3577,8 @@ next_year They are analogous. Please refer to their documentation above and take into account the following differences: -* +change+ accepts an additional +:usec+ option. -* +Time+ understands DST, so you get correct DST calculations as in +* `change` accepts an additional `:usec` option. +* `Time` understands DST, so you get correct DST calculations as in ```ruby Time.zone_default @@ -3591,17 +3591,17 @@ t.advance(:seconds => 1) # => Sun Mar 28 03:00:00 +0200 2010 ``` -* If +since+ or +ago+ jump to a time that can't be expressed with +Time+ a +DateTime+ object is returned instead. +* If `since` or `ago` jump to a time that can't be expressed with `Time` a `DateTime` object is returned instead. -#### +Time.current+ +#### `Time.current` -Active Support defines +Time.current+ to be today in the current time zone. That's like +Time.now+, except that it honors the user time zone, if defined. It also defines +Time.yesterday+ and +Time.tomorrow+, and the instance predicates +past?+, +today?+, and +future?+, all of them relative to +Time.current+. +Active Support defines `Time.current` to be today in the current time zone. That's like `Time.now`, except that it honors the user time zone, if defined. It also defines `Time.yesterday` and `Time.tomorrow`, and the instance predicates `past?`, `today?`, and `future?`, all of them relative to `Time.current`. -When making Time comparisons using methods which honor the user time zone, make sure to use +Time.current+ and not +Time.now+. There are cases where the user time zone might be in the future compared to the system time zone, which +Time.today+ uses by default. This means +Time.now+ may equal +Time.yesterday+. +When making Time comparisons using methods which honor the user time zone, make sure to use `Time.current` and not `Time.now`. There are cases where the user time zone might be in the future compared to the system time zone, which `Time.today` uses by default. This means `Time.now` may equal `Time.yesterday`. -#### +all_day+, +all_week+, +all_month+, +all_quarter+ and +all_year+ +#### `all_day`, `all_week`, `all_month`, `all_quarter` and `all_year` -The method +all_day+ returns a range representing the whole day of the current time. +The method `all_day` returns a range representing the whole day of the current time. ```ruby now = Time.current @@ -3610,7 +3610,7 @@ now.all_day # => Mon, 09 Aug 2010 00:00:00 UTC <plus>00:00..Mon, 09 Aug 2010 23:59:59 UTC <plus>00:00 ``` -Analogously, +all_week+, +all_month+, +all_quarter+ and +all_year+ all serve the purpose of generating time ranges. +Analogously, `all_week`, `all_month`, `all_quarter` and `all_year` all serve the purpose of generating time ranges. ```ruby now = Time.current @@ -3627,7 +3627,7 @@ now.all_year ### Time Constructors -Active Support defines +Time.current+ to be +Time.zone.now+ if there's a user time zone defined, with fallback to +Time.now+: +Active Support defines `Time.current` to be `Time.zone.now` if there's a user time zone defined, with fallback to `Time.now`: ```ruby Time.zone_default @@ -3636,9 +3636,9 @@ Time.current # => Fri, 06 Aug 2010 17:11:58 CEST +02:00 ``` -Analogously to +DateTime+, the predicates +past?+, and +future?+ are relative to +Time.current+. +Analogously to `DateTime`, the predicates `past?`, and `future?` are relative to `Time.current`. -Use the +local_time+ class method to create time objects honoring the user time zone: +Use the `local_time` class method to create time objects honoring the user time zone: ```ruby Time.zone_default @@ -3647,7 +3647,7 @@ Time.local_time(2010, 8, 15) # => Sun Aug 15 00:00:00 +0200 2010 ``` -The +utc_time+ class method returns a time in UTC: +The `utc_time` class method returns a time in UTC: ```ruby Time.zone_default @@ -3656,9 +3656,9 @@ Time.utc_time(2010, 8, 15) # => Sun Aug 15 00:00:00 UTC 2010 ``` -Both +local_time+ and +utc_time+ accept up to seven positional arguments: year, month, day, hour, min, sec, usec. Year is mandatory, month and day default to 1, and the rest default to 0. +Both `local_time` and `utc_time` accept up to seven positional arguments: year, month, day, hour, min, sec, usec. Year is mandatory, month and day default to 1, and the rest default to 0. -If the time to be constructed lies beyond the range supported by +Time+ in the runtime platform, usecs are discarded and a +DateTime+ object is returned instead. +If the time to be constructed lies beyond the range supported by `Time` in the runtime platform, usecs are discarded and a `DateTime` object is returned instead. #### Durations @@ -3673,23 +3673,23 @@ now - 1.week # => Mon, 02 Aug 2010 23:21:11 UTC +00:00 ``` -They translate to calls to +since+ or +advance+. For example here we get the correct jump in the calendar reform: +They translate to calls to `since` or `advance`. For example here we get the correct jump in the calendar reform: ```ruby Time.utc_time(1582, 10, 3) + 5.days # => Mon Oct 18 00:00:00 UTC 1582 ``` -Extensions to +File+ +Extensions to `File` -------------------- -### +atomic_write+ +### `atomic_write` -With the class method +File.atomic_write+ you can write to a file in a way that will prevent any reader from seeing half-written content. +With the class method `File.atomic_write` you can write to a file in a way that will prevent any reader from seeing half-written content. -The name of the file is passed as an argument, and the method yields a file handle opened for writing. Once the block is done +atomic_write+ closes the file handle and completes its job. +The name of the file is passed as an argument, and the method yields a file handle opened for writing. Once the block is done `atomic_write` closes the file handle and completes its job. -For example, Action Pack uses this method to write asset cache files like +all.css+: +For example, Action Pack uses this method to write asset cache files like `all.css`: ```ruby File.atomic_write(joined_asset_path) do |cache| @@ -3697,27 +3697,27 @@ File.atomic_write(joined_asset_path) do |cache| end ``` -To accomplish this +atomic_write+ creates a temporary file. That's the file the code in the block actually writes to. On completion, the temporary file is renamed, which is an atomic operation on POSIX systems. If the target file exists +atomic_write+ overwrites it and keeps owners and permissions. +To accomplish this `atomic_write` creates a temporary file. That's the file the code in the block actually writes to. On completion, the temporary file is renamed, which is an atomic operation on POSIX systems. If the target file exists `atomic_write` overwrites it and keeps owners and permissions. -WARNING. Note you can't append with +atomic_write+. +WARNING. Note you can't append with `atomic_write`. The auxiliary file is written in a standard directory for temporary files, but you can pass a directory of your choice as second argument. -NOTE: Defined in +active_support/core_ext/file/atomic.rb+. +NOTE: Defined in `active_support/core_ext/file/atomic.rb`. -Extensions to +Logger+ +Extensions to `Logger` ---------------------- -### +around_[level]+ +### `around_[level]` -Takes two arguments, a +before_message+ and +after_message+ and calls the current level method on the +Logger+ instance, passing in the +before_message+, then the specified message, then the +after_message+: +Takes two arguments, a `before_message` and `after_message` and calls the current level method on the `Logger` instance, passing in the `before_message`, then the specified message, then the `after_message`: ```ruby logger = Logger.new("log/development.log") logger.around_info("before", "after") { |logger| logger.info("during") } ``` -### +silence+ +### `silence` Silences every log level lesser to the specified one for the duration of the given block. Log level orders are: debug, info, error and fatal. @@ -3729,9 +3729,9 @@ logger.silence(Logger::INFO) do end ``` -### +datetime_format=+ +### `datetime_format=` -Modifies the datetime format output by the formatter class associated with this logger. If the formatter class does not have a +datetime_format+ method then this is ignored. +Modifies the datetime format output by the formatter class associated with this logger. If the formatter class does not have a `datetime_format` method then this is ignored. ```ruby class Logger::FormatWithTime < Logger::Formatter @@ -3747,18 +3747,18 @@ logger.formatter = Logger::FormatWithTime logger.info("<- is the current time") ``` -NOTE: Defined in +active_support/core_ext/logger.rb+. +NOTE: Defined in `active_support/core_ext/logger.rb`. -Extensions to +NameError+ +Extensions to `NameError` ------------------------- -Active Support adds +missing_name?+ to +NameError+, which tests whether the exception was raised because of the name passed as argument. +Active Support adds `missing_name?` to `NameError`, which tests whether the exception was raised because of the name passed as argument. The name may be given as a symbol or string. A symbol is tested against the bare constant name, a string is against the fully-qualified constant name. -TIP: A symbol can represent a fully-qualified constant name as in +:"ActiveRecord::Base"+, so the behavior for symbols is defined for convenience, not because it has to be that way technically. +TIP: A symbol can represent a fully-qualified constant name as in `:"ActiveRecord::Base"`, so the behavior for symbols is defined for convenience, not because it has to be that way technically. -For example, when an action of +PostsController+ is called Rails tries optimistically to use +PostsHelper+. It is OK that the helper module does not exist, so if an exception for that constant name is raised it should be silenced. But it could be the case that +posts_helper.rb+ raises a +NameError+ due to an actual unknown constant. That should be reraised. The method +missing_name?+ provides a way to distinguish both cases: +For example, when an action of `PostsController` is called Rails tries optimistically to use `PostsHelper`. It is OK that the helper module does not exist, so if an exception for that constant name is raised it should be silenced. But it could be the case that `posts_helper.rb` raises a `NameError` due to an actual unknown constant. That should be reraised. The method `missing_name?` provides a way to distinguish both cases: ```ruby def default_helper_module! @@ -3772,16 +3772,16 @@ rescue NameError => e end ``` -NOTE: Defined in +active_support/core_ext/name_error.rb+. +NOTE: Defined in `active_support/core_ext/name_error.rb`. -Extensions to +LoadError+ +Extensions to `LoadError` ------------------------- -Active Support adds +is_missing?+ to +LoadError+, and also assigns that class to the constant +MissingSourceFile+ for backwards compatibility. +Active Support adds `is_missing?` to `LoadError`, and also assigns that class to the constant `MissingSourceFile` for backwards compatibility. -Given a path name +is_missing?+ tests whether the exception was raised due to that particular file (except perhaps for the ".rb" extension). +Given a path name `is_missing?` tests whether the exception was raised due to that particular file (except perhaps for the ".rb" extension). -For example, when an action of +PostsController+ is called Rails tries to load +posts_helper.rb+, but that file may not exist. That's fine, the helper module is not mandatory so Rails silences a load error. But it could be the case that the helper module does exist and in turn requires another library that is missing. In that case Rails must reraise the exception. The method +is_missing?+ provides a way to distinguish both cases: +For example, when an action of `PostsController` is called Rails tries to load `posts_helper.rb`, but that file may not exist. That's fine, the helper module is not mandatory so Rails silences a load error. But it could be the case that the helper module does exist and in turn requires another library that is missing. In that case Rails must reraise the exception. The method `is_missing?` provides a way to distinguish both cases: ```ruby def default_helper_module! @@ -3795,4 +3795,4 @@ rescue NameError => e end ``` -NOTE: Defined in +active_support/core_ext/load_error.rb+. +NOTE: Defined in `active_support/core_ext/load_error.rb`. diff --git a/guides/source/active_support_instrumentation.md b/guides/source/active_support_instrumentation.md index 1bd3daa46a..e5abbe15c0 100644 --- a/guides/source/active_support_instrumentation.md +++ b/guides/source/active_support_instrumentation.md @@ -32,7 +32,7 @@ ActionController ### write_fragment.action_controller |_.Key |_.Value| -|+:key+ |The complete key| +|`:key` |The complete key| ```ruby { @@ -43,7 +43,7 @@ ActionController ### read_fragment.action_controller |_.Key |_.Value| -|+:key+ |The complete key| +|`:key` |The complete key| ```ruby { @@ -54,7 +54,7 @@ ActionController ### expire_fragment.action_controller |_.Key |_.Value| -|+:key+ |The complete key| +|`:key` |The complete key| ```ruby { @@ -65,7 +65,7 @@ ActionController ### exist_fragment?.action_controller |_.Key |_.Value| -|+:key+ |The complete key| +|`:key` |The complete key| ```ruby { @@ -76,7 +76,7 @@ ActionController ### write_page.action_controller |_.Key |_.Value| -|+:path+ |The complete path| +|`:path` |The complete path| ```ruby { @@ -87,7 +87,7 @@ ActionController ### expire_page.action_controller |_.Key |_.Value| -|+:path+ |The complete path| +|`:path` |The complete path| ```ruby { @@ -98,12 +98,12 @@ ActionController ### start_processing.action_controller |_.Key |_.Value | -|+:controller+ |The controller name| -|+:action+ |The action| -|+:params+ |Hash of request parameters without any filtered parameter| -|+:format+ |html/js/json/xml etc| -|+:method+ |HTTP request verb| -|+:path+ |Request path| +|`:controller` |The controller name| +|`:action` |The action| +|`:params` |Hash of request parameters without any filtered parameter| +|`:format` |html/js/json/xml etc| +|`:method` |HTTP request verb| +|`:path` |Request path| ```ruby { @@ -119,13 +119,13 @@ ActionController ### process_action.action_controller |_.Key |_.Value | -|+:controller+ |The controller name| -|+:action+ |The action| -|+:params+ |Hash of request parameters without any filtered parameter| -|+:format+ |html/js/json/xml etc| -|+:method+ |HTTP request verb| -|+:path+ |Request path| -|+:view_runtime+ |Amount spent in view in ms| +|`:controller` |The controller name| +|`:action` |The action| +|`:params` |Hash of request parameters without any filtered parameter| +|`:format` |html/js/json/xml etc| +|`:method` |HTTP request verb| +|`:path` |Request path| +|`:view_runtime` |Amount spent in view in ms| ```ruby { @@ -144,19 +144,19 @@ ActionController ### send_file.action_controller |_.Key |_.Value | -|+:path+ |Complete path to the file| +|`:path` |Complete path to the file| INFO. Additional keys may be added by the caller. ### send_data.action_controller -+ActionController+ does not had any specific information to the payload. All options are passed through to the payload. +`ActionController` does not had any specific information to the payload. All options are passed through to the payload. ### redirect_to.action_controller |_.Key |_.Value | -|+:status+ |HTTP response code| -|+:location+ |URL to redirect to| +|`:status` |HTTP response code| +|`:location` |URL to redirect to| ```ruby { @@ -168,7 +168,7 @@ INFO. Additional keys may be added by the caller. ### halted_callback.action_controller |_.Key |_.Value | -|+:filter+ |Filter that halted the action| +|`:filter` |Filter that halted the action| ```ruby { @@ -182,8 +182,8 @@ ActionView ### render_template.action_view |_.Key |_.Value | -|+:identifier+ |Full path to template| -|+:layout+ |Applicable layout| +|`:identifier` |Full path to template| +|`:layout` |Applicable layout| ```ruby { @@ -195,7 +195,7 @@ ActionView ### render_partial.action_view |_.Key |_.Value | -|+:identifier+ |Full path to template| +|`:identifier` |Full path to template| ```ruby { @@ -209,9 +209,9 @@ ActiveRecord ### sql.active_record |_.Key |_.Value | -|+:sql+ |SQL statement| -|+:name+ |Name of the operation| -|+:object_id+ |+self.object_id+| +|`:sql` |SQL statement| +|`:name` |Name of the operation| +|`:object_id` |`self.object_id`| INFO. The adapters will add their own data as well. @@ -227,9 +227,9 @@ INFO. The adapters will add their own data as well. ### identity.active_record |_.Key |_.Value | -|+:line+ |Primary Key of object in the identity map| -|+:name+ |Record's class| -|+:connection_id+ |+self.object_id+| +|`:line` |Primary Key of object in the identity map| +|`:name` |Record's class| +|`:connection_id` |`self.object_id`| ActionMailer ------------ @@ -237,15 +237,15 @@ ActionMailer ### receive.action_mailer |_.Key |_.Value| -|+:mailer+ |Name of the mailer class| -|+:message_id+ |ID of the message, generated by the Mail gem| -|+:subject+ |Subject of the mail| -|+:to+ |To address(es) of the mail| -|+:from+ |From address of the mail| -|+:bcc+ |BCC addresses of the mail| -|+:cc+ |CC addresses of the mail| -|+:date+ |Date of the mail| -|+:mail+ |The encoded form of the mail| +|`:mailer` |Name of the mailer class| +|`:message_id` |ID of the message, generated by the Mail gem| +|`:subject` |Subject of the mail| +|`:to` |To address(es) of the mail| +|`:from` |From address of the mail| +|`:bcc` |BCC addresses of the mail| +|`:cc` |CC addresses of the mail| +|`:date` |Date of the mail| +|`:mail` |The encoded form of the mail| ```ruby { @@ -262,15 +262,15 @@ ActionMailer ### deliver.action_mailer |_.Key |_.Value| -|+:mailer+ |Name of the mailer class| -|+:message_id+ |ID of the message, generated by the Mail gem| -|+:subject+ |Subject of the mail| -|+:to+ |To address(es) of the mail| -|+:from+ |From address of the mail| -|+:bcc+ |BCC addresses of the mail| -|+:cc+ |CC addresses of the mail| -|+:date+ |Date of the mail| -|+:mail+ |The encoded form of the mail| +|`:mailer` |Name of the mailer class| +|`:message_id` |ID of the message, generated by the Mail gem| +|`:subject` |Subject of the mail| +|`:to` |To address(es) of the mail| +|`:from` |From address of the mail| +|`:bcc` |BCC addresses of the mail| +|`:cc` |CC addresses of the mail| +|`:date` |Date of the mail| +|`:mail` |The encoded form of the mail| ```ruby { @@ -290,9 +290,9 @@ ActiveResource ### request.active_resource |_.Key |_.Value| -|+:method+ |HTTP method| -|+:request_uri+ |Complete URI| -|+:result+ |HTTP response object| +|`:method` |HTTP method| +|`:request_uri` |Complete URI| +|`:result` |HTTP response object| ActiveSupport ------------- @@ -300,16 +300,16 @@ ActiveSupport ### cache_read.active_support |_.Key |_.Value| -|+:key+ |Key used in the store| -|+:hit+ |If this read is a hit| -|+:super_operation+ |:fetch is added when a read is used with +#fetch+| +|`:key` |Key used in the store| +|`:hit` |If this read is a hit| +|`:super_operation` |:fetch is added when a read is used with `#fetch`| ### cache_generate.active_support -This event is only used when +#fetch+ is called with a block. +This event is only used when `#fetch` is called with a block. |_.Key |_.Value| -|+:key+ |Key used in the store| +|`:key` |Key used in the store| INFO. Options passed to fetch will be merged with the payload when writing to the store @@ -322,10 +322,10 @@ INFO. Options passed to fetch will be merged with the payload when writing to th ### cache_fetch_hit.active_support -This event is only used when +#fetch+ is called with a block. +This event is only used when `#fetch` is called with a block. |_.Key |_.Value| -|+:key+ |Key used in the store| +|`:key` |Key used in the store| INFO. Options passed to fetch will be merged with the payload. @@ -338,7 +338,7 @@ INFO. Options passed to fetch will be merged with the payload. ### cache_write.active_support |_.Key |_.Value| -|+:key+ |Key used in the store| +|`:key` |Key used in the store| INFO. Cache stores my add their own keys @@ -351,7 +351,7 @@ INFO. Cache stores my add their own keys ### cache_delete.active_support |_.Key |_.Value| -|+:key+ |Key used in the store| +|`:key` |Key used in the store| ```ruby { @@ -362,7 +362,7 @@ INFO. Cache stores my add their own keys ### cache_exist?.active_support |_.Key |_.Value| -|+:key+ |Key used in the store| +|`:key` |Key used in the store| ```ruby { @@ -376,13 +376,13 @@ Rails ### deprecation.rails |_.Key |_.Value| -|+:message+ |The deprecation warning| -|+:callstack+ |Where the deprecation came from| +|`:message` |The deprecation warning| +|`:callstack` |Where the deprecation came from| Subscribing to an event ----------------------- -Subscribing to an event is easy. Use +ActiveSupport::Notifications.subscribe+ with a block to +Subscribing to an event is easy. Use `ActiveSupport::Notifications.subscribe` with a block to listen to any notification. The block receives the following arguments: @@ -400,7 +400,7 @@ ActiveSupport::Notifications.subscribe "process_action.action_controller" do |na end ``` -Defining all those block arguments each time can be tedious. You can easily create an +ActiveSupport::Notifications::Event+ +Defining all those block arguments each time can be tedious. You can easily create an `ActiveSupport::Notifications::Event` from block args like this: ```ruby @@ -424,7 +424,7 @@ ActiveSupport::Notifications.subscribe "process_action.action_controller" do |*a ``` You may also subscribe to events matching a regular expresssion. This enables you to subscribe to -multiple events at once. Here's you could subscribe to everything from +ActionController+. +multiple events at once. Here's you could subscribe to everything from `ActionController`. ```ruby ActiveSupport::Notifications.subscribe /action_controller/ do |*args| @@ -435,10 +435,10 @@ end Creating custom events ---------------------- -Adding your own events is easy as well. +ActiveSupport::Notifications+ will take care of -all the heavy lifting for you. Simply call +instrument+ with a +name+, +payload+ and a block. -The notification will be sent after the block returns. +ActiveSupport+ will generate the start and end times -as well as the unique ID. All data passed into the +insturment+ call will make it into the payload. +Adding your own events is easy as well. `ActiveSupport::Notifications` will take care of +all the heavy lifting for you. Simply call `instrument` with a `name`, `payload` and a block. +The notification will be sent after the block returns. `ActiveSupport` will generate the start and end times +as well as the unique ID. All data passed into the `insturment` call will make it into the payload. Here's an example: @@ -456,5 +456,5 @@ ActiveSupport::Notifications.subscribe "my.custom.event" do |name, started, fini end ``` -You should follow Rails conventions when defining your own events. The format is: +event.library+. -If you application is sending Tweets, you should create an event named +tweet.twitter+. +You should follow Rails conventions when defining your own events. The format is: `event.library`. +If you application is sending Tweets, you should create an event named `tweet.twitter`. diff --git a/guides/source/ajax_on_rails.md b/guides/source/ajax_on_rails.md index 7317d47097..54e1ac67bf 100644 --- a/guides/source/ajax_on_rails.md +++ b/guides/source/ajax_on_rails.md @@ -23,9 +23,9 @@ page is not reloaded and new information can be dynamically included in the page The way that happens is by inserting, removing or changing parts of the DOM. The DOM, or Document Object Model, is a convention to represent the HTML document as a set of nodes that contain other nodes. For example, a list of names is represented -as a +ul+ element node containing several +li+ element nodes. An AJAX call can -be made to obtain a new list item to include, and append it inside a +li+ node to -the +ul+ node. +as a `ul` element node containing several `li` element nodes. An AJAX call can +be made to obtain a new list item to include, and append it inside a `li` node to +the `ul` node. ### Asynchronous JavaScript + XML @@ -38,15 +38,15 @@ not required, you respond to the HTTP request with JSON or regular HTML as well. The DOM (Document Object Model) is a convention to represent HTML (or XML) documents, as a set of nodes that act as objects and contain other nodes. You can -have a +div+ element that contains other +div+ elements as well as +p+ elements +have a `div` element that contains other `div` elements as well as `p` elements that contain text. ### Standard HTML communication vs AJAX In regular HTML comunications, when you click on a link, the browser makes an HTTP -+GET+ request, the server responds with a new HTML document that the browsers renders +`GET` request, the server responds with a new HTML document that the browsers renders and then replaces the previous one. The same thing happens when you click a button to -submit a form, except that you make and HTTP +POST+ request, but you also get a new +submit a form, except that you make and HTTP `POST` request, but you also get a new HTML document that the browser renders and replaces the current one. In AJAX communications, the request is separate, and the response is evaluated in JavaScript instead of rendered by the browser. That way you can have more control over the content @@ -56,12 +56,12 @@ Built-in Rails Helpers ---------------------- Rails 4.0 ships with "jQuery":http://jquery.com as the default JavaScript library. -The Gemfile contains +gem 'jquery-rails'+ which provides the +jquery.js+ and -+jquery_ujs.js+ files via the asset pipeline. +The Gemfile contains `gem 'jquery-rails'` which provides the `jquery.js` and +`jquery_ujs.js` files via the asset pipeline. -You will have to use the +require+ directive to tell Sprockets to load +jquery.js+ -and +jquery.js+. For example, a new Rails application includes a default -+app/assets/javascripts/application.js+ file which contains the following lines: +You will have to use the `require` directive to tell Sprockets to load `jquery.js` +and `jquery.js`. For example, a new Rails application includes a default +`app/assets/javascripts/application.js` file which contains the following lines: ``` // ... @@ -70,9 +70,9 @@ and +jquery.js+. For example, a new Rails application includes a default // ... ``` -The +application.js+ file acts like a manifest and is used to tell Sprockets the -files that you wish to require. In this case, you are requiring the files +jquery.js+ -and +jquery_ujs.js+ provided by the +jquery-rails+ gem. +The `application.js` file acts like a manifest and is used to tell Sprockets the +files that you wish to require. In this case, you are requiring the files `jquery.js` +and `jquery_ujs.js` provided by the `jquery-rails` gem. If the application is not using the asset pipeline, this can be accessed as: @@ -80,17 +80,17 @@ If the application is not using the asset pipeline, this can be accessed as: javascript_include_tag :defaults ``` -By default, +:defaults+ loads jQuery. +By default, `:defaults` loads jQuery. You can also choose to use Prototype instead of jQuery and specify the option -using +-j+ switch while generating the application. +using `-j` switch while generating the application. ```bash rails new app_name -j prototype ``` -This will add the +prototype-rails+ gem to the Gemfile and modify the -+app/assets/javascripts/application.js+ file: +This will add the `prototype-rails` gem to the Gemfile and modify the +`app/assets/javascripts/application.js` file: ``` // ... @@ -164,9 +164,9 @@ will produce ### The Quintessential AJAX Rails Helper: link_to_remote -Let's start with what is probably the most often used helper: +link_to_remote+. It has an interesting feature from the documentation point of view: the options supplied to +link_to_remote+ are shared by all other AJAX helpers, so learning the mechanics and options of +link_to_remote+ is a great help when using other helpers. +Let's start with what is probably the most often used helper: `link_to_remote`. It has an interesting feature from the documentation point of view: the options supplied to `link_to_remote` are shared by all other AJAX helpers, so learning the mechanics and options of `link_to_remote` is a great help when using other helpers. -The signature of +link_to_remote+ function is the same as that of the standard +link_to+ helper: +The signature of `link_to_remote` function is the same as that of the standard `link_to` helper: ```ruby def link_to_remote(name, options = {}, html_options = nil) @@ -181,8 +181,8 @@ link_to_remote "Add to cart", ``` * The very first parameter, a string, is the text of the link which appears on the page. -* The second parameter, the +options+ hash is the most interesting part as it has the AJAX specific stuff: -** *:url* This is the only parameter that is always required to generate the simplest remote link (technically speaking, it is not required, you can pass an empty +options+ hash to +link_to_remote+ - but in this case the URL used for the POST request will be equal to your current URL which is probably not your intention). This URL points to your AJAX action handler. The URL is typically specified by Rails REST view helpers, but you can use the +url_for+ format too. +* The second parameter, the `options` hash is the most interesting part as it has the AJAX specific stuff: +** *:url* This is the only parameter that is always required to generate the simplest remote link (technically speaking, it is not required, you can pass an empty `options` hash to `link_to_remote` - but in this case the URL used for the POST request will be equal to your current URL which is probably not your intention). This URL points to your AJAX action handler. The URL is typically specified by Rails REST view helpers, but you can use the `url_for` format too. ** *:update* Specifying a DOM id of the element we would like to update. The above example demonstrates the simplest way of accomplishing this - however, we are in trouble if the server responds with an error message because that will be injected into the page too! However, Rails has a solution for this situation: ```ruby @@ -191,15 +191,15 @@ link_to_remote "Add to cart", :update => { :success => "cart", :failure => "error" } ``` -If the server returns 200, the output of the above example is equivalent to our first, simple one. However, in case of error, the element with the DOM id +error+ is updated rather than the +cart+ element. +If the server returns 200, the output of the above example is equivalent to our first, simple one. However, in case of error, the element with the DOM id `error` is updated rather than the `cart` element. -** *position* By default (i.e. when not specifying this option, like in the examples before) the response is injected into the element with the specified DOM id, replacing the original content of the element (if there was any). You might want to alter this behavior by keeping the original content - the only question is where to place the new content? This can specified by the +position+ parameter, with four possibilities: -*** +:before+ Inserts the response text just before the target element. More precisely, it creates a text node from the response and inserts it as the left sibling of the target element. -*** +:after+ Similar behavior to +:before+, but in this case the response is inserted after the target element. -*** +:top+ Inserts the text into the target element, before its original content. If the target element was empty, this is equivalent with not specifying +:position+ at all. -*** +:bottom+ The counterpart of +:top+: the response is inserted after the target element's original content. +** *position* By default (i.e. when not specifying this option, like in the examples before) the response is injected into the element with the specified DOM id, replacing the original content of the element (if there was any). You might want to alter this behavior by keeping the original content - the only question is where to place the new content? This can specified by the `position` parameter, with four possibilities: +*** `:before` Inserts the response text just before the target element. More precisely, it creates a text node from the response and inserts it as the left sibling of the target element. +*** `:after` Similar behavior to `:before`, but in this case the response is inserted after the target element. +*** `:top` Inserts the text into the target element, before its original content. If the target element was empty, this is equivalent with not specifying `:position` at all. +*** `:bottom` The counterpart of `:top`: the response is inserted after the target element's original content. -A typical example of using +:bottom+ is inserting a new <li> element into an existing list: +A typical example of using `:bottom` is inserting a new <li> element into an existing list: ```ruby link_to_remote "Add new item", @@ -209,7 +209,7 @@ link_to_remote "Add new item", ``` ** *:method* Most typically you want to use a POST request when adding a remote -link to your view so this is the default behavior. However, sometimes you'll want to update (PATCH/PUT) or delete/destroy (DELETE) something and you can specify this with the +:method+ option. Let's see an example for a typical AJAX link for deleting an item from a list: +link to your view so this is the default behavior. However, sometimes you'll want to update (PATCH/PUT) or delete/destroy (DELETE) something and you can specify this with the `:method` option. Let's see an example for a typical AJAX link for deleting an item from a list: ```ruby link_to_remote "Delete the item", @@ -220,11 +220,11 @@ link_to_remote "Delete the item", Note that if we wouldn't override the default behavior (POST), the above snippet would route to the create action rather than destroy. ** *JavaScript filters* You can customize the remote call further by wrapping it with some JavaScript code. Let's say in the previous example, when deleting a link, you'd like to ask for a confirmation by showing a simple modal text box to the user. This is a typical example what you can accomplish with these options - let's see them one by one: -*** +:condition+ => +code+ Evaluates +code+ (which should evaluate to a boolean) and proceeds if it's true, cancels the request otherwise. -*** +:before+ => +code+ Evaluates the +code+ just before launching the request. The output of the code has no influence on the execution. Typically used show a progress indicator (see this in action in the next example). -*** +:after+ => +code+ Evaluates the +code+ after launching the request. Note that this is different from the +:success+ or +:complete+ callback (covered in the next section) since those are triggered after the request is completed, while the code snippet passed to +:after+ is evaluated after the remote call is made. A common example is to disable elements on the page or otherwise prevent further action while the request is completed. -*** +:submit+ => +dom_id+ This option does not make sense for +link_to_remote+, but we'll cover it for the sake of completeness. By default, the parent element of the form elements the user is going to submit is the current form - use this option if you want to change the default behavior. By specifying this option you can change the parent element to the element specified by the DOM id +dom_id+. -*** +:with+ > +code+ The JavaScript code snippet in +code+ is evaluated and added to the request URL as a parameter (or set of parameters). Therefore, +code+ should return a valid URL query string (like "item_type=8" or "item_type=8&sort=true"). Usually you want to obtain some value(s) from the page - let's see an example: +*** `:condition` => `code` Evaluates `code` (which should evaluate to a boolean) and proceeds if it's true, cancels the request otherwise. +*** `:before` => `code` Evaluates the `code` just before launching the request. The output of the code has no influence on the execution. Typically used show a progress indicator (see this in action in the next example). +*** `:after` => `code` Evaluates the `code` after launching the request. Note that this is different from the `:success` or `:complete` callback (covered in the next section) since those are triggered after the request is completed, while the code snippet passed to `:after` is evaluated after the remote call is made. A common example is to disable elements on the page or otherwise prevent further action while the request is completed. +*** `:submit` => `dom_id` This option does not make sense for `link_to_remote`, but we'll cover it for the sake of completeness. By default, the parent element of the form elements the user is going to submit is the current form - use this option if you want to change the default behavior. By specifying this option you can change the parent element to the element specified by the DOM id `dom_id`. +*** `:with` > `code` The JavaScript code snippet in `code` is evaluated and added to the request URL as a parameter (or set of parameters). Therefore, `code` should return a valid URL query string (like "item_type=8" or "item_type=8&sort=true"). Usually you want to obtain some value(s) from the page - let's see an example: ```ruby link_to_remote "Update record", @@ -235,13 +235,13 @@ link_to_remote "Update record", This generates a remote link which adds 2 parameters to the standard URL generated by Rails, taken from the page (contained in the elements matched by the 'status' and 'completed' DOM id). -** *Callbacks* Since an AJAX call is typically asynchronous, as its name suggests (this is not a rule, and you can fire a synchronous request - see the last option, +:type+) your only way of communicating with a request once it is fired is via specifying callbacks. There are six options at your disposal (in fact 508, counting all possible response types, but these six are the most frequent and therefore specified by a constant): -*** +:loading:+ => +code+ The request is in the process of receiving the data, but the transfer is not completed yet. -*** +:loaded:+ => +code+ The transfer is completed, but the data is not processed and returned yet -*** +:interactive:+ => +code+ One step after +:loaded+: The data is fully received and being processed -*** +:success:+ => +code+ The data is fully received, parsed and the server responded with "200 OK" -*** +:failure:+ => +code+ The data is fully received, parsed and the server responded with *anything* but "200 OK" (typically 404 or 500, but in general with any status code ranging from 100 to 509) -*** +:complete:+ => +code+ The combination of the previous two: The request has finished receiving and parsing the data, and returned a status code (which can be anything). +** *Callbacks* Since an AJAX call is typically asynchronous, as its name suggests (this is not a rule, and you can fire a synchronous request - see the last option, `:type`) your only way of communicating with a request once it is fired is via specifying callbacks. There are six options at your disposal (in fact 508, counting all possible response types, but these six are the most frequent and therefore specified by a constant): +*** `:loading:` => `code` The request is in the process of receiving the data, but the transfer is not completed yet. +*** `:loaded:` => `code` The transfer is completed, but the data is not processed and returned yet +*** `:interactive:` => `code` One step after `:loaded`: The data is fully received and being processed +*** `:success:` => `code` The data is fully received, parsed and the server responded with "200 OK" +*** `:failure:` => `code` The data is fully received, parsed and the server responded with *anything* but "200 OK" (typically 404 or 500, but in general with any status code ranging from 100 to 509) +*** `:complete:` => `code` The combination of the previous two: The request has finished receiving and parsing the data, and returned a status code (which can be anything). *** Any other status code ranging from 100 to 509: Additionally you might want to check for other HTTP status codes, such as 404. In this case simply use the status code as a number: ```ruby link_to_remote "Add new item", @@ -249,7 +249,7 @@ link_to_remote "Add new item", :update => "item_list", 404 => "alert('Item not found!')" ``` -Let's see a typical example for the most frequent callbacks, +:success+, +:failure+ and +:complete+ in action: +Let's see a typical example for the most frequent callbacks, `:success`, `:failure` and `:complete` in action: ```ruby link_to_remote "Add new item", @@ -261,28 +261,28 @@ link_to_remote "Add new item", :failure => "display_error(request)" ``` -** *:type* If you want to fire a synchronous request for some obscure reason (blocking the browser while the request is processed and doesn't return a status code), you can use the +:type+ option with the value of +:synchronous+. -* Finally, using the +html_options+ parameter you can add HTML attributes to the generated tag. It works like the same parameter of the +link_to+ helper. There are interesting side effects for the +href+ and +onclick+ parameters though: -** If you specify the +href+ parameter, the AJAX link will degrade gracefully, i.e. the link will point to the URL even if JavaScript is disabled in the client browser -** +link_to_remote+ gains its AJAX behavior by specifying the remote call in the onclick handler of the link. If you supply +html_options[:onclick]+ you override the default behavior, so use this with care! +** *:type* If you want to fire a synchronous request for some obscure reason (blocking the browser while the request is processed and doesn't return a status code), you can use the `:type` option with the value of `:synchronous`. +* Finally, using the `html_options` parameter you can add HTML attributes to the generated tag. It works like the same parameter of the `link_to` helper. There are interesting side effects for the `href` and `onclick` parameters though: +** If you specify the `href` parameter, the AJAX link will degrade gracefully, i.e. the link will point to the URL even if JavaScript is disabled in the client browser +** `link_to_remote` gains its AJAX behavior by specifying the remote call in the onclick handler of the link. If you supply `html_options[:onclick]` you override the default behavior, so use this with care! -We are finished with +link_to_remote+. I know this is quite a lot to digest for one helper function, but remember, these options are common for all the rest of the Rails view helpers, so we will take a look at the differences / additional parameters in the next sections. +We are finished with `link_to_remote`. I know this is quite a lot to digest for one helper function, but remember, these options are common for all the rest of the Rails view helpers, so we will take a look at the differences / additional parameters in the next sections. ### AJAX Forms There are three different ways of adding AJAX forms to your view using Rails Prototype helpers. They are slightly different, but striving for the same goal: instead of submitting the form using the standard HTTP request/response cycle, it is submitted asynchronously, thus not reloading the page. These methods are the following: -* +remote_form_for+ (and its alias +form_remote_for+) is tied to Rails most tightly of the three since it takes a resource, model or array of resources (in case of a nested resource) as a parameter. -* +form_remote_tag+ AJAXifies the form by serializing and sending its data in the background -* +submit_to_remote+ and +button_to_remote+ is more rarely used than the previous two. Rather than creating an AJAX form, you add a button/input +* `remote_form_for` (and its alias `form_remote_for`) is tied to Rails most tightly of the three since it takes a resource, model or array of resources (in case of a nested resource) as a parameter. +* `form_remote_tag` AJAXifies the form by serializing and sending its data in the background +* `submit_to_remote` and `button_to_remote` is more rarely used than the previous two. Rather than creating an AJAX form, you add a button/input Let's see them in action one by one! -#### +remote_form_for+ +#### `remote_form_for` -#### +form_remote_tag+ +#### `form_remote_tag` -#### +submit_to_remote+ +#### `submit_to_remote` ### Serving JavaScript @@ -295,7 +295,7 @@ def javascript_test end ``` -(Note: if you want to test the above method, create a +link_to_remote+ with a single parameter - +:url+, pointing to the +javascript_test+ action) +(Note: if you want to test the above method, create a `link_to_remote` with a single parameter - `:url`, pointing to the `javascript_test` action) What happens here is that by specifying the Content-Type header variable, we instruct the browser to evaluate the text we are sending over (rather than displaying it as plain text, which is the default behavior). diff --git a/guides/source/api_documentation_guidelines.md b/guides/source/api_documentation_guidelines.md index a20df89e68..2493829edf 100644 --- a/guides/source/api_documentation_guidelines.md +++ b/guides/source/api_documentation_guidelines.md @@ -30,7 +30,7 @@ Communicate to the reader the current way of doing things, both explicitly and i Documentation has to be concise but comprehensive. Explore and document edge cases. What happens if a module is anonymous? What if a collection is empty? What if an argument is nil? -The proper names of Rails components have a space in between the words, like "Active Support". +ActiveRecord+ is a Ruby module, whereas Active Record is an ORM. All Rails documentation should consistently refer to Rails components by their proper name, and if in your next blog post or presentation you remember this tidbit and take it into account that'd be phenomenal. +The proper names of Rails components have a space in between the words, like "Active Support". `ActiveRecord` is a Ruby module, whereas Active Record is an ORM. All Rails documentation should consistently refer to Rails components by their proper name, and if in your next blog post or presentation you remember this tidbit and take it into account that'd be phenomenal. Spell names correctly: Arel, Test::Unit, RSpec, HTML, MySQL, JavaScript, ERB. When in doubt, please have a look at some authoritative source like their official documentation. @@ -92,7 +92,7 @@ If a line is too long, the comment may be placed on the next line: # # => <label for="post_title" class="title_label">A short title</label> ``` -Avoid using any printing methods like +puts+ or +p+ for that purpose. +Avoid using any printing methods like `puts` or `p` for that purpose. On the other hand, regular comments do not use an arrow: @@ -119,7 +119,7 @@ Fonts Use fixed-width fonts for: * Constants, in particular class and module names. * Method names. -* Literals like +nil+, +false+, +true+, +self+. +* Literals like `nil`, `false`, `true`, `self`. * Symbols. * Method parameters. * File names. @@ -134,7 +134,7 @@ class Array end ``` -WARNING: Using a pair of ++...++ for fixed-width font only works with *words*; that is: anything matching `\A\w+\z`. For anything else use +<tt>...</tt>+, notably symbols, setters, inline snippets, etc. +WARNING: Using a pair of `+...+` for fixed-width font only works with *words*; that is: anything matching `\A\w+\z`. For anything else use `<tt>...</tt>`, notably symbols, setters, inline snippets, etc. ### Regular Font @@ -144,7 +144,7 @@ When "true" and "false" are English words rather than Ruby keywords use a regula # Runs all the validations within the specified context. Returns true if no errors are found, # false otherwise. # -# If the argument is false (default is +nil+), the context is set to `:create` if +# If the argument is false (default is `nil`), the context is set to `:create` if # `new_record?` is true, and to `:update` if it is not. # # Validations with no `:on` option will run no matter the context. Validations with @@ -168,7 +168,7 @@ The description starts in upper case and ends with a full stop—it's standard E Dynamically Generated Methods ----------------------------- -Methods created with +(module|class)_eval(STRING)+ have a comment by their side with an instance of the generated code. That comment is 2 spaces away from the template: +Methods created with `(module|class)_eval(STRING)` have a comment by their side with an instance of the generated code. That comment is 2 spaces away from the template: ```ruby for severity in Severity.constants diff --git a/guides/source/asset_pipeline.md b/guides/source/asset_pipeline.md index f80c111632..ee6209fd88 100644 --- a/guides/source/asset_pipeline.md +++ b/guides/source/asset_pipeline.md @@ -17,11 +17,11 @@ What is the Asset Pipeline? The asset pipeline provides a framework to concatenate and minify or compress JavaScript and CSS assets. It also adds the ability to write these assets in other languages such as CoffeeScript, Sass and ERB. -Prior to Rails 3.1 these features were added through third-party Ruby libraries such as Jammit and Sprockets. Rails 3.1 is integrated with Sprockets through Action Pack which depends on the +sprockets+ gem, by default. +Prior to Rails 3.1 these features were added through third-party Ruby libraries such as Jammit and Sprockets. Rails 3.1 is integrated with Sprockets through Action Pack which depends on the `sprockets` gem, by default. Making the asset pipeline a core feature of Rails means that all developers can benefit from the power of having their assets pre-processed, compressed and minified by one central library, Sprockets. This is part of Rails' "fast by default" strategy as outlined by DHH in his keynote at RailsConf 2011. -In Rails 3.1, the asset pipeline is enabled by default. It can be disabled in +config/application.rb+ by putting this line inside the application class definition: +In Rails 3.1, the asset pipeline is enabled by default. It can be disabled in `config/application.rb` by putting this line inside the application class definition: ```ruby config.assets.enabled = false @@ -40,9 +40,9 @@ You should use the defaults for all new applications unless you have a specific The first feature of the pipeline is to concatenate assets. This is important in a production environment, because it can reduce the number of requests that a browser must make to render a web page. Web browsers are limited in the number of requests that they can make in parallel, so fewer requests can mean faster loading for your application. -Rails 2.x introduced the ability to concatenate JavaScript and CSS assets by placing +:cache => true+ at the end of the +javascript_include_tag+ and +stylesheet_link_tag+ methods. But this technique has some limitations. For example, it cannot generate the caches in advance, and it is not able to transparently include assets provided by third-party libraries. +Rails 2.x introduced the ability to concatenate JavaScript and CSS assets by placing `:cache => true` at the end of the `javascript_include_tag` and `stylesheet_link_tag` methods. But this technique has some limitations. For example, it cannot generate the caches in advance, and it is not able to transparently include assets provided by third-party libraries. -Starting with version 3.1, Rails defaults to concatenating all JavaScript files into one master +.js+ file and all CSS files into one master +.css+ file. As you'll learn later in this guide, you can customize this strategy to group files any way you like. In production, Rails inserts an MD5 fingerprint into each filename so that the file is cached by the web browser. You can invalidate the cache by altering this fingerprint, which happens automatically whenever you change the file contents.. +Starting with version 3.1, Rails defaults to concatenating all JavaScript files into one master `.js` file and all CSS files into one master `.css` file. As you'll learn later in this guide, you can customize this strategy to group files any way you like. In production, Rails inserts an MD5 fingerprint into each filename so that the file is cached by the web browser. You can invalidate the cache by altering this fingerprint, which happens automatically whenever you change the file contents.. The second feature of the asset pipeline is asset minification or compression. For CSS files, this is done by removing whitespace and comments. For JavaScript, more complex processes can be applied. You can choose from a set of built in options or specify your own. @@ -54,7 +54,7 @@ Fingerprinting is a technique that makes the name of a file dependent on the con When a filename is unique and based on its content, HTTP headers can be set to encourage caches everywhere (whether at CDNs, at ISPs, in networking equipment, or in web browsers) to keep their own copy of the content. When the content is updated, the fingerprint will change. This will cause the remote clients to request a new copy of the content. This is generally known as _cache busting_. -The technique that Rails uses for fingerprinting is to insert a hash of the content into the name, usually at the end. For example a CSS file +global.css+ could be renamed with an MD5 digest of its contents: +The technique that Rails uses for fingerprinting is to insert a hash of the content into the name, usually at the end. For example a CSS file `global.css` could be renamed with an MD5 digest of its contents: ``` global-908e25f4bf641868d8683022a5b62f54.css @@ -87,7 +87,7 @@ The query string strategy has several disadvantages: Fingerprinting fixes these problems by avoiding query strings, and by ensuring that filenames are consistent based on their content. -Fingerprinting is enabled by default for production and disabled for all other environments. You can enable or disable it in your configuration through the +config.assets.digest+ option. +Fingerprinting is enabled by default for production and disabled for all other environments. You can enable or disable it in your configuration through the `config.assets.digest` option. More reading: @@ -98,33 +98,33 @@ More reading: How to Use the Asset Pipeline ----------------------------- -In previous versions of Rails, all assets were located in subdirectories of +public+ such as +images+, +javascripts+ and +stylesheets+. With the asset pipeline, the preferred location for these assets is now the +app/assets+ directory. Files in this directory are served by the Sprockets middleware included in the sprockets gem. +In previous versions of Rails, all assets were located in subdirectories of `public` such as `images`, `javascripts` and `stylesheets`. With the asset pipeline, the preferred location for these assets is now the `app/assets` directory. Files in this directory are served by the Sprockets middleware included in the sprockets gem. -Assets can still be placed in the +public+ hierarchy. Any assets under +public+ will be served as static files by the application or web server. You should use +app/assets+ for files that must undergo some pre-processing before they are served. +Assets can still be placed in the `public` hierarchy. Any assets under `public` will be served as static files by the application or web server. You should use `app/assets` for files that must undergo some pre-processing before they are served. -In production, Rails precompiles these files to +public/assets+ by default. The precompiled copies are then served as static assets by the web server. The files in +app/assets+ are never served directly in production. +In production, Rails precompiles these files to `public/assets` by default. The precompiled copies are then served as static assets by the web server. The files in `app/assets` are never served directly in production. -When you generate a scaffold or a controller, Rails also generates a JavaScript file (or CoffeeScript file if the +coffee-rails+ gem is in the +Gemfile+) and a Cascading Style Sheet file (or SCSS file if +sass-rails+ is in the +Gemfile+) for that controller. +When you generate a scaffold or a controller, Rails also generates a JavaScript file (or CoffeeScript file if the `coffee-rails` gem is in the `Gemfile`) and a Cascading Style Sheet file (or SCSS file if `sass-rails` is in the `Gemfile`) for that controller. -For example, if you generate a +ProjectsController+, Rails will also add a new file at +app/assets/javascripts/projects.js.coffee+ and another at +app/assets/stylesheets/projects.css.scss+. You should put any JavaScript or CSS unique to a controller inside their respective asset files, as these files can then be loaded just for these controllers with lines such as +<%= javascript_include_tag params[:controller] %>+ or +<%= stylesheet_link_tag params[:controller] %>+. +For example, if you generate a `ProjectsController`, Rails will also add a new file at `app/assets/javascripts/projects.js.coffee` and another at `app/assets/stylesheets/projects.css.scss`. You should put any JavaScript or CSS unique to a controller inside their respective asset files, as these files can then be loaded just for these controllers with lines such as `<%= javascript_include_tag params[:controller] %>` or `<%= stylesheet_link_tag params[:controller] %>`. NOTE: You must have an "ExecJS":https://github.com/sstephenson/execjs#readme supported runtime in order to use CoffeeScript. If you are using Mac OS X or Windows you have a JavaScript runtime installed in your operating system. Check "ExecJS":https://github.com/sstephenson/execjs#readme documentation to know all supported JavaScript runtimes. ### Asset Organization -Pipeline assets can be placed inside an application in one of three locations: +app/assets+, +lib/assets+ or +vendor/assets+. +Pipeline assets can be placed inside an application in one of three locations: `app/assets`, `lib/assets` or `vendor/assets`. -+app/assets+ is for assets that are owned by the application, such as custom images, JavaScript files or stylesheets. +`app/assets` is for assets that are owned by the application, such as custom images, JavaScript files or stylesheets. -+lib/assets+ is for your own libraries' code that doesn't really fit into the scope of the application or those libraries which are shared across applications. +`lib/assets` is for your own libraries' code that doesn't really fit into the scope of the application or those libraries which are shared across applications. -+vendor/assets+ is for assets that are owned by outside entities, such as code for JavaScript plugins and CSS frameworks. +`vendor/assets` is for assets that are owned by outside entities, such as code for JavaScript plugins and CSS frameworks. #### Search paths When a file is referenced from a manifest or a helper, Sprockets searches the three default asset locations for it. -The default locations are: +app/assets/images+ and the subdirectories +javascripts+ and +stylesheets+ in all three asset locations, but these subdirectories are not special. Any path under +assets/*+ will be searched. +The default locations are: `app/assets/images` and the subdirectories `javascripts` and `stylesheets` in all three asset locations, but these subdirectories are not special. Any path under `assets/*` will be searched. For example, these files: @@ -156,23 +156,23 @@ is referenced as: //= require sub/something ``` -You can view the search path by inspecting +Rails.application.config.assets.paths+ in the Rails console. +You can view the search path by inspecting `Rails.application.config.assets.paths` in the Rails console. -Besides the standard +assets/*+ paths, additional (fully qualified) paths can be added to the pipeline in +config/application.rb+. For example: +Besides the standard `assets/*` paths, additional (fully qualified) paths can be added to the pipeline in `config/application.rb`. For example: ```ruby config.assets.paths << Rails.root.join("lib", "videoplayer", "flash") ``` -Paths are traversed in the order that they occur in the search path. By default, this means the files in +app/assets+ take precedence, and will mask corresponding paths in +lib+ and +vendor+. +Paths are traversed in the order that they occur in the search path. By default, this means the files in `app/assets` take precedence, and will mask corresponding paths in `lib` and `vendor`. It is important to note that files you want to reference outside a manifest must be added to the precompile array or they will not be available in the production environment. #### Using index files -Sprockets uses files named +index+ (with the relevant extensions) for a special purpose. +Sprockets uses files named `index` (with the relevant extensions) for a special purpose. -For example, if you have a jQuery library with many modules, which is stored in +lib/assets/library_name+, the file +lib/assets/library_name/index.js+ serves as the manifest for all files in this library. This file could include a list of all the required files in order, or a simple `require_tree` directive. +For example, if you have a jQuery library with many modules, which is stored in `lib/assets/library_name`, the file `lib/assets/library_name/index.js` serves as the manifest for all files in this library. This file could include a list of all the required files in order, or a simple `require_tree` directive. The library as a whole can be accessed in the site's application manifest like so: @@ -184,24 +184,24 @@ This simplifies maintenance and keeps things clean by allowing related code to b ### Coding Links to Assets -Sprockets does not add any new methods to access your assets - you still use the familiar +javascript_include_tag+ and +stylesheet_link_tag+. +Sprockets does not add any new methods to access your assets - you still use the familiar `javascript_include_tag` and `stylesheet_link_tag`. ```erb <%= stylesheet_link_tag "application" %> <%= javascript_include_tag "application" %> ``` -In regular views you can access images in the +assets/images+ directory like this: +In regular views you can access images in the `assets/images` directory like this: ```erb <%= image_tag "rails.png" %> ``` -Provided that the pipeline is enabled within your application (and not disabled in the current environment context), this file is served by Sprockets. If a file exists at +public/assets/rails.png+ it is served by the web server. +Provided that the pipeline is enabled within your application (and not disabled in the current environment context), this file is served by Sprockets. If a file exists at `public/assets/rails.png` it is served by the web server. -Alternatively, a request for a file with an MD5 hash such as +public/assets/rails-af27b6a414e6da00003503148be9b409.png+ is treated the same way. How these hashes are generated is covered in the "In Production":#in-production section later on in this guide. +Alternatively, a request for a file with an MD5 hash such as `public/assets/rails-af27b6a414e6da00003503148be9b409.png` is treated the same way. How these hashes are generated is covered in the "In Production":#in-production section later on in this guide. -Sprockets will also look through the paths specified in +config.assets.paths+ which includes the standard application paths and any path added by Rails engines. +Sprockets will also look through the paths specified in `config.assets.paths` which includes the standard application paths and any path added by Rails engines. Images can also be organized into subdirectories if required, and they can be accessed by specifying the directory's name in the tag: @@ -213,15 +213,15 @@ WARNING: If you're precompiling your assets (see "In Production":#in-production #### CSS and ERB -The asset pipeline automatically evaluates ERB. This means that if you add an +erb+ extension to a CSS asset (for example, +application.css.erb+), then helpers like +asset_path+ are available in your CSS rules: +The asset pipeline automatically evaluates ERB. This means that if you add an `erb` extension to a CSS asset (for example, `application.css.erb`), then helpers like `asset_path` are available in your CSS rules: ``` .class { background-image: url(<%= asset_path 'image.png' %>) } ``` -This writes the path to the particular asset being referenced. In this example, it would make sense to have an image in one of the asset load paths, such as +app/assets/images/image.png+, which would be referenced here. If this image is already available in +public/assets+ as a fingerprinted file, then that path is referenced. +This writes the path to the particular asset being referenced. In this example, it would make sense to have an image in one of the asset load paths, such as `app/assets/images/image.png`, which would be referenced here. If this image is already available in `public/assets` as a fingerprinted file, then that path is referenced. -If you want to use a "data URI":http://en.wikipedia.org/wiki/Data_URI_scheme -- a method of embedding the image data directly into the CSS file -- you can use the +asset_data_uri+ helper. +If you want to use a "data URI":http://en.wikipedia.org/wiki/Data_URI_scheme -- a method of embedding the image data directly into the CSS file -- you can use the `asset_data_uri` helper. ``` #logo { background: url(<%= asset_data_uri 'logo.png' %>) } @@ -229,23 +229,23 @@ If you want to use a "data URI":http://en.wikipedia.org/wiki/Data_URI_scheme -- This inserts a correctly-formatted data URI into the CSS source. -Note that the closing tag cannot be of the style +-%>+. +Note that the closing tag cannot be of the style `-%>`. #### CSS and Sass -When using the asset pipeline, paths to assets must be re-written and +sass-rails+ provides +-url+ and +-path+ helpers (hyphenated in Sass, underscored in Ruby) for the following asset classes: image, font, video, audio, JavaScript and stylesheet. +When using the asset pipeline, paths to assets must be re-written and `sass-rails` provides `-url` and `-path` helpers (hyphenated in Sass, underscored in Ruby) for the following asset classes: image, font, video, audio, JavaScript and stylesheet. -* +image-url("rails.png")+ becomes +url(/assets/rails.png)+ -* +image-path("rails.png")+ becomes +"/assets/rails.png"+. +* `image-url("rails.png")` becomes `url(/assets/rails.png)` +* `image-path("rails.png")` becomes `"/assets/rails.png"`. The more generic form can also be used but the asset path and class must both be specified: -* +asset-url("rails.png", image)+ becomes +url(/assets/rails.png)+ -* +asset-path("rails.png", image)+ becomes +"/assets/rails.png"+ +* `asset-url("rails.png", image)` becomes `url(/assets/rails.png)` +* `asset-path("rails.png", image)` becomes `"/assets/rails.png"` #### JavaScript/CoffeeScript and ERB -If you add an +erb+ extension to a JavaScript asset, making it something such as +application.js.erb+, then you can use the +asset_path+ helper in your JavaScript code: +If you add an `erb` extension to a JavaScript asset, making it something such as `application.js.erb`, then you can use the `asset_path` helper in your JavaScript code: ```erb $('#logo').attr({ @@ -255,7 +255,7 @@ $('#logo').attr({ This writes the path to the particular asset being referenced. -Similarly, you can use the +asset_path+ helper in CoffeeScript files with +erb+ extension (e.g., +application.js.coffee.erb+): +Similarly, you can use the `asset_path` helper in CoffeeScript files with `erb` extension (e.g., `application.js.coffee.erb`): ``` $('#logo').attr src: "<%= asset_path('logo.png') %>" @@ -263,9 +263,9 @@ $('#logo').attr src: "<%= asset_path('logo.png') %>" ### Manifest Files and Directives -Sprockets uses manifest files to determine which assets to include and serve. These manifest files contain _directives_ -- instructions that tell Sprockets which files to require in order to build a single CSS or JavaScript file. With these directives, Sprockets loads the files specified, processes them if necessary, concatenates them into one single file and then compresses them (if +Rails.application.config.assets.compress+ is true). By serving one file rather than many, the load time of pages can be greatly reduced because the browser makes fewer requests. +Sprockets uses manifest files to determine which assets to include and serve. These manifest files contain _directives_ -- instructions that tell Sprockets which files to require in order to build a single CSS or JavaScript file. With these directives, Sprockets loads the files specified, processes them if necessary, concatenates them into one single file and then compresses them (if `Rails.application.config.assets.compress` is true). By serving one file rather than many, the load time of pages can be greatly reduced because the browser makes fewer requests. -For example, a new Rails application includes a default +app/assets/javascripts/application.js+ file which contains the following lines: +For example, a new Rails application includes a default `app/assets/javascripts/application.js` file which contains the following lines: ``` // ... @@ -274,15 +274,15 @@ For example, a new Rails application includes a default +app/assets/javascripts/ //= require_tree . ``` -In JavaScript files, the directives begin with +//=+. In this case, the file is using the +require+ and the +require_tree+ directives. The +require+ directive is used to tell Sprockets the files that you wish to require. Here, you are requiring the files +jquery.js+ and +jquery_ujs.js+ that are available somewhere in the search path for Sprockets. You need not supply the extensions explicitly. Sprockets assumes you are requiring a +.js+ file when done from within a +.js+ file. +In JavaScript files, the directives begin with `//=`. In this case, the file is using the `require` and the `require_tree` directives. The `require` directive is used to tell Sprockets the files that you wish to require. Here, you are requiring the files `jquery.js` and `jquery_ujs.js` that are available somewhere in the search path for Sprockets. You need not supply the extensions explicitly. Sprockets assumes you are requiring a `.js` file when done from within a `.js` file. -NOTE. In Rails 3.1 the +jquery-rails+ gem provides the +jquery.js+ and +jquery_ujs.js+ files via the asset pipeline. You won't see them in the application tree. +NOTE. In Rails 3.1 the `jquery-rails` gem provides the `jquery.js` and `jquery_ujs.js` files via the asset pipeline. You won't see them in the application tree. -The +require_tree+ directive tells Sprockets to recursively include _all_ JavaScript files in the specified directory into the output. These paths must be specified relative to the manifest file. You can also use the +require_directory+ directive which includes all JavaScript files only in the directory specified, without recursion. +The `require_tree` directive tells Sprockets to recursively include _all_ JavaScript files in the specified directory into the output. These paths must be specified relative to the manifest file. You can also use the `require_directory` directive which includes all JavaScript files only in the directory specified, without recursion. -Directives are processed top to bottom, but the order in which files are included by +require_tree+ is unspecified. You should not rely on any particular order among those. If you need to ensure some particular JavaScript ends up above some other in the concatenated file, require the prerequisite file first in the manifest. Note that the family of +require+ directives prevents files from being included twice in the output. +Directives are processed top to bottom, but the order in which files are included by `require_tree` is unspecified. You should not rely on any particular order among those. If you need to ensure some particular JavaScript ends up above some other in the concatenated file, require the prerequisite file first in the manifest. Note that the family of `require` directives prevents files from being included twice in the output. -Rails also creates a default +app/assets/stylesheets/application.css+ file which contains these lines: +Rails also creates a default `app/assets/stylesheets/application.css` file which contains these lines: ``` /* ... @@ -291,13 +291,13 @@ Rails also creates a default +app/assets/stylesheets/application.css+ file which */ ``` -The directives that work in the JavaScript files also work in stylesheets (though obviously including stylesheets rather than JavaScript files). The +require_tree+ directive in a CSS manifest works the same way as the JavaScript one, requiring all stylesheets from the current directory. +The directives that work in the JavaScript files also work in stylesheets (though obviously including stylesheets rather than JavaScript files). The `require_tree` directive in a CSS manifest works the same way as the JavaScript one, requiring all stylesheets from the current directory. -In this example +require_self+ is used. This puts the CSS contained within the file (if any) at the precise location of the +require_self+ call. If +require_self+ is called more than once, only the last call is respected. +In this example `require_self` is used. This puts the CSS contained within the file (if any) at the precise location of the `require_self` call. If `require_self` is called more than once, only the last call is respected. -NOTE. If you want to use multiple Sass files, you should generally use the "Sass +@import+ rule":http://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html#import instead of these Sprockets directives. Using Sprockets directives all Sass files exist within their own scope, making variables or mixins only available within the document they were defined in. +NOTE. If you want to use multiple Sass files, you should generally use the "Sass `@import` rule":http://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html#import instead of these Sprockets directives. Using Sprockets directives all Sass files exist within their own scope, making variables or mixins only available within the document they were defined in. -You can have as many manifest files as you need. For example the +admin.css+ and +admin.js+ manifest could contain the JS and CSS files that are used for the admin section of an application. +You can have as many manifest files as you need. For example the `admin.css` and `admin.js` manifest could contain the JS and CSS files that are used for the admin section of an application. The same remarks about ordering made above apply. In particular, you can specify individual files and they are compiled in the order specified. For example, you might concatenate three CSS files together this way: @@ -312,20 +312,20 @@ The same remarks about ordering made above apply. In particular, you can specify ### Preprocessing -The file extensions used on an asset determine what preprocessing is applied. When a controller or a scaffold is generated with the default Rails gemset, a CoffeeScript file and a SCSS file are generated in place of a regular JavaScript and CSS file. The example used before was a controller called "projects", which generated an +app/assets/javascripts/projects.js.coffee+ and an +app/assets/stylesheets/projects.css.scss+ file. +The file extensions used on an asset determine what preprocessing is applied. When a controller or a scaffold is generated with the default Rails gemset, a CoffeeScript file and a SCSS file are generated in place of a regular JavaScript and CSS file. The example used before was a controller called "projects", which generated an `app/assets/javascripts/projects.js.coffee` and an `app/assets/stylesheets/projects.css.scss` file. -When these files are requested, they are processed by the processors provided by the +coffee-script+ and +sass+ gems and then sent back to the browser as JavaScript and CSS respectively. +When these files are requested, they are processed by the processors provided by the `coffee-script` and `sass` gems and then sent back to the browser as JavaScript and CSS respectively. -Additional layers of preprocessing can be requested by adding other extensions, where each extension is processed in a right-to-left manner. These should be used in the order the processing should be applied. For example, a stylesheet called +app/assets/stylesheets/projects.css.scss.erb+ is first processed as ERB, then SCSS, and finally served as CSS. The same applies to a JavaScript file -- +app/assets/javascripts/projects.js.coffee.erb+ is processed as ERB, then CoffeeScript, and served as JavaScript. +Additional layers of preprocessing can be requested by adding other extensions, where each extension is processed in a right-to-left manner. These should be used in the order the processing should be applied. For example, a stylesheet called `app/assets/stylesheets/projects.css.scss.erb` is first processed as ERB, then SCSS, and finally served as CSS. The same applies to a JavaScript file -- `app/assets/javascripts/projects.js.coffee.erb` is processed as ERB, then CoffeeScript, and served as JavaScript. -Keep in mind that the order of these preprocessors is important. For example, if you called your JavaScript file +app/assets/javascripts/projects.js.erb.coffee+ then it would be processed with the CoffeeScript interpreter first, which wouldn't understand ERB and therefore you would run into problems. +Keep in mind that the order of these preprocessors is important. For example, if you called your JavaScript file `app/assets/javascripts/projects.js.erb.coffee` then it would be processed with the CoffeeScript interpreter first, which wouldn't understand ERB and therefore you would run into problems. In Development -------------- In development mode, assets are served as separate files in the order they are specified in the manifest file. -This manifest +app/assets/javascripts/application.js+: +This manifest `app/assets/javascripts/application.js`: ``` //= require core @@ -341,11 +341,11 @@ would generate this HTML: <script src="/assets/tickets.js?body=1"></script> ``` -The +body+ param is required by Sprockets. +The `body` param is required by Sprockets. ### Turning Debugging off -You can turn off debug mode by updating +config/environments/development.rb+ to include: +You can turn off debug mode by updating `config/environments/development.rb` to include: ```ruby config.assets.debug = false @@ -357,7 +357,7 @@ When debug mode is off, Sprockets concatenates and runs the necessary preprocess <script src="/assets/application.js"></script> ``` -Assets are compiled and cached on the first request after the server is started. Sprockets sets a +must-revalidate+ Cache-Control HTTP header to reduce request overhead on subsequent requests -- on these the browser gets a 304 (Not Modified) response. +Assets are compiled and cached on the first request after the server is started. Sprockets sets a `must-revalidate` Cache-Control HTTP header to reduce request overhead on subsequent requests -- on these the browser gets a 304 (Not Modified) response. If any of the files in the manifest have changed between requests, the server responds with a new compiled file. @@ -368,7 +368,7 @@ Debug mode can also be enabled in the Rails helper methods: <%= javascript_include_tag "application", :debug => true %> ``` -The +:debug+ option is redundant if debug mode is on. +The `:debug` option is redundant if debug mode is on. You could potentially also enable compression in development mode as a sanity check, and disable it on-demand as required for debugging. @@ -393,7 +393,7 @@ generates something like this: <link href="/assets/application-4dd5b109ee3439da54f5bdfd78a80473.css" media="screen" rel="stylesheet" /> ``` -The fingerprinting behavior is controlled by the setting of +config.assets.digest+ setting in Rails (which defaults to +true+ for production and +false+ for everything else). +The fingerprinting behavior is controlled by the setting of `config.assets.digest` setting in Rails (which defaults to `true` for production and `false` for everything else). NOTE: Under normal circumstances the default option should not be changed. If there are no digests in the filenames, and far-future headers are set, remote clients will never know to refetch the files when their content changes. @@ -401,7 +401,7 @@ NOTE: Under normal circumstances the default option should not be changed. If th Rails comes bundled with a rake task to compile the asset manifests and other files in the pipeline to the disk. -Compiled assets are written to the location specified in +config.assets.prefix+. By default, this is the +public/assets+ directory. +Compiled assets are written to the location specified in `config.assets.prefix`. By default, this is the `public/assets` directory. You can call this task on the server during deployment to create compiled versions of your assets directly on the server. See the next section for information on compiling locally. @@ -412,37 +412,37 @@ bundle exec rake assets:precompile ``` For faster asset precompiles, you can partially load your application by setting -+config.assets.initialize_on_precompile+ to false in +config/application.rb+, though in that case templates +`config.assets.initialize_on_precompile` to false in `config/application.rb`, though in that case templates cannot see application objects or methods. *Heroku requires this to be false.* -WARNING: If you set +config.assets.initialize_on_precompile+ to false, be sure to -test +rake assets:precompile+ locally before deploying. It may expose bugs where +WARNING: If you set `config.assets.initialize_on_precompile` to false, be sure to +test `rake assets:precompile` locally before deploying. It may expose bugs where your assets reference application objects or methods, since those are still in scope in development mode regardless of the value of this flag. Changing this flag also affects engines. Engines can define assets for precompilation as well. Since the complete environment is not loaded, engines (or other gems) will not be loaded, which can cause missing assets. -Capistrano (v2.8.0 and above) includes a recipe to handle this in deployment. Add the following line to +Capfile+: +Capistrano (v2.8.0 and above) includes a recipe to handle this in deployment. Add the following line to `Capfile`: ```erb load 'deploy/assets' ``` -This links the folder specified in +config.assets.prefix+ to +shared/assets+. If you already use this shared folder you'll need to write your own deployment task. +This links the folder specified in `config.assets.prefix` to `shared/assets`. If you already use this shared folder you'll need to write your own deployment task. It is important that this folder is shared between deployments so that remotely cached pages that reference the old compiled assets still work for the life of the cached page. -NOTE. If you are precompiling your assets locally, you can use +bundle install --without assets+ on the server to avoid installing the assets gems (the gems in the assets group in the Gemfile). +NOTE. If you are precompiling your assets locally, you can use `bundle install --without assets` on the server to avoid installing the assets gems (the gems in the assets group in the Gemfile). -The default matcher for compiling files includes +application.js+, +application.css+ and all non-JS/CSS files (this will include all image assets automatically): +The default matcher for compiling files includes `application.js`, `application.css` and all non-JS/CSS files (this will include all image assets automatically): ```ruby [ Proc.new{ |path| !%w(.js .css).include?(File.extname(path)) }, /application.(css|js)$/ ] ``` -NOTE. The matcher (and other members of the precompile array; see below) is applied to final compiled file names. This means that anything that compiles to JS/CSS is excluded, as well as raw JS/CSS files; for example, +.coffee+ and +.scss+ files are *not* automatically included as they compile to JS/CSS. +NOTE. The matcher (and other members of the precompile array; see below) is applied to final compiled file names. This means that anything that compiles to JS/CSS is excluded, as well as raw JS/CSS files; for example, `.coffee` and `.scss` files are *not* automatically included as they compile to JS/CSS. -If you have other manifests or individual stylesheets and JavaScript files to include, you can add them to the +precompile+ array: +If you have other manifests or individual stylesheets and JavaScript files to include, you can add them to the `precompile` array: ```erb config.assets.precompile += ['admin.js', 'admin.css', 'swfObject.js'] @@ -450,7 +450,7 @@ config.assets.precompile += ['admin.js', 'admin.css', 'swfObject.js'] NOTE. Always specify an expected compiled filename that ends with js or css, even if you want to add Sass or CoffeeScript files to the precompile array. -The rake task also generates a +manifest.yml+ that contains a list with all your assets and their respective fingerprints. This is used by the Rails helper methods to avoid handing the mapping requests back to Sprockets. A typical manifest file looks like: +The rake task also generates a `manifest.yml` that contains a list with all your assets and their respective fingerprints. This is used by the Rails helper methods to avoid handing the mapping requests back to Sprockets. A typical manifest file looks like: ``` --- @@ -461,9 +461,9 @@ application.js: application-3fdab497b8fb70d20cfc5495239dfc29.js application.css: application-8af74128f904600e41a6e39241464e03.css ``` -The default location for the manifest is the root of the location specified in +config.assets.prefix+ ('/assets' by default). +The default location for the manifest is the root of the location specified in `config.assets.prefix` ('/assets' by default). -This can be changed with the +config.assets.manifest+ option. A fully specified path is required: +This can be changed with the `config.assets.manifest` option. A fully specified path is required: ```erb config.assets.manifest = '/path/to/some/other/location' @@ -478,7 +478,7 @@ Precompiled assets exist on the filesystem and are served directly by your web s For Apache: ``` -# The Expires* directives requires the Apache module +mod_expires+ to be enabled. +# The Expires* directives requires the Apache module `mod_expires` to be enabled. <LocationMatch "^/assets/.*$"> # Use of ETag is discouraged when Last-Modified is present Header unset ETag @@ -505,7 +505,7 @@ location ~ ^/assets/ { When files are precompiled, Sprockets also creates a "gzipped":http://en.wikipedia.org/wiki/Gzip (.gz) version of your assets. Web servers are typically configured to use a moderate compression ratio as a compromise, but since precompilation happens once, Sprockets uses the maximum compression ratio, thus reducing the size of the data transfer to the minimum. On the other hand, web servers can be configured to serve compressed content directly from disk, rather than deflating non-compressed files themselves. -Nginx is able to do this automatically enabling +gzip_static+: +Nginx is able to do this automatically enabling `gzip_static`: ``` location ~ ^/(assets)/ { @@ -516,7 +516,7 @@ location ~ ^/(assets)/ { } ``` -This directive is available if the core module that provides this feature was compiled with the web server. Ubuntu packages, even +nginx-light+ have the module compiled. Otherwise, you may need to perform a manual compilation: +This directive is available if the core module that provides this feature was compiled with the web server. Ubuntu packages, even `nginx-light` have the module compiled. Otherwise, you may need to perform a manual compilation: ``` ./configure --with-http_gzip_static_module @@ -553,9 +553,9 @@ You will also need this in application.rb: config.assets.initialize_on_precompile = false ``` -The +prefix+ change makes Rails use a different URL for serving assets in development mode, and pass all requests to Sprockets. The prefix is still set to +/assets+ in the production environment. Without this change, the application would serve the precompiled assets from +public/assets+ in development, and you would not see any local changes until you compile assets again. +The `prefix` change makes Rails use a different URL for serving assets in development mode, and pass all requests to Sprockets. The prefix is still set to `/assets` in the production environment. Without this change, the application would serve the precompiled assets from `public/assets` in development, and you would not see any local changes until you compile assets again. -The +initialize_on_precompile+ change tells the precompile task to run without invoking Rails. This is because the precompile task runs in production mode by default, and will attempt to connect to your specified production database. Please note that you cannot have code in pipeline files that relies on Rails resources (such as the database) when compiling locally with this option. +The `initialize_on_precompile` change tells the precompile task to run without invoking Rails. This is because the precompile task runs in production mode by default, and will attempt to connect to your specified production database. Please note that you cannot have code in pipeline files that relies on Rails resources (such as the database) when compiling locally with this option. You will also need to ensure that any compressors or minifiers are available on your development system. @@ -573,7 +573,7 @@ config.assets.compile = true On the first request the assets are compiled and cached as outlined in development above, and the manifest names used in the helpers are altered to include the MD5 hash. -Sprockets also sets the +Cache-Control+ HTTP header to +max-age=31536000+. This signals all caches between your server and the client browser that this content (the file served) can be cached for 1 year. The effect of this is to reduce the number of requests for this asset from your server; the asset has a good chance of being in the local browser cache or some intermediate cache. +Sprockets also sets the `Cache-Control` HTTP header to `max-age=31536000`. This signals all caches between your server and the client browser that this content (the file served) can be cached for 1 year. The effect of this is to reduce the number of requests for this asset from your server; the asset has a good chance of being in the local browser cache or some intermediate cache. This mode uses more memory, performs more poorly than the default and is not recommended. @@ -592,33 +592,33 @@ Customizing the Pipeline There is currently one option for compressing CSS, YUI. The "YUI CSS compressor":http://developer.yahoo.com/yui/compressor/css.html provides minification. -The following line enables YUI compression, and requires the +yui-compressor+ gem. +The following line enables YUI compression, and requires the `yui-compressor` gem. ```erb config.assets.css_compressor = :yui ``` -The +config.assets.compress+ must be set to +true+ to enable CSS compression. +The `config.assets.compress` must be set to `true` to enable CSS compression. ### JavaScript Compression -Possible options for JavaScript compression are +:closure+, +:uglifier+ and +:yui+. These require the use of the +closure-compiler+, +uglifier+ or +yui-compressor+ gems, respectively. +Possible options for JavaScript compression are `:closure`, `:uglifier` and `:yui`. These require the use of the `closure-compiler`, `uglifier` or `yui-compressor` gems, respectively. -The default Gemfile includes "uglifier":https://github.com/lautis/uglifier. This gem wraps "UglifierJS":https://github.com/mishoo/UglifyJS (written for NodeJS) in Ruby. It compresses your code by removing white space. It also includes other optimizations such as changing your +if+ and +else+ statements to ternary operators where possible. +The default Gemfile includes "uglifier":https://github.com/lautis/uglifier. This gem wraps "UglifierJS":https://github.com/mishoo/UglifyJS (written for NodeJS) in Ruby. It compresses your code by removing white space. It also includes other optimizations such as changing your `if` and `else` statements to ternary operators where possible. -The following line invokes +uglifier+ for JavaScript compression. +The following line invokes `uglifier` for JavaScript compression. ```erb config.assets.js_compressor = :uglifier ``` -Note that +config.assets.compress+ must be set to +true+ to enable JavaScript compression +Note that `config.assets.compress` must be set to `true` to enable JavaScript compression -NOTE: You will need an "ExecJS":https://github.com/sstephenson/execjs#readme supported runtime in order to use +uglifier+. If you are using Mac OS X or Windows you have a JavaScript runtime installed in your operating system. Check the "ExecJS":https://github.com/sstephenson/execjs#readme documentation for information on all of the supported JavaScript runtimes. +NOTE: You will need an "ExecJS":https://github.com/sstephenson/execjs#readme supported runtime in order to use `uglifier`. If you are using Mac OS X or Windows you have a JavaScript runtime installed in your operating system. Check the "ExecJS":https://github.com/sstephenson/execjs#readme documentation for information on all of the supported JavaScript runtimes. ### Using Your Own Compressor -The compressor config settings for CSS and JavaScript also take any object. This object must have a +compress+ method that takes a string as the sole argument and it must return a string. +The compressor config settings for CSS and JavaScript also take any object. This object must have a `compress` method that takes a string as the sole argument and it must return a string. ```erb class Transformer @@ -628,7 +628,7 @@ class Transformer end ``` -To enable this, pass a +new+ object to the config option in +application.rb+: +To enable this, pass a `new` object to the config option in `application.rb`: ```erb config.assets.css_compressor = Transformer.new @@ -637,7 +637,7 @@ config.assets.css_compressor = Transformer.new ### Changing the _assets_ Path -The public path that Sprockets uses by default is +/assets+. +The public path that Sprockets uses by default is `/assets`. This can be changed to something else: @@ -658,12 +658,12 @@ Apache and nginx support this option, which can be enabled in `config/environmen # config.action_dispatch.x_sendfile_header = 'X-Accel-Redirect' # for nginx ``` -WARNING: If you are upgrading an existing application and intend to use this option, take care to paste this configuration option only into +production.rb+ and any other environments you define with production behavior (not +application.rb+). +WARNING: If you are upgrading an existing application and intend to use this option, take care to paste this configuration option only into `production.rb` and any other environments you define with production behavior (not `application.rb`). Assets Cache Store ------------------ -The default Rails cache store will be used by Sprockets to cache assets in development and production. This can be changed by setting +config.assets.cache_store+. +The default Rails cache store will be used by Sprockets to cache assets in development and production. This can be changed by setting `config.assets.cache_store`. ```ruby config.assets.cache_store = :memory_store @@ -680,7 +680,7 @@ Adding Assets to Your Gems Assets can also come from external sources in the form of gems. -A good example of this is the +jquery-rails+ gem which comes with Rails as the standard JavaScript library gem. This gem contains an engine class which inherits from +Rails::Engine+. By doing this, Rails is informed that the directory for this gem may contain assets and the +app/assets+, +lib/assets+ and +vendor/assets+ directories of this engine are added to the search path of Sprockets. +A good example of this is the `jquery-rails` gem which comes with Rails as the standard JavaScript library gem. This gem contains an engine class which inherits from `Rails::Engine`. By doing this, Rails is informed that the directory for this gem may contain assets and the `app/assets`, `lib/assets` and `vendor/assets` directories of this engine are added to the search path of Sprockets. Making Your Library or Gem a Pre-Processor ------------------------------------------ @@ -690,13 +690,13 @@ TODO: Registering gems on "Tilt":https://github.com/rtomayko/tilt enabling Sproc Upgrading from Old Versions of Rails ------------------------------------ -There are a few issues when upgrading. The first is moving the files from +public/+ to the new locations. See "Asset Organization":#asset-organization above for guidance on the correct locations for different file types. +There are a few issues when upgrading. The first is moving the files from `public/` to the new locations. See "Asset Organization":#asset-organization above for guidance on the correct locations for different file types. -Next will be avoiding duplicate JavaScript files. Since jQuery is the default JavaScript library from Rails 3.1 onwards, you don't need to copy +jquery.js+ into +app/assets+ and it will be included automatically. +Next will be avoiding duplicate JavaScript files. Since jQuery is the default JavaScript library from Rails 3.1 onwards, you don't need to copy `jquery.js` into `app/assets` and it will be included automatically. The third is updating the various environment files with the correct default options. The following changes reflect the defaults in version 3.1.0. -In +application.rb+: +In `application.rb`: ```erb # Enable the asset pipeline @@ -709,7 +709,7 @@ config.assets.version = '1.0' # config.assets.prefix = "/assets" ``` -In +development.rb+: +In `development.rb`: ```erb # Do not compress assets @@ -719,7 +719,7 @@ config.assets.compress = false config.assets.debug = true ``` -And in +production.rb+: +And in `production.rb`: ```erb # Compress JavaScripts and CSS @@ -742,9 +742,9 @@ config.assets.digest = true # config.assets.precompile += %w( search.js ) ``` -You should not need to change +test.rb+. The defaults in the test environment are: +config.assets.compile+ is true and +config.assets.compress+, +config.assets.debug+ and +config.assets.digest+ are false. +You should not need to change `test.rb`. The defaults in the test environment are: `config.assets.compile` is true and `config.assets.compress`, `config.assets.debug` and `config.assets.digest` are false. -The following should also be added to +Gemfile+: +The following should also be added to `Gemfile`: ``` # Gems used only for assets and not required @@ -756,7 +756,7 @@ group :assets do end ``` -If you use the +assets+ group with Bundler, please make sure that your +config/application.rb+ has the following Bundler require statement: +If you use the `assets` group with Bundler, please make sure that your `config/application.rb` has the following Bundler require statement: ```ruby if defined?(Bundler) diff --git a/guides/source/association_basics.md b/guides/source/association_basics.md index 215ff0c7f9..17f41196fe 100644 --- a/guides/source/association_basics.md +++ b/guides/source/association_basics.md @@ -68,20 +68,20 @@ To learn more about the different types of associations, read the next section o The Types of Associations ------------------------- -In Rails, an _association_ is a connection between two Active Record models. Associations are implemented using macro-style calls, so that you can declaratively add features to your models. For example, by declaring that one model +belongs_to+ another, you instruct Rails to maintain Primary Key–Foreign Key information between instances of the two models, and you also get a number of utility methods added to your model. Rails supports six types of associations: +In Rails, an _association_ is a connection between two Active Record models. Associations are implemented using macro-style calls, so that you can declaratively add features to your models. For example, by declaring that one model `belongs_to` another, you instruct Rails to maintain Primary Key–Foreign Key information between instances of the two models, and you also get a number of utility methods added to your model. Rails supports six types of associations: -* +belongs_to+ -* +has_one+ -* +has_many+ -* +has_many :through+ -* +has_one :through+ -* +has_and_belongs_to_many+ +* `belongs_to` +* `has_one` +* `has_many` +* `has_many :through` +* `has_one :through` +* `has_and_belongs_to_many` In the remainder of this guide, you'll learn how to declare and use the various forms of associations. But first, a quick introduction to the situations where each association type is appropriate. -### The +belongs_to+ Association +### The `belongs_to` Association -A +belongs_to+ association sets up a one-to-one connection with another model, such that each instance of the declaring model "belongs to" one instance of the other model. For example, if your application includes customers and orders, and each order can be assigned to exactly one customer, you'd declare the order model this way: +A `belongs_to` association sets up a one-to-one connection with another model, such that each instance of the declaring model "belongs to" one instance of the other model. For example, if your application includes customers and orders, and each order can be assigned to exactly one customer, you'd declare the order model this way: ```ruby class Order < ActiveRecord::Base @@ -91,11 +91,11 @@ end !images/belongs_to.png(belongs_to Association Diagram)! -NOTE: +belongs_to+ associations _must_ use the singular term. If you used the pluralized form in the above example for the +customer+ association in the +Order+ model, you would be told that there was an "uninitialized constant Order::Customers". This is because Rails automatically infers the class name from the association name. If the association name is wrongly pluralized, then the inferred class will be wrongly pluralized too. +NOTE: `belongs_to` associations _must_ use the singular term. If you used the pluralized form in the above example for the `customer` association in the `Order` model, you would be told that there was an "uninitialized constant Order::Customers". This is because Rails automatically infers the class name from the association name. If the association name is wrongly pluralized, then the inferred class will be wrongly pluralized too. -### The +has_one+ Association +### The `has_one` Association -A +has_one+ association also sets up a one-to-one connection with another model, but with somewhat different semantics (and consequences). This association indicates that each instance of a model contains or possesses one instance of another model. For example, if each supplier in your application has only one account, you'd declare the supplier model like this: +A `has_one` association also sets up a one-to-one connection with another model, but with somewhat different semantics (and consequences). This association indicates that each instance of a model contains or possesses one instance of another model. For example, if each supplier in your application has only one account, you'd declare the supplier model like this: ```ruby class Supplier < ActiveRecord::Base @@ -105,9 +105,9 @@ end !images/has_one.png(has_one Association Diagram)! -### The +has_many+ Association +### The `has_many` Association -A +has_many+ association indicates a one-to-many connection with another model. You'll often find this association on the "other side" of a +belongs_to+ association. This association indicates that each instance of the model has zero or more instances of another model. For example, in an application containing customers and orders, the customer model could be declared like this: +A `has_many` association indicates a one-to-many connection with another model. You'll often find this association on the "other side" of a `belongs_to` association. This association indicates that each instance of the model has zero or more instances of another model. For example, in an application containing customers and orders, the customer model could be declared like this: ```ruby class Customer < ActiveRecord::Base @@ -115,13 +115,13 @@ class Customer < ActiveRecord::Base end ``` -NOTE: The name of the other model is pluralized when declaring a +has_many+ association. +NOTE: The name of the other model is pluralized when declaring a `has_many` association. !images/has_many.png(has_many Association Diagram)! -### The +has_many :through+ Association +### The `has_many :through` Association -A +has_many :through+ association is often used to set up a many-to-many connection with another model. This association indicates that the declaring model can be matched with zero or more instances of another model by proceeding _through_ a third model. For example, consider a medical practice where patients make appointments to see physicians. The relevant association declarations could look like this: +A `has_many :through` association is often used to set up a many-to-many connection with another model. This association indicates that the declaring model can be matched with zero or more instances of another model by proceeding _through_ a third model. For example, consider a medical practice where patients make appointments to see physicians. The relevant association declarations could look like this: ```ruby class Physician < ActiveRecord::Base @@ -152,7 +152,7 @@ new join models are created for newly associated objects, and if some are gone t WARNING: Automatic deletion of join models is direct, no destroy callbacks are triggered. -The +has_many :through+ association is also useful for setting up "shortcuts" through nested +has_many+ associations. For example, if a document has many sections, and a section has many paragraphs, you may sometimes want to get a simple collection of all paragraphs in the document. You could set that up this way: +The `has_many :through` association is also useful for setting up "shortcuts" through nested `has_many` associations. For example, if a document has many sections, and a section has many paragraphs, you may sometimes want to get a simple collection of all paragraphs in the document. You could set that up this way: ```ruby class Document < ActiveRecord::Base @@ -170,15 +170,15 @@ class Paragraph < ActiveRecord::Base end ``` -With +:through => :sections+ specified, Rails will now understand: +With `:through => :sections` specified, Rails will now understand: ```ruby @document.paragraphs ``` -### The +has_one :through+ Association +### The `has_one :through` Association -A +has_one :through+ association sets up a one-to-one connection with another model. This association indicates that the declaring model can be matched with one instance of another model by proceeding _through_ a third model. For example, if each supplier has one account, and each account is associated with one account history, then the customer model could look like this: +A `has_one :through` association sets up a one-to-one connection with another model. This association indicates that the declaring model can be matched with one instance of another model by proceeding _through_ a third model. For example, if each supplier has one account, and each account is associated with one account history, then the customer model could look like this: ```ruby class Supplier < ActiveRecord::Base @@ -198,9 +198,9 @@ end !images/has_one_through.png(has_one :through Association Diagram)! -### The +has_and_belongs_to_many+ Association +### The `has_and_belongs_to_many` Association -A +has_and_belongs_to_many+ association creates a direct many-to-many connection with another model, with no intervening model. For example, if your application includes assemblies and parts, with each assembly having many parts and each part appearing in many assemblies, you could declare the models this way: +A `has_and_belongs_to_many` association creates a direct many-to-many connection with another model, with no intervening model. For example, if your application includes assemblies and parts, with each assembly having many parts and each part appearing in many assemblies, you could declare the models this way: ```ruby class Assembly < ActiveRecord::Base @@ -214,11 +214,11 @@ end !images/habtm.png(has_and_belongs_to_many Association Diagram)! -### Choosing Between +belongs_to+ and +has_one+ +### Choosing Between `belongs_to` and `has_one` -If you want to set up a one-to-one relationship between two models, you'll need to add +belongs_to+ to one, and +has_one+ to the other. How do you know which is which? +If you want to set up a one-to-one relationship between two models, you'll need to add `belongs_to` to one, and `has_one` to the other. How do you know which is which? -The distinction is in where you place the foreign key (it goes on the table for the class declaring the +belongs_to+ association), but you should give some thought to the actual meaning of the data as well. The +has_one+ relationship says that one of something is yours - that is, that something points back to you. For example, it makes more sense to say that a supplier owns an account than that an account owns a supplier. This suggests that the correct relationships are like this: +The distinction is in where you place the foreign key (it goes on the table for the class declaring the `belongs_to` association), but you should give some thought to the actual meaning of the data as well. The `has_one` relationship says that one of something is yours - that is, that something points back to you. For example, it makes more sense to say that a supplier owns an account than that an account owns a supplier. This suggests that the correct relationships are like this: ```ruby class Supplier < ActiveRecord::Base @@ -249,11 +249,11 @@ class CreateSuppliers < ActiveRecord::Migration end ``` -NOTE: Using +t.integer :supplier_id+ makes the foreign key naming obvious and explicit. In current versions of Rails, you can abstract away this implementation detail by using +t.references :supplier+ instead. +NOTE: Using `t.integer :supplier_id` makes the foreign key naming obvious and explicit. In current versions of Rails, you can abstract away this implementation detail by using `t.references :supplier` instead. -### Choosing Between +has_many :through+ and +has_and_belongs_to_many+ +### Choosing Between `has_many :through` and `has_and_belongs_to_many` -Rails offers two different ways to declare a many-to-many relationship between models. The simpler way is to use +has_and_belongs_to_many+, which allows you to make the association directly: +Rails offers two different ways to declare a many-to-many relationship between models. The simpler way is to use `has_and_belongs_to_many`, which allows you to make the association directly: ```ruby class Assembly < ActiveRecord::Base @@ -265,7 +265,7 @@ class Part < ActiveRecord::Base end ``` -The second way to declare a many-to-many relationship is to use +has_many :through+. This makes the association indirectly, through a join model: +The second way to declare a many-to-many relationship is to use `has_many :through`. This makes the association indirectly, through a join model: ```ruby class Assembly < ActiveRecord::Base @@ -284,9 +284,9 @@ class Part < ActiveRecord::Base end ``` -The simplest rule of thumb is that you should set up a +has_many :through+ relationship if you need to work with the relationship model as an independent entity. If you don't need to do anything with the relationship model, it may be simpler to set up a +has_and_belongs_to_many+ relationship (though you'll need to remember to create the joining table in the database). +The simplest rule of thumb is that you should set up a `has_many :through` relationship if you need to work with the relationship model as an independent entity. If you don't need to do anything with the relationship model, it may be simpler to set up a `has_and_belongs_to_many` relationship (though you'll need to remember to create the joining table in the database). -You should use +has_many :through+ if you need validations, callbacks, or extra attributes on the join model. +You should use `has_many :through` if you need validations, callbacks, or extra attributes on the join model. ### Polymorphic Associations @@ -306,11 +306,11 @@ class Product < ActiveRecord::Base end ``` -You can think of a polymorphic +belongs_to+ declaration as setting up an interface that any other model can use. From an instance of the +Employee+ model, you can retrieve a collection of pictures: +@employee.pictures+. +You can think of a polymorphic `belongs_to` declaration as setting up an interface that any other model can use. From an instance of the `Employee` model, you can retrieve a collection of pictures: `@employee.pictures`. -Similarly, you can retrieve +@product.pictures+. +Similarly, you can retrieve `@product.pictures`. -If you have an instance of the +Picture+ model, you can get to its parent via +@picture.imageable+. To make this work, you need to declare both a foreign key column and a type column in the model that declares the polymorphic interface: +If you have an instance of the `Picture` model, you can get to its parent via `@picture.imageable`. To make this work, you need to declare both a foreign key column and a type column in the model that declares the polymorphic interface: ```ruby class CreatePictures < ActiveRecord::Migration @@ -325,7 +325,7 @@ class CreatePictures < ActiveRecord::Migration end ``` -This migration can be simplified by using the +t.references+ form: +This migration can be simplified by using the `t.references` form: ```ruby class CreatePictures < ActiveRecord::Migration @@ -353,7 +353,7 @@ class Employee < ActiveRecord::Base end ``` -With this setup, you can retrieve +@employee.subordinates+ and +@employee.manager+. +With this setup, you can retrieve `@employee.subordinates` and `@employee.manager`. Tips, Tricks, and Warnings -------------------------- @@ -376,7 +376,7 @@ customer.orders.size # uses the cached copy of orders customer.orders.empty? # uses the cached copy of orders ``` -But what if you want to reload the cache, because data might have been changed by some other part of the application? Just pass +true+ to the association call: +But what if you want to reload the cache, because data might have been changed by some other part of the application? Just pass `true` to the association call: ```ruby customer.orders # retrieves orders from the database @@ -387,15 +387,15 @@ customer.orders(true).empty? # discards the cached copy of orders ### Avoiding Name Collisions -You are not free to use just any name for your associations. Because creating an association adds a method with that name to the model, it is a bad idea to give an association a name that is already used for an instance method of +ActiveRecord::Base+. The association method would override the base method and break things. For instance, +attributes+ or +connection+ are bad names for associations. +You are not free to use just any name for your associations. Because creating an association adds a method with that name to the model, it is a bad idea to give an association a name that is already used for an instance method of `ActiveRecord::Base`. The association method would override the base method and break things. For instance, `attributes` or `connection` are bad names for associations. ### Updating the Schema -Associations are extremely useful, but they are not magic. You are responsible for maintaining your database schema to match your associations. In practice, this means two things, depending on what sort of associations you are creating. For +belongs_to+ associations you need to create foreign keys, and for +has_and_belongs_to_many+ associations you need to create the appropriate join table. +Associations are extremely useful, but they are not magic. You are responsible for maintaining your database schema to match your associations. In practice, this means two things, depending on what sort of associations you are creating. For `belongs_to` associations you need to create foreign keys, and for `has_and_belongs_to_many` associations you need to create the appropriate join table. -#### Creating Foreign Keys for +belongs_to+ Associations +#### Creating Foreign Keys for `belongs_to` Associations -When you declare a +belongs_to+ association, you need to create foreign keys as appropriate. For example, consider this model: +When you declare a `belongs_to` association, you need to create foreign keys as appropriate. For example, consider this model: ```ruby class Order < ActiveRecord::Base @@ -417,13 +417,13 @@ class CreateOrders < ActiveRecord::Migration end ``` -If you create an association some time after you build the underlying model, you need to remember to create an +add_column+ migration to provide the necessary foreign key. +If you create an association some time after you build the underlying model, you need to remember to create an `add_column` migration to provide the necessary foreign key. -#### Creating Join Tables for +has_and_belongs_to_many+ Associations +#### Creating Join Tables for `has_and_belongs_to_many` Associations -If you create a +has_and_belongs_to_many+ association, you need to explicitly create the joining table. Unless the name of the join table is explicitly specified by using the +:join_table+ option, Active Record creates the name by using the lexical order of the class names. So a join between customer and order models will give the default join table name of "customers_orders" because "c" outranks "o" in lexical ordering. +If you create a `has_and_belongs_to_many` association, you need to explicitly create the joining table. Unless the name of the join table is explicitly specified by using the `:join_table` option, Active Record creates the name by using the lexical order of the class names. So a join between customer and order models will give the default join table name of "customers_orders" because "c" outranks "o" in lexical ordering. -WARNING: The precedence between model names is calculated using the +<+ operator for +String+. This means that if the strings are of different lengths, and the strings are equal when compared up to the shortest length, then the longer string is considered of higher lexical precedence than the shorter one. For example, one would expect the tables "paper_boxes" and "papers" to generate a join table name of "papers_paper_boxes" because of the length of the name "paper_boxes", but it in fact generates a join table name of "paper_boxes_papers" (because the underscore '_' is lexicographically _less_ than 's' in common encodings). +WARNING: The precedence between model names is calculated using the `<` operator for `String`. This means that if the strings are of different lengths, and the strings are equal when compared up to the shortest length, then the longer string is considered of higher lexical precedence than the shorter one. For example, one would expect the tables "paper_boxes" and "papers" to generate a join table name of "papers_paper_boxes" because of the length of the name "paper_boxes", but it in fact generates a join table name of "paper_boxes_papers" (because the underscore '_' is lexicographically _less_ than 's' in common encodings). Whatever the name, you must manually generate the join table with an appropriate migration. For example, consider these associations: @@ -437,7 +437,7 @@ class Part < ActiveRecord::Base end ``` -These need to be backed up by a migration to create the +assemblies_parts+ table. This table should be created without a primary key: +These need to be backed up by a migration to create the `assemblies_parts` table. This table should be created without a primary key: ```ruby class CreateAssemblyPartJoinTable < ActiveRecord::Migration @@ -450,7 +450,7 @@ class CreateAssemblyPartJoinTable < ActiveRecord::Migration end ``` -We pass +:id => false+ to +create_table+ because that table does not represent a model. That's required for the association to work properly. If you observe any strange behavior in a +has_and_belongs_to_many+ association like mangled models IDs, or exceptions about conflicting IDs chances are you forgot that bit. +We pass `:id => false` to `create_table` because that table does not represent a model. That's required for the association to work properly. If you observe any strange behavior in a `has_and_belongs_to_many` association like mangled models IDs, or exceptions about conflicting IDs chances are you forgot that bit. ### Controlling Association Scope @@ -470,7 +470,7 @@ module MyApplication end ``` -This will work fine, because both the +Supplier+ and the +Account+ class are defined within the same scope. But the following will _not_ work, because +Supplier+ and +Account+ are defined in different scopes: +This will work fine, because both the `Supplier` and the `Account` class are defined within the same scope. But the following will _not_ work, because `Supplier` and `Account` are defined in different scopes: ```ruby module MyApplication @@ -532,7 +532,7 @@ c.first_name = 'Manny' c.first_name == o.customer.first_name # => false ``` -This happens because c and o.customer are two different in-memory representations of the same data, and neither one is automatically refreshed from changes to the other. Active Record provides the +:inverse_of+ option so that you can inform it of these relations: +This happens because c and o.customer are two different in-memory representations of the same data, and neither one is automatically refreshed from changes to the other. Active Record provides the `:inverse_of` option so that you can inform it of these relations: ```ruby class Customer < ActiveRecord::Base @@ -554,32 +554,32 @@ c.first_name = 'Manny' c.first_name == o.customer.first_name # => true ``` -There are a few limitations to +inverse_of+ support: +There are a few limitations to `inverse_of` support: * They do not work with `:through` associations. * They do not work with `:polymorphic` associations. * They do not work with `:as` associations. -* For +belongs_to+ associations, +has_many+ inverse associations are ignored. +* For `belongs_to` associations, `has_many` inverse associations are ignored. Detailed Association Reference ------------------------------ The following sections give the details of each type of association, including the methods that they add and the options that you can use when declaring an association. -### +belongs_to+ Association Reference +### `belongs_to` Association Reference -The +belongs_to+ association creates a one-to-one match with another model. In database terms, this association says that this class contains the foreign key. If the other class contains the foreign key, then you should use +has_one+ instead. +The `belongs_to` association creates a one-to-one match with another model. In database terms, this association says that this class contains the foreign key. If the other class contains the foreign key, then you should use `has_one` instead. -#### Methods Added by +belongs_to+ +#### Methods Added by `belongs_to` -When you declare a +belongs_to+ association, the declaring class automatically gains four methods related to the association: +When you declare a `belongs_to` association, the declaring class automatically gains four methods related to the association: * `<em>association</em>(force_reload = false)` * `<em>association</em>=(associate)` * `build_<em>association</em>(attributes = {})` * `create_<em>association</em>(attributes = {})` -In all of these methods, `<em>association</em>` is replaced with the symbol passed as the first argument to +belongs_to+. For example, given the declaration: +In all of these methods, `<em>association</em>` is replaced with the symbol passed as the first argument to `belongs_to`. For example, given the declaration: ```ruby class Order < ActiveRecord::Base @@ -596,17 +596,17 @@ build_customer create_customer ``` -NOTE: When initializing a new +has_one+ or +belongs_to+ association you must use the +build_+ prefix to build the association, rather than the +association.build+ method that would be used for +has_many+ or +has_and_belongs_to_many+ associations. To create one, use the +create_+ prefix. +NOTE: When initializing a new `has_one` or `belongs_to` association you must use the `build_` prefix to build the association, rather than the `association.build` method that would be used for `has_many` or `has_and_belongs_to_many` associations. To create one, use the `create_` prefix. ##### `<em>association</em>(force_reload = false)` -The `<em>association</em>` method returns the associated object, if any. If no associated object is found, it returns +nil+. +The `<em>association</em>` method returns the associated object, if any. If no associated object is found, it returns `nil`. ```ruby @customer = @order.customer ``` -If the associated object has already been retrieved from the database for this object, the cached version will be returned. To override this behavior (and force a database read), pass +true+ as the +force_reload+ argument. +If the associated object has already been retrieved from the database for this object, the cached version will be returned. To override this behavior (and force a database read), pass `true` as the `force_reload` argument. ##### `_association_=(associate)` @@ -635,9 +635,9 @@ The `create_<em>association</em>` method returns a new object of the associated ``` -#### Options for +belongs_to+ +#### Options for `belongs_to` -While Rails uses intelligent defaults that will work well in most situations, there may be times when you want to customize the behavior of the +belongs_to+ association reference. Such customizations can easily be accomplished by passing options and scope blocks when you create the association. For example, this assocation uses two such options: +While Rails uses intelligent defaults that will work well in most situations, there may be times when you want to customize the behavior of the `belongs_to` association reference. Such customizations can easily be accomplished by passing options and scope blocks when you create the association. For example, this assocation uses two such options: ```ruby class Order < ActiveRecord::Base @@ -646,25 +646,25 @@ class Order < ActiveRecord::Base end ``` -The +belongs_to+ association supports these options: +The `belongs_to` association supports these options: -* +:autosave+ -* +:class_name+ -* +:counter_cache+ -* +:dependent+ -* +:foreign_key+ -* +:inverse_of+ -* +:polymorphic+ -* +:touch+ -* +:validate+ +* `:autosave` +* `:class_name` +* `:counter_cache` +* `:dependent` +* `:foreign_key` +* `:inverse_of` +* `:polymorphic` +* `:touch` +* `:validate` -##### +:autosave+ +##### `:autosave` -If you set the +:autosave+ option to +true+, Rails will save any loaded members and destroy members that are marked for destruction whenever you save the parent object. +If you set the `:autosave` option to `true`, Rails will save any loaded members and destroy members that are marked for destruction whenever you save the parent object. -##### +:class_name+ +##### `:class_name` -If the name of the other model cannot be derived from the association name, you can use the +:class_name+ option to supply the model name. For example, if an order belongs to a customer, but the actual name of the model containing customers is +Patron+, you'd set things up this way: +If the name of the other model cannot be derived from the association name, you can use the `:class_name` option to supply the model name. For example, if an order belongs to a customer, but the actual name of the model containing customers is `Patron`, you'd set things up this way: ```ruby class Order < ActiveRecord::Base @@ -672,9 +672,9 @@ class Order < ActiveRecord::Base end ``` -##### +:counter_cache+ +##### `:counter_cache` -The +:counter_cache+ option can be used to make finding the number of belonging objects more efficient. Consider these models: +The `:counter_cache` option can be used to make finding the number of belonging objects more efficient. Consider these models: ```ruby class Order < ActiveRecord::Base @@ -685,7 +685,7 @@ class Customer < ActiveRecord::Base end ``` -With these declarations, asking for the value of +@customer.orders.size+ requires making a call to the database to perform a +COUNT(*)+ query. To avoid this call, you can add a counter cache to the _belonging_ model: +With these declarations, asking for the value of `@customer.orders.size` requires making a call to the database to perform a `COUNT(*)` query. To avoid this call, you can add a counter cache to the _belonging_ model: ```ruby class Order < ActiveRecord::Base @@ -696,9 +696,9 @@ class Customer < ActiveRecord::Base end ``` -With this declaration, Rails will keep the cache value up to date, and then return that value in response to the +size+ method. +With this declaration, Rails will keep the cache value up to date, and then return that value in response to the `size` method. -Although the +:counter_cache+ option is specified on the model that includes the +belongs_to+ declaration, the actual column must be added to the _associated_ model. In the case above, you would need to add a column named +orders_count+ to the +Customer+ model. You can override the default column name if you need to: +Although the `:counter_cache` option is specified on the model that includes the `belongs_to` declaration, the actual column must be added to the _associated_ model. In the case above, you would need to add a column named `orders_count` to the `Customer` model. You can override the default column name if you need to: ```ruby class Order < ActiveRecord::Base @@ -709,17 +709,17 @@ class Customer < ActiveRecord::Base end ``` -Counter cache columns are added to the containing model's list of read-only attributes through +attr_readonly+. +Counter cache columns are added to the containing model's list of read-only attributes through `attr_readonly`. -##### +:dependent+ +##### `:dependent` -If you set the +:dependent+ option to +:destroy+, then deleting this object will call the +destroy+ method on the associated object to delete that object. If you set the +:dependent+ option to +:delete+, then deleting this object will delete the associated object _without_ calling its +destroy+ method. +If you set the `:dependent` option to `:destroy`, then deleting this object will call the `destroy` method on the associated object to delete that object. If you set the `:dependent` option to `:delete`, then deleting this object will delete the associated object _without_ calling its `destroy` method. -WARNING: You should not specify this option on a +belongs_to+ association that is connected with a +has_many+ association on the other class. Doing so can lead to orphaned records in your database. +WARNING: You should not specify this option on a `belongs_to` association that is connected with a `has_many` association on the other class. Doing so can lead to orphaned records in your database. -##### +:foreign_key+ +##### `:foreign_key` -By convention, Rails assumes that the column used to hold the foreign key on this model is the name of the association with the suffix +_id+ added. The +:foreign_key+ option lets you set the name of the foreign key directly: +By convention, Rails assumes that the column used to hold the foreign key on this model is the name of the association with the suffix `_id` added. The `:foreign_key` option lets you set the name of the foreign key directly: ```ruby class Order < ActiveRecord::Base @@ -730,9 +730,9 @@ end TIP: In any case, Rails will not create foreign key columns for you. You need to explicitly define them as part of your migrations. -##### +:inverse_of+ +##### `:inverse_of` -The +:inverse_of+ option specifies the name of the +has_many+ or +has_one+ association that is the inverse of this association. Does not work in combination with the +:polymorphic+ options. +The `:inverse_of` option specifies the name of the `has_many` or `has_one` association that is the inverse of this association. Does not work in combination with the `:polymorphic` options. ```ruby class Customer < ActiveRecord::Base @@ -744,13 +744,13 @@ class Order < ActiveRecord::Base end ``` -##### +:polymorphic+ +##### `:polymorphic` -Passing +true+ to the +:polymorphic+ option indicates that this is a polymorphic association. Polymorphic associations were discussed in detail <a href="#polymorphic-associations">earlier in this guide</a>. +Passing `true` to the `:polymorphic` option indicates that this is a polymorphic association. Polymorphic associations were discussed in detail <a href="#polymorphic-associations">earlier in this guide</a>. -##### +:touch+ +##### `:touch` -If you set the +:touch+ option to +:true+, then the +updated_at+ or +updated_on+ timestamp on the associated object will be set to the current time whenever this object is saved or destroyed: +If you set the `:touch` option to `:true`, then the `updated_at` or `updated_on` timestamp on the associated object will be set to the current time whenever this object is saved or destroyed: ```ruby class Order < ActiveRecord::Base @@ -770,13 +770,13 @@ class Order < ActiveRecord::Base end ``` -##### +:validate+ +##### `:validate` -If you set the +:validate+ option to +true+, then associated objects will be validated whenever you save this object. By default, this is +false+: associated objects will not be validated when this object is saved. +If you set the `:validate` option to `true`, then associated objects will be validated whenever you save this object. By default, this is `false`: associated objects will not be validated when this object is saved. -#### Scopes for +belongs_to+ +#### Scopes for `belongs_to` -There may be times when you wish to customize the query used by +belongs_to+. Such customizations can be achieved via a scope block. For example: +There may be times when you wish to customize the query used by `belongs_to`. Such customizations can be achieved via a scope block. For example: ```ruby class Order < ActiveRecord::Base @@ -787,14 +787,14 @@ end You can use any of the standard "querying methods":active_record_querying.html inside the scope block. The following ones are discussed below: -* +where+ -* +includes+ -* +readonly+ -* +select+ +* `where` +* `includes` +* `readonly` +* `select` -##### +where+ +##### `where` -The +where+ method lets you specify the conditions that the associated object must meet. +The `where` method lets you specify the conditions that the associated object must meet. ```ruby class Order < ActiveRecord::Base @@ -802,9 +802,9 @@ class Order < ActiveRecord::Base end ``` -##### +includes+ +##### `includes` -You can use the +includes+ method let you specify second-order associations that should be eager-loaded when this association is used. For example, consider these models: +You can use the `includes` method let you specify second-order associations that should be eager-loaded when this association is used. For example, consider these models: ```ruby class LineItem < ActiveRecord::Base @@ -821,7 +821,7 @@ class Customer < ActiveRecord::Base end ``` -If you frequently retrieve customers directly from line items (+@line_item.order.customer+), then you can make your code somewhat more efficient by including customers in the association from line items to orders: +If you frequently retrieve customers directly from line items (`@line_item.order.customer`), then you can make your code somewhat more efficient by including customers in the association from line items to orders: ```ruby class LineItem < ActiveRecord::Base @@ -838,17 +838,17 @@ class Customer < ActiveRecord::Base end ``` -NOTE: There's no need to use +includes+ for immediate associations - that is, if you have +Order belongs_to :customer+, then the customer is eager-loaded automatically when it's needed. +NOTE: There's no need to use `includes` for immediate associations - that is, if you have `Order belongs_to :customer`, then the customer is eager-loaded automatically when it's needed. -##### +readonly+ +##### `readonly` -If you use +readonly+, then the associated object will be read-only when retrieved via the association. +If you use `readonly`, then the associated object will be read-only when retrieved via the association. -##### +select+ +##### `select` -The +select+ method lets you override the SQL +SELECT+ clause that is used to retrieve data about the associated object. By default, Rails retrieves all columns. +The `select` method lets you override the SQL `SELECT` clause that is used to retrieve data about the associated object. By default, Rails retrieves all columns. -TIP: If you use the +select+ method on a +belongs_to+ association, you should also set the +:foreign_key+ option to guarantee the correct results. +TIP: If you use the `select` method on a `belongs_to` association, you should also set the `:foreign_key` option to guarantee the correct results. #### Do Any Associated Objects Exist? @@ -862,22 +862,22 @@ end #### When are Objects Saved? -Assigning an object to a +belongs_to+ association does _not_ automatically save the object. It does not save the associated object either. +Assigning an object to a `belongs_to` association does _not_ automatically save the object. It does not save the associated object either. -### +has_one+ Association Reference +### `has_one` Association Reference -The +has_one+ association creates a one-to-one match with another model. In database terms, this association says that the other class contains the foreign key. If this class contains the foreign key, then you should use +belongs_to+ instead. +The `has_one` association creates a one-to-one match with another model. In database terms, this association says that the other class contains the foreign key. If this class contains the foreign key, then you should use `belongs_to` instead. -#### Methods Added by +has_one+ +#### Methods Added by `has_one` -When you declare a +has_one+ association, the declaring class automatically gains four methods related to the association: +When you declare a `has_one` association, the declaring class automatically gains four methods related to the association: * `<em>association</em>(force_reload = false)` * `<em>association</em>=(associate)` * `build_<em>association</em>(attributes = {})` * `create_<em>association</em>(attributes = {})` -In all of these methods, `<em>association</em>` is replaced with the symbol passed as the first argument to +has_one+. For example, given the declaration: +In all of these methods, `<em>association</em>` is replaced with the symbol passed as the first argument to `has_one`. For example, given the declaration: ```ruby class Supplier < ActiveRecord::Base @@ -885,7 +885,7 @@ class Supplier < ActiveRecord::Base end ``` -Each instance of the +Supplier+ model will have these methods: +Each instance of the `Supplier` model will have these methods: ```ruby account @@ -894,17 +894,17 @@ build_account create_account ``` -NOTE: When initializing a new +has_one+ or +belongs_to+ association you must use the +build_+ prefix to build the association, rather than the +association.build+ method that would be used for +has_many+ or +has_and_belongs_to_many+ associations. To create one, use the +create_+ prefix. +NOTE: When initializing a new `has_one` or `belongs_to` association you must use the `build_` prefix to build the association, rather than the `association.build` method that would be used for `has_many` or `has_and_belongs_to_many` associations. To create one, use the `create_` prefix. ##### `<em>association</em>(force_reload = false)` -The `<em>association</em>` method returns the associated object, if any. If no associated object is found, it returns +nil+. +The `<em>association</em>` method returns the associated object, if any. If no associated object is found, it returns `nil`. ```ruby @account = @supplier.account ``` -If the associated object has already been retrieved from the database for this object, the cached version will be returned. To override this behavior (and force a database read), pass +true+ as the +force_reload+ argument. +If the associated object has already been retrieved from the database for this object, the cached version will be returned. To override this behavior (and force a database read), pass `true` as the `force_reload` argument. ##### `<em>association</em>=(associate)` @@ -930,9 +930,9 @@ The `create_<em>association</em>` method returns a new object of the associated @account = @supplier.create_account(:terms => "Net 30") ``` -#### Options for +has_one+ +#### Options for `has_one` -While Rails uses intelligent defaults that will work well in most situations, there may be times when you want to customize the behavior of the +has_one+ association reference. Such customizations can easily be accomplished by passing options when you create the association. For example, this assocation uses two such options: +While Rails uses intelligent defaults that will work well in most situations, there may be times when you want to customize the behavior of the `has_one` association reference. Such customizations can easily be accomplished by passing options when you create the association. For example, this assocation uses two such options: ```ruby class Supplier < ActiveRecord::Base @@ -940,31 +940,31 @@ class Supplier < ActiveRecord::Base end ``` -The +has_one+ association supports these options: +The `has_one` association supports these options: -* +:as+ -* +:autosave+ -* +:class_name+ -* +:dependent+ -* +:foreign_key+ -* +:inverse_of+ -* +:primary_key+ -* +:source+ -* +:source_type+ -* +:through+ -* +:validate+ +* `:as` +* `:autosave` +* `:class_name` +* `:dependent` +* `:foreign_key` +* `:inverse_of` +* `:primary_key` +* `:source` +* `:source_type` +* `:through` +* `:validate` -##### +:as+ +##### `:as` -Setting the +:as+ option indicates that this is a polymorphic association. Polymorphic associations were discussed in detail <a href="#polymorphic-associations">earlier in this guide</a>. +Setting the `:as` option indicates that this is a polymorphic association. Polymorphic associations were discussed in detail <a href="#polymorphic-associations">earlier in this guide</a>. -##### +:autosave+ +##### `:autosave` -If you set the +:autosave+ option to +true+, Rails will save any loaded members and destroy members that are marked for destruction whenever you save the parent object. +If you set the `:autosave` option to `true`, Rails will save any loaded members and destroy members that are marked for destruction whenever you save the parent object. -##### +:class_name+ +##### `:class_name` -If the name of the other model cannot be derived from the association name, you can use the +:class_name+ option to supply the model name. For example, if a supplier has an account, but the actual name of the model containing accounts is +Billing+, you'd set things up this way: +If the name of the other model cannot be derived from the association name, you can use the `:class_name` option to supply the model name. For example, if a supplier has an account, but the actual name of the model containing accounts is `Billing`, you'd set things up this way: ```ruby class Supplier < ActiveRecord::Base @@ -972,19 +972,19 @@ class Supplier < ActiveRecord::Base end ``` -##### +:dependent+ +##### `:dependent` Controls what happens to the associated object when its owner is destroyed: -* +:destroy+ causes the associated object to also be destroyed -* +:delete+ causes the asssociated object to be deleted directly from the database (so callbacks will not execute) -* +:nullify+ causes the foreign key to be set to +NULL+. Callbacks are not executed. -* +:restrict_with_exception+ causes an exception to be raised if there is an associated record -* +:restrict_with_error+ causes an error to be added to the owner if there is an associated object +* `:destroy` causes the associated object to also be destroyed +* `:delete` causes the asssociated object to be deleted directly from the database (so callbacks will not execute) +* `:nullify` causes the foreign key to be set to `NULL`. Callbacks are not executed. +* `:restrict_with_exception` causes an exception to be raised if there is an associated record +* `:restrict_with_error` causes an error to be added to the owner if there is an associated object -##### +:foreign_key+ +##### `:foreign_key` -By convention, Rails assumes that the column used to hold the foreign key on the other model is the name of this model with the suffix +_id+ added. The +:foreign_key+ option lets you set the name of the foreign key directly: +By convention, Rails assumes that the column used to hold the foreign key on the other model is the name of this model with the suffix `_id` added. The `:foreign_key` option lets you set the name of the foreign key directly: ```ruby class Supplier < ActiveRecord::Base @@ -994,9 +994,9 @@ end TIP: In any case, Rails will not create foreign key columns for you. You need to explicitly define them as part of your migrations. -##### +:inverse_of+ +##### `:inverse_of` -The +:inverse_of+ option specifies the name of the +belongs_to+ association that is the inverse of this association. Does not work in combination with the +:through+ or +:as+ options. +The `:inverse_of` option specifies the name of the `belongs_to` association that is the inverse of this association. Does not work in combination with the `:through` or `:as` options. ```ruby class Supplier < ActiveRecord::Base @@ -1008,29 +1008,29 @@ class Account < ActiveRecord::Base end ``` -##### +:primary_key+ +##### `:primary_key` -By convention, Rails assumes that the column used to hold the primary key of this model is +id+. You can override this and explicitly specify the primary key with the +:primary_key+ option. +By convention, Rails assumes that the column used to hold the primary key of this model is `id`. You can override this and explicitly specify the primary key with the `:primary_key` option. -##### +:source+ +##### `:source` -The +:source+ option specifies the source association name for a +has_one :through+ association. +The `:source` option specifies the source association name for a `has_one :through` association. -##### +:source_type+ +##### `:source_type` -The +:source_type+ option specifies the source association type for a +has_one :through+ association that proceeds through a polymorphic association. +The `:source_type` option specifies the source association type for a `has_one :through` association that proceeds through a polymorphic association. -##### +:through+ +##### `:through` -The +:through+ option specifies a join model through which to perform the query. +has_one :through+ associations were discussed in detail <a href="#the-has_one-through-association">earlier in this guide</a>. +The `:through` option specifies a join model through which to perform the query. `has_one :through` associations were discussed in detail <a href="#the-has_one-through-association">earlier in this guide</a>. -##### +:validate+ +##### `:validate` -If you set the +:validate+ option to +true+, then associated objects will be validated whenever you save this object. By default, this is +false+: associated objects will not be validated when this object is saved. +If you set the `:validate` option to `true`, then associated objects will be validated whenever you save this object. By default, this is `false`: associated objects will not be validated when this object is saved. -#### Scopes for +has_one+ +#### Scopes for `has_one` -There may be times when you wish to customize the query used by +has_one+. Such customizations can be achieved via a scope block. For example: +There may be times when you wish to customize the query used by `has_one`. Such customizations can be achieved via a scope block. For example: ```ruby class Supplier < ActiveRecord::Base @@ -1040,14 +1040,14 @@ end You can use any of the standard "querying methods":active_record_querying.html inside the scope block. The following ones are discussed below: -* +where+ -* +includes+ -* +readonly+ -* +select+ +* `where` +* `includes` +* `readonly` +* `select` -##### +where+ +##### `where` -The +where+ method lets you specify the conditions that the associated object must meet. +The `where` method lets you specify the conditions that the associated object must meet. ```ruby class Supplier < ActiveRecord::Base @@ -1055,9 +1055,9 @@ class Supplier < ActiveRecord::Base end ``` -##### +includes+ +##### `includes` -You can use the +includes+ method to specify second-order associations that should be eager-loaded when this association is used. For example, consider these models: +You can use the `includes` method to specify second-order associations that should be eager-loaded when this association is used. For example, consider these models: ```ruby class Supplier < ActiveRecord::Base @@ -1074,7 +1074,7 @@ class Representative < ActiveRecord::Base end ``` -If you frequently retrieve representatives directly from suppliers (+@supplier.account.representative+), then you can make your code somewhat more efficient by including representatives in the association from suppliers to accounts: +If you frequently retrieve representatives directly from suppliers (`@supplier.account.representative`), then you can make your code somewhat more efficient by including representatives in the association from suppliers to accounts: ```ruby class Supplier < ActiveRecord::Base @@ -1091,13 +1091,13 @@ class Representative < ActiveRecord::Base end ``` -##### +readonly+ +##### `readonly` -If you use the +readonly+ method, then the associated object will be read-only when retrieved via the association. +If you use the `readonly` method, then the associated object will be read-only when retrieved via the association. -##### +select+ +##### `select` -The +select+ method lets you override the SQL +SELECT+ clause that is used to retrieve data about the associated object. By default, Rails retrieves all columns. +The `select` method lets you override the SQL `SELECT` clause that is used to retrieve data about the associated object. By default, Rails retrieves all columns. #### Do Any Associated Objects Exist? @@ -1111,21 +1111,21 @@ end #### When are Objects Saved? -When you assign an object to a +has_one+ association, that object is automatically saved (in order to update its foreign key). In addition, any object being replaced is also automatically saved, because its foreign key will change too. +When you assign an object to a `has_one` association, that object is automatically saved (in order to update its foreign key). In addition, any object being replaced is also automatically saved, because its foreign key will change too. -If either of these saves fails due to validation errors, then the assignment statement returns +false+ and the assignment itself is cancelled. +If either of these saves fails due to validation errors, then the assignment statement returns `false` and the assignment itself is cancelled. -If the parent object (the one declaring the +has_one+ association) is unsaved (that is, +new_record?+ returns +true+) then the child objects are not saved. They will automatically when the parent object is saved. +If the parent object (the one declaring the `has_one` association) is unsaved (that is, `new_record?` returns `true`) then the child objects are not saved. They will automatically when the parent object is saved. -If you want to assign an object to a +has_one+ association without saving the object, use the `<em>association</em>.build` method. +If you want to assign an object to a `has_one` association without saving the object, use the `<em>association</em>.build` method. -### +has_many+ Association Reference +### `has_many` Association Reference -The +has_many+ association creates a one-to-many relationship with another model. In database terms, this association says that the other class will have a foreign key that refers to instances of this class. +The `has_many` association creates a one-to-many relationship with another model. In database terms, this association says that the other class will have a foreign key that refers to instances of this class. -#### Methods Added by +has_many+ +#### Methods Added by `has_many` -When you declare a +has_many+ association, the declaring class automatically gains 13 methods related to the association: +When you declare a `has_many` association, the declaring class automatically gains 13 methods related to the association: * `<em>collection</em>(force_reload = false)` * `<em>collection</em><<(object, ...)` @@ -1142,7 +1142,7 @@ When you declare a +has_many+ association, the declaring class automatically gai * `<em>collection</em>.build(attributes = {}, ...)` * `<em>collection</em>.create(attributes = {})` -In all of these methods, `<em>collection</em>` is replaced with the symbol passed as the first argument to +has_many+, and `<em>collection_singular</em>` is replaced with the singularized version of that symbol.. For example, given the declaration: +In all of these methods, `<em>collection</em>` is replaced with the symbol passed as the first argument to `has_many`, and `<em>collection_singular</em>` is replaced with the singularized version of that symbol.. For example, given the declaration: ```ruby class Customer < ActiveRecord::Base @@ -1187,13 +1187,13 @@ The `<em>collection</em><<` method adds one or more objects to the collection by ##### `<em>collection</em>.delete(object, ...)` -The `<em>collection</em>.delete` method removes one or more objects from the collection by setting their foreign keys to +NULL+. +The `<em>collection</em>.delete` method removes one or more objects from the collection by setting their foreign keys to `NULL`. ```ruby @customer.orders.delete(@order1) ``` -WARNING: Additionally, objects will be destroyed if they're associated with +:dependent => :destroy+, and deleted if they're associated with +:dependent => :delete_all+. +WARNING: Additionally, objects will be destroyed if they're associated with `:dependent => :destroy`, and deleted if they're associated with `:dependent => :delete_all`. ##### `<em>collection</em>=objects` @@ -1214,11 +1214,11 @@ The `<em>collection_singular</em>_ids=` method makes the collection contain only ##### `<em>collection</em>.clear` -The `<em>collection</em>.clear` method removes every object from the collection. This destroys the associated objects if they are associated with +:dependent => :destroy+, deletes them directly from the database if +:dependent => :delete_all+, and otherwise sets their foreign keys to +NULL+. +The `<em>collection</em>.clear` method removes every object from the collection. This destroys the associated objects if they are associated with `:dependent => :destroy`, deletes them directly from the database if `:dependent => :delete_all`, and otherwise sets their foreign keys to `NULL`. ##### `<em>collection</em>.empty?` -The `<em>collection</em>.empty?` method returns +true+ if the collection does not contain any associated objects. +The `<em>collection</em>.empty?` method returns `true` if the collection does not contain any associated objects. ```ruby <% if @customer.orders.empty? %> @@ -1236,7 +1236,7 @@ The `<em>collection</em>.size` method returns the number of objects in the colle ##### `<em>collection</em>.find(...)` -The `<em>collection</em>.find` method finds objects within the collection. It uses the same syntax and options as +ActiveRecord::Base.find+. +The `<em>collection</em>.find` method finds objects within the collection. It uses the same syntax and options as `ActiveRecord::Base.find`. ```ruby @open_orders = @customer.orders.find(1) @@ -1253,7 +1253,7 @@ The `<em>collection</em>.where` method finds objects within the collection based ##### `<em>collection</em>.exists?(...)` -The `<em>collection</em>.exists?` method checks whether an object meeting the supplied conditions exists in the collection. It uses the same syntax and options as +ActiveRecord::Base.exists?+. +The `<em>collection</em>.exists?` method checks whether an object meeting the supplied conditions exists in the collection. It uses the same syntax and options as `ActiveRecord::Base.exists?`. ##### `<em>collection</em>.build(attributes = {}, ...)` @@ -1273,9 +1273,9 @@ The `<em>collection</em>.create` method returns a new object of the associated t :order_number => "A12345") ``` -#### Options for +has_many+ +#### Options for `has_many` -While Rails uses intelligent defaults that will work well in most situations, there may be times when you want to customize the behavior of the +has_many+ association reference. Such customizations can easily be accomplished by passing options when you create the association. For example, this assocation uses two such options: +While Rails uses intelligent defaults that will work well in most situations, there may be times when you want to customize the behavior of the `has_many` association reference. Such customizations can easily be accomplished by passing options when you create the association. For example, this assocation uses two such options: ```ruby class Customer < ActiveRecord::Base @@ -1283,31 +1283,31 @@ class Customer < ActiveRecord::Base end ``` -The +has_many+ association supports these options: +The `has_many` association supports these options: -* +:as+ -* +:autosave+ -* +:class_name+ -* +:dependent+ -* +:foreign_key+ -* +:inverse_of+ -* +:primary_key+ -* +:source+ -* +:source_type+ -* +:through+ -* +:validate+ +* `:as` +* `:autosave` +* `:class_name` +* `:dependent` +* `:foreign_key` +* `:inverse_of` +* `:primary_key` +* `:source` +* `:source_type` +* `:through` +* `:validate` -##### +:as+ +##### `:as` -Setting the +:as+ option indicates that this is a polymorphic association, as discussed <a href="#polymorphic-associations">earlier in this guide</a>. +Setting the `:as` option indicates that this is a polymorphic association, as discussed <a href="#polymorphic-associations">earlier in this guide</a>. -##### +:autosave+ +##### `:autosave` -If you set the +:autosave+ option to +true+, Rails will save any loaded members and destroy members that are marked for destruction whenever you save the parent object. +If you set the `:autosave` option to `true`, Rails will save any loaded members and destroy members that are marked for destruction whenever you save the parent object. -##### +:class_name+ +##### `:class_name` -If the name of the other model cannot be derived from the association name, you can use the +:class_name+ option to supply the model name. For example, if a customer has many orders, but the actual name of the model containing orders is +Transaction+, you'd set things up this way: +If the name of the other model cannot be derived from the association name, you can use the `:class_name` option to supply the model name. For example, if a customer has many orders, but the actual name of the model containing orders is `Transaction`, you'd set things up this way: ```ruby class Customer < ActiveRecord::Base @@ -1315,21 +1315,21 @@ class Customer < ActiveRecord::Base end ``` -##### +:dependent+ +##### `:dependent` Controls what happens to the associated objects when their owner is destroyed: -* +:destroy+ causes all the associated objects to also be destroyed -* +:delete_all+ causes all the asssociated objects to be deleted directly from the database (so callbacks will not execute) -* +:nullify+ causes the foreign keys to be set to +NULL+. Callbacks are not executed. -* +:restrict_with_exception+ causes an exception to be raised if there are any associated records -* +:restrict_with_error+ causes an error to be added to the owner if there are any associated objects +* `:destroy` causes all the associated objects to also be destroyed +* `:delete_all` causes all the asssociated objects to be deleted directly from the database (so callbacks will not execute) +* `:nullify` causes the foreign keys to be set to `NULL`. Callbacks are not executed. +* `:restrict_with_exception` causes an exception to be raised if there are any associated records +* `:restrict_with_error` causes an error to be added to the owner if there are any associated objects -NOTE: This option is ignored when you use the +:through+ option on the association. +NOTE: This option is ignored when you use the `:through` option on the association. -##### +:foreign_key+ +##### `:foreign_key` -By convention, Rails assumes that the column used to hold the foreign key on the other model is the name of this model with the suffix +_id+ added. The +:foreign_key+ option lets you set the name of the foreign key directly: +By convention, Rails assumes that the column used to hold the foreign key on the other model is the name of this model with the suffix `_id` added. The `:foreign_key` option lets you set the name of the foreign key directly: ```ruby class Customer < ActiveRecord::Base @@ -1339,9 +1339,9 @@ end TIP: In any case, Rails will not create foreign key columns for you. You need to explicitly define them as part of your migrations. -##### +:inverse_of+ +##### `:inverse_of` -The +:inverse_of+ option specifies the name of the +belongs_to+ association that is the inverse of this association. Does not work in combination with the +:through+ or +:as+ options. +The `:inverse_of` option specifies the name of the `belongs_to` association that is the inverse of this association. Does not work in combination with the `:through` or `:as` options. ```ruby class Customer < ActiveRecord::Base @@ -1353,29 +1353,29 @@ class Order < ActiveRecord::Base end ``` -##### +:primary_key+ +##### `:primary_key` -By convention, Rails assumes that the column used to hold the primary key of the association is +id+. You can override this and explicitly specify the primary key with the +:primary_key+ option. +By convention, Rails assumes that the column used to hold the primary key of the association is `id`. You can override this and explicitly specify the primary key with the `:primary_key` option. -##### +:source+ +##### `:source` -The +:source+ option specifies the source association name for a +has_many :through+ association. You only need to use this option if the name of the source association cannot be automatically inferred from the association name. +The `:source` option specifies the source association name for a `has_many :through` association. You only need to use this option if the name of the source association cannot be automatically inferred from the association name. -##### +:source_type+ +##### `:source_type` -The +:source_type+ option specifies the source association type for a +has_many :through+ association that proceeds through a polymorphic association. +The `:source_type` option specifies the source association type for a `has_many :through` association that proceeds through a polymorphic association. -##### +:through+ +##### `:through` -The +:through+ option specifies a join model through which to perform the query. +has_many :through+ associations provide a way to implement many-to-many relationships, as discussed <a href="#the-has_many-through-association">earlier in this guide</a>. +The `:through` option specifies a join model through which to perform the query. `has_many :through` associations provide a way to implement many-to-many relationships, as discussed <a href="#the-has_many-through-association">earlier in this guide</a>. -##### +:validate+ +##### `:validate` -If you set the +:validate+ option to +false+, then associated objects will not be validated whenever you save this object. By default, this is +true+: associated objects will be validated when this object is saved. +If you set the `:validate` option to `false`, then associated objects will not be validated whenever you save this object. By default, this is `true`: associated objects will be validated when this object is saved. -#### Scopes for +has_many+ +#### Scopes for `has_many` -There may be times when you wish to customize the query used by +has_many+. Such customizations can be achieved via a scope block. For example: +There may be times when you wish to customize the query used by `has_many`. Such customizations can be achieved via a scope block. For example: ```ruby class Customer < ActiveRecord::Base @@ -1385,20 +1385,20 @@ end You can use any of the standard "querying methods":active_record_querying.html inside the scope block. The following ones are discussed below: -* +where+ -* +extending+ -* +group+ -* +includes+ -* +limit+ -* +offset+ -* +order+ -* +readonly+ -* +select+ -* +uniq+ +* `where` +* `extending` +* `group` +* `includes` +* `limit` +* `offset` +* `order` +* `readonly` +* `select` +* `uniq` -##### +where+ +##### `where` -The +where+ method lets you specify the conditions that the associated object must meet. +The `where` method lets you specify the conditions that the associated object must meet. ```ruby class Customer < ActiveRecord::Base @@ -1416,15 +1416,15 @@ class Customer < ActiveRecord::Base end ``` -If you use a hash-style +where+ option, then record creation via this association will be automatically scoped using the hash. In this case, using +@customer.confirmed_orders.create+ or +@customer.confirmed_orders.build+ will create orders where the confirmed column has the value +true+. +If you use a hash-style `where` option, then record creation via this association will be automatically scoped using the hash. In this case, using `@customer.confirmed_orders.create` or `@customer.confirmed_orders.build` will create orders where the confirmed column has the value `true`. -##### +extending+ +##### `extending` -The +extending+ method specifies a named module to extend the association proxy. Association extensions are discussed in detail <a href="#association-extensions">later in this guide</a>. +The `extending` method specifies a named module to extend the association proxy. Association extensions are discussed in detail <a href="#association-extensions">later in this guide</a>. -##### +group+ +##### `group` -The +group+ method supplies an attribute name to group the result set by, using a +GROUP BY+ clause in the finder SQL. +The `group` method supplies an attribute name to group the result set by, using a `GROUP BY` clause in the finder SQL. ```ruby class Customer < ActiveRecord::Base @@ -1433,9 +1433,9 @@ class Customer < ActiveRecord::Base end ``` -##### +includes+ +##### `includes` -You can use the +includes+ method to specify second-order associations that should be eager-loaded when this association is used. For example, consider these models: +You can use the `includes` method to specify second-order associations that should be eager-loaded when this association is used. For example, consider these models: ```ruby class Customer < ActiveRecord::Base @@ -1452,7 +1452,7 @@ class LineItem < ActiveRecord::Base end ``` -If you frequently retrieve line items directly from customers (+@customer.orders.line_items+), then you can make your code somewhat more efficient by including line items in the association from customers to orders: +If you frequently retrieve line items directly from customers (`@customer.orders.line_items`), then you can make your code somewhat more efficient by including line items in the association from customers to orders: ```ruby class Customer < ActiveRecord::Base @@ -1469,9 +1469,9 @@ class LineItem < ActiveRecord::Base end ``` -##### +limit+ +##### `limit` -The +limit+ method lets you restrict the total number of objects that will be fetched through an association. +The `limit` method lets you restrict the total number of objects that will be fetched through an association. ```ruby class Customer < ActiveRecord::Base @@ -1481,13 +1481,13 @@ class Customer < ActiveRecord::Base end ``` -##### +offset+ +##### `offset` -The +offset+ method lets you specify the starting offset for fetching objects via an association. For example, +-> { offset(11) }+ will skip the first 11 records. +The `offset` method lets you specify the starting offset for fetching objects via an association. For example, `-> { offset(11) }` will skip the first 11 records. -##### +order+ +##### `order` -The +order+ method dictates the order in which associated objects will be received (in the syntax used by an SQL +ORDER BY+ clause). +The `order` method dictates the order in which associated objects will be received (in the syntax used by an SQL `ORDER BY` clause). ```ruby class Customer < ActiveRecord::Base @@ -1495,19 +1495,19 @@ class Customer < ActiveRecord::Base end ``` -##### +readonly+ +##### `readonly` -If you use the +readonly+ method, then the associated objects will be read-only when retrieved via the association. +If you use the `readonly` method, then the associated objects will be read-only when retrieved via the association. -##### +select+ +##### `select` -The +select+ method lets you override the SQL +SELECT+ clause that is used to retrieve data about the associated objects. By default, Rails retrieves all columns. +The `select` method lets you override the SQL `SELECT` clause that is used to retrieve data about the associated objects. By default, Rails retrieves all columns. -WARNING: If you specify your own +select+, be sure to include the primary key and foreign key columns of the associated model. If you do not, Rails will throw an error. +WARNING: If you specify your own `select`, be sure to include the primary key and foreign key columns of the associated model. If you do not, Rails will throw an error. -##### +uniq+ +##### `uniq` -Use the +uniq+ method to keep the collection free of duplicates. This is mostly useful together with the +:through+ option. +Use the `uniq` method to keep the collection free of duplicates. This is mostly useful together with the `:through` option. ```ruby class Person < ActiveRecord::Base @@ -1523,9 +1523,9 @@ person.posts.inspect # => [#<Post id: 5, name: "a1">, #<Post id: 5, name: "a1">] Reading.all.inspect # => [#<Reading id: 12, person_id: 5, post_id: 5>, #<Reading id: 13, person_id: 5, post_id: 5>] ``` -In the above case there are two readings and +person.posts+ brings out both of them even though these records are pointing to the same post. +In the above case there are two readings and `person.posts` brings out both of them even though these records are pointing to the same post. -Now let's set +uniq+: +Now let's set `uniq`: ```ruby class Person @@ -1541,25 +1541,25 @@ person.posts.inspect # => [#<Post id: 7, name: "a1">] Reading.all.inspect # => [#<Reading id: 16, person_id: 7, post_id: 7>, #<Reading id: 17, person_id: 7, post_id: 7>] ``` -In the above case there are still two readings. However +person.posts+ shows only one post because the collection loads only unique records. +In the above case there are still two readings. However `person.posts` shows only one post because the collection loads only unique records. #### When are Objects Saved? -When you assign an object to a +has_many+ association, that object is automatically saved (in order to update its foreign key). If you assign multiple objects in one statement, then they are all saved. +When you assign an object to a `has_many` association, that object is automatically saved (in order to update its foreign key). If you assign multiple objects in one statement, then they are all saved. -If any of these saves fails due to validation errors, then the assignment statement returns +false+ and the assignment itself is cancelled. +If any of these saves fails due to validation errors, then the assignment statement returns `false` and the assignment itself is cancelled. -If the parent object (the one declaring the +has_many+ association) is unsaved (that is, +new_record?+ returns +true+) then the child objects are not saved when they are added. All unsaved members of the association will automatically be saved when the parent is saved. +If the parent object (the one declaring the `has_many` association) is unsaved (that is, `new_record?` returns `true`) then the child objects are not saved when they are added. All unsaved members of the association will automatically be saved when the parent is saved. -If you want to assign an object to a +has_many+ association without saving the object, use the `<em>collection</em>.build` method. +If you want to assign an object to a `has_many` association without saving the object, use the `<em>collection</em>.build` method. -### +has_and_belongs_to_many+ Association Reference +### `has_and_belongs_to_many` Association Reference -The +has_and_belongs_to_many+ association creates a many-to-many relationship with another model. In database terms, this associates two classes via an intermediate join table that includes foreign keys referring to each of the classes. +The `has_and_belongs_to_many` association creates a many-to-many relationship with another model. In database terms, this associates two classes via an intermediate join table that includes foreign keys referring to each of the classes. -#### Methods Added by +has_and_belongs_to_many+ +#### Methods Added by `has_and_belongs_to_many` -When you declare a +has_and_belongs_to_many+ association, the declaring class automatically gains 13 methods related to the association: +When you declare a `has_and_belongs_to_many` association, the declaring class automatically gains 13 methods related to the association: * `<em>collection</em>(force_reload = false)` * `<em>collection</em><<(object, ...)` @@ -1576,7 +1576,7 @@ When you declare a +has_and_belongs_to_many+ association, the declaring class au * `<em>collection</em>.build(attributes = {})` * `<em>collection</em>.create(attributes = {})` -In all of these methods, `<em>collection</em>` is replaced with the symbol passed as the first argument to +has_and_belongs_to_many+, and `<em>collection_singular</em>` is replaced with the singularized version of that symbol. For example, given the declaration: +In all of these methods, `<em>collection</em>` is replaced with the symbol passed as the first argument to `has_and_belongs_to_many`, and `<em>collection_singular</em>` is replaced with the singularized version of that symbol. For example, given the declaration: ```ruby class Part < ActiveRecord::Base @@ -1605,9 +1605,9 @@ assemblies.create(attributes = {}) ##### Additional Column Methods -If the join table for a +has_and_belongs_to_many+ association has additional columns beyond the two foreign keys, these columns will be added as attributes to records retrieved via that association. Records returned with additional attributes will always be read-only, because Rails cannot save changes to those attributes. +If the join table for a `has_and_belongs_to_many` association has additional columns beyond the two foreign keys, these columns will be added as attributes to records retrieved via that association. Records returned with additional attributes will always be read-only, because Rails cannot save changes to those attributes. -WARNING: The use of extra attributes on the join table in a +has_and_belongs_to_many+ association is deprecated. If you require this sort of complex behavior on the table that joins two models in a many-to-many relationship, you should use a +has_many :through+ association instead of +has_and_belongs_to_many+. +WARNING: The use of extra attributes on the join table in a `has_and_belongs_to_many` association is deprecated. If you require this sort of complex behavior on the table that joins two models in a many-to-many relationship, you should use a `has_many :through` association instead of `has_and_belongs_to_many`. ##### `<em>collection</em>(force_reload = false)` @@ -1658,7 +1658,7 @@ The `<em>collection</em>.clear` method removes every object from the collection ##### `<em>collection</em>.empty?` -The `<em>collection</em>.empty?` method returns +true+ if the collection does not contain any associated objects. +The `<em>collection</em>.empty?` method returns `true` if the collection does not contain any associated objects. ```ruby <% if @part.assemblies.empty? %> @@ -1676,7 +1676,7 @@ The `<em>collection</em>.size` method returns the number of objects in the colle ##### `<em>collection</em>.find(...)` -The `<em>collection</em>.find` method finds objects within the collection. It uses the same syntax and options as +ActiveRecord::Base.find+. It also adds the additional condition that the object must be in the collection. +The `<em>collection</em>.find` method finds objects within the collection. It uses the same syntax and options as `ActiveRecord::Base.find`. It also adds the additional condition that the object must be in the collection. ```ruby @assembly = @part.assemblies.find(1) @@ -1692,7 +1692,7 @@ The `<em>collection</em>.where` method finds objects within the collection based ##### `<em>collection</em>.exists?(...)` -The `<em>collection</em>.exists?` method checks whether an object meeting the supplied conditions exists in the collection. It uses the same syntax and options as +ActiveRecord::Base.exists?+. +The `<em>collection</em>.exists?` method checks whether an object meeting the supplied conditions exists in the collection. It uses the same syntax and options as `ActiveRecord::Base.exists?`. ##### `<em>collection</em>.build(attributes = {})` @@ -1712,9 +1712,9 @@ The `<em>collection</em>.create` method returns a new object of the associated t {:assembly_name => "Transmission housing"}) ``` -#### Options for +has_and_belongs_to_many+ +#### Options for `has_and_belongs_to_many` -While Rails uses intelligent defaults that will work well in most situations, there may be times when you want to customize the behavior of the +has_and_belongs_to_many+ association reference. Such customizations can easily be accomplished by passing options when you create the association. For example, this assocation uses two such options: +While Rails uses intelligent defaults that will work well in most situations, there may be times when you want to customize the behavior of the `has_and_belongs_to_many` association reference. Such customizations can easily be accomplished by passing options when you create the association. For example, this assocation uses two such options: ```ruby class Parts < ActiveRecord::Base @@ -1723,20 +1723,20 @@ class Parts < ActiveRecord::Base end ``` -The +has_and_belongs_to_many+ association supports these options: +The `has_and_belongs_to_many` association supports these options: -* +:association_foreign_key+ -* +:autosave+ -* +:class_name+ -* +:foreign_key+ -* +:join_table+ -* +:validate+ +* `:association_foreign_key` +* `:autosave` +* `:class_name` +* `:foreign_key` +* `:join_table` +* `:validate` -##### +:association_foreign_key+ +##### `:association_foreign_key` -By convention, Rails assumes that the column in the join table used to hold the foreign key pointing to the other model is the name of that model with the suffix +_id+ added. The +:association_foreign_key+ option lets you set the name of the foreign key directly: +By convention, Rails assumes that the column in the join table used to hold the foreign key pointing to the other model is the name of that model with the suffix `_id` added. The `:association_foreign_key` option lets you set the name of the foreign key directly: -TIP: The +:foreign_key+ and +:association_foreign_key+ options are useful when setting up a many-to-many self-join. For example: +TIP: The `:foreign_key` and `:association_foreign_key` options are useful when setting up a many-to-many self-join. For example: ```ruby class User < ActiveRecord::Base @@ -1746,13 +1746,13 @@ class User < ActiveRecord::Base end ``` -##### +:autosave+ +##### `:autosave` -If you set the +:autosave+ option to +true+, Rails will save any loaded members and destroy members that are marked for destruction whenever you save the parent object. +If you set the `:autosave` option to `true`, Rails will save any loaded members and destroy members that are marked for destruction whenever you save the parent object. -##### +:class_name+ +##### `:class_name` -If the name of the other model cannot be derived from the association name, you can use the +:class_name+ option to supply the model name. For example, if a part has many assemblies, but the actual name of the model containing assemblies is +Gadget+, you'd set things up this way: +If the name of the other model cannot be derived from the association name, you can use the `:class_name` option to supply the model name. For example, if a part has many assemblies, but the actual name of the model containing assemblies is `Gadget`, you'd set things up this way: ```ruby class Parts < ActiveRecord::Base @@ -1760,9 +1760,9 @@ class Parts < ActiveRecord::Base end ``` -##### +:foreign_key+ +##### `:foreign_key` -By convention, Rails assumes that the column in the join table used to hold the foreign key pointing to this model is the name of this model with the suffix +_id+ added. The +:foreign_key+ option lets you set the name of the foreign key directly: +By convention, Rails assumes that the column in the join table used to hold the foreign key pointing to this model is the name of this model with the suffix `_id` added. The `:foreign_key` option lets you set the name of the foreign key directly: ```ruby class User < ActiveRecord::Base @@ -1772,17 +1772,17 @@ class User < ActiveRecord::Base end ``` -##### +:join_table+ +##### `:join_table` -If the default name of the join table, based on lexical ordering, is not what you want, you can use the +:join_table+ option to override the default. +If the default name of the join table, based on lexical ordering, is not what you want, you can use the `:join_table` option to override the default. -##### +:validate+ +##### `:validate` -If you set the +:validate+ option to +false+, then associated objects will not be validated whenever you save this object. By default, this is +true+: associated objects will be validated when this object is saved. +If you set the `:validate` option to `false`, then associated objects will not be validated whenever you save this object. By default, this is `true`: associated objects will be validated when this object is saved. -#### Scopes for +has_and_belongs_to_many+ +#### Scopes for `has_and_belongs_to_many` -There may be times when you wish to customize the query used by +has_and_belongs_to_many+. Such customizations can be achieved via a scope block. For example: +There may be times when you wish to customize the query used by `has_and_belongs_to_many`. Such customizations can be achieved via a scope block. For example: ```ruby class Parts < ActiveRecord::Base @@ -1792,20 +1792,20 @@ end You can use any of the standard "querying methods":active_record_querying.html inside the scope block. The following ones are discussed below: -* +where+ -* +extending+ -* +group+ -* +includes+ -* +limit+ -* +offset+ -* +order+ -* +readonly+ -* +select+ -* +uniq+ +* `where` +* `extending` +* `group` +* `includes` +* `limit` +* `offset` +* `order` +* `readonly` +* `select` +* `uniq` -##### +where+ +##### `where` -The +where+ method lets you specify the conditions that the associated object must meet. +The `where` method lets you specify the conditions that the associated object must meet. ```ruby class Parts < ActiveRecord::Base @@ -1823,15 +1823,15 @@ class Parts < ActiveRecord::Base end ``` -If you use a hash-style +where+, then record creation via this association will be automatically scoped using the hash. In this case, using +@parts.assemblies.create+ or +@parts.assemblies.build+ will create orders where the +factory+ column has the value "Seattle". +If you use a hash-style `where`, then record creation via this association will be automatically scoped using the hash. In this case, using `@parts.assemblies.create` or `@parts.assemblies.build` will create orders where the `factory` column has the value "Seattle". -##### +extending+ +##### `extending` -The +extending+ method specifies a named module to extend the association proxy. Association extensions are discussed in detail <a href="#association-extensions">later in this guide</a>. +The `extending` method specifies a named module to extend the association proxy. Association extensions are discussed in detail <a href="#association-extensions">later in this guide</a>. -##### +group+ +##### `group` -The +group+ method supplies an attribute name to group the result set by, using a +GROUP BY+ clause in the finder SQL. +The `group` method supplies an attribute name to group the result set by, using a `GROUP BY` clause in the finder SQL. ```ruby class Parts < ActiveRecord::Base @@ -1839,13 +1839,13 @@ class Parts < ActiveRecord::Base end ``` -##### +includes+ +##### `includes` -You can use the +includes+ method to specify second-order associations that should be eager-loaded when this association is used. +You can use the `includes` method to specify second-order associations that should be eager-loaded when this association is used. -##### +limit+ +##### `limit` -The +limit+ method lets you restrict the total number of objects that will be fetched through an association. +The `limit` method lets you restrict the total number of objects that will be fetched through an association. ```ruby class Parts < ActiveRecord::Base @@ -1854,13 +1854,13 @@ class Parts < ActiveRecord::Base end ``` -##### +offset+ +##### `offset` -The +offset+ method lets you specify the starting offset for fetching objects via an association. For example, if you set +offset(11)+, it will skip the first 11 records. +The `offset` method lets you specify the starting offset for fetching objects via an association. For example, if you set `offset(11)`, it will skip the first 11 records. -##### +order+ +##### `order` -The +order+ method dictates the order in which associated objects will be received (in the syntax used by an SQL +ORDER BY+ clause). +The `order` method dictates the order in which associated objects will be received (in the syntax used by an SQL `ORDER BY` clause). ```ruby class Parts < ActiveRecord::Base @@ -1869,38 +1869,38 @@ class Parts < ActiveRecord::Base end ``` -##### +readonly+ +##### `readonly` -If you use the +readonly+ method, then the associated objects will be read-only when retrieved via the association. +If you use the `readonly` method, then the associated objects will be read-only when retrieved via the association. -##### +select+ +##### `select` -The +select+ method lets you override the SQL +SELECT+ clause that is used to retrieve data about the associated objects. By default, Rails retrieves all columns. +The `select` method lets you override the SQL `SELECT` clause that is used to retrieve data about the associated objects. By default, Rails retrieves all columns. -##### +uniq+ +##### `uniq` -Use the +uniq+ method to remove duplicates from the collection. +Use the `uniq` method to remove duplicates from the collection. #### When are Objects Saved? -When you assign an object to a +has_and_belongs_to_many+ association, that object is automatically saved (in order to update the join table). If you assign multiple objects in one statement, then they are all saved. +When you assign an object to a `has_and_belongs_to_many` association, that object is automatically saved (in order to update the join table). If you assign multiple objects in one statement, then they are all saved. -If any of these saves fails due to validation errors, then the assignment statement returns +false+ and the assignment itself is cancelled. +If any of these saves fails due to validation errors, then the assignment statement returns `false` and the assignment itself is cancelled. -If the parent object (the one declaring the +has_and_belongs_to_many+ association) is unsaved (that is, +new_record?+ returns +true+) then the child objects are not saved when they are added. All unsaved members of the association will automatically be saved when the parent is saved. +If the parent object (the one declaring the `has_and_belongs_to_many` association) is unsaved (that is, `new_record?` returns `true`) then the child objects are not saved when they are added. All unsaved members of the association will automatically be saved when the parent is saved. -If you want to assign an object to a +has_and_belongs_to_many+ association without saving the object, use the `<em>collection</em>.build` method. +If you want to assign an object to a `has_and_belongs_to_many` association without saving the object, use the `<em>collection</em>.build` method. ### Association Callbacks -Normal callbacks hook into the life cycle of Active Record objects, allowing you to work with those objects at various points. For example, you can use a +:before_save+ callback to cause something to happen just before an object is saved. +Normal callbacks hook into the life cycle of Active Record objects, allowing you to work with those objects at various points. For example, you can use a `:before_save` callback to cause something to happen just before an object is saved. Association callbacks are similar to normal callbacks, but they are triggered by events in the life cycle of a collection. There are four available association callbacks: -* +before_add+ -* +after_add+ -* +before_remove+ -* +after_remove+ +* `before_add` +* `after_add` +* `before_remove` +* `after_remove` You define association callbacks by adding options to the association declaration. For example: @@ -1933,7 +1933,7 @@ class Customer < ActiveRecord::Base end ``` -If a +before_add+ callback throws an exception, the object does not get added to the collection. Similarly, if a +before_remove+ callback throws an exception, the object does not get removed from the collection. +If a `before_add` callback throws an exception, the object does not get added to the collection. Similarly, if a `before_remove` callback throws an exception, the object does not get removed from the collection. ### Association Extensions @@ -1967,8 +1967,8 @@ class Supplier < ActiveRecord::Base end ``` -Extensions can refer to the internals of the association proxy using these three attributes of the +proxy_association+ accessor: +Extensions can refer to the internals of the association proxy using these three attributes of the `proxy_association` accessor: -* +proxy_association.owner+ returns the object that the association is a part of. -* +proxy_association.reflection+ returns the reflection object that describes the association. -* +proxy_association.target+ returns the associated object for +belongs_to+ or +has_one+, or the collection of associated objects for +has_many+ or +has_and_belongs_to_many+. +* `proxy_association.owner` returns the object that the association is a part of. +* `proxy_association.reflection` returns the reflection object that describes the association. +* `proxy_association.target` returns the associated object for `belongs_to` or `has_one`, or the collection of associated objects for `has_many` or `has_and_belongs_to_many`. diff --git a/guides/source/caching_with_rails.md b/guides/source/caching_with_rails.md index d48e674366..5bc8117ac5 100644 --- a/guides/source/caching_with_rails.md +++ b/guides/source/caching_with_rails.md @@ -17,7 +17,7 @@ Basic Caching This is an introduction to the three types of caching techniques that Rails provides by default without the use of any third party plugins. -To start playing with caching you'll want to ensure that +config.action_controller.perform_caching+ is set to +true+, if you're running in development mode. This flag is normally set in the corresponding +config/environments/*.rb+ and caching is disabled by default for development and test, and enabled for production. +To start playing with caching you'll want to ensure that `config.action_controller.perform_caching` is set to `true`, if you're running in development mode. This flag is normally set in the corresponding `config/environments/*.rb` and caching is disabled by default for development and test, and enabled for production. ```ruby config.action_controller.perform_caching = true @@ -27,7 +27,7 @@ config.action_controller.perform_caching = true Page caching is a Rails mechanism which allows the request for a generated page to be fulfilled by the webserver (i.e. Apache or nginx), without ever having to go through the Rails stack at all. Obviously, this is super-fast. Unfortunately, it can't be applied to every situation (such as pages that need authentication) and since the webserver is literally just serving a file from the filesystem, cache expiration is an issue that needs to be dealt with. -To enable page caching, you need to use the +caches_page+ method. +To enable page caching, you need to use the `caches_page` method. ```ruby class ProductsController < ActionController @@ -40,11 +40,11 @@ class ProductsController < ActionController end ``` -Let's say you have a controller called +ProductsController+ and an +index+ action that lists all the products. The first time anyone requests +/products+, Rails will generate a file called +products.html+ and the webserver will then look for that file before it passes the next request for +/products+ to your Rails application. +Let's say you have a controller called `ProductsController` and an `index` action that lists all the products. The first time anyone requests `/products`, Rails will generate a file called `products.html` and the webserver will then look for that file before it passes the next request for `/products` to your Rails application. -By default, the page cache directory is set to +Rails.public_path+ (which is usually set to the +public+ folder) and this can be configured by changing the configuration setting +config.action_controller.page_cache_directory+. Changing the default from +public+ helps avoid naming conflicts, since you may want to put other static html in +public+, but changing this will require web server reconfiguration to let the web server know where to serve the cached files from. +By default, the page cache directory is set to `Rails.public_path` (which is usually set to the `public` folder) and this can be configured by changing the configuration setting `config.action_controller.page_cache_directory`. Changing the default from `public` helps avoid naming conflicts, since you may want to put other static html in `public`, but changing this will require web server reconfiguration to let the web server know where to serve the cached files from. -The Page Caching mechanism will automatically add a +.html+ extension to requests for pages that do not have an extension to make it easy for the webserver to find those pages and this can be configured by changing the configuration setting +config.action_controller.page_cache_extension+. +The Page Caching mechanism will automatically add a `.html` extension to requests for pages that do not have an extension to make it easy for the webserver to find those pages and this can be configured by changing the configuration setting `config.action_controller.page_cache_extension`. In order to expire this page when a new product is added we could extend our example controller like this: @@ -66,9 +66,9 @@ end If you want a more complicated expiration scheme, you can use cache sweepers to expire cached objects when things change. This is covered in the section on Sweepers. -By default, page caching automatically gzips files (for example, to +products.html.gz+ if user requests +/products+) to reduce the size of data transmitted (web servers are typically configured to use a moderate compression ratio as a compromise, but since precompilation happens once, compression ratio is maximum). +By default, page caching automatically gzips files (for example, to `products.html.gz` if user requests `/products`) to reduce the size of data transmitted (web servers are typically configured to use a moderate compression ratio as a compromise, but since precompilation happens once, compression ratio is maximum). -Nginx is able to serve compressed content directly from disk by enabling +gzip_static+: +Nginx is able to serve compressed content directly from disk by enabling `gzip_static`: ``` location / { @@ -76,19 +76,19 @@ location / { } ``` -You can disable gzipping by setting +:gzip+ option to false (for example, if action returns image): +You can disable gzipping by setting `:gzip` option to false (for example, if action returns image): ```ruby caches_page :image, :gzip => false ``` -Or, you can set custom gzip compression level (level names are taken from +Zlib+ constants): +Or, you can set custom gzip compression level (level names are taken from `Zlib` constants): ```ruby caches_page :image, :gzip => :best_speed ``` -NOTE: Page caching ignores all parameters. For example +/products?page=1+ will be written out to the filesystem as +products.html+ with no reference to the +page+ parameter. Thus, if someone requests +/products?page=2+ later, they will get the cached first page. A workaround for this limitation is to include the parameters in the page's path, e.g. +/productions/page/1+. +NOTE: Page caching ignores all parameters. For example `/products?page=1` will be written out to the filesystem as `products.html` with no reference to the `page` parameter. Thus, if someone requests `/products?page=2` later, they will get the cached first page. A workaround for this limitation is to include the parameters in the page's path, e.g. `/productions/page/1`. INFO: Page caching runs in an after filter. Thus, invalid requests won't generate spurious cache entries as long as you halt them. Typically, a redirection in some before filter that checks request preconditions does the job. @@ -96,9 +96,9 @@ INFO: Page caching runs in an after filter. Thus, invalid requests won't generat Page Caching cannot be used for actions that have before filters - for example, pages that require authentication. This is where Action Caching comes in. Action Caching works like Page Caching except the incoming web request hits the Rails stack so that before filters can be run on it before the cache is served. This allows authentication and other restrictions to be run while still serving the result of the output from a cached copy. -Clearing the cache works in a similar way to Page Caching, except you use +expire_action+ instead of +expire_page+. +Clearing the cache works in a similar way to Page Caching, except you use `expire_action` instead of `expire_page`. -Let's say you only wanted authenticated users to call actions on +ProductsController+. +Let's say you only wanted authenticated users to call actions on `ProductsController`. ```ruby class ProductsController < ActionController @@ -117,11 +117,11 @@ class ProductsController < ActionController end ``` -You can also use +:if+ (or +:unless+) to pass a Proc that specifies when the action should be cached. Also, you can use +:layout => false+ to cache without layout so that dynamic information in the layout such as logged in user info or the number of items in the cart can be left uncached. This feature is available as of Rails 2.2. +You can also use `:if` (or `:unless`) to pass a Proc that specifies when the action should be cached. Also, you can use `:layout => false` to cache without layout so that dynamic information in the layout such as logged in user info or the number of items in the cart can be left uncached. This feature is available as of Rails 2.2. -You can modify the default action cache path by passing a +:cache_path+ option. This will be passed directly to +ActionCachePath.path_for+. This is handy for actions with multiple possible routes that should be cached differently. If a block is given, it is called with the current controller instance. +You can modify the default action cache path by passing a `:cache_path` option. This will be passed directly to `ActionCachePath.path_for`. This is handy for actions with multiple possible routes that should be cached differently. If a block is given, it is called with the current controller instance. -Finally, if you are using memcached or Ehcache, you can also pass +:expires_in+. In fact, all parameters not used by +caches_action+ are sent to the underlying cache store. +Finally, if you are using memcached or Ehcache, you can also pass `:expires_in`. In fact, all parameters not used by `caches_action` are sent to the underlying cache store. INFO: Action caching runs in an after filter. Thus, invalid requests won't generate spurious cache entries as long as you halt them. Typically, a redirection in some before filter that checks request preconditions does the job. @@ -146,20 +146,20 @@ As an example, if you wanted to show all the orders placed on your website in re <% end %> ``` -The cache block in our example will bind to the action that called it and is written out to the same place as the Action Cache, which means that if you want to cache multiple fragments per action, you should provide an +action_suffix+ to the cache call: +The cache block in our example will bind to the action that called it and is written out to the same place as the Action Cache, which means that if you want to cache multiple fragments per action, you should provide an `action_suffix` to the cache call: ```ruby <% cache(:action => 'recent', :action_suffix => 'all_products') do %> All available products: ``` -and you can expire it using the +expire_fragment+ method, like so: +and you can expire it using the `expire_fragment` method, like so: ```ruby expire_fragment(:controller => 'products', :action => 'recent', :action_suffix => 'all_products') ``` -If you don't want the cache block to bind to the action that called it, you can also use globally keyed fragments by calling the +cache+ method with a key: +If you don't want the cache block to bind to the action that called it, you can also use globally keyed fragments by calling the `cache` method with a key: ```ruby <% cache('all_available_products') do %> @@ -167,7 +167,7 @@ If you don't want the cache block to bind to the action that called it, you can <% end %> ``` -This fragment is then available to all actions in the +ProductsController+ using the key and can be expired the same way: +This fragment is then available to all actions in the `ProductsController` using the key and can be expired the same way: ```ruby expire_fragment('all_available_products') @@ -175,7 +175,7 @@ expire_fragment('all_available_products') ### Sweepers -Cache sweeping is a mechanism which allows you to get around having a ton of +expire_{page,action,fragment}+ calls in your code. It does this by moving all the work required to expire cached content into an +ActionController::Caching::Sweeper+ subclass. This class is an observer and looks for changes to an Active Record object via callbacks, and when a change occurs it expires the caches associated with that object in an around or after filter. +Cache sweeping is a mechanism which allows you to get around having a ton of `expire_{page,action,fragment}` calls in your code. It does this by moving all the work required to expire cached content into an `ActionController::Caching::Sweeper` subclass. This class is an observer and looks for changes to an Active Record object via callbacks, and when a change occurs it expires the caches associated with that object in an around or after filter. TIP: Sweepers rely on the use of Active Record and Active Record Observers. The object you are observing must be an Active Record model. @@ -233,7 +233,7 @@ class ProductsController < ActionController end ``` -Sometimes it is necessary to disambiguate the controller when you call +expire_action+, such as when there are two identically named controllers in separate namespaces: +Sometimes it is necessary to disambiguate the controller when you call `expire_action`, such as when there are two identically named controllers in separate namespaces: ```ruby class ProductsController < ActionController @@ -267,7 +267,7 @@ class ProductSweeper < ActionController::Caching::Sweeper end ``` -Note the use of '/products' here rather than 'products'. If you wanted to expire an action cache for the +Admin::ProductsController+, you would use 'admin/products' instead. +Note the use of '/products' here rather than 'products'. If you wanted to expire an action cache for the `Admin::ProductsController`, you would use 'admin/products' instead. ### SQL Caching @@ -304,37 +304,37 @@ TIP: Page caches are always stored on disk. ### Configuration -You can set up your application's default cache store by calling +config.cache_store=+ in the Application definition inside your +config/application.rb+ file or in an Application.configure block in an environment specific configuration file (i.e. +config/environments/*.rb+). The first argument will be the cache store to use and the rest of the argument will be passed as arguments to the cache store constructor. +You can set up your application's default cache store by calling `config.cache_store=` in the Application definition inside your `config/application.rb` file or in an Application.configure block in an environment specific configuration file (i.e. `config/environments/*.rb`). The first argument will be the cache store to use and the rest of the argument will be passed as arguments to the cache store constructor. ```ruby config.cache_store = :memory_store ``` -NOTE: Alternatively, you can call +ActionController::Base.cache_store+ outside of a configuration block. +NOTE: Alternatively, you can call `ActionController::Base.cache_store` outside of a configuration block. -You can access the cache by calling +Rails.cache+. +You can access the cache by calling `Rails.cache`. ### ActiveSupport::Cache::Store This class provides the foundation for interacting with the cache in Rails. This is an abstract class and you cannot use it on its own. Rather you must use a concrete implementation of the class tied to a storage engine. Rails ships with several implementations documented below. -The main methods to call are +read+, +write+, +delete+, +exist?+, and +fetch+. The fetch method takes a block and will either return an existing value from the cache, or evaluate the block and write the result to the cache if no value exists. +The main methods to call are `read`, `write`, `delete`, `exist?`, and `fetch`. The fetch method takes a block and will either return an existing value from the cache, or evaluate the block and write the result to the cache if no value exists. There are some common options used by all cache implementations. These can be passed to the constructor or the various methods to interact with entries. -* +:namespace+ - This option can be used to create a namespace within the cache store. It is especially useful if your application shares a cache with other applications. The default value will include the application name and Rails environment. +* `:namespace` - This option can be used to create a namespace within the cache store. It is especially useful if your application shares a cache with other applications. The default value will include the application name and Rails environment. -* +:compress+ - This option can be used to indicate that compression should be used in the cache. This can be useful for transferring large cache entries over a slow network. +* `:compress` - This option can be used to indicate that compression should be used in the cache. This can be useful for transferring large cache entries over a slow network. -* +:compress_threshold+ - This options is used in conjunction with the +:compress+ option to indicate a threshold under which cache entries should not be compressed. This defaults to 16 kilobytes. +* `:compress_threshold` - This options is used in conjunction with the `:compress` option to indicate a threshold under which cache entries should not be compressed. This defaults to 16 kilobytes. -* +:expires_in+ - This option sets an expiration time in seconds for the cache entry when it will be automatically removed from the cache. +* `:expires_in` - This option sets an expiration time in seconds for the cache entry when it will be automatically removed from the cache. -* +:race_condition_ttl+ - This option is used in conjunction with the +:expires_in+ option. It will prevent race conditions when cache entries expire by preventing multiple processes from simultaneously regenerating the same entry (also known as the dog pile effect). This option sets the number of seconds that an expired entry can be reused while a new value is being regenerated. It's a good practice to set this value if you use the +:expires_in+ option. +* `:race_condition_ttl` - This option is used in conjunction with the `:expires_in` option. It will prevent race conditions when cache entries expire by preventing multiple processes from simultaneously regenerating the same entry (also known as the dog pile effect). This option sets the number of seconds that an expired entry can be reused while a new value is being regenerated. It's a good practice to set this value if you use the `:expires_in` option. ### ActiveSupport::Cache::MemoryStore -This cache store keeps entries in memory in the same Ruby process. The cache store has a bounded size specified by the +:size+ options to the initializer (default is 32Mb). When the cache exceeds the allotted size, a cleanup will occur and the least recently used entries will be removed. +This cache store keeps entries in memory in the same Ruby process. The cache store has a bounded size specified by the `:size` options to the initializer (default is 32Mb). When the cache exceeds the allotted size, a cleanup will occur and the least recently used entries will be removed. ```ruby config.cache_store = :memory_store, { :size => 64.megabytes } @@ -358,11 +358,11 @@ Note that the cache will grow until the disk is full unless you periodically cle ### ActiveSupport::Cache::MemCacheStore -This cache store uses Danga's +memcached+ server to provide a centralized cache for your application. Rails uses the bundled +dalli+ gem by default. This is currently the most popular cache store for production websites. It can be used to provide a single, shared cache cluster with very a high performance and redundancy. +This cache store uses Danga's `memcached` server to provide a centralized cache for your application. Rails uses the bundled `dalli` gem by default. This is currently the most popular cache store for production websites. It can be used to provide a single, shared cache cluster with very a high performance and redundancy. When initializing the cache, you need to specify the addresses for all memcached servers in your cluster. If none is specified, it will assume memcached is running on the local host on the default port, but this is not an ideal set up for larger sites. -The +write+ and +fetch+ methods on this cache accept two additional options that take advantage of features specific to memcached. You can specify +:raw+ to send a value directly to the server with no serialization. The value must be a string or number. You can use memcached direct operation like +increment+ and +decrement+ only on raw values. You can also specify +:unless_exist+ if you don't want memcached to overwrite an existing entry. +The `write` and `fetch` methods on this cache accept two additional options that take advantage of features specific to memcached. You can specify `:raw` to send a value directly to the server with no serialization. The value must be a string or number. You can use memcached direct operation like `increment` and `decrement` only on raw values. You can also specify `:unless_exist` if you don't want memcached to overwrite an existing entry. ```ruby config.cache_store = :mem_cache_store, "cache-1.example.com", "cache-2.example.com" @@ -376,9 +376,9 @@ If you are using JRuby you can use Terracotta's Ehcache as the cache store for y config.cache_store = :ehcache_store ``` -When initializing the cache, you may use the +:ehcache_config+ option to specify the Ehcache config file to use (where the default is "ehcache.xml" in your Rails config directory), and the :cache_name option to provide a custom name for your cache (the default is rails_cache). +When initializing the cache, you may use the `:ehcache_config` option to specify the Ehcache config file to use (where the default is "ehcache.xml" in your Rails config directory), and the :cache_name option to provide a custom name for your cache (the default is rails_cache). -In addition to the standard +:expires_in+ option, the +write+ method on this cache can also accept the additional +:unless_exist+ option, which will cause the cache store to use Ehcache's +putIfAbsent+ method instead of +put+, and therefore will not overwrite an existing entry. Additionally, the +write+ method supports all of the properties exposed by the "Ehcache Element class":http://ehcache.org/apidocs/net/sf/ehcache/Element.html , including: +In addition to the standard `:expires_in` option, the `write` method on this cache can also accept the additional `:unless_exist` option, which will cause the cache store to use Ehcache's `putIfAbsent` method instead of `put`, and therefore will not overwrite an existing entry. Additionally, the `write` method supports all of the properties exposed by the "Ehcache Element class":http://ehcache.org/apidocs/net/sf/ehcache/Element.html , including: |_. Property |_. Argument Type |_. Description | | elementEvictionData | ElementEvictionData | Sets this element's eviction data instance. | @@ -387,7 +387,7 @@ In addition to the standard +:expires_in+ option, the +write+ method on this cac | timeToLive, ttl, expires_in | int | Sets time to Live | | version | long | Sets the version attribute of the ElementAttributes object. | -These options are passed to the +write+ method as Hash options using either camelCase or underscore notation, as in the following examples: +These options are passed to the `write` method as Hash options using either camelCase or underscore notation, as in the following examples: ```ruby Rails.cache.write('key', 'value', :time_to_idle => 60.seconds, :timeToLive => 600.seconds) @@ -399,7 +399,7 @@ For more information about Ehcache for JRuby and Rails, see "http://ehcache.org/ ### ActiveSupport::Cache::NullStore -This cache store implementation is meant to be used only in development or test environments and it never stores anything. This can be very useful in development when you have code that interacts directly with +Rails.cache+, but caching may interfere with being able to see the results of code changes. With this cache store, all +fetch+ and +read+ operations will result in a miss. +This cache store implementation is meant to be used only in development or test environments and it never stores anything. This can be very useful in development when you have code that interacts directly with `Rails.cache`, but caching may interfere with being able to see the results of code changes. With this cache store, all `fetch` and `read` operations will result in a miss. ```ruby config.cache_store = :null_store @@ -407,7 +407,7 @@ config.cache_store = :null_store ### Custom Cache Stores -You can create your own custom cache store by simply extending +ActiveSupport::Cache::Store+ and implementing the appropriate methods. In this way, you can swap in any number of caching technologies into your Rails application. +You can create your own custom cache store by simply extending `ActiveSupport::Cache::Store` and implementing the appropriate methods. In this way, you can swap in any number of caching technologies into your Rails application. To use a custom cache store, simple set the cache store to a new instance of the class. @@ -417,7 +417,7 @@ config.cache_store = MyCacheStore.new ### Cache Keys -The keys used in a cache can be any object that responds to either +:cache_key+ or to +:to_param+. You can implement the +:cache_key+ method on your classes if you need to generate custom keys. Active Record will generate keys based on the class name and record id. +The keys used in a cache can be any object that responds to either `:cache_key` or to `:to_param`. You can implement the `:cache_key` method on your classes if you need to generate custom keys. Active Record will generate keys based on the class name and record id. You can use Hashes and Arrays of values as cache keys. @@ -426,14 +426,14 @@ You can use Hashes and Arrays of values as cache keys. Rails.cache.read(:site => "mysite", :owners => [owner_1, owner_2]) ``` -The keys you use on +Rails.cache+ will not be the same as those actually used with the storage engine. They may be modified with a namespace or altered to fit technology backend constraints. This means, for instance, that you can't save values with +Rails.cache+ and then try to pull them out with the +memcache-client+ gem. However, you also don't need to worry about exceeding the memcached size limit or violating syntax rules. +The keys you use on `Rails.cache` will not be the same as those actually used with the storage engine. They may be modified with a namespace or altered to fit technology backend constraints. This means, for instance, that you can't save values with `Rails.cache` and then try to pull them out with the `memcache-client` gem. However, you also don't need to worry about exceeding the memcached size limit or violating syntax rules. Conditional GET support ----------------------- Conditional GETs are a feature of the HTTP specification that provide a way for web servers to tell browsers that the response to a GET request hasn't changed since the last request and can be safely pulled from the browser cache. -They work by using the +HTTP_IF_NONE_MATCH+ and +HTTP_IF_MODIFIED_SINCE+ headers to pass back and forth both a unique content identifier and the timestamp of when the content was last changed. If the browser makes a request where the content identifier (etag) or last modified since timestamp matches the server’s version then the server only needs to send back an empty response with a not modified status. +They work by using the `HTTP_IF_NONE_MATCH` and `HTTP_IF_MODIFIED_SINCE` headers to pass back and forth both a unique content identifier and the timestamp of when the content was last changed. If the browser makes a request where the content identifier (etag) or last modified since timestamp matches the server’s version then the server only needs to send back an empty response with a not modified status. It is the server's (i.e. our) responsibility to look for a last modified timestamp and the if-none-match header and determine whether or not to send back the full response. With conditional-get support in Rails this is a pretty easy task: @@ -459,7 +459,7 @@ class ProductsController < ApplicationController end ``` -Instead of a options hash, you can also simply pass in a model, Rails will use the +updated_at+ and +cache_key+ methods for setting +last_modified+ and +etag+: +Instead of a options hash, you can also simply pass in a model, Rails will use the `updated_at` and `cache_key` methods for setting `last_modified` and `etag`: <ruby> class ProductsController < ApplicationController diff --git a/guides/source/command_line.md b/guides/source/command_line.md index 83ed244d49..38b15c9590 100644 --- a/guides/source/command_line.md +++ b/guides/source/command_line.md @@ -29,11 +29,11 @@ There are a few commands that are absolutely critical to your everyday usage of Let's create a simple Rails application to step through each of these commands in context. -### +rails new+ +### `rails new` -The first thing we'll want to do is create a new Rails application by running the +rails new+ command after installing Rails. +The first thing we'll want to do is create a new Rails application by running the `rails new` command after installing Rails. -INFO: You can install the rails gem by typing +gem install rails+, if you don't have it already. +INFO: You can install the rails gem by typing `gem install rails`, if you don't have it already. ```bash $ rails new commandsapp @@ -52,13 +52,13 @@ $ rails new commandsapp Rails will set you up with what seems like a huge amount of stuff for such a tiny command! You've got the entire Rails directory structure now with all the code you need to run our simple application right out of the box. -### +rails server+ +### `rails server` -The +rails server+ command launches a small web server named WEBrick which comes bundled with Ruby. You'll use this any time you want to access your application through a web browser. +The `rails server` command launches a small web server named WEBrick which comes bundled with Ruby. You'll use this any time you want to access your application through a web browser. INFO: WEBrick isn't your only option for serving Rails. We'll get to that "later":#different-servers. -With no further work, +rails server+ will run our new shiny Rails app: +With no further work, `rails server` will run our new shiny Rails app: ```bash $ cd commandsapp @@ -76,17 +76,17 @@ With just three commands we whipped up a Rails server listening on port 3000. Go INFO: You can also use the alias "s" to start the server: `rails s`. -The server can be run on a different port using the +-p+ option. The default development environment can be changed using +-e+. +The server can be run on a different port using the `-p` option. The default development environment can be changed using `-e`. ```bash $ rails server -e production -p 4000 ``` -The +-b+ option binds Rails to the specified ip, by default it is 0.0.0.0. You can run a server as a daemon by passing a +-d+ option. +The `-b` option binds Rails to the specified ip, by default it is 0.0.0.0. You can run a server as a daemon by passing a `-d` option. -### +rails generate+ +### `rails generate` -The +rails generate+ command uses templates to create a whole lot of things. Running +rails generate+ by itself gives a list of available generators: +The `rails generate` command uses templates to create a whole lot of things. Running `rails generate` by itself gives a list of available generators: INFO: You can also use the alias "g" to invoke the generator command: `rails g`. @@ -113,7 +113,7 @@ Using generators will save you a large amount of time by writing *boilerplate co Let's make our own controller with the controller generator. But what command should we use? Let's ask the generator: -INFO: All Rails console utilities have help text. As with most *nix utilities, you can try adding +--help+ or +-h+ to the end, for example +rails server --help+. +INFO: All Rails console utilities have help text. As with most *nix utilities, you can try adding `--help` or `-h` to the end, for example `rails server --help`. ```bash $ rails generate controller @@ -140,7 +140,7 @@ Example: Helper: app/helpers/credit_card_helper.rb ``` -The controller generator is expecting parameters in the form of +generate controller ControllerName action1 action2+. Let's make a +Greetings+ controller with an action of *hello*, which will say something nice to us. +The controller generator is expecting parameters in the form of `generate controller ControllerName action1 action2`. Let's make a `Greetings` controller with an action of *hello*, which will say something nice to us. ```bash $ rails generate controller Greetings hello @@ -164,7 +164,7 @@ $ rails generate controller Greetings hello What all did this generate? It made sure a bunch of directories were in our application, and created a controller file, a view file, a functional test file, a helper for the view, a JavaScript file and a stylesheet file. -Check out the controller and modify it a little (in +app/controllers/greetings_controller.rb+): +Check out the controller and modify it a little (in `app/controllers/greetings_controller.rb`): ```ruby class GreetingsController < ApplicationController @@ -174,14 +174,14 @@ class GreetingsController < ApplicationController end ``` -Then the view, to display our message (in +app/views/greetings/hello.html.erb+): +Then the view, to display our message (in `app/views/greetings/hello.html.erb`): ```html <h1>A Greeting for You!</h1> <p><%= @message %></p> ``` -Fire up your server using +rails server+. +Fire up your server using `rails server`. ```bash $ rails server @@ -211,7 +211,7 @@ Description: Create rails files for model generator. ``` -NOTE: For a list of available field types, refer to the "API documentation":http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/TableDefinition.html#method-i-column for the column method for the +TableDefinition+ class. +NOTE: For a list of available field types, refer to the "API documentation":http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/TableDefinition.html#method-i-column for the column method for the `TableDefinition` class. But instead of generating a model directly (which we'll be doing later), let's set up a scaffold. A *scaffold* in Rails is a full set of model, database migration for that model, controller to manipulate it, views to view and manipulate the data, and a test suite for each of the above. @@ -250,9 +250,9 @@ $ rails generate scaffold HighScore game:string score:integer create app/assets/stylesheets/scaffolds.css.scss ``` -The generator checks that there exist the directories for models, controllers, helpers, layouts, functional and unit tests, stylesheets, creates the views, controller, model and database migration for HighScore (creating the +high_scores+ table and fields), takes care of the route for the *resource*, and new tests for everything. +The generator checks that there exist the directories for models, controllers, helpers, layouts, functional and unit tests, stylesheets, creates the views, controller, model and database migration for HighScore (creating the `high_scores` table and fields), takes care of the route for the *resource*, and new tests for everything. -The migration requires that we *migrate*, that is, run some Ruby code (living in that +20120528060026_create_high_scores.rb+) to modify the schema of our database. Which database? The sqlite3 database that Rails will create for you when we run the +rake db:migrate+ command. We'll talk more about Rake in-depth in a little while. +The migration requires that we *migrate*, that is, run some Ruby code (living in that `20120528060026_create_high_scores.rb`) to modify the schema of our database. Which database? The sqlite3 database that Rails will create for you when we run the `rake db:migrate` command. We'll talk more about Rake in-depth in a little while. ```bash $ rake db:migrate @@ -272,19 +272,19 @@ $ rails server Go to your browser and open "http://localhost:3000/high_scores":http://localhost:3000/high_scores, now we can create new high scores (55,160 on Space Invaders!) -### +rails console+ +### `rails console` -The +console+ command lets you interact with your Rails application from the command line. On the underside, +rails console+ uses IRB, so if you've ever used it, you'll be right at home. This is useful for testing out quick ideas with code and changing data server-side without touching the website. +The `console` command lets you interact with your Rails application from the command line. On the underside, `rails console` uses IRB, so if you've ever used it, you'll be right at home. This is useful for testing out quick ideas with code and changing data server-side without touching the website. INFO: You can also use the alias "c" to invoke the console: `rails c`. -You can specify the environment in which the +console+ command should operate. +You can specify the environment in which the `console` command should operate. ```bash $ rails console staging ``` -If you wish to test out some code without changing any data, you can do that by invoking +rails console --sandbox+. +If you wish to test out some code without changing any data, you can do that by invoking `rails console --sandbox`. ```bash $ rails console --sandbox @@ -293,13 +293,13 @@ Any modifications you make will be rolled back on exit irb(main):001:0> ``` -### +rails dbconsole+ +### `rails dbconsole` -+rails dbconsole+ figures out which database you're using and drops you into whichever command line interface you would use with it (and figures out the command line parameters to give to it, too!). It supports MySQL, PostgreSQL, SQLite and SQLite3. +`rails dbconsole` figures out which database you're using and drops you into whichever command line interface you would use with it (and figures out the command line parameters to give to it, too!). It supports MySQL, PostgreSQL, SQLite and SQLite3. INFO: You can also use the alias "db" to invoke the dbconsole: `rails db`. -### +rails runner+ +### `rails runner` `runner` runs Ruby code in the context of Rails non-interactively. For instance: @@ -309,15 +309,15 @@ $ rails runner "Model.long_running_method" INFO: You can also use the alias "r" to invoke the runner: `rails r`. -You can specify the environment in which the +runner+ command should operate using the +-e+ switch. +You can specify the environment in which the `runner` command should operate using the `-e` switch. ```bash $ rails runner -e staging "Model.long_running_method" ``` -### +rails destroy+ +### `rails destroy` -Think of +destroy+ as the opposite of +generate+. It'll figure out what generate did, and undo it. +Think of `destroy` as the opposite of `generate`. It'll figure out what generate did, and undo it. INFO: You can also use the alias "d" to invoke the destroy command: `rails d`. @@ -343,9 +343,9 @@ $ rails destroy model Oops Rake ---- -Rake is Ruby Make, a standalone Ruby utility that replaces the Unix utility 'make', and uses a 'Rakefile' and +.rake+ files to build up a list of tasks. In Rails, Rake is used for common administration tasks, especially sophisticated ones that build off of each other. +Rake is Ruby Make, a standalone Ruby utility that replaces the Unix utility 'make', and uses a 'Rakefile' and `.rake` files to build up a list of tasks. In Rails, Rake is used for common administration tasks, especially sophisticated ones that build off of each other. -You can get a list of Rake tasks available to you, which will often depend on your current directory, by typing +rake --tasks+. Each task has a description, and should help you find the thing you need. +You can get a list of Rake tasks available to you, which will often depend on your current directory, by typing `rake --tasks`. Each task has a description, and should help you find the thing you need. ```bash $ rake --tasks @@ -361,7 +361,7 @@ rake tmp:clear # Clear session, cache, and socket files from tmp/ (narr rake tmp:create # Creates tmp directories for sessions, cache, sockets, and pids ``` -### +about+ +### `about` `rake about` gives information about version numbers for Ruby, RubyGems, Rails, the Rails subcomponents, your application's folder, the current Rails environment name, your app's database adapter, and schema version. It is useful when you need to ask for help, check if a security patch might affect you, or when you need some stats for an existing Rails installation. @@ -384,27 +384,27 @@ Database adapter sqlite3 Database schema version 20110805173523 ``` -### +assets+ +### `assets` You can precompile the assets in `app/assets` using `rake assets:precompile` and remove those compiled assets using `rake assets:clean`. -### +db+ +### `db` -The most common tasks of the +db:+ Rake namespace are +migrate+ and +create+, and it will pay off to try out all of the migration rake tasks (+up+, +down+, +redo+, +reset+). +rake db:version+ is useful when troubleshooting, telling you the current version of the database. +The most common tasks of the `db:` Rake namespace are `migrate` and `create`, and it will pay off to try out all of the migration rake tasks (`up`, `down`, `redo`, `reset`). `rake db:version` is useful when troubleshooting, telling you the current version of the database. More information about migrations can be found in the "Migrations":migrations.html guide. -### +doc+ +### `doc` -The +doc:+ namespace has the tools to generate documentation for your app, API documentation, guides. Documentation can also be stripped which is mainly useful for slimming your codebase, like if you're writing a Rails application for an embedded platform. +The `doc:` namespace has the tools to generate documentation for your app, API documentation, guides. Documentation can also be stripped which is mainly useful for slimming your codebase, like if you're writing a Rails application for an embedded platform. -* +rake doc:app+ generates documentation for your application in +doc/app+. -* +rake doc:guides+ generates Rails guides in +doc/guides+. -* +rake doc:rails+ generates API documentation for Rails in +doc/api+. +* `rake doc:app` generates documentation for your application in `doc/app`. +* `rake doc:guides` generates Rails guides in `doc/guides`. +* `rake doc:rails` generates API documentation for Rails in `doc/api`. -### +notes+ +### `notes` -+rake notes+ will search through your code for comments beginning with FIXME, OPTIMIZE or TODO. The search is done in files with extension +.builder+, +.rb+, +.erb+, +.haml+ and +.slim+ for both default and custom annotations. +`rake notes` will search through your code for comments beginning with FIXME, OPTIMIZE or TODO. The search is done in files with extension `.builder`, `.rb`, `.erb`, `.haml` and `.slim` for both default and custom annotations. ```bash $ rake notes @@ -418,7 +418,7 @@ app/model/school.rb: * [ 17] [FIXME] ``` -If you are looking for a specific annotation, say FIXME, you can use +rake notes:fixme+. Note that you have to lower case the annotation's name. +If you are looking for a specific annotation, say FIXME, you can use `rake notes:fixme`. Note that you have to lower case the annotation's name. ```bash $ rake notes:fixme @@ -430,7 +430,7 @@ app/model/school.rb: * [ 17] ``` -You can also use custom annotations in your code and list them using +rake notes:custom+ by specifying the annotation using an environment variable +ANNOTATION+. +You can also use custom annotations in your code and list them using `rake notes:custom` by specifying the annotation using an environment variable `ANNOTATION`. ```bash $ rake notes:custom ANNOTATION=BUG @@ -441,7 +441,7 @@ app/model/post.rb: NOTE. When using specific annotations and custom annotations, the annotation name (FIXME, BUG etc) is not displayed in the output lines. -By default, +rake notes+ will look in the +app+, +config+, +lib+, +script+ and +test+ directories. If you would like to search other directories, you can provide them as a comma separated list in an environment variable +SOURCE_ANNOTATION_DIRECTORIES+. +By default, `rake notes` will look in the `app`, `config`, `lib`, `script` and `test` directories. If you would like to search other directories, you can provide them as a comma separated list in an environment variable `SOURCE_ANNOTATION_DIRECTORIES`. ```bash $ export SOURCE_ANNOTATION_DIRECTORIES='rspec,vendor' @@ -453,31 +453,31 @@ rspec/model/user_spec.rb: * [122] [TODO] Verify the user that has a subscription works ``` -### +routes+ +### `routes` -+rake routes+ will list all of your defined routes, which is useful for tracking down routing problems in your app, or giving you a good overview of the URLs in an app you're trying to get familiar with. +`rake routes` will list all of your defined routes, which is useful for tracking down routing problems in your app, or giving you a good overview of the URLs in an app you're trying to get familiar with. -### +test+ +### `test` INFO: A good description of unit testing in Rails is given in "A Guide to Testing Rails Applications":testing.html -Rails comes with a test suite called `Test::Unit`. Rails owes its stability to the use of tests. The tasks available in the +test:+ namespace helps in running the different tests you will hopefully write. +Rails comes with a test suite called `Test::Unit`. Rails owes its stability to the use of tests. The tasks available in the `test:` namespace helps in running the different tests you will hopefully write. -### +tmp+ +### `tmp` The `Rails.root/tmp` directory is, like the *nix /tmp directory, the holding place for temporary files like sessions (if you're using a file store for files), process id files, and cached actions. -The +tmp:+ namespaced tasks will help you clear the `Rails.root/tmp` directory: +The `tmp:` namespaced tasks will help you clear the `Rails.root/tmp` directory: -* +rake tmp:cache:clear+ clears `tmp/cache`. -* +rake tmp:sessions:clear+ clears `tmp/sessions`. -* +rake tmp:sockets:clear+ clears `tmp/sockets`. -* +rake tmp:clear+ clears all the three: cache, sessions and sockets. +* `rake tmp:cache:clear` clears `tmp/cache`. +* `rake tmp:sessions:clear` clears `tmp/sessions`. +* `rake tmp:sockets:clear` clears `tmp/sockets`. +* `rake tmp:clear` clears all the three: cache, sessions and sockets. ### Miscellaneous -* +rake stats+ is great for looking at statistics on your code, displaying things like KLOCs (thousands of lines of code) and your code to test ratio. -* +rake secret+ will give you a pseudo-random key to use for your session secret. +* `rake stats` is great for looking at statistics on your code, displaying things like KLOCs (thousands of lines of code) and your code to test ratio. +* `rake secret` will give you a pseudo-random key to use for your session secret. * `rake time:zones:all` lists all the timezones Rails knows about. ### Writing Rake Tasks @@ -486,7 +486,7 @@ If you have (or want to write) any automation scripts outside your app (data imp INFO: "Complete guide about how to write tasks":http://rake.rubyforge.org/files/doc/rakefile_rdoc.html is available in the official documentation. -Tasks should be placed in `Rails.root/lib/tasks` and should have a +.rake+ extension. +Tasks should be placed in `Rails.root/lib/tasks` and should have a `.rake` extension. Each task should be defined in next format (dependencies are optional): @@ -525,7 +525,7 @@ rake "task_name[value 1]" # entire argument string should be quoted rake do:nothing ``` -NOTE: If your need to interact with your application models, perform database queries and so on, your task should depend on the +environment+ task, which will load your application code. +NOTE: If your need to interact with your application models, perform database queries and so on, your task should depend on the `environment` task, which will load your application code. The Rails Advanced Command Line ------------------------------- @@ -536,7 +536,7 @@ More advanced use of the command line is focused around finding useful (even sur When creating a new Rails application, you have the option to specify what kind of database and what kind of source code management system your application is going to use. This will save you a few minutes, and certainly many keystrokes. -Let's see what a +--git+ option and a +--database=postgresql+ option will do for us: +Let's see what a `--git` option and a `--database=postgresql` option will do for us: ```bash $ mkdir gitapp @@ -590,15 +590,15 @@ development: It also generated some lines in our database.yml configuration corresponding to our choice of PostgreSQL for database. -NOTE. The only catch with using the SCM options is that you have to make your application's directory first, then initialize your SCM, then you can run the +rails new+ command to generate the basis of your app. +NOTE. The only catch with using the SCM options is that you have to make your application's directory first, then initialize your SCM, then you can run the `rails new` command to generate the basis of your app. -### +server+ with Different Backends +### `server` with Different Backends Many people have created a large number of different web servers in Ruby, and many of them can be used to run Rails. Since version 2.3, Rails uses Rack to serve its webpages, which means that any webserver that implements a Rack handler can be used. This includes WEBrick, Mongrel, Thin, and Phusion Passenger (to name a few!). NOTE: For more details on the Rack integration, see "Rails on Rack":rails_on_rack.html. -To use a different server, just install its gem, then use its name for the first parameter to +rails server+: +To use a different server, just install its gem, then use its name for the first parameter to `rails server`: ```bash $ sudo gem install mongrel diff --git a/guides/source/configuring.md b/guides/source/configuring.md index 58909e60d0..a895707f9a 100644 --- a/guides/source/configuring.md +++ b/guides/source/configuring.md @@ -13,7 +13,7 @@ Locations for Initialization Code Rails offers four standard spots to place initialization code: -* +config/application.rb+ +* `config/application.rb` * Environment-specific configuration files * Initializers * After-initializers @@ -21,20 +21,20 @@ Rails offers four standard spots to place initialization code: Running Code Before Rails ------------------------- -In the rare event that your application needs to run some code before Rails itself is loaded, put it above the call to +require 'rails/all'+ in +config/application.rb+. +In the rare event that your application needs to run some code before Rails itself is loaded, put it above the call to `require 'rails/all'` in `config/application.rb`. Configuring Rails Components ---------------------------- -In general, the work of configuring Rails means configuring the components of Rails, as well as configuring Rails itself. The configuration file +config/application.rb+ and environment-specific configuration files (such as +config/environments/production.rb+) allow you to specify the various settings that you want to pass down to all of the components. +In general, the work of configuring Rails means configuring the components of Rails, as well as configuring Rails itself. The configuration file `config/application.rb` and environment-specific configuration files (such as `config/environments/production.rb`) allow you to specify the various settings that you want to pass down to all of the components. -For example, the default +config/application.rb+ file includes this setting: +For example, the default `config/application.rb` file includes this setting: ```ruby config.filter_parameters += [:password] ``` -This is a setting for Rails itself. If you want to pass settings to individual Rails components, you can do so via the same +config+ object in +config/application.rb+: +This is a setting for Rails itself. If you want to pass settings to individual Rails components, you can do so via the same `config` object in `config/application.rb`: ```ruby config.active_record.observers = [:hotel_observer, :review_observer] @@ -44,9 +44,9 @@ Rails will use that particular setting to configure Active Record. ### Rails General Configuration -These configuration methods are to be called on a +Rails::Railtie+ object, such as a subclass of +Rails::Engine+ or +Rails::Application+. +These configuration methods are to be called on a `Rails::Railtie` object, such as a subclass of `Rails::Engine` or `Rails::Application`. -* +config.after_initialize+ takes a block which will be run _after_ Rails has finished initializing the application. That includes the initialization of the framework itself, engines, and all the application's initializers in +config/initializers+. Note that this block _will_ be run for rake tasks. Useful for configuring values set up by other initializers: +* `config.after_initialize` takes a block which will be run _after_ Rails has finished initializing the application. That includes the initialization of the framework itself, engines, and all the application's initializers in `config/initializers`. Note that this block _will_ be run for rake tasks. Useful for configuring values set up by other initializers: ```ruby config.after_initialize do @@ -54,31 +54,31 @@ config.after_initialize do end ``` -* +config.asset_host+ sets the host for the assets. Useful when CDNs are used for hosting assets, or when you want to work around the concurrency constraints builtin in browsers using different domain aliases. Shorter version of +config.action_controller.asset_host+. +* `config.asset_host` sets the host for the assets. Useful when CDNs are used for hosting assets, or when you want to work around the concurrency constraints builtin in browsers using different domain aliases. Shorter version of `config.action_controller.asset_host`. -* +config.asset_path+ lets you decorate asset paths. This can be a callable, a string, or be +nil+ which is the default. For example, the normal path for +blog.js+ would be +/javascripts/blog.js+, let that absolute path be +path+. If +config.asset_path+ is a callable, Rails calls it when generating asset paths passing +path+ as argument. If +config.asset_path+ is a string, it is expected to be a +sprintf+ format string with a +%s+ where +path+ will get inserted. In either case, Rails outputs the decorated path. Shorter version of +config.action_controller.asset_path+. +* `config.asset_path` lets you decorate asset paths. This can be a callable, a string, or be `nil` which is the default. For example, the normal path for `blog.js` would be `/javascripts/blog.js`, let that absolute path be `path`. If `config.asset_path` is a callable, Rails calls it when generating asset paths passing `path` as argument. If `config.asset_path` is a string, it is expected to be a `sprintf` format string with a `%s` where `path` will get inserted. In either case, Rails outputs the decorated path. Shorter version of `config.action_controller.asset_path`. ```ruby config.asset_path = proc { |path| "/blog/public#{path}" } ``` -NOTE. The +config.asset_path+ configuration is ignored if the asset pipeline is enabled, which is the default. +NOTE. The `config.asset_path` configuration is ignored if the asset pipeline is enabled, which is the default. -* +config.autoload_once_paths+ accepts an array of paths from which Rails will autoload constants that won't be wiped per request. Relevant if +config.cache_classes+ is false, which is the case in development mode by default. Otherwise, all autoloading happens only once. All elements of this array must also be in +autoload_paths+. Default is an empty array. +* `config.autoload_once_paths` accepts an array of paths from which Rails will autoload constants that won't be wiped per request. Relevant if `config.cache_classes` is false, which is the case in development mode by default. Otherwise, all autoloading happens only once. All elements of this array must also be in `autoload_paths`. Default is an empty array. -* +config.autoload_paths+ accepts an array of paths from which Rails will autoload constants. Default is all directories under +app+. +* `config.autoload_paths` accepts an array of paths from which Rails will autoload constants. Default is all directories under `app`. -* +config.cache_classes+ controls whether or not application classes and modules should be reloaded on each request. Defaults to false in development mode, and true in test and production modes. Can also be enabled with +threadsafe!+. +* `config.cache_classes` controls whether or not application classes and modules should be reloaded on each request. Defaults to false in development mode, and true in test and production modes. Can also be enabled with `threadsafe!`. -* +config.action_view.cache_template_loading+ controls whether or not templates should be reloaded on each request. Defaults to whatever is set for +config.cache_classes+. +* `config.action_view.cache_template_loading` controls whether or not templates should be reloaded on each request. Defaults to whatever is set for `config.cache_classes`. -* +config.cache_store+ configures which cache store to use for Rails caching. Options include one of the symbols +:memory_store+, +:file_store+, +:mem_cache_store+, +:null_store+, or an object that implements the cache API. Defaults to +:file_store+ if the directory +tmp/cache+ exists, and to +:memory_store+ otherwise. +* `config.cache_store` configures which cache store to use for Rails caching. Options include one of the symbols `:memory_store`, `:file_store`, `:mem_cache_store`, `:null_store`, or an object that implements the cache API. Defaults to `:file_store` if the directory `tmp/cache` exists, and to `:memory_store` otherwise. -* +config.colorize_logging+ specifies whether or not to use ANSI color codes when logging information. Defaults to true. +* `config.colorize_logging` specifies whether or not to use ANSI color codes when logging information. Defaults to true. -* +config.consider_all_requests_local+ is a flag. If true then any error will cause detailed debugging information to be dumped in the HTTP response, and the +Rails::Info+ controller will show the application runtime context in +/rails/info/properties+. True by default in development and test environments, and false in production mode. For finer-grained control, set this to false and implement +local_request?+ in controllers to specify which requests should provide debugging information on errors. +* `config.consider_all_requests_local` is a flag. If true then any error will cause detailed debugging information to be dumped in the HTTP response, and the `Rails::Info` controller will show the application runtime context in `/rails/info/properties`. True by default in development and test environments, and false in production mode. For finer-grained control, set this to false and implement `local_request?` in controllers to specify which requests should provide debugging information on errors. -* +config.console+ allows you to set class that will be used as console you run +rails console+. It's best to run it in +console+ block: +* `config.console` allows you to set class that will be used as console you run `rails console`. It's best to run it in `console` block: ```ruby console do @@ -89,89 +89,89 @@ console do end ``` -* +config.dependency_loading+ is a flag that allows you to disable constant autoloading setting it to false. It only has effect if +config.cache_classes+ is true, which it is by default in production mode. This flag is set to false by +config.threadsafe!+. +* `config.dependency_loading` is a flag that allows you to disable constant autoloading setting it to false. It only has effect if `config.cache_classes` is true, which it is by default in production mode. This flag is set to false by `config.threadsafe!`. -* +config.eager_load+ when true, eager loads all registered `config.eager_load_namespaces`. This includes your application, engines, Rails frameworks and any other registered namespace. +* `config.eager_load` when true, eager loads all registered `config.eager_load_namespaces`. This includes your application, engines, Rails frameworks and any other registered namespace. -* +config.eager_load_namespaces+ registers namespaces that are eager loaded when +config.eager_load+ is true. All namespaces in the list must respond to the +eager_load!+ method. +* `config.eager_load_namespaces` registers namespaces that are eager loaded when `config.eager_load` is true. All namespaces in the list must respond to the `eager_load!` method. -* +config.eager_load_paths+ accepts an array of paths from which Rails will eager load on boot if cache classes is enabled. Defaults to every folder in the +app+ directory of the application. +* `config.eager_load_paths` accepts an array of paths from which Rails will eager load on boot if cache classes is enabled. Defaults to every folder in the `app` directory of the application. -* +config.encoding+ sets up the application-wide encoding. Defaults to UTF-8. +* `config.encoding` sets up the application-wide encoding. Defaults to UTF-8. -* +config.exceptions_app+ sets the exceptions application invoked by the ShowException middleware when an exception happens. Defaults to +ActionDispatch::PublicExceptions.new(Rails.public_path)+. +* `config.exceptions_app` sets the exceptions application invoked by the ShowException middleware when an exception happens. Defaults to `ActionDispatch::PublicExceptions.new(Rails.public_path)`. -* +config.file_watcher+ the class used to detect file updates in the filesystem when +config.reload_classes_only_on_change+ is true. Must conform to +ActiveSupport::FileUpdateChecker+ API. +* `config.file_watcher` the class used to detect file updates in the filesystem when `config.reload_classes_only_on_change` is true. Must conform to `ActiveSupport::FileUpdateChecker` API. -* +config.filter_parameters+ used for filtering out the parameters that you don't want shown in the logs, such as passwords or credit card numbers. +* `config.filter_parameters` used for filtering out the parameters that you don't want shown in the logs, such as passwords or credit card numbers. -* +config.force_ssl+ forces all requests to be under HTTPS protocol by using +ActionDispatch::SSL+ middleware. +* `config.force_ssl` forces all requests to be under HTTPS protocol by using `ActionDispatch::SSL` middleware. -* +config.log_level+ defines the verbosity of the Rails logger. This option defaults to +:debug+ for all modes except production, where it defaults to +:info+. +* `config.log_level` defines the verbosity of the Rails logger. This option defaults to `:debug` for all modes except production, where it defaults to `:info`. -* +config.log_tags+ accepts a list of methods that respond to +request+ object. This makes it easy to tag log lines with debug information like subdomain and request id -- both very helpful in debugging multi-user production applications. +* `config.log_tags` accepts a list of methods that respond to `request` object. This makes it easy to tag log lines with debug information like subdomain and request id -- both very helpful in debugging multi-user production applications. -* +config.logger+ accepts a logger conforming to the interface of Log4r or the default Ruby +Logger+ class. Defaults to an instance of +ActiveSupport::BufferedLogger+, with auto flushing off in production mode. +* `config.logger` accepts a logger conforming to the interface of Log4r or the default Ruby `Logger` class. Defaults to an instance of `ActiveSupport::BufferedLogger`, with auto flushing off in production mode. -* +config.middleware+ allows you to configure the application's middleware. This is covered in depth in the "Configuring Middleware":#configuring-middleware section below. +* `config.middleware` allows you to configure the application's middleware. This is covered in depth in the "Configuring Middleware":#configuring-middleware section below. -* +config.queue+ configures a different queue implementation for the application. Defaults to +ActiveSupport::SynchronousQueue+. Note that, if the default queue is changed, the default +queue_consumer+ is not going to be initialized, it is up to the new queue implementation to handle starting and shutting down its own consumer(s). +* `config.queue` configures a different queue implementation for the application. Defaults to `ActiveSupport::SynchronousQueue`. Note that, if the default queue is changed, the default `queue_consumer` is not going to be initialized, it is up to the new queue implementation to handle starting and shutting down its own consumer(s). -* +config.queue_consumer+ configures a different consumer implementation for the default queue. Defaults to +ActiveSupport::ThreadedQueueConsumer+. +* `config.queue_consumer` configures a different consumer implementation for the default queue. Defaults to `ActiveSupport::ThreadedQueueConsumer`. -* +config.reload_classes_only_on_change+ enables or disables reloading of classes only when tracked files change. By default tracks everything on autoload paths and is set to true. If +config.cache_classes+ is true, this option is ignored. +* `config.reload_classes_only_on_change` enables or disables reloading of classes only when tracked files change. By default tracks everything on autoload paths and is set to true. If `config.cache_classes` is true, this option is ignored. -* +config.secret_token+ used for specifying a key which allows sessions for the application to be verified against a known secure key to prevent tampering. Applications get +config.secret_token+ initialized to a random key in +config/initializers/secret_token.rb+. +* `config.secret_token` used for specifying a key which allows sessions for the application to be verified against a known secure key to prevent tampering. Applications get `config.secret_token` initialized to a random key in `config/initializers/secret_token.rb`. -* +config.serve_static_assets+ configures Rails itself to serve static assets. Defaults to true, but in the production environment is turned off as the server software (e.g. Nginx or Apache) used to run the application should serve static assets instead. Unlike the default setting set this to true when running (absolutely not recommended!) or testing your app in production mode using WEBrick. Otherwise you won´t be able use page caching and requests for files that exist regularly under the public directory will anyway hit your Rails app. +* `config.serve_static_assets` configures Rails itself to serve static assets. Defaults to true, but in the production environment is turned off as the server software (e.g. Nginx or Apache) used to run the application should serve static assets instead. Unlike the default setting set this to true when running (absolutely not recommended!) or testing your app in production mode using WEBrick. Otherwise you won´t be able use page caching and requests for files that exist regularly under the public directory will anyway hit your Rails app. -* +config.session_store+ is usually set up in +config/initializers/session_store.rb+ and specifies what class to use to store the session. Possible values are +:cookie_store+ which is the default, +:mem_cache_store+, and +:disabled+. The last one tells Rails not to deal with sessions. Custom session stores can also be specified: +* `config.session_store` is usually set up in `config/initializers/session_store.rb` and specifies what class to use to store the session. Possible values are `:cookie_store` which is the default, `:mem_cache_store`, and `:disabled`. The last one tells Rails not to deal with sessions. Custom session stores can also be specified: ```ruby config.session_store :my_custom_store ``` -This custom store must be defined as +ActionDispatch::Session::MyCustomStore+. +This custom store must be defined as `ActionDispatch::Session::MyCustomStore`. -* +config.time_zone+ sets the default time zone for the application and enables time zone awareness for Active Record. +* `config.time_zone` sets the default time zone for the application and enables time zone awareness for Active Record. -* +config.whiny_nils+ enables or disables warnings when a certain set of methods are invoked on +nil+ and it does not respond to them. Defaults to true in development and test environments. +* `config.whiny_nils` enables or disables warnings when a certain set of methods are invoked on `nil` and it does not respond to them. Defaults to true in development and test environments. ### Configuring Assets -Rails 3.1, by default, is set up to use the +sprockets+ gem to manage assets within an application. This gem concatenates and compresses assets in order to make serving them much less painful. +Rails 3.1, by default, is set up to use the `sprockets` gem to manage assets within an application. This gem concatenates and compresses assets in order to make serving them much less painful. -* +config.assets.enabled+ a flag that controls whether the asset pipeline is enabled. It is explicitly initialized in +config/application.rb+. +* `config.assets.enabled` a flag that controls whether the asset pipeline is enabled. It is explicitly initialized in `config/application.rb`. -* +config.assets.compress+ a flag that enables the compression of compiled assets. It is explicitly set to true in +config/production.rb+. +* `config.assets.compress` a flag that enables the compression of compiled assets. It is explicitly set to true in `config/production.rb`. -* +config.assets.css_compressor+ defines the CSS compressor to use. It is set by default by +sass-rails+. The unique alternative value at the moment is +:yui+, which uses the +yui-compressor+ gem. +* `config.assets.css_compressor` defines the CSS compressor to use. It is set by default by `sass-rails`. The unique alternative value at the moment is `:yui`, which uses the `yui-compressor` gem. -* +config.assets.js_compressor+ defines the JavaScript compressor to use. Possible values are +:closure+, +:uglifier+ and +:yui+ which require the use of the +closure-compiler+, +uglifier+ or +yui-compressor+ gems respectively. +* `config.assets.js_compressor` defines the JavaScript compressor to use. Possible values are `:closure`, `:uglifier` and `:yui` which require the use of the `closure-compiler`, `uglifier` or `yui-compressor` gems respectively. -* +config.assets.paths+ contains the paths which are used to look for assets. Appending paths to this configuration option will cause those paths to be used in the search for assets. +* `config.assets.paths` contains the paths which are used to look for assets. Appending paths to this configuration option will cause those paths to be used in the search for assets. -* +config.assets.precompile+ allows you to specify additional assets (other than +application.css+ and +application.js+) which are to be precompiled when +rake assets:precompile+ is run. +* `config.assets.precompile` allows you to specify additional assets (other than `application.css` and `application.js`) which are to be precompiled when `rake assets:precompile` is run. -* +config.assets.prefix+ defines the prefix where assets are served from. Defaults to +/assets+. +* `config.assets.prefix` defines the prefix where assets are served from. Defaults to `/assets`. -* +config.assets.digest+ enables the use of MD5 fingerprints in asset names. Set to +true+ by default in +production.rb+. +* `config.assets.digest` enables the use of MD5 fingerprints in asset names. Set to `true` by default in `production.rb`. -* +config.assets.debug+ disables the concatenation and compression of assets. Set to +true+ by default in +development.rb+. +* `config.assets.debug` disables the concatenation and compression of assets. Set to `true` by default in `development.rb`. -* +config.assets.manifest+ defines the full path to be used for the asset precompiler's manifest file. Defaults to using +config.assets.prefix+. +* `config.assets.manifest` defines the full path to be used for the asset precompiler's manifest file. Defaults to using `config.assets.prefix`. -* +config.assets.cache_store+ defines the cache store that Sprockets will use. The default is the Rails file store. +* `config.assets.cache_store` defines the cache store that Sprockets will use. The default is the Rails file store. -* +config.assets.version+ is an option string that is used in MD5 hash generation. This can be changed to force all files to be recompiled. +* `config.assets.version` is an option string that is used in MD5 hash generation. This can be changed to force all files to be recompiled. -* +config.assets.compile+ is a boolean that can be used to turn on live Sprockets compilation in production. +* `config.assets.compile` is a boolean that can be used to turn on live Sprockets compilation in production. -* +config.assets.logger+ accepts a logger conforming to the interface of Log4r or the default Ruby +Logger+ class. Defaults to the same configured at +config.logger+. Setting +config.assets.logger+ to false will turn off served assets logging. +* `config.assets.logger` accepts a logger conforming to the interface of Log4r or the default Ruby `Logger` class. Defaults to the same configured at `config.logger`. Setting `config.assets.logger` to false will turn off served assets logging. ### Configuring Generators -Rails 3 allows you to alter what generators are used with the +config.generators+ method. This method takes a block: +Rails 3 allows you to alter what generators are used with the `config.generators` method. This method takes a block: ```ruby config.generators do |g| @@ -182,59 +182,59 @@ end The full set of methods that can be used in this block are as follows: -* +assets+ allows to create assets on generating a scaffold. Defaults to +true+. -* +force_plural+ allows pluralized model names. Defaults to +false+. -* +helper+ defines whether or not to generate helpers. Defaults to +true+. -* +integration_tool+ defines which integration tool to use. Defaults to +nil+. -* +javascripts+ turns on the hook for JavaScript files in generators. Used in Rails for when the +scaffold+ generator is run. Defaults to +true+. -* +javascript_engine+ configures the engine to be used (for eg. coffee) when generating assets. Defaults to +nil+. -* +orm+ defines which orm to use. Defaults to +false+ and will use Active Record by default. -* +performance_tool+ defines which performance tool to use. Defaults to +nil+. -* +resource_controller+ defines which generator to use for generating a controller when using +rails generate resource+. Defaults to +:controller+. -* +scaffold_controller+ different from +resource_controller+, defines which generator to use for generating a _scaffolded_ controller when using +rails generate scaffold+. Defaults to +:scaffold_controller+. -* +stylesheets+ turns on the hook for stylesheets in generators. Used in Rails for when the +scaffold+ generator is run, but this hook can be used in other generates as well. Defaults to +true+. -* +stylesheet_engine+ configures the stylesheet engine (for eg. sass) to be used when generating assets. Defaults to +:css+. -* +test_framework+ defines which test framework to use. Defaults to +false+ and will use Test::Unit by default. -* +template_engine+ defines which template engine to use, such as ERB or Haml. Defaults to +:erb+. +* `assets` allows to create assets on generating a scaffold. Defaults to `true`. +* `force_plural` allows pluralized model names. Defaults to `false`. +* `helper` defines whether or not to generate helpers. Defaults to `true`. +* `integration_tool` defines which integration tool to use. Defaults to `nil`. +* `javascripts` turns on the hook for JavaScript files in generators. Used in Rails for when the `scaffold` generator is run. Defaults to `true`. +* `javascript_engine` configures the engine to be used (for eg. coffee) when generating assets. Defaults to `nil`. +* `orm` defines which orm to use. Defaults to `false` and will use Active Record by default. +* `performance_tool` defines which performance tool to use. Defaults to `nil`. +* `resource_controller` defines which generator to use for generating a controller when using `rails generate resource`. Defaults to `:controller`. +* `scaffold_controller` different from `resource_controller`, defines which generator to use for generating a _scaffolded_ controller when using `rails generate scaffold`. Defaults to `:scaffold_controller`. +* `stylesheets` turns on the hook for stylesheets in generators. Used in Rails for when the `scaffold` generator is run, but this hook can be used in other generates as well. Defaults to `true`. +* `stylesheet_engine` configures the stylesheet engine (for eg. sass) to be used when generating assets. Defaults to `:css`. +* `test_framework` defines which test framework to use. Defaults to `false` and will use Test::Unit by default. +* `template_engine` defines which template engine to use, such as ERB or Haml. Defaults to `:erb`. ### Configuring Middleware Every Rails application comes with a standard set of middleware which it uses in this order in the development environment: -* +ActionDispatch::SSL+ forces every request to be under HTTPS protocol. Will be available if +config.force_ssl+ is set to +true+. Options passed to this can be configured by using +config.ssl_options+. -* +ActionDispatch::Static+ is used to serve static assets. Disabled if +config.serve_static_assets+ is +true+. -* +Rack::Lock+ wraps the app in mutex so it can only be called by a single thread at a time. Only enabled when +config.cache_classes_+ is +false+. -* +ActiveSupport::Cache::Strategy::LocalCache+ serves as a basic memory backed cache. This cache is not thread safe and is intended only for serving as a temporary memory cache for a single thread. -* +Rack::Runtime+ sets an +X-Runtime+ header, containing the time (in seconds) taken to execute the request. -* +Rails::Rack::Logger+ notifies the logs that the request has began. After request is complete, flushes all the logs. -* +ActionDispatch::ShowExceptions+ rescues any exception returned by the application and renders nice exception pages if the request is local or if +config.consider_all_requests_local+ is set to +true+. If +config.action_dispatch.show_exceptions+ is set to +false+, exceptions will be raised regardless. -* +ActionDispatch::RequestId+ makes a unique X-Request-Id header available to the response and enables the +ActionDispatch::Request#uuid+ method. -* +ActionDispatch::RemoteIp+ checks for IP spoofing attacks. Configurable with the +config.action_dispatch.ip_spoofing_check+ and +config.action_dispatch.trusted_proxies+ settings. -* +Rack::Sendfile+ intercepts responses whose body is being served from a file and replaces it with a server specific X-Sendfile header. Configurable with +config.action_dispatch.x_sendfile_header+. -* +ActionDispatch::Callbacks+ runs the prepare callbacks before serving the request. -* +ActiveRecord::ConnectionAdapters::ConnectionManagement+ cleans active connections after each request, unless the +rack.test+ key in the request environment is set to +true+. -* +ActiveRecord::QueryCache+ caches all SELECT queries generated in a request. If any INSERT or UPDATE takes place then the cache is cleaned. -* +ActionDispatch::Cookies+ sets cookies for the request. -* +ActionDispatch::Session::CookieStore+ is responsible for storing the session in cookies. An alternate middleware can be used for this by changing the +config.action_controller.session_store+ to an alternate value. Additionally, options passed to this can be configured by using +config.action_controller.session_options+. -* +ActionDispatch::Flash+ sets up the +flash+ keys. Only available if +config.action_controller.session_store+ is set to a value. -* +ActionDispatch::ParamsParser+ parses out parameters from the request into +params+. -* +Rack::MethodOverride+ allows the method to be overridden if +params[:_method]+ is set. This is the middleware which supports the PATCH, PUT, and DELETE HTTP method types. -* +ActionDispatch::Head+ converts HEAD requests to GET requests and serves them as so. -* +ActionDispatch::BestStandardsSupport+ enables "best standards support" so that IE8 renders some elements correctly. - -Besides these usual middleware, you can add your own by using the +config.middleware.use+ method: +* `ActionDispatch::SSL` forces every request to be under HTTPS protocol. Will be available if `config.force_ssl` is set to `true`. Options passed to this can be configured by using `config.ssl_options`. +* `ActionDispatch::Static` is used to serve static assets. Disabled if `config.serve_static_assets` is `true`. +* `Rack::Lock` wraps the app in mutex so it can only be called by a single thread at a time. Only enabled when `config.cache_classes_` is `false`. +* `ActiveSupport::Cache::Strategy::LocalCache` serves as a basic memory backed cache. This cache is not thread safe and is intended only for serving as a temporary memory cache for a single thread. +* `Rack::Runtime` sets an `X-Runtime` header, containing the time (in seconds) taken to execute the request. +* `Rails::Rack::Logger` notifies the logs that the request has began. After request is complete, flushes all the logs. +* `ActionDispatch::ShowExceptions` rescues any exception returned by the application and renders nice exception pages if the request is local or if `config.consider_all_requests_local` is set to `true`. If `config.action_dispatch.show_exceptions` is set to `false`, exceptions will be raised regardless. +* `ActionDispatch::RequestId` makes a unique X-Request-Id header available to the response and enables the `ActionDispatch::Request#uuid` method. +* `ActionDispatch::RemoteIp` checks for IP spoofing attacks. Configurable with the `config.action_dispatch.ip_spoofing_check` and `config.action_dispatch.trusted_proxies` settings. +* `Rack::Sendfile` intercepts responses whose body is being served from a file and replaces it with a server specific X-Sendfile header. Configurable with `config.action_dispatch.x_sendfile_header`. +* `ActionDispatch::Callbacks` runs the prepare callbacks before serving the request. +* `ActiveRecord::ConnectionAdapters::ConnectionManagement` cleans active connections after each request, unless the `rack.test` key in the request environment is set to `true`. +* `ActiveRecord::QueryCache` caches all SELECT queries generated in a request. If any INSERT or UPDATE takes place then the cache is cleaned. +* `ActionDispatch::Cookies` sets cookies for the request. +* `ActionDispatch::Session::CookieStore` is responsible for storing the session in cookies. An alternate middleware can be used for this by changing the `config.action_controller.session_store` to an alternate value. Additionally, options passed to this can be configured by using `config.action_controller.session_options`. +* `ActionDispatch::Flash` sets up the `flash` keys. Only available if `config.action_controller.session_store` is set to a value. +* `ActionDispatch::ParamsParser` parses out parameters from the request into `params`. +* `Rack::MethodOverride` allows the method to be overridden if `params[:_method]` is set. This is the middleware which supports the PATCH, PUT, and DELETE HTTP method types. +* `ActionDispatch::Head` converts HEAD requests to GET requests and serves them as so. +* `ActionDispatch::BestStandardsSupport` enables "best standards support" so that IE8 renders some elements correctly. + +Besides these usual middleware, you can add your own by using the `config.middleware.use` method: ```ruby config.middleware.use Magical::Unicorns ``` -This will put the +Magical::Unicorns+ middleware on the end of the stack. You can use +insert_before+ if you wish to add a middleware before another. +This will put the `Magical::Unicorns` middleware on the end of the stack. You can use `insert_before` if you wish to add a middleware before another. ```ruby config.middleware.insert_before ActionDispatch::Head, Magical::Unicorns ``` -There's also +insert_after+ which will insert a middleware after another: +There's also `insert_after` which will insert a middleware after another: ```ruby config.middleware.insert_after ActionDispatch::Head, Magical::Unicorns @@ -254,113 +254,113 @@ config.middleware.delete ActionDispatch::BestStandardsSupport ### Configuring i18n -* +config.i18n.default_locale+ sets the default locale of an application used for i18n. Defaults to +:en+. +* `config.i18n.default_locale` sets the default locale of an application used for i18n. Defaults to `:en`. -* +config.i18n.load_path+ sets the path Rails uses to look for locale files. Defaults to +config/locales/*.{yml,rb}+. +* `config.i18n.load_path` sets the path Rails uses to look for locale files. Defaults to `config/locales/*.{yml,rb}`. ### Configuring Active Record `config.active_record` includes a variety of configuration options: -* +config.active_record.logger+ accepts a logger conforming to the interface of Log4r or the default Ruby Logger class, which is then passed on to any new database connections made. You can retrieve this logger by calling +logger+ on either an Active Record model class or an Active Record model instance. Set to +nil+ to disable logging. +* `config.active_record.logger` accepts a logger conforming to the interface of Log4r or the default Ruby Logger class, which is then passed on to any new database connections made. You can retrieve this logger by calling `logger` on either an Active Record model class or an Active Record model instance. Set to `nil` to disable logging. -* +config.active_record.primary_key_prefix_type+ lets you adjust the naming for primary key columns. By default, Rails assumes that primary key columns are named +id+ (and this configuration option doesn't need to be set.) There are two other choices: -** +:table_name+ would make the primary key for the Customer class +customerid+ -** +:table_name_with_underscore+ would make the primary key for the Customer class +customer_id+ +* `config.active_record.primary_key_prefix_type` lets you adjust the naming for primary key columns. By default, Rails assumes that primary key columns are named `id` (and this configuration option doesn't need to be set.) There are two other choices: +** `:table_name` would make the primary key for the Customer class `customerid` +** `:table_name_with_underscore` would make the primary key for the Customer class `customer_id` -* +config.active_record.table_name_prefix+ lets you set a global string to be prepended to table names. If you set this to +northwest_+, then the Customer class will look for +northwest_customers+ as its table. The default is an empty string. +* `config.active_record.table_name_prefix` lets you set a global string to be prepended to table names. If you set this to `northwest_`, then the Customer class will look for `northwest_customers` as its table. The default is an empty string. -* +config.active_record.table_name_suffix+ lets you set a global string to be appended to table names. If you set this to +_northwest+, then the Customer class will look for +customers_northwest+ as its table. The default is an empty string. +* `config.active_record.table_name_suffix` lets you set a global string to be appended to table names. If you set this to `_northwest`, then the Customer class will look for `customers_northwest` as its table. The default is an empty string. -* +config.active_record.pluralize_table_names+ specifies whether Rails will look for singular or plural table names in the database. If set to true (the default), then the Customer class will use the +customers+ table. If set to false, then the Customer class will use the +customer+ table. +* `config.active_record.pluralize_table_names` specifies whether Rails will look for singular or plural table names in the database. If set to true (the default), then the Customer class will use the `customers` table. If set to false, then the Customer class will use the `customer` table. -* +config.active_record.default_timezone+ determines whether to use +Time.local+ (if set to +:local+) or +Time.utc+ (if set to +:utc+) when pulling dates and times from the database. The default is +:utc+ for Rails, although Active Record defaults to +:local+ when used outside of Rails. +* `config.active_record.default_timezone` determines whether to use `Time.local` (if set to `:local`) or `Time.utc` (if set to `:utc`) when pulling dates and times from the database. The default is `:utc` for Rails, although Active Record defaults to `:local` when used outside of Rails. -* +config.active_record.schema_format+ controls the format for dumping the database schema to a file. The options are +:ruby+ (the default) for a database-independent version that depends on migrations, or +:sql+ for a set of (potentially database-dependent) SQL statements. +* `config.active_record.schema_format` controls the format for dumping the database schema to a file. The options are `:ruby` (the default) for a database-independent version that depends on migrations, or `:sql` for a set of (potentially database-dependent) SQL statements. -* +config.active_record.timestamped_migrations+ controls whether migrations are numbered with serial integers or with timestamps. The default is true, to use timestamps, which are preferred if there are multiple developers working on the same application. +* `config.active_record.timestamped_migrations` controls whether migrations are numbered with serial integers or with timestamps. The default is true, to use timestamps, which are preferred if there are multiple developers working on the same application. -* +config.active_record.lock_optimistically+ controls whether Active Record will use optimistic locking and is true by default. +* `config.active_record.lock_optimistically` controls whether Active Record will use optimistic locking and is true by default. -* +config.active_record.whitelist_attributes+ will create an empty whitelist of attributes available for mass-assignment security for all models in your app. +* `config.active_record.whitelist_attributes` will create an empty whitelist of attributes available for mass-assignment security for all models in your app. -* +config.active_record.auto_explain_threshold_in_seconds+ configures the threshold for automatic EXPLAINs (+nil+ disables this feature). Queries exceeding the threshold get their query plan logged. Default is 0.5 in development mode. +* `config.active_record.auto_explain_threshold_in_seconds` configures the threshold for automatic EXPLAINs (`nil` disables this feature). Queries exceeding the threshold get their query plan logged. Default is 0.5 in development mode. -* +config.active_record.mass_assignment_sanitizer+ will determine the strictness of the mass assignment sanitization within Rails. Defaults to +:strict+. In this mode, mass assigning any non-+attr_accessible+ attribute in a +create+ or +update_attributes+ call will raise an exception. Setting this option to +:logger+ will only print to the log file when an attribute is being assigned and will not raise an exception. +* `config.active_record.mass_assignment_sanitizer` will determine the strictness of the mass assignment sanitization within Rails. Defaults to `:strict`. In this mode, mass assigning any non-`attr_accessible` attribute in a `create` or `update_attributes` call will raise an exception. Setting this option to `:logger` will only print to the log file when an attribute is being assigned and will not raise an exception. The MySQL adapter adds one additional configuration option: -* +ActiveRecord::ConnectionAdapters::MysqlAdapter.emulate_booleans+ controls whether Active Record will consider all +tinyint(1)+ columns in a MySQL database to be booleans and is true by default. +* `ActiveRecord::ConnectionAdapters::MysqlAdapter.emulate_booleans` controls whether Active Record will consider all `tinyint(1)` columns in a MySQL database to be booleans and is true by default. The schema dumper adds one additional configuration option: -* +ActiveRecord::SchemaDumper.ignore_tables+ accepts an array of tables that should _not_ be included in any generated schema file. This setting is ignored unless +config.active_record.schema_format == :ruby+. +* `ActiveRecord::SchemaDumper.ignore_tables` accepts an array of tables that should _not_ be included in any generated schema file. This setting is ignored unless `config.active_record.schema_format == :ruby`. ### Configuring Action Controller `config.action_controller` includes a number of configuration settings: -* +config.action_controller.asset_host+ sets the host for the assets. Useful when CDNs are used for hosting assets rather than the application server itself. +* `config.action_controller.asset_host` sets the host for the assets. Useful when CDNs are used for hosting assets rather than the application server itself. -* +config.action_controller.asset_path+ takes a block which configures where assets can be found. Shorter version of +config.action_controller.asset_path+. +* `config.action_controller.asset_path` takes a block which configures where assets can be found. Shorter version of `config.action_controller.asset_path`. -* +config.action_controller.page_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. +* `config.action_controller.page_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. -* +config.action_controller.page_cache_extension+ configures the extension used for cached pages saved to +page_cache_directory+. Defaults to +.html+. +* `config.action_controller.page_cache_extension` configures the extension used for cached pages saved to `page_cache_directory`. Defaults to `.html`. -* +config.action_controller.perform_caching+ configures whether the application should perform caching or not. Set to false in development mode, true in production. +* `config.action_controller.perform_caching` configures whether the application should perform caching or not. Set to false in development mode, true in production. -* +config.action_controller.default_charset+ specifies the default character set for all renders. The default is "utf-8". +* `config.action_controller.default_charset` specifies the default character set for all renders. The default is "utf-8". -* +config.action_controller.logger+ accepts a logger conforming to the interface of Log4r or the default Ruby Logger class, which is then used to log information from Action Controller. Set to +nil+ to disable logging. +* `config.action_controller.logger` accepts a logger conforming to the interface of Log4r or the default Ruby Logger class, which is then used to log information from Action Controller. Set to `nil` to disable logging. -* +config.action_controller.request_forgery_protection_token+ sets the token parameter name for RequestForgery. Calling +protect_from_forgery+ sets it to +:authenticity_token+ by default. +* `config.action_controller.request_forgery_protection_token` sets the token parameter name for RequestForgery. Calling `protect_from_forgery` sets it to `:authenticity_token` by default. -* +config.action_controller.allow_forgery_protection+ enables or disables CSRF protection. By default this is false in test mode and true in all other modes. +* `config.action_controller.allow_forgery_protection` enables or disables CSRF protection. By default this is false in test mode and true in all other modes. -* +config.action_controller.relative_url_root+ can be used to tell Rails that you are deploying to a subdirectory. The default is +ENV['RAILS_RELATIVE_URL_ROOT']+. +* `config.action_controller.relative_url_root` can be used to tell Rails that you are deploying to a subdirectory. The default is `ENV['RAILS_RELATIVE_URL_ROOT']`. The caching code adds two additional settings: -* +ActionController::Base.page_cache_directory+ sets the directory where Rails will create cached pages for your web server. The default is +Rails.public_path+ (which is usually set to `Rails.root + "/public"`). +* `ActionController::Base.page_cache_directory` sets the directory where Rails will create cached pages for your web server. The default is `Rails.public_path` (which is usually set to `Rails.root + "/public"`). -* +ActionController::Base.page_cache_extension+ sets the extension to be used when generating pages for the cache (this is ignored if the incoming request already has an extension). The default is +.html+. +* `ActionController::Base.page_cache_extension` sets the extension to be used when generating pages for the cache (this is ignored if the incoming request already has an extension). The default is `.html`. ### Configuring Action Dispatch -* +config.action_dispatch.session_store+ sets the name of the store for session data. The default is +:cookie_store+; other valid options include +:active_record_store+, +:mem_cache_store+ or the name of your own custom class. +* `config.action_dispatch.session_store` sets the name of the store for session data. The default is `:cookie_store`; other valid options include `:active_record_store`, `:mem_cache_store` or the name of your own custom class. -* +config.action_dispatch.default_headers+ is a hash with HTTP headers that are set by default in each response. By default, this is defined as: +* `config.action_dispatch.default_headers` is a hash with HTTP headers that are set by default in each response. By default, this is defined as: ```ruby config.action_dispatch.default_headers = { 'X-Frame-Options' => 'SAMEORIGIN', 'X-XSS-Protection' => '1; mode=block', 'X-Content-Type-Options' => 'nosniff' } ``` -* +config.action_dispatch.tld_length+ sets the TLD (top-level domain) length for the application. Defaults to +1+. +* `config.action_dispatch.tld_length` sets the TLD (top-level domain) length for the application. Defaults to `1`. -* +ActionDispatch::Callbacks.before+ takes a block of code to run before the request. +* `ActionDispatch::Callbacks.before` takes a block of code to run before the request. -* +ActionDispatch::Callbacks.to_prepare+ takes a block to run after +ActionDispatch::Callbacks.before+, but before the request. Runs for every request in +development+ mode, but only once for +production+ or environments with +cache_classes+ set to +true+. +* `ActionDispatch::Callbacks.to_prepare` takes a block to run after `ActionDispatch::Callbacks.before`, but before the request. Runs for every request in `development` mode, but only once for `production` or environments with `cache_classes` set to `true`. -* +ActionDispatch::Callbacks.after+ takes a block of code to run after the request. +* `ActionDispatch::Callbacks.after` takes a block of code to run after the request. ### Configuring Action View `config.action_view` includes a small number of configuration settings: -* +config.action_view.field_error_proc+ provides an HTML generator for displaying errors that come from Active Record. The default is +* `config.action_view.field_error_proc` provides an HTML generator for displaying errors that come from Active Record. The default is ```ruby Proc.new { |html_tag, instance| %Q(<div class="field_with_errors">#{html_tag}</div>).html_safe } ``` -* +config.action_view.default_form_builder+ tells Rails which form builder to use by default. The default is +ActionView::Helpers::FormBuilder+. If you want your form builder class to be loaded after initialization (so it's reloaded on each request in development), you can pass it as a +String+ +* `config.action_view.default_form_builder` tells Rails which form builder to use by default. The default is `ActionView::Helpers::FormBuilder`. If you want your form builder class to be loaded after initialization (so it's reloaded on each request in development), you can pass it as a `String` -* +config.action_view.logger+ accepts a logger conforming to the interface of Log4r or the default Ruby Logger class, which is then used to log information from Action View. Set to +nil+ to disable logging. +* `config.action_view.logger` accepts a logger conforming to the interface of Log4r or the default Ruby Logger class, which is then used to log information from Action View. Set to `nil` to disable logging. -* +config.action_view.erb_trim_mode+ gives the trim mode to be used by ERB. It defaults to +'-'+. See the "ERB documentation":http://www.ruby-doc.org/stdlib/libdoc/erb/rdoc/ for more information. +* `config.action_view.erb_trim_mode` gives the trim mode to be used by ERB. It defaults to `'-'`. See the "ERB documentation":http://www.ruby-doc.org/stdlib/libdoc/erb/rdoc/ for more information. -* +config.action_view.javascript_expansions+ is a hash containing expansions that can be used for the JavaScript include tag. By default, this is defined as: +* `config.action_view.javascript_expansions` is a hash containing expansions that can be used for the JavaScript include tag. By default, this is defined as: ```ruby config.action_view.javascript_expansions = { :defaults => %w(jquery jquery_ujs) } @@ -378,49 +378,49 @@ And can reference in the view with the following code: <%= javascript_include_tag :prototype %> ``` -* +config.action_view.stylesheet_expansions+ works in much the same way as +javascript_expansions+, but has no default key. Keys defined for this hash can be referenced in the view like such: +* `config.action_view.stylesheet_expansions` works in much the same way as `javascript_expansions`, but has no default key. Keys defined for this hash can be referenced in the view like such: ```ruby <%= stylesheet_link_tag :special %> ``` -* +config.action_view.cache_asset_ids+ With the cache enabled, the asset tag helper methods will make fewer expensive file system calls (the default implementation checks the file system timestamp). However this prevents you from modifying any asset files while the server is running. +* `config.action_view.cache_asset_ids` With the cache enabled, the asset tag helper methods will make fewer expensive file system calls (the default implementation checks the file system timestamp). However this prevents you from modifying any asset files while the server is running. -* +config.action_view.embed_authenticity_token_in_remote_forms+ allows you to set the default behavior for +authenticity_token+ in forms with +:remote => true+. By default it's set to false, which means that remote forms will not include +authenticity_token+, which is helpful when you're fragment-caching the form. Remote forms get the authenticity from the +meta+ tag, so embedding is unnecessary unless you support browsers without JavaScript. In such case you can either pass +:authenticity_token => true+ as a form option or set this config setting to +true+ +* `config.action_view.embed_authenticity_token_in_remote_forms` allows you to set the default behavior for `authenticity_token` in forms with `:remote => true`. By default it's set to false, which means that remote forms will not include `authenticity_token`, which is helpful when you're fragment-caching the form. Remote forms get the authenticity from the `meta` tag, so embedding is unnecessary unless you support browsers without JavaScript. In such case you can either pass `:authenticity_token => true` as a form option or set this config setting to `true` -* +config.action_view.prefix_partial_path_with_controller_namespace+ determines whether or not partials are looked up from a subdirectory in templates rendered from namespaced controllers. For example, consider a controller named +Admin::PostsController+ which renders this template: +* `config.action_view.prefix_partial_path_with_controller_namespace` determines whether or not partials are looked up from a subdirectory in templates rendered from namespaced controllers. For example, consider a controller named `Admin::PostsController` which renders this template: ```erb <%= render @post %> ``` -The default setting is +true+, which uses the partial at +/admin/posts/_post.erb+. Setting the value to +false+ would render +/posts/_post.erb+, which is the same behavior as rendering from a non-namespaced controller such as +PostsController+. +The default setting is `true`, which uses the partial at `/admin/posts/_post.erb`. Setting the value to `false` would render `/posts/_post.erb`, which is the same behavior as rendering from a non-namespaced controller such as `PostsController`. ### Configuring Action Mailer -There are a number of settings available on +config.action_mailer+: +There are a number of settings available on `config.action_mailer`: -* +config.action_mailer.logger+ accepts a logger conforming to the interface of Log4r or the default Ruby Logger class, which is then used to log information from Action Mailer. Set to +nil+ to disable logging. +* `config.action_mailer.logger` accepts a logger conforming to the interface of Log4r or the default Ruby Logger class, which is then used to log information from Action Mailer. Set to `nil` to disable logging. -* +config.action_mailer.smtp_settings+ allows detailed configuration for the +:smtp+ delivery method. It accepts a hash of options, which can include any of these options: -** +: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+. +* `config.action_mailer.smtp_settings` allows detailed configuration for the `:smtp` delivery method. It accepts a hash of options, which can include any of these options: +** `: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`. -* +config.action_mailer.sendmail_settings+ allows detailed configuration for the +sendmail+ delivery method. It accepts a hash of options, which can include any of these options: -** +:location+ - The location of the sendmail executable. Defaults to +/usr/sbin/sendmail+. -** +:arguments+ - The command line arguments. Defaults to +-i -t+. +* `config.action_mailer.sendmail_settings` allows detailed configuration for the `sendmail` delivery method. It accepts a hash of options, which can include any of these options: +** `:location` - The location of the sendmail executable. Defaults to `/usr/sbin/sendmail`. +** `:arguments` - The command line arguments. Defaults to `-i -t`. -* +config.action_mailer.raise_delivery_errors+ specifies whether to raise an error if email delivery cannot be completed. It defaults to true. +* `config.action_mailer.raise_delivery_errors` specifies whether to raise an error if email delivery cannot be completed. It defaults to true. -* +config.action_mailer.delivery_method+ defines the delivery method. The allowed values are +:smtp+ (default), +:sendmail+, and +:test+. +* `config.action_mailer.delivery_method` defines the delivery method. The allowed values are `:smtp` (default), `:sendmail`, and `:test`. -* +config.action_mailer.perform_deliveries+ specifies whether mail will actually be delivered and is true by default. It can be convenient to set it to false for testing. +* `config.action_mailer.perform_deliveries` specifies whether mail will actually be delivered and is true by default. It can be convenient to set it to false for testing. -* +config.action_mailer.default_options+ configures Action Mailer defaults. Use to set options like `from` or `reply_to` for every mailer. These default to: +* `config.action_mailer.default_options` configures Action Mailer defaults. Use to set options like `from` or `reply_to` for every mailer. These default to: ```ruby :mime_version => "1.0", :charset => "UTF-8", @@ -428,17 +428,17 @@ There are a number of settings available on +config.action_mailer+: :parts_order => [ "text/plain", "text/enriched", "text/html" ] ``` -* +config.action_mailer.observers+ registers observers which will be notified when mail is delivered. +* `config.action_mailer.observers` registers observers which will be notified when mail is delivered. ```ruby config.action_mailer.observers = ["MailObserver"] ``` -* +config.action_mailer.interceptors+ registers interceptors which will be called before mail is sent. +* `config.action_mailer.interceptors` registers interceptors which will be called before mail is sent. ```ruby config.action_mailer.interceptors = ["MailInterceptor"] ``` -* +config.action_mailer.queue+ registers the queue that will be used to deliver the mail. +* `config.action_mailer.queue` registers the queue that will be used to deliver the mail. ```ruby config.action_mailer.queue = SomeQueue.new ``` @@ -447,33 +447,33 @@ config.action_mailer.queue = SomeQueue.new There are a few configuration options available in Active Support: -* +config.active_support.bare+ enables or disables the loading of +active_support/all+ when booting Rails. Defaults to +nil+, which means +active_support/all+ is loaded. +* `config.active_support.bare` enables or disables the loading of `active_support/all` when booting Rails. Defaults to `nil`, which means `active_support/all` is loaded. -* +config.active_support.escape_html_entities_in_json+ enables or disables the escaping of HTML entities in JSON serialization. Defaults to +false+. +* `config.active_support.escape_html_entities_in_json` enables or disables the escaping of HTML entities in JSON serialization. Defaults to `false`. -* +config.active_support.use_standard_json_time_format+ enables or disables serializing dates to ISO 8601 format. Defaults to +true+. +* `config.active_support.use_standard_json_time_format` enables or disables serializing dates to ISO 8601 format. Defaults to `true`. -* +ActiveSupport::BufferedLogger.silencer+ is set to +false+ to disable the ability to silence logging in a block. The default is +true+. +* `ActiveSupport::BufferedLogger.silencer` is set to `false` to disable the ability to silence logging in a block. The default is `true`. -* +ActiveSupport::Cache::Store.logger+ specifies the logger to use within cache store operations. +* `ActiveSupport::Cache::Store.logger` specifies the logger to use within cache store operations. -* +ActiveSupport::Deprecation.behavior+ alternative setter to +config.active_support.deprecation+ which configures the behavior of deprecation warnings for Rails. +* `ActiveSupport::Deprecation.behavior` alternative setter to `config.active_support.deprecation` which configures the behavior of deprecation warnings for Rails. -* +ActiveSupport::Deprecation.silence+ takes a block in which all deprecation warnings are silenced. +* `ActiveSupport::Deprecation.silence` takes a block in which all deprecation warnings are silenced. -* +ActiveSupport::Deprecation.silenced+ sets whether or not to display deprecation warnings. +* `ActiveSupport::Deprecation.silenced` sets whether or not to display deprecation warnings. -* +ActiveSupport::Logger.silencer+ is set to +false+ to disable the ability to silence logging in a block. The default is +true+. +* `ActiveSupport::Logger.silencer` is set to `false` to disable the ability to silence logging in a block. The default is `true`. ### Configuring a Database -Just about every Rails application will interact with a database. The database to use is specified in a configuration file called +config/database.yml+. If you open this file in a new Rails application, you'll see a default database configured to use SQLite3. The file contains sections for three different environments in which Rails can run by default: +Just about every Rails application will interact with a database. The database to use is specified in a configuration file called `config/database.yml`. If you open this file in a new Rails application, you'll see a default database configured to use SQLite3. The file contains sections for three different environments in which Rails can run by default: -* The +development+ environment is used on your development/local computer as you interact manually with the application. -* The +test+ environment is used when running automated tests. -* The +production+ environment is used when you deploy your application for the world to use. +* The `development` environment is used on your development/local computer as you interact manually with the application. +* The `test` environment is used when running automated tests. +* The `production` environment is used when you deploy your application for the world to use. -TIP: You don't have to update the database configurations manually. If you look at the options of the application generator, you will see that one of the options is named `--database`. This option allows you to choose an adapter from a list of the most used relational databases. You can even run the generator repeatedly: `cd .. && rails new blog --database=mysql`. When you confirm the overwriting of the +config/database.yml+ file, your application will be configured for MySQL instead of SQLite. Detailed examples of the common database connections are below. +TIP: You don't have to update the database configurations manually. If you look at the options of the application generator, you will see that one of the options is named `--database`. This option allows you to choose an adapter from a list of the most used relational databases. You can even run the generator repeatedly: `cd .. && rails new blog --database=mysql`. When you confirm the overwriting of the `config/database.yml` file, your application will be configured for MySQL instead of SQLite. Detailed examples of the common database connections are below. #### Configuring an SQLite3 Database @@ -493,7 +493,7 @@ NOTE: Rails uses an SQLite3 database for data storage by default because it is a #### Configuring a MySQL Database -If you choose to use MySQL instead of the shipped SQLite3 database, your +config/database.yml+ will look a little different. Here's the development section: +If you choose to use MySQL instead of the shipped SQLite3 database, your `config/database.yml` will look a little different. Here's the development section: ```yaml development: @@ -506,11 +506,11 @@ development: socket: /tmp/mysql.sock ``` -If your development computer's MySQL installation includes a root user with an empty password, this configuration should work for you. Otherwise, change the username and password in the +development+ section as appropriate. +If your development computer's MySQL installation includes a root user with an empty password, this configuration should work for you. Otherwise, change the username and password in the `development` section as appropriate. #### Configuring a PostgreSQL Database -If you choose to use PostgreSQL, your +config/database.yml+ will be customized to use PostgreSQL databases: +If you choose to use PostgreSQL, your `config/database.yml` will be customized to use PostgreSQL databases: ```yaml development: @@ -532,7 +532,7 @@ production: #### Configuring an SQLite3 Database for JRuby Platform -If you choose to use SQLite3 and are using JRuby, your +config/database.yml+ will look a little different. Here's the development section: +If you choose to use SQLite3 and are using JRuby, your `config/database.yml` will look a little different. Here's the development section: ```yaml development: @@ -542,7 +542,7 @@ development: #### Configuring a MySQL Database for JRuby Platform -If you choose to use MySQL and are using JRuby, your +config/database.yml+ will look a little different. Here's the development section: +If you choose to use MySQL and are using JRuby, your `config/database.yml` will look a little different. Here's the development section: ```yaml development: @@ -554,7 +554,7 @@ development: #### Configuring a PostgreSQL Database for JRuby Platform -If you choose to use PostgreSQL and are using JRuby, your +config/database.yml+ will look a little different. Here's the development section: +If you choose to use PostgreSQL and are using JRuby, your `config/database.yml` will look a little different. Here's the development section: ```yaml development: @@ -565,47 +565,47 @@ development: password: ``` -Change the username and password in the +development+ section as appropriate. +Change the username and password in the `development` section as appropriate. Rails Environment Settings -------------------------- Some parts of Rails can also be configured externally by supplying environment variables. The following environment variables are recognized by various parts of Rails: -* +ENV["RAILS_ENV"]+ defines the Rails environment (production, development, test, and so on) that Rails will run under. +* `ENV["RAILS_ENV"]` defines the Rails environment (production, development, test, and so on) that Rails will run under. -* +ENV["RAILS_RELATIVE_URL_ROOT"]+ is used by the routing code to recognize URLs when you deploy your application to a subdirectory. +* `ENV["RAILS_RELATIVE_URL_ROOT"]` is used by the routing code to recognize URLs when you deploy your application to a subdirectory. -* +ENV["RAILS_ASSET_ID"]+ will override the default cache-busting timestamps that Rails generates for downloadable assets. +* `ENV["RAILS_ASSET_ID"]` will override the default cache-busting timestamps that Rails generates for downloadable assets. -* +ENV["RAILS_CACHE_ID"]+ and +ENV["RAILS_APP_VERSION"]+ are used to generate expanded cache keys in Rails' caching code. This allows you to have multiple separate caches from the same application. +* `ENV["RAILS_CACHE_ID"]` and `ENV["RAILS_APP_VERSION"]` are used to generate expanded cache keys in Rails' caching code. This allows you to have multiple separate caches from the same application. Using Initializer Files ----------------------- -After loading the framework and any gems in your application, Rails turns to loading initializers. An initializer is any Ruby file stored under +config/initializers+ in your application. You can use initializers to hold configuration settings that should be made after all of the frameworks and gems are loaded, such as options to configure settings for these parts. +After loading the framework and any gems in your application, Rails turns to loading initializers. An initializer is any Ruby file stored under `config/initializers` in your application. You can use initializers to hold configuration settings that should be made after all of the frameworks and gems are loaded, such as options to configure settings for these parts. NOTE: You can use subfolders to organize your initializers if you like, because Rails will look into the whole file hierarchy from the initializers folder on down. -TIP: If you have any ordering dependency in your initializers, you can control the load order through naming. Initializer files are loaded in alphabetical order by their path. For example, +01_critical.rb+ will be loaded before +02_normal.rb+. +TIP: If you have any ordering dependency in your initializers, you can control the load order through naming. Initializer files are loaded in alphabetical order by their path. For example, `01_critical.rb` will be loaded before `02_normal.rb`. Initialization events --------------------- Rails has 5 initialization events which can be hooked into (listed in the order that they are run): -* +before_configuration+: This is run as soon as the application constant inherits from +Rails::Application+. The +config+ calls are evaluated before this happens. +* `before_configuration`: This is run as soon as the application constant inherits from `Rails::Application`. The `config` calls are evaluated before this happens. -* +before_initialize+: This is run directly before the initialization process of the application occurs with the +:bootstrap_hook+ initializer near the beginning of the Rails initialization process. +* `before_initialize`: This is run directly before the initialization process of the application occurs with the `:bootstrap_hook` initializer near the beginning of the Rails initialization process. -* +to_prepare+: Run after the initializers are run for all Railties (including the application itself), but before eager loading and the middleware stack is built. More importantly, will run upon every request in +development+, but only once (during boot-up) in +production+ and +test+. +* `to_prepare`: Run after the initializers are run for all Railties (including the application itself), but before eager loading and the middleware stack is built. More importantly, will run upon every request in `development`, but only once (during boot-up) in `production` and `test`. -* +before_eager_load+: This is run directly before eager loading occurs, which is the default behaviour for the +production+ environment and not for the +development+ environment. +* `before_eager_load`: This is run directly before eager loading occurs, which is the default behaviour for the `production` environment and not for the `development` environment. -* +after_initialize+: Run directly after the initialization of the application, but before the application initializers are run. +* `after_initialize`: Run directly after the initialization of the application, but before the application initializers are run. -To define an event for these hooks, use the block syntax within a +Rails::Application+, +Rails::Railtie+ or +Rails::Engine+ subclass: +To define an event for these hooks, use the block syntax within a `Rails::Application`, `Rails::Railtie` or `Rails::Engine` subclass: ```ruby module YourApp @@ -617,7 +617,7 @@ module YourApp end ``` -Alternatively, you can also do it through the +config+ method on the +Rails.application+ object: +Alternatively, you can also do it through the `config` method on the `Rails.application` object: ```ruby Rails.application.config.before_initialize do @@ -625,11 +625,11 @@ Rails.application.config.before_initialize do end ``` -WARNING: Some parts of your application, notably observers and routing, are not yet set up at the point where the +after_initialize+ block is called. +WARNING: Some parts of your application, notably observers and routing, are not yet set up at the point where the `after_initialize` block is called. -### +Rails::Railtie#initializer+ +### `Rails::Railtie#initializer` -Rails has several initializers that run on startup that are all defined by using the +initializer+ method from +Rails::Railtie+. Here's an example of the +initialize_whiny_nils+ initializer from Active Support: +Rails has several initializers that run on startup that are all defined by using the `initializer` method from `Rails::Railtie`. Here's an example of the `initialize_whiny_nils` initializer from Active Support: ```ruby initializer "active_support.initialize_whiny_nils" do |app| @@ -637,38 +637,38 @@ initializer "active_support.initialize_whiny_nils" do |app| end ``` -The +initializer+ method takes three arguments with the first being the name for the initializer and the second being an options hash (not shown here) and the third being a block. The +:before+ key in the options hash can be specified to specify which initializer this new initializer must run before, and the +:after+ key will specify which initializer to run this initializer _after_. +The `initializer` method takes three arguments with the first being the name for the initializer and the second being an options hash (not shown here) and the third being a block. The `:before` key in the options hash can be specified to specify which initializer this new initializer must run before, and the `:after` key will specify which initializer to run this initializer _after_. -Initializers defined using the +initializer+ method will be ran in the order they are defined in, with the exception of ones that use the +:before+ or +:after+ methods. +Initializers defined using the `initializer` method will be ran in the order they are defined in, with the exception of ones that use the `:before` or `:after` methods. WARNING: You may put your initializer before or after any other initializer in the chain, as long as it is logical. Say you have 4 initializers called "one" through "four" (defined in that order) and you define "four" to go _before_ "four" but _after_ "three", that just isn't logical and Rails will not be able to determine your initializer order. -The block argument of the +initializer+ method is the instance of the application itself, and so we can access the configuration on it by using the +config+ method as done in the example. +The block argument of the `initializer` method is the instance of the application itself, and so we can access the configuration on it by using the `config` method as done in the example. -Because +Rails::Application+ inherits from +Rails::Railtie+ (indirectly), you can use the +initializer+ method in +config/application.rb+ to define initializers for the application. +Because `Rails::Application` inherits from `Rails::Railtie` (indirectly), you can use the `initializer` method in `config/application.rb` to define initializers for the application. ### Initializers Below is a comprehensive list of all the initializers found in Rails in the order that they are defined (and therefore run in, unless otherwise stated). -*+load_environment_hook+* -Serves as a placeholder so that +:load_environment_config+ can be defined to run before it. +*`load_environment_hook`* +Serves as a placeholder so that `:load_environment_config` can be defined to run before it. -*+load_active_support+* Requires +active_support/dependencies+ which sets up the basis for Active Support. Optionally requires +active_support/all+ if +config.active_support.bare+ is un-truthful, which is the default. +*`load_active_support`* Requires `active_support/dependencies` which sets up the basis for Active Support. Optionally requires `active_support/all` if `config.active_support.bare` is un-truthful, which is the default. -*+initialize_logger+* Initializes the logger (an +ActiveSupport::BufferedLogger+ object) for the application and makes it accessible at +Rails.logger+, provided that no initializer inserted before this point has defined +Rails.logger+. +*`initialize_logger`* Initializes the logger (an `ActiveSupport::BufferedLogger` object) for the application and makes it accessible at `Rails.logger`, provided that no initializer inserted before this point has defined `Rails.logger`. -*+initialize_cache+* If +Rails.cache+ isn't set yet, initializes the cache by referencing the value in +config.cache_store+ and stores the outcome as +Rails.cache+. If this object responds to the +middleware+ method, its middleware is inserted before +Rack::Runtime+ in the middleware stack. +*`initialize_cache`* If `Rails.cache` isn't set yet, initializes the cache by referencing the value in `config.cache_store` and stores the outcome as `Rails.cache`. If this object responds to the `middleware` method, its middleware is inserted before `Rack::Runtime` in the middleware stack. -*+set_clear_dependencies_hook+* Provides a hook for +active_record.set_dispatch_hooks+ to use, which will run before this initializer. This initializer -- which runs only if +cache_classes+ is set to +false+ -- uses +ActionDispatch::Callbacks.after+ to remove the constants which have been referenced during the request from the object space so that they will be reloaded during the following request. +*`set_clear_dependencies_hook`* Provides a hook for `active_record.set_dispatch_hooks` to use, which will run before this initializer. This initializer -- which runs only if `cache_classes` is set to `false` -- uses `ActionDispatch::Callbacks.after` to remove the constants which have been referenced during the request from the object space so that they will be reloaded during the following request. -*+initialize_dependency_mechanism+* If +config.cache_classes+ is true, configures +ActiveSupport::Dependencies.mechanism+ to +require+ dependencies rather than +load+ them. +*`initialize_dependency_mechanism`* If `config.cache_classes` is true, configures `ActiveSupport::Dependencies.mechanism` to `require` dependencies rather than `load` them. -*+bootstrap_hook+* Runs all configured +before_initialize+ blocks. +*`bootstrap_hook`* Runs all configured `before_initialize` blocks. -*+i18n.callbacks+* In the development environment, sets up a +to_prepare+ callback which will call +I18n.reload!+ if any of the locales have changed since the last request. In production mode this callback will only run on the first request. +*`i18n.callbacks`* In the development environment, sets up a `to_prepare` callback which will call `I18n.reload!` if any of the locales have changed since the last request. In production mode this callback will only run on the first request. -*+active_support.initialize_whiny_nils+* Requires +active_support/whiny_nil+ if +config.whiny_nils+ is true. This file will output errors such as: +*`active_support.initialize_whiny_nils`* Requires `active_support/whiny_nil` if `config.whiny_nils` is true. This file will output errors such as: ``` Called id for nil, which would mistakenly be 4 -- if you really wanted the id of nil, use object_id @@ -682,86 +682,86 @@ You might have expected an instance of Array. The error occurred while evaluating nil.each ``` -*+active_support.deprecation_behavior+* Sets up deprecation reporting for environments, defaulting to +:log+ for development, +:notify+ for production and +:stderr+ for test. If a value isn't set for +config.active_support.deprecation+ then this initializer will prompt the user to configure this line in the current environment's +config/environments+ file. Can be set to an array of values. +*`active_support.deprecation_behavior`* Sets up deprecation reporting for environments, defaulting to `:log` for development, `:notify` for production and `:stderr` for test. If a value isn't set for `config.active_support.deprecation` then this initializer will prompt the user to configure this line in the current environment's `config/environments` file. Can be set to an array of values. -*+active_support.initialize_time_zone+* Sets the default time zone for the application based on the +config.time_zone+ setting, which defaults to "UTC". +*`active_support.initialize_time_zone`* Sets the default time zone for the application based on the `config.time_zone` setting, which defaults to "UTC". -*+action_dispatch.configure+* Configures the +ActionDispatch::Http::URL.tld_length+ to be set to the value of +config.action_dispatch.tld_length+. +*`action_dispatch.configure`* Configures the `ActionDispatch::Http::URL.tld_length` to be set to the value of `config.action_dispatch.tld_length`. -*+action_view.cache_asset_ids+* Sets +ActionView::Helpers::AssetTagHelper::AssetPaths.cache_asset_ids+ to +false+ when Active Support loads, but only if +config.cache_classes+ is too. +*`action_view.cache_asset_ids`* Sets `ActionView::Helpers::AssetTagHelper::AssetPaths.cache_asset_ids` to `false` when Active Support loads, but only if `config.cache_classes` is too. -*+action_view.javascript_expansions+* Registers the expansions set up by +config.action_view.javascript_expansions+ and +config.action_view.stylesheet_expansions+ to be recognized by Action View and therefore usable in the views. +*`action_view.javascript_expansions`* Registers the expansions set up by `config.action_view.javascript_expansions` and `config.action_view.stylesheet_expansions` to be recognized by Action View and therefore usable in the views. -*+action_view.set_configs+* Sets up Action View by using the settings in +config.action_view+ by +send+'ing the method names as setters to +ActionView::Base+ and passing the values through. +*`action_view.set_configs`* Sets up Action View by using the settings in `config.action_view` by `send`'ing the method names as setters to `ActionView::Base` and passing the values through. -*+action_controller.logger+* Sets +ActionController::Base.logger+ -- if it's not already set -- to +Rails.logger+. +*`action_controller.logger`* Sets `ActionController::Base.logger` -- if it's not already set -- to `Rails.logger`. -*+action_controller.initialize_framework_caches+* Sets +ActionController::Base.cache_store+ -- if it's not already set -- to +Rails.cache+. +*`action_controller.initialize_framework_caches`* Sets `ActionController::Base.cache_store` -- if it's not already set -- to `Rails.cache`. -*+action_controller.set_configs+* Sets up Action Controller by using the settings in +config.action_controller+ by +send+'ing the method names as setters to +ActionController::Base+ and passing the values through. +*`action_controller.set_configs`* Sets up Action Controller by using the settings in `config.action_controller` by `send`'ing the method names as setters to `ActionController::Base` and passing the values through. -*+action_controller.compile_config_methods+* Initializes methods for the config settings specified so that they are quicker to access. +*`action_controller.compile_config_methods`* Initializes methods for the config settings specified so that they are quicker to access. -*+active_record.initialize_timezone+* Sets +ActiveRecord::Base.time_zone_aware_attributes+ to true, as well as setting +ActiveRecord::Base.default_timezone+ to UTC. When attributes are read from the database, they will be converted into the time zone specified by +Time.zone+. +*`active_record.initialize_timezone`* Sets `ActiveRecord::Base.time_zone_aware_attributes` to true, as well as setting `ActiveRecord::Base.default_timezone` to UTC. When attributes are read from the database, they will be converted into the time zone specified by `Time.zone`. -*+active_record.logger+* Sets +ActiveRecord::Base.logger+ -- if it's not already set -- to +Rails.logger+. +*`active_record.logger`* Sets `ActiveRecord::Base.logger` -- if it's not already set -- to `Rails.logger`. -*+active_record.set_configs+* Sets up Active Record by using the settings in +config.active_record+ by +send+'ing the method names as setters to +ActiveRecord::Base+ and passing the values through. +*`active_record.set_configs`* Sets up Active Record by using the settings in `config.active_record` by `send`'ing the method names as setters to `ActiveRecord::Base` and passing the values through. -*+active_record.initialize_database+* Loads the database configuration (by default) from +config/database.yml+ and establishes a connection for the current environment. +*`active_record.initialize_database`* Loads the database configuration (by default) from `config/database.yml` and establishes a connection for the current environment. -*+active_record.log_runtime+* Includes +ActiveRecord::Railties::ControllerRuntime+ which is responsible for reporting the time taken by Active Record calls for the request back to the logger. +*`active_record.log_runtime`* Includes `ActiveRecord::Railties::ControllerRuntime` which is responsible for reporting the time taken by Active Record calls for the request back to the logger. -*+active_record.set_dispatch_hooks+* Resets all reloadable connections to the database if +config.cache_classes+ is set to +false+. +*`active_record.set_dispatch_hooks`* Resets all reloadable connections to the database if `config.cache_classes` is set to `false`. -*+action_mailer.logger+* Sets +ActionMailer::Base.logger+ -- if it's not already set -- to +Rails.logger+. +*`action_mailer.logger`* Sets `ActionMailer::Base.logger` -- if it's not already set -- to `Rails.logger`. -*+action_mailer.set_configs+* Sets up Action Mailer by using the settings in +config.action_mailer+ by +send+'ing the method names as setters to +ActionMailer::Base+ and passing the values through. +*`action_mailer.set_configs`* Sets up Action Mailer by using the settings in `config.action_mailer` by `send`'ing the method names as setters to `ActionMailer::Base` and passing the values through. -*+action_mailer.compile_config_methods+* Initializes methods for the config settings specified so that they are quicker to access. +*`action_mailer.compile_config_methods`* Initializes methods for the config settings specified so that they are quicker to access. -*+set_load_path+* This initializer runs before +bootstrap_hook+. Adds the +vendor+, +lib+, all directories of +app+ and any paths specified by +config.load_paths+ to +$LOAD_PATH+. +*`set_load_path`* This initializer runs before `bootstrap_hook`. Adds the `vendor`, `lib`, all directories of `app` and any paths specified by `config.load_paths` to `$LOAD_PATH`. -*+set_autoload_paths+* This initializer runs before +bootstrap_hook+. Adds all sub-directories of +app+ and paths specified by +config.autoload_paths+ to +ActiveSupport::Dependencies.autoload_paths+. +*`set_autoload_paths`* This initializer runs before `bootstrap_hook`. Adds all sub-directories of `app` and paths specified by `config.autoload_paths` to `ActiveSupport::Dependencies.autoload_paths`. -*+add_routing_paths+* Loads (by default) all +config/routes.rb+ files (in the application and railties, including engines) and sets up the routes for the application. +*`add_routing_paths`* Loads (by default) all `config/routes.rb` files (in the application and railties, including engines) and sets up the routes for the application. -*+add_locales+* Adds the files in +config/locales+ (from the application, railties and engines) to +I18n.load_path+, making available the translations in these files. +*`add_locales`* Adds the files in `config/locales` (from the application, railties and engines) to `I18n.load_path`, making available the translations in these files. -*+add_view_paths+* Adds the directory +app/views+ from the application, railties and engines to the lookup path for view files for the application. +*`add_view_paths`* Adds the directory `app/views` from the application, railties and engines to the lookup path for view files for the application. -*+load_environment_config+* Loads the +config/environments+ file for the current environment. +*`load_environment_config`* Loads the `config/environments` file for the current environment. -*+append_asset_paths+* Finds asset paths for the application and all attached railties and keeps a track of the available directories in +config.static_asset_paths+. +*`append_asset_paths`* Finds asset paths for the application and all attached railties and keeps a track of the available directories in `config.static_asset_paths`. -*+prepend_helpers_path+* Adds the directory +app/helpers+ from the application, railties and engines to the lookup path for helpers for the application. +*`prepend_helpers_path`* Adds the directory `app/helpers` from the application, railties and engines to the lookup path for helpers for the application. -*+load_config_initializers+* Loads all Ruby files from +config/initializers+ in the application, railties and engines. The files in this directory can be used to hold configuration settings that should be made after all of the frameworks are loaded. +*`load_config_initializers`* Loads all Ruby files from `config/initializers` in the application, railties and engines. The files in this directory can be used to hold configuration settings that should be made after all of the frameworks are loaded. -*+engines_blank_point+* Provides a point-in-initialization to hook into if you wish to do anything before engines are loaded. After this point, all railtie and engine initializers are run. +*`engines_blank_point`* Provides a point-in-initialization to hook into if you wish to do anything before engines are loaded. After this point, all railtie and engine initializers are run. -*+add_generator_templates+* Finds templates for generators at +lib/templates+ for the application, railities and engines and adds these to the +config.generators.templates+ setting, which will make the templates available for all generators to reference. +*`add_generator_templates`* Finds templates for generators at `lib/templates` for the application, railities and engines and adds these to the `config.generators.templates` setting, which will make the templates available for all generators to reference. -*+ensure_autoload_once_paths_as_subset+* Ensures that the +config.autoload_once_paths+ only contains paths from +config.autoload_paths+. If it contains extra paths, then an exception will be raised. +*`ensure_autoload_once_paths_as_subset`* Ensures that the `config.autoload_once_paths` only contains paths from `config.autoload_paths`. If it contains extra paths, then an exception will be raised. -*+add_to_prepare_blocks+* The block for every +config.to_prepare+ call in the application, a railtie or engine is added to the +to_prepare+ callbacks for Action Dispatch which will be ran per request in development, or before the first request in production. +*`add_to_prepare_blocks`* The block for every `config.to_prepare` call in the application, a railtie or engine is added to the `to_prepare` callbacks for Action Dispatch which will be ran per request in development, or before the first request in production. -*+add_builtin_route+* If the application is running under the development environment then this will append the route for +rails/info/properties+ to the application routes. This route provides the detailed information such as Rails and Ruby version for +public/index.html+ in a default Rails application. +*`add_builtin_route`* If the application is running under the development environment then this will append the route for `rails/info/properties` to the application routes. This route provides the detailed information such as Rails and Ruby version for `public/index.html` in a default Rails application. -*+build_middleware_stack+* Builds the middleware stack for the application, returning an object which has a +call+ method which takes a Rack environment object for the request. +*`build_middleware_stack`* Builds the middleware stack for the application, returning an object which has a `call` method which takes a Rack environment object for the request. -*+eager_load!+* If +config.eager_load+ is true, runs the +config.before_eager_load+ hooks and then calls +eager_load!+ which will load all +config.eager_load_namespaces+. +*`eager_load!`* If `config.eager_load` is true, runs the `config.before_eager_load` hooks and then calls `eager_load!` which will load all `config.eager_load_namespaces`. -*+finisher_hook+* Provides a hook for after the initialization of process of the application is complete, as well as running all the +config.after_initialize+ blocks for the application, railties and engines. +*`finisher_hook`* Provides a hook for after the initialization of process of the application is complete, as well as running all the `config.after_initialize` blocks for the application, railties and engines. -*+set_routes_reloader+* Configures Action Dispatch to reload the routes file using +ActionDispatch::Callbacks.to_prepare+. +*`set_routes_reloader`* Configures Action Dispatch to reload the routes file using `ActionDispatch::Callbacks.to_prepare`. -*+disable_dependency_loading+* Disables the automatic dependency loading if the +config.eager_load+ is set to true. +*`disable_dependency_loading`* Disables the automatic dependency loading if the `config.eager_load` is set to true. Database pooling ---------------- -Active Record database connections are managed by +ActiveRecord::ConnectionAdapters::ConnectionPool+ which ensures that a connection pool synchronizes the amount of thread access to a limited number of database connections. This limit defaults to 5 and can be configured in +database.yml+. +Active Record database connections are managed by `ActiveRecord::ConnectionAdapters::ConnectionPool` which ensures that a connection pool synchronizes the amount of thread access to a limited number of database connections. This limit defaults to 5 and can be configured in `database.yml`. ```ruby development: @@ -775,4 +775,4 @@ Since the connection pooling is handled inside of ActiveRecord by default, all a Any one request will check out a connection the first time it requires access to the database, after which it will check the connection back in, at the end of the request, meaning that the additional connection slot will be available again for the next request in the queue. -NOTE. If you have enabled +Rails.threadsafe!+ mode then there could be a chance that several threads may be accessing multiple connections simultaneously. So depending on your current request load, you could very well have multiple threads contending for a limited amount of connections. +NOTE. If you have enabled `Rails.threadsafe!` mode then there could be a chance that several threads may be accessing multiple connections simultaneously. So depending on your current request load, you could very well have multiple threads contending for a limited amount of connections. diff --git a/guides/source/contributing_to_ruby_on_rails.md b/guides/source/contributing_to_ruby_on_rails.md index 34f8f475af..073a986b2f 100644 --- a/guides/source/contributing_to_ruby_on_rails.md +++ b/guides/source/contributing_to_ruby_on_rails.md @@ -60,7 +60,7 @@ Ruby on Rails uses Git for source code control. The "Git homepage":http://git-sc #### Clone the Ruby on Rails Repository -Navigate to the folder where you want the Ruby on Rails source code (it will create its own +rails+ subdirectory) and run: +Navigate to the folder where you want the Ruby on Rails source code (it will create its own `rails` subdirectory) and run: ```bash $ git clone git://github.com/rails/rails.git @@ -85,7 +85,7 @@ $ sudo yum install libxml2 libxml2-devel libxslt libxslt-devel If you have any problems with these libraries, you should install them manually compiling the source code. Just follow the instructions at the "Red Hat/CentOS section of the Nokogiri tutorials":http://nokogiri.org/tutorials/installing_nokogiri.html#red_hat__centos . -Also, SQLite3 and its development files for the +sqlite3-ruby+ gem -- in Ubuntu you're done with just +Also, SQLite3 and its development files for the `sqlite3-ruby` gem -- in Ubuntu you're done with just ```bash $ sudo apt-get install sqlite3 libsqlite3-dev @@ -123,7 +123,7 @@ $ cd actionpack $ bundle exec rake test ``` -If you want to run the tests located in a specific directory use the +TEST_DIR+ environment variable. For example, this will run the tests of the +railties/test/generators+ directory only: +If you want to run the tests located in a specific directory use the `TEST_DIR` environment variable. For example, this will run the tests of the `railties/test/generators` directory only: ```bash $ cd railties @@ -139,13 +139,13 @@ $ bundle exec ruby -Itest test/template/form_helper_test.rb #### Active Record Setup -The test suite of Active Record attempts to run four times: once for SQLite3, once for each of the two MySQL gems (+mysql+ and +mysql2+), and once for PostgreSQL. We are going to see now how to set up the environment for them. +The test suite of Active Record attempts to run four times: once for SQLite3, once for each of the two MySQL gems (`mysql` and `mysql2`), and once for PostgreSQL. We are going to see now how to set up the environment for them. WARNING: If you're working with Active Record code, you _must_ ensure that the tests pass for at least MySQL, PostgreSQL, and SQLite3. Subtle differences between the various adapters have been behind the rejection of many patches that looked OK when tested only against MySQL. ##### Database Configuration -The Active Record test suite requires a custom config file: +activerecord/test/config.yml+. An example is provided in +activerecord/test/config.example.yml+ which can be copied and used as needed for your environment. +The Active Record test suite requires a custom config file: `activerecord/test/config.yml`. An example is provided in `activerecord/test/config.example.yml` which can be copied and used as needed for your environment. ##### MySQL and PostgreSQL @@ -170,9 +170,9 @@ $ rm .bundle/config $ bundle install ``` -We need first to delete +.bundle/config+ because Bundler remembers in that file that we didn't want to install the "db" group (alternatively you can edit the file). +We need first to delete `.bundle/config` because Bundler remembers in that file that we didn't want to install the "db" group (alternatively you can edit the file). -In order to be able to run the test suite against MySQL you need to create a user named +rails+ with privileges on the test databases: +In order to be able to run the test suite against MySQL you need to create a user named `rails` with privileges on the test databases: ```bash mysql> GRANT ALL PRIVILEGES ON activerecord_unittest.* @@ -205,7 +205,7 @@ NOTE: Using the rake task to create the test databases ensures they have the cor NOTE: You'll see the following warning (or localized warning) during activating HStore extension in PostgreSQL 9.1.x or earlier: "WARNING: => is deprecated as an operator". -If you’re using another database, check the file +activerecord/test/config.yml+ or +activerecord/test/config.example.yml+ for default connection information. You can edit +activerecord/test/config.yml+ to provide different credentials on your machine if you must, but obviously you should not push any such changes back to Rails. +If you’re using another database, check the file `activerecord/test/config.yml` or `activerecord/test/config.example.yml` for default connection information. You can edit `activerecord/test/config.yml` to provide different credentials on your machine if you must, but obviously you should not push any such changes back to Rails. Testing Active Record --------------------- @@ -217,7 +217,7 @@ $ cd activerecord $ bundle exec rake test_sqlite3 ``` -You can now run the tests as you did for +sqlite3+. The tasks are respectively +You can now run the tests as you did for `sqlite3`. The tasks are respectively ```bash test_mysql @@ -239,7 +239,7 @@ You can also run any single test separately: $ ARCONN=sqlite3 ruby -Itest test/cases/associations/has_many_associations_test.rb ``` -You can invoke +test_jdbcmysql+, +test_jdbcsqlite3+ or +test_jdbcpostgresql+ also. See the file +activerecord/RUNNING_UNIT_TESTS+ for information on running more targeted database tests, or the file +ci/travis.rb+ for the test suite run by the continuous integration server. +You can invoke `test_jdbcmysql`, `test_jdbcsqlite3` or `test_jdbcpostgresql` also. See the file `activerecord/RUNNING_UNIT_TESTS` for information on running more targeted database tests, or the file `ci/travis.rb` for the test suite run by the continuous integration server. ### Warnings @@ -348,7 +348,7 @@ It doesn’t matter much what name you use, because this branch will only exist ### Write Your Code -Now get busy and add or edit code. You’re on your branch now, so you can write whatever you want (you can check to make sure you’re on the right branch with +git branch -a+). But if you’re planning to submit your change back for inclusion in Rails, keep a few things in mind: +Now get busy and add or edit code. You’re on your branch now, so you can write whatever you want (you can check to make sure you’re on the right branch with `git branch -a`). But if you’re planning to submit your change back for inclusion in Rails, keep a few things in mind: * Get the code right. * Use Rails idioms and helpers. @@ -364,9 +364,9 @@ Rails follows a simple set of coding style conventions. * Two spaces, no tabs (for indentation). * No trailing whitespace. Blank lines should not have any spaces. * Indent after private/protected. -* Prefer +&&+/+||+ over +and+/+or+. +* Prefer `&&`/`||` over `and`/`or`. * Prefer class << self over self.method for class methods. -* Use +MyClass.my_method(my_arg)+ not +my_method( my_arg )+ or +my_method my_arg+. +* Use `MyClass.my_method(my_arg)` not `my_method( my_arg )` or `my_method my_arg`. * Use a = b and not a=b. * Follow the conventions in the source you see used already. @@ -558,7 +558,7 @@ $ git apply ~/my_changes.patch This works well for simple changes. However, if your changes are complicated or if the code in master has deviated significantly from your target branch, it might require more work on your part. The difficulty of a backport varies greatly from case to case, and sometimes it is simply not worth the effort. -Once you have resolved all conflicts and made sure all the tests are passing, push your changes and open a separate pull request for your backport. It is also worth noting that older branches might have a different set of build targets than master. When possible, it is best to first test your backport locally against the Ruby versions listed in +.travis.yml+ before submitting your pull request. +Once you have resolved all conflicts and made sure all the tests are passing, push your changes and open a separate pull request for your backport. It is also worth noting that older branches might have a different set of build targets than master. When possible, it is best to first test your backport locally against the Ruby versions listed in `.travis.yml` before submitting your pull request. And then... think about your next contribution! diff --git a/guides/source/debugging_rails_applications.md b/guides/source/debugging_rails_applications.md index 35d4f5fb8f..3f0f29ba47 100644 --- a/guides/source/debugging_rails_applications.md +++ b/guides/source/debugging_rails_applications.md @@ -15,13 +15,13 @@ View Helpers for Debugging One common task is to inspect the contents of a variable. In Rails, you can do this with three methods: -* +debug+ -* +to_yaml+ -* +inspect+ +* `debug` +* `to_yaml` +* `inspect` -### +debug+ +### `debug` -The +debug+ helper will return a <pre>-tag that renders the object using the YAML format. This will generate human-readable data from any object. For example, if you have this code in a view: +The `debug` helper will return a <pre>-tag that renders the object using the YAML format. This will generate human-readable data from any object. For example, if you have this code in a view: ```html <%= debug @post %> @@ -48,7 +48,7 @@ attributes_cache: {} Title: Rails debugging guide ``` -### +to_yaml+ +### `to_yaml` Displaying an instance variable, or any other object or method, in YAML format can be achieved this way: @@ -60,7 +60,7 @@ Displaying an instance variable, or any other object or method, in YAML format c </p> ``` -The +to_yaml+ method converts the method to YAML format leaving it more readable, and then the +simple_format+ helper is used to render each line as in the console. This is how +debug+ method does its magic. +The `to_yaml` method converts the method to YAML format leaving it more readable, and then the `simple_format` helper is used to render each line as in the console. This is how `debug` method does its magic. As a result of this, you will have something like this in your view: @@ -78,9 +78,9 @@ attributes_cache: {} Title: Rails debugging guide ``` -### +inspect+ +### `inspect` -Another useful method for displaying object values is +inspect+, especially when working with arrays or hashes. This will print the object value as a string. For example: +Another useful method for displaying object values is `inspect`, especially when working with arrays or hashes. This will print the object value as a string. For example: ```html <%= [1, 2, 3, 4, 5].inspect %> @@ -105,29 +105,29 @@ It can also be useful to save information to log files at runtime. Rails maintai ### What is the Logger? -Rails makes use of the +ActiveSupport::BufferedLogger+ class to write log information. You can also substitute another logger such as +Log4r+ if you wish. +Rails makes use of the `ActiveSupport::BufferedLogger` class to write log information. You can also substitute another logger such as `Log4r` if you wish. -You can specify an alternative logger in your +environment.rb+ or any environment file: +You can specify an alternative logger in your `environment.rb` or any environment file: ```ruby Rails.logger = Logger.new(STDOUT) Rails.logger = Log4r::Logger.new("Application Log") ``` -Or in the +Initializer+ section, add _any_ of the following +Or in the `Initializer` section, add _any_ of the following ```ruby config.logger = Logger.new(STDOUT) config.logger = Log4r::Logger.new("Application Log") ``` -TIP: By default, each log is created under +Rails.root/log/+ and the log file name is +environment_name.log+. +TIP: By default, each log is created under `Rails.root/log/` and the log file name is `environment_name.log`. ### Log Levels -When something is logged it's printed into the corresponding log if the log level of the message is equal or higher than the configured log level. If you want to know the current log level you can call the +Rails.logger.level+ method. +When something is logged it's printed into the corresponding log if the log level of the message is equal or higher than the configured log level. If you want to know the current log level you can call the `Rails.logger.level` method. -The available log levels are: +:debug+, +:info+, +:warn+, +:error+, +:fatal+, and +:unknown+, corresponding to the log level numbers from 0 up to 5 respectively. To change the default log level, use +The available log levels are: `:debug`, `:info`, `:warn`, `:error`, `:fatal`, and `:unknown`, corresponding to the log level numbers from 0 up to 5 respectively. To change the default log level, use ```ruby config.log_level = :warn # In any environment initializer, or @@ -136,11 +136,11 @@ Rails.logger.level = 0 # at any time This is useful when you want to log under development or staging, but you don't want to flood your production log with unnecessary information. -TIP: The default Rails log level is +info+ in production mode and +debug+ in development and test mode. +TIP: The default Rails log level is `info` in production mode and `debug` in development and test mode. ### Sending Messages -To write in the current log use the +logger.(debug|info|warn|error|fatal)+ method from within a controller, model or mailer: +To write in the current log use the `logger.(debug|info|warn|error|fatal)` method from within a controller, model or mailer: ```ruby logger.debug "Person attributes hash: #{@person.attributes.inspect}" @@ -196,7 +196,7 @@ Adding extra logging like this makes it easy to search for unexpected or unusual ### Tagged Logging -When running multi-user, multi-account applications, it’s often useful to be able to filter the logs using some custom rules. +TaggedLogging+ in Active Support helps in doing exactly that by stamping log lines with subdomains, request ids, and anything else to aid debugging such applications. +When running multi-user, multi-account applications, it’s often useful to be able to filter the logs using some custom rules. `TaggedLogging` in Active Support helps in doing exactly that by stamping log lines with subdomains, request ids, and anything else to aid debugging such applications. ```ruby logger = ActiveSupport::TaggedLogging.new(Logger.new(STDOUT)) @@ -205,7 +205,7 @@ logger.tagged("BCX", "Jason") { logger.info "Stuff" } # Logs " logger.tagged("BCX") { logger.tagged("Jason") { logger.info "Stuff" } } # Logs "[BCX] [Jason] Stuff" ``` -Debugging with the +debugger+ gem +Debugging with the `debugger` gem --------------------------------- When your code is behaving in unexpected ways, you can try printing to logs or the console to diagnose the problem. Unfortunately, there are times when this sort of error tracking is not effective in finding the root cause of a problem. When you actually need to journey into your running source code, the debugger is your best companion. @@ -214,13 +214,13 @@ The debugger can also help you if you want to learn about the Rails source code ### Setup -Rails uses the +debugger+ gem to set breakpoints and step through live code. To install it, just run: +Rails uses the `debugger` gem to set breakpoints and step through live code. To install it, just run: ```bash $ gem install debugger ``` -Rails has had built-in support for debugging since Rails 2.0. Inside any Rails application you can invoke the debugger by calling the +debugger+ method. +Rails has had built-in support for debugging since Rails 2.0. Inside any Rails application you can invoke the debugger by calling the `debugger` method. Here's an example: @@ -239,7 +239,7 @@ If you see the message in the console or logs: ***** Debugger requested, but was not available: Start server with --debugger to enable ***** ``` -Make sure you have started your web server with the option +--debugger+: +Make sure you have started your web server with the option `--debugger`: ```bash $ rails server --debugger @@ -249,11 +249,11 @@ $ rails server --debugger ... ``` -TIP: In development mode, you can dynamically +require \'debugger\'+ instead of restarting the server, if it was started without +--debugger+. +TIP: In development mode, you can dynamically `require \'debugger\'` instead of restarting the server, if it was started without `--debugger`. ### The Shell -As soon as your application calls the +debugger+ method, the debugger will be started in a debugger shell inside the terminal window where you launched your application server, and you will be placed at the debugger's prompt +(rdb:n)+. The _n_ is the thread number. The prompt will also show you the next line of code that is waiting to run. +As soon as your application calls the `debugger` method, the debugger will be started in a debugger shell inside the terminal window where you launched your application server, and you will be placed at the debugger's prompt `(rdb:n)`. The _n_ is the thread number. The prompt will also show you the next line of code that is waiting to run. If you got there by a browser request, the browser tab containing the request will be hung until the debugger has finished and the trace has finished processing the entire request. @@ -264,7 +264,7 @@ For example: (rdb:7) ``` -Now it's time to explore and dig into your application. A good place to start is by asking the debugger for help... so type: +help+ (You didn't see that coming, right?) +Now it's time to explore and dig into your application. A good place to start is by asking the debugger for help... so type: `help` (You didn't see that coming, right?) ```bash (rdb:7) help @@ -279,11 +279,11 @@ condition down finish list ps save thread var continue edit frame method putl set tmate where ``` -TIP: To view the help menu for any command use +help <command-name>+ in active debug mode. For example: _+help var+_ +TIP: To view the help menu for any command use `help <command-name>` in active debug mode. For example: _`help var`_ -The next command to learn is one of the most useful: +list+. You can abbreviate any debugging command by supplying just enough letters to distinguish them from other commands, so you can also use +l+ for the +list+ command. +The next command to learn is one of the most useful: `list`. You can abbreviate any debugging command by supplying just enough letters to distinguish them from other commands, so you can also use `l` for the `list` command. -This command shows you where you are in the code by printing 10 lines centered around the current line; the current line in this particular case is line 6 and is marked by +=>+. +This command shows you where you are in the code by printing 10 lines centered around the current line; the current line in this particular case is line 6 and is marked by `=>`. ```bash (rdb:7) list @@ -300,7 +300,7 @@ This command shows you where you are in the code by printing 10 lines centered a 10 format.json { render :json => @posts } ``` -If you repeat the +list+ command, this time using just +l+, the next ten lines of the file will be printed out. +If you repeat the `list` command, this time using just `l`, the next ten lines of the file will be printed out. ```bash (rdb:7) l @@ -317,9 +317,9 @@ If you repeat the +list+ command, this time using just +l+, the next ten lines o 20 format.html # show.html.erb ``` -And so on until the end of the current file. When the end of file is reached, the +list+ command will start again from the beginning of the file and continue again up to the end, treating the file as a circular buffer. +And so on until the end of the current file. When the end of file is reached, the `list` command will start again from the beginning of the file and continue again up to the end, treating the file as a circular buffer. -On the other hand, to see the previous ten lines you should type +list-+ (or +l-+) +On the other hand, to see the previous ten lines you should type `list-` (or `l-`) ```bash (rdb:7) l- @@ -336,8 +336,8 @@ On the other hand, to see the previous ten lines you should type +list-+ (or +l- 10 format.json { render :json => @posts } ``` -This way you can move inside the file, being able to see the code above and over the line you added the +debugger+. -Finally, to see where you are in the code again you can type +list=+ +This way you can move inside the file, being able to see the code above and over the line you added the `debugger`. +Finally, to see where you are in the code again you can type `list=` ```bash (rdb:7) list= @@ -360,7 +360,7 @@ When you start debugging your application, you will be placed in different conte The debugger creates a context when a stopping point or an event is reached. The context has information about the suspended program which enables a debugger to inspect the frame stack, evaluate variables from the perspective of the debugged program, and contains information about the place where the debugged program is stopped. -At any time you can call the +backtrace+ command (or its alias +where+) to print the backtrace of the application. This can be very helpful to know how you got where you are. If you ever wondered about how you got somewhere in your code, then +backtrace+ will supply the answer. +At any time you can call the `backtrace` command (or its alias `where`) to print the backtrace of the application. This can be very helpful to know how you got where you are. If you ever wondered about how you got somewhere in your code, then `backtrace` will supply the answer. ```bash (rdb:5) where @@ -375,7 +375,7 @@ At any time you can call the +backtrace+ command (or its alias +where+) to print ... ``` -You move anywhere you want in this trace (thus changing the context) by using the +frame _n_+ command, where _n_ is the specified frame number. +You move anywhere you want in this trace (thus changing the context) by using the `frame _n_` command, where _n_ is the specified frame number. ```bash (rdb:5) frame 2 @@ -385,17 +385,17 @@ You move anywhere you want in this trace (thus changing the context) by using th The available variables are the same as if you were running the code line by line. After all, that's what debugging is. -Moving up and down the stack frame: You can use +up [n]+ (+u+ for abbreviated) and +down [n]+ commands in order to change the context _n_ frames up or down the stack respectively. _n_ defaults to one. Up in this case is towards higher-numbered stack frames, and down is towards lower-numbered stack frames. +Moving up and down the stack frame: You can use `up [n]` (`u` for abbreviated) and `down [n]` commands in order to change the context _n_ frames up or down the stack respectively. _n_ defaults to one. Up in this case is towards higher-numbered stack frames, and down is towards lower-numbered stack frames. ### Threads -The debugger can list, stop, resume and switch between running threads by using the command +thread+ (or the abbreviated +th+). This command has a handful of options: +The debugger can list, stop, resume and switch between running threads by using the command `thread` (or the abbreviated `th`). This command has a handful of options: -* +thread+ shows the current thread. -* +thread list+ is used to list all threads and their statuses. The plus + character and the number indicates the current thread of execution. -* +thread stop _n_+ stop thread _n_. -* +thread resume _n_+ resumes thread _n_. -* +thread switch _n_+ switches the current thread context to _n_. +* `thread` shows the current thread. +* `thread list` is used to list all threads and their statuses. The plus + character and the number indicates the current thread of execution. +* `thread stop _n_` stop thread _n_. +* `thread resume _n_` resumes thread _n_. +* `thread switch _n_` switches the current thread context to _n_. This command is very helpful, among other occasions, when you are debugging concurrent threads and need to verify that there are no race conditions in your code. @@ -411,7 +411,7 @@ This example shows how you can print the instance_variables defined within the c ["@_response", "@action_name", "@url", "@_session", "@_cookies", "@performed_render", "@_flash", "@template", "@_params", "@before_filter_chain_aborted", "@request_origin", "@_headers", "@performed_redirect", "@_request"] ``` -As you may have figured out, all of the variables that you can access from a controller are displayed. This list is dynamically updated as you execute code. For example, run the next line using +next+ (you'll learn more about this command later in this guide). +As you may have figured out, all of the variables that you can access from a controller are displayed. This list is dynamically updated as you execute code. For example, run the next line using `next` (you'll learn more about this command later in this guide). ```bash (rdb:11) next @@ -429,11 +429,11 @@ And then ask again for the instance_variables: true ``` -Now +@posts+ is included in the instance variables, because the line defining it was executed. +Now `@posts` is included in the instance variables, because the line defining it was executed. -TIP: You can also step into *irb* mode with the command +irb+ (of course!). This way an irb session will be started within the context you invoked it. But be warned: this is an experimental feature. +TIP: You can also step into *irb* mode with the command `irb` (of course!). This way an irb session will be started within the context you invoked it. But be warned: this is an experimental feature. -The +var+ method is the most convenient way to show variables and their values: +The `var` method is the most convenient way to show variables and their values: ```bash var @@ -459,30 +459,30 @@ You can also inspect for an object method this way: @new_record = true ``` -TIP: The commands +p+ (print) and +pp+ (pretty print) can be used to evaluate Ruby expressions and display the value of variables to the console. +TIP: The commands `p` (print) and `pp` (pretty print) can be used to evaluate Ruby expressions and display the value of variables to the console. -You can use also +display+ to start watching variables. This is a good way of tracking the values of a variable while the execution goes on. +You can use also `display` to start watching variables. This is a good way of tracking the values of a variable while the execution goes on. ```bash (rdb:1) display @recent_comments 1: @recent_comments = ``` -The variables inside the displaying list will be printed with their values after you move in the stack. To stop displaying a variable use +undisplay _n_+ where _n_ is the variable number (1 in the last example). +The variables inside the displaying list will be printed with their values after you move in the stack. To stop displaying a variable use `undisplay _n_` where _n_ is the variable number (1 in the last example). ### Step by Step Now you should know where you are in the running trace and be able to print the available variables. But lets continue and move on with the application execution. -Use +step+ (abbreviated +s+) to continue running your program until the next logical stopping point and return control to the debugger. +Use `step` (abbreviated `s`) to continue running your program until the next logical stopping point and return control to the debugger. -TIP: You can also use `step<plus> n` and `step- n` to move forward or backward +n+ steps respectively. +TIP: You can also use `step<plus> n` and `step- n` to move forward or backward `n` steps respectively. -You may also use +next+ which is similar to step, but function or method calls that appear within the line of code are executed without stopping. As with step, you may use plus sign to move _n_ steps. +You may also use `next` which is similar to step, but function or method calls that appear within the line of code are executed without stopping. As with step, you may use plus sign to move _n_ steps. -The difference between +next+ and +step+ is that +step+ stops at the next line of code executed, doing just a single step, while +next+ moves to the next line without descending inside methods. +The difference between `next` and `step` is that `step` stops at the next line of code executed, doing just a single step, while `next` moves to the next line without descending inside methods. -For example, consider this block of code with an included +debugger+ statement: +For example, consider this block of code with an included `debugger` statement: ```ruby class Author < ActiveRecord::Base @@ -496,7 +496,7 @@ class Author < ActiveRecord::Base end ``` -TIP: You can use the debugger while using +rails console+. Just remember to +require "debugger"+ before calling the +debugger+ method. +TIP: You can use the debugger while using `rails console`. Just remember to `require "debugger"` before calling the `debugger` method. ```bash $ rails console @@ -533,7 +533,7 @@ You are at the end of the line, but... was this line executed? You can inspect t @attributes_cache = {} ``` -+@recent_comments+ hasn't been defined yet, so it's clear that this line hasn't been executed yet. Use the +next+ command to move on in the code: +`@recent_comments` hasn't been defined yet, so it's clear that this line hasn't been executed yet. Use the `next` command to move on in the code: ```bash (rdb:1) next @@ -546,26 +546,26 @@ You are at the end of the line, but... was this line executed? You can inspect t @recent_comments = [] ``` -Now you can see that the +@comments+ relationship was loaded and @recent_comments defined because the line was executed. +Now you can see that the `@comments` relationship was loaded and @recent_comments defined because the line was executed. -If you want to go deeper into the stack trace you can move single +steps+, through your calling methods and into Rails code. This is one of the best ways to find bugs in your code, or perhaps in Ruby or Rails. +If you want to go deeper into the stack trace you can move single `steps`, through your calling methods and into Rails code. This is one of the best ways to find bugs in your code, or perhaps in Ruby or Rails. ### Breakpoints A breakpoint makes your application stop whenever a certain point in the program is reached. The debugger shell is invoked in that line. -You can add breakpoints dynamically with the command +break+ (or just +b+). There are 3 possible ways of adding breakpoints manually: +You can add breakpoints dynamically with the command `break` (or just `b`). There are 3 possible ways of adding breakpoints manually: -* +break line+: set breakpoint in the _line_ in the current source file. -* +break file:line [if expression]+: set breakpoint in the _line_ number inside the _file_. If an _expression_ is given it must evaluated to _true_ to fire up the debugger. -* +break class(.|\#)method [if expression]+: set breakpoint in _method_ (. and \# for class and instance method respectively) defined in _class_. The _expression_ works the same way as with file:line. +* `break line`: set breakpoint in the _line_ in the current source file. +* `break file:line [if expression]`: set breakpoint in the _line_ number inside the _file_. If an _expression_ is given it must evaluated to _true_ to fire up the debugger. +* `break class(.|\#)method [if expression]`: set breakpoint in _method_ (. and \# for class and instance method respectively) defined in _class_. The _expression_ works the same way as with file:line. ```bash (rdb:5) break 10 Breakpoint 1 file /PathTo/project/vendor/rails/actionpack/lib/action_controller/filters.rb, line 10 ``` -Use +info breakpoints _n_+ or +info break _n_+ to list breakpoints. If you supply a number, it lists that breakpoint. Otherwise it lists all breakpoints. +Use `info breakpoints _n_` or `info break _n_` to list breakpoints. If you supply a number, it lists that breakpoint. Otherwise it lists all breakpoints. ```bash (rdb:5) info breakpoints @@ -573,7 +573,7 @@ Num Enb What 1 y at filters.rb:10 ``` -To delete breakpoints: use the command +delete _n_+ to remove the breakpoint number _n_. If no number is specified, it deletes all breakpoints that are currently active.. +To delete breakpoints: use the command `delete _n_` to remove the breakpoint number _n_. If no number is specified, it deletes all breakpoints that are currently active.. ```bash (rdb:5) delete 1 @@ -583,49 +583,49 @@ No breakpoints. You can also enable or disable breakpoints: -* +enable breakpoints+: allow a list _breakpoints_ or all of them if no list is specified, to stop your program. This is the default state when you create a breakpoint. -* +disable breakpoints+: the _breakpoints_ will have no effect on your program. +* `enable breakpoints`: allow a list _breakpoints_ or all of them if no list is specified, to stop your program. This is the default state when you create a breakpoint. +* `disable breakpoints`: the _breakpoints_ will have no effect on your program. ### Catching Exceptions -The command +catch exception-name+ (or just +cat exception-name+) can be used to intercept an exception of type _exception-name_ when there would otherwise be is no handler for it. +The command `catch exception-name` (or just `cat exception-name`) can be used to intercept an exception of type _exception-name_ when there would otherwise be is no handler for it. -To list all active catchpoints use +catch+. +To list all active catchpoints use `catch`. ### Resuming Execution There are two ways to resume execution of an application that is stopped in the debugger: -* +continue+ [line-specification] (or +c+): resume program execution, at the address where your script last stopped; any breakpoints set at that address are bypassed. The optional argument line-specification allows you to specify a line number to set a one-time breakpoint which is deleted when that breakpoint is reached. -* +finish+ [frame-number] (or +fin+): execute until the selected stack frame returns. If no frame number is given, the application will run until the currently selected frame returns. The currently selected frame starts out the most-recent frame or 0 if no frame positioning (e.g up, down or frame) has been performed. If a frame number is given it will run until the specified frame returns. +* `continue` [line-specification] (or `c`): resume program execution, at the address where your script last stopped; any breakpoints set at that address are bypassed. The optional argument line-specification allows you to specify a line number to set a one-time breakpoint which is deleted when that breakpoint is reached. +* `finish` [frame-number] (or `fin`): execute until the selected stack frame returns. If no frame number is given, the application will run until the currently selected frame returns. The currently selected frame starts out the most-recent frame or 0 if no frame positioning (e.g up, down or frame) has been performed. If a frame number is given it will run until the specified frame returns. ### Editing Two commands allow you to open code from the debugger into an editor: -* +edit [file:line]+: edit _file_ using the editor specified by the EDITOR environment variable. A specific _line_ can also be given. -* +tmate _n_+ (abbreviated +tm+): open the current file in TextMate. It uses n-th frame if _n_ is specified. +* `edit [file:line]`: edit _file_ using the editor specified by the EDITOR environment variable. A specific _line_ can also be given. +* `tmate _n_` (abbreviated `tm`): open the current file in TextMate. It uses n-th frame if _n_ is specified. ### Quitting -To exit the debugger, use the +quit+ command (abbreviated +q+), or its alias +exit+. +To exit the debugger, use the `quit` command (abbreviated `q`), or its alias `exit`. A simple quit tries to terminate all threads in effect. Therefore your server will be stopped and you will have to start it again. ### Settings -The +debugger+ gem can automatically show the code you're stepping through and reload it when you change it in an editor. Here are a few of the available options: +The `debugger` gem can automatically show the code you're stepping through and reload it when you change it in an editor. Here are a few of the available options: -* +set reload+: Reload source code when changed. -* +set autolist+: Execute +list+ command on every breakpoint. -* +set listsize _n_+: Set number of source lines to list by default to _n_. -* +set forcestep+: Make sure the +next+ and +step+ commands always move to a new line +* `set reload`: Reload source code when changed. +* `set autolist`: Execute `list` command on every breakpoint. +* `set listsize _n_`: Set number of source lines to list by default to _n_. +* `set forcestep`: Make sure the `next` and `step` commands always move to a new line -You can see the full list by using +help set+. Use +help set _subcommand_+ to learn about a particular +set+ command. +You can see the full list by using `help set`. Use `help set _subcommand_` to learn about a particular `set` command. -TIP: You can save these settings in an +.rdebugrc+ file in your home directory. The debugger reads these global settings when it starts. +TIP: You can save these settings in an `.rdebugrc` file in your home directory. The debugger reads these global settings when it starts. -Here's a good start for an +.rdebugrc+: +Here's a good start for an `.rdebugrc`: ```bash set autolist @@ -664,7 +664,7 @@ Start a server instance with BleakHouse integration: $ RAILS_ENV=production BLEAK_HOUSE=1 ruby-bleak-house rails server ``` -Make sure to run a couple hundred requests to get better data samples, then press +CTRL-C+. The server will stop and Bleak House will produce a dumpfile in +/tmp+: +Make sure to run a couple hundred requests to get better data samples, then press `CTRL-C`. The server will stop and Bleak House will produce a dumpfile in `/tmp`: ```bash ** BleakHouse: working... @@ -697,7 +697,7 @@ If "BleakHouse":https://github.com/evan/bleak_house/ doesn't report any heap gro "Valgrind":http://valgrind.org/ is a Linux-only application for detecting C-based memory leaks and race conditions. -There are Valgrind tools that can automatically detect many memory management and threading bugs, and profile your programs in detail. For example, a C extension in the interpreter calls +malloc()+ but is doesn't properly call +free()+, this memory won't be available until the app terminates. +There are Valgrind tools that can automatically detect many memory management and threading bugs, and profile your programs in detail. For example, a C extension in the interpreter calls `malloc()` but is doesn't properly call `free()`, this memory won't be available until the app terminates. For further information on how to install Valgrind and use with Ruby, refer to "Valgrind and Ruby":http://blog.evanweaver.com/articles/2008/02/05/valgrind-and-ruby/ by Evan Weaver. diff --git a/guides/source/engines.md b/guides/source/engines.md index bd7b3ec25e..7a2c1af23e 100644 --- a/guides/source/engines.md +++ b/guides/source/engines.md @@ -14,15 +14,15 @@ In this guide you will learn about engines and how they can be used to provide a What are engines? ----------------- -Engines can be considered miniature applications that provide functionality to their host applications. A Rails application is actually just a "supercharged" engine, with the +Rails::Application+ class inheriting a lot of its behaviour from +Rails::Engine+. +Engines can be considered miniature applications that provide functionality to their host applications. A Rails application is actually just a "supercharged" engine, with the `Rails::Application` class inheriting a lot of its behaviour from `Rails::Engine`. Therefore, engines and applications can be thought of almost the same thing, just with very minor differences, as you'll see throughout this guide. Engines and applications also share a common structure. -Engines are also closely related to plugins where the two share a common +lib+ directory structure and are both generated using the +rails plugin new+ generator. The difference being that an engine is considered a "full plugin" by Rails as indicated by the +--full+ option that's passed to the generator command, but this guide will refer to them simply as "engines" throughout. An engine *can* be a plugin, and a plugin *can* be an engine. +Engines are also closely related to plugins where the two share a common `lib` directory structure and are both generated using the `rails plugin new` generator. The difference being that an engine is considered a "full plugin" by Rails as indicated by the `--full` option that's passed to the generator command, but this guide will refer to them simply as "engines" throughout. An engine *can* be a plugin, and a plugin *can* be an engine. The engine that will be created in this guide will be called "blorgh". The engine will provide blogging functionality to its host applications, allowing for new posts and comments to be created. At the beginning of this guide, you will be working solely within the engine itself, but in later sections you'll see how to hook it into an application. -Engines can also be isolated from their host applications. This means that an application is able to have a path provided by a routing helper such as +posts_path+ and use an engine also that provides a path also called +posts_path+, and the two would not clash. Along with this, controllers, models and table names are also namespaced. You'll see how to do this later in this guide. +Engines can also be isolated from their host applications. This means that an application is able to have a path provided by a routing helper such as `posts_path` and use an engine also that provides a path also called `posts_path`, and the two would not clash. Along with this, controllers, models and table names are also namespaced. You'll see how to do this later in this guide. It's important to keep in mind at all times that the application should *always* take precedence over its engines. An application is the object that has final say in what goes on in the universe (with the universe being the application's environment) where the engine should only be enhancing it, rather than changing it drastically. @@ -33,7 +33,7 @@ Finally, engines would not have been possible without the work of James Adam, Pi Generating an engine -------------------- -To generate an engine with Rails 3.1, you will need to run the plugin generator and pass it the +--full+ and +--mountable+ options. To generate the beginnings of the "blorgh" engine you will need to run this command in a terminal: +To generate an engine with Rails 3.1, you will need to run the plugin generator and pass it the `--full` and `--mountable` options. To generate the beginnings of the "blorgh" engine you will need to run this command in a terminal: ```bash $ rails plugin new blorgh --full --mountable @@ -45,9 +45,9 @@ The full list of options for the plugin generator may be seen by typing: $ rails plugin --help ``` -The +--full+ option tells the plugin generator that you want to create an engine, creating the basic directory structure of an engine by providing things such as an +app+ directory and a +config/routes.rb+ file. This generator also provides a file at +lib/blorgh/engine.rb+ which is identical in function to a standard Rails application's +config/application.rb+ file. +The `--full` option tells the plugin generator that you want to create an engine, creating the basic directory structure of an engine by providing things such as an `app` directory and a `config/routes.rb` file. This generator also provides a file at `lib/blorgh/engine.rb` which is identical in function to a standard Rails application's `config/application.rb` file. -The +--mountable+ option tells the generator to mount the engine inside the dummy testing application located at +test/dummy+. It does this by placing this line into the dummy application's routes file at +test/dummy/config/routes.rb+: +The `--mountable` option tells the generator to mount the engine inside the dummy testing application located at `test/dummy`. It does this by placing this line into the dummy application's routes file at `test/dummy/config/routes.rb`: ```ruby mount Blorgh::Engine, :at => "blorgh" @@ -57,13 +57,13 @@ mount Blorgh::Engine, :at => "blorgh" #### Critical files -At the root of this brand new engine's directory lives a +blorgh.gemspec+ file. When you include the engine into an application later on, you will do so with this line in the Rails application's +Gemfile+: +At the root of this brand new engine's directory lives a `blorgh.gemspec` file. When you include the engine into an application later on, you will do so with this line in the Rails application's `Gemfile`: ```ruby gem 'blorgh', :path => "vendor/engines/blorgh" ``` -By specifying it as a gem within the +Gemfile+, Bundler will load it as such, parsing this +blorgh.gemspec+ file and requiring a file within the +lib+ directory called +lib/blorgh.rb+. This file requires the +blorgh/engine.rb+ file (located at +lib/blorgh/engine.rb+) and defines a base module called +Blorgh+. +By specifying it as a gem within the `Gemfile`, Bundler will load it as such, parsing this `blorgh.gemspec` file and requiring a file within the `lib` directory called `lib/blorgh.rb`. This file requires the `blorgh/engine.rb` file (located at `lib/blorgh/engine.rb`) and defines a base module called `Blorgh`. ```ruby require "blorgh/engine" @@ -72,9 +72,9 @@ module Blorgh end ``` -TIP: Some engines choose to use this file to put global configuration options for their engine. It's a relatively good idea, and so if you want to offer configuration options, the file where your engine's +module+ is defined is perfect for that. Place the methods inside the module and you'll be good to go. +TIP: Some engines choose to use this file to put global configuration options for their engine. It's a relatively good idea, and so if you want to offer configuration options, the file where your engine's `module` is defined is perfect for that. Place the methods inside the module and you'll be good to go. -Within +lib/blorgh/engine.rb+ is the base class for the engine: +Within `lib/blorgh/engine.rb` is the base class for the engine: ```ruby module Blorgh @@ -84,43 +84,43 @@ module Blorgh end ``` -By inheriting from the +Rails::Engine+ class, this gem notifies Rails that there's an engine at the specified path, and will correctly mount the engine inside the application, performing tasks such as adding the +app+ directory of the engine to the load path for models, mailers, controllers and views. +By inheriting from the `Rails::Engine` class, this gem notifies Rails that there's an engine at the specified path, and will correctly mount the engine inside the application, performing tasks such as adding the `app` directory of the engine to the load path for models, mailers, controllers and views. -The +isolate_namespace+ method here deserves special notice. This call is responsible for isolating the controllers, models, routes and other things into their own namespace, away from similar components inside the application. Without this, there is a possibility that the engine's components could "leak" into the application, causing unwanted disruption, or that important engine components could be overridden by similarly named things within the application. One of the examples of such conflicts are helpers. Without calling +isolate_namespace+, engine's helpers would be included in an application's controllers. +The `isolate_namespace` method here deserves special notice. This call is responsible for isolating the controllers, models, routes and other things into their own namespace, away from similar components inside the application. Without this, there is a possibility that the engine's components could "leak" into the application, causing unwanted disruption, or that important engine components could be overridden by similarly named things within the application. One of the examples of such conflicts are helpers. Without calling `isolate_namespace`, engine's helpers would be included in an application's controllers. -NOTE: It is *highly* recommended that the +isolate_namespace+ line be left within the +Engine+ class definition. Without it, classes generated in an engine *may* conflict with an application. +NOTE: It is *highly* recommended that the `isolate_namespace` line be left within the `Engine` class definition. Without it, classes generated in an engine *may* conflict with an application. -What this isolation of the namespace means is that a model generated by a call to +rails g model+ such as +rails g model post+ won't be called +Post+, but instead be namespaced and called +Blorgh::Post+. In addition, the table for the model is namespaced, becoming +blorgh_posts+, rather than simply +posts+. Similar to the model namespacing, a controller called +PostsController+ becomes +Blorgh::PostsController+ and the views for that controller will not be at +app/views/posts+, but +app/views/blorgh/posts+ instead. Mailers are namespaced as well. +What this isolation of the namespace means is that a model generated by a call to `rails g model` such as `rails g model post` won't be called `Post`, but instead be namespaced and called `Blorgh::Post`. In addition, the table for the model is namespaced, becoming `blorgh_posts`, rather than simply `posts`. Similar to the model namespacing, a controller called `PostsController` becomes `Blorgh::PostsController` and the views for that controller will not be at `app/views/posts`, but `app/views/blorgh/posts` instead. Mailers are namespaced as well. Finally, routes will also be isolated within the engine. This is one of the most important parts about namespacing, and is discussed later in the "Routes":#routes section of this guide. -#### +app+ directory +#### `app` directory -Inside the +app+ directory are the standard +assets+, +controllers+, +helpers+, +mailers+, +models+ and +views+ directories that you should be familiar with from an application. The +helpers+, +mailers+ and +models+ directories are empty and so aren't described in this section. We'll look more into models in a future section, when we're writing the engine. +Inside the `app` directory are the standard `assets`, `controllers`, `helpers`, `mailers`, `models` and `views` directories that you should be familiar with from an application. The `helpers`, `mailers` and `models` directories are empty and so aren't described in this section. We'll look more into models in a future section, when we're writing the engine. -Within the +app/assets+ directory, there are the +images+, +javascripts+ and +stylesheets+ directories which, again, you should be familiar with due to their similarity to an application. One difference here however is that each directory contains a sub-directory with the engine name. Because this engine is going to be namespaced, its assets should be too. +Within the `app/assets` directory, there are the `images`, `javascripts` and `stylesheets` directories which, again, you should be familiar with due to their similarity to an application. One difference here however is that each directory contains a sub-directory with the engine name. Because this engine is going to be namespaced, its assets should be too. -Within the +app/controllers+ directory there is a +blorgh+ directory and inside that a file called +application_controller.rb+. This file will provide any common functionality for the controllers of the engine. The +blorgh+ directory is where the other controllers for the engine will go. By placing them within this namespaced directory, you prevent them from possibly clashing with identically-named controllers within other engines or even within the application. +Within the `app/controllers` directory there is a `blorgh` directory and inside that a file called `application_controller.rb`. This file will provide any common functionality for the controllers of the engine. The `blorgh` directory is where the other controllers for the engine will go. By placing them within this namespaced directory, you prevent them from possibly clashing with identically-named controllers within other engines or even within the application. -NOTE: The +ApplicationController+ class inside an engine is named just like a Rails application in order to make it easier for you to convert your applications into engines. +NOTE: The `ApplicationController` class inside an engine is named just like a Rails application in order to make it easier for you to convert your applications into engines. -Lastly, the +app/views+ directory contains a +layouts+ folder which contains a file at +blorgh/application.html.erb+ which allows you to specify a layout for the engine. If this engine is to be used as a stand-alone engine, then you would add any customization to its layout in this file, rather than the application's +app/views/layouts/application.html.erb+ file. +Lastly, the `app/views` directory contains a `layouts` folder which contains a file at `blorgh/application.html.erb` which allows you to specify a layout for the engine. If this engine is to be used as a stand-alone engine, then you would add any customization to its layout in this file, rather than the application's `app/views/layouts/application.html.erb` file. If you don't want to force a layout on to users of the engine, then you can delete this file and reference a different layout in the controllers of your engine. -#### +script+ directory +#### `script` directory -This directory contains one file, +script/rails+, which enables you to use the +rails+ sub-commands and generators just like you would within an application. This means that you will very easily be able to generate new controllers and models for this engine by running commands like this: +This directory contains one file, `script/rails`, which enables you to use the `rails` sub-commands and generators just like you would within an application. This means that you will very easily be able to generate new controllers and models for this engine by running commands like this: ```bash rails g model ``` -Keeping in mind, of course, that anything generated with these commands inside an engine that has +isolate_namespace+ inside the +Engine+ class will be namespaced. +Keeping in mind, of course, that anything generated with these commands inside an engine that has `isolate_namespace` inside the `Engine` class will be namespaced. -#### +test+ directory +#### `test` directory -The +test+ directory is where tests for the engine will go. To test the engine, there is a cut-down version of a Rails application embedded within it at +test/dummy+. This application will mount the engine in the +test/dummy/config/routes.rb+ file: +The `test` directory is where tests for the engine will go. To test the engine, there is a cut-down version of a Rails application embedded within it at `test/dummy`. This application will mount the engine in the `test/dummy/config/routes.rb` file: ```ruby Rails.application.routes.draw do @@ -128,9 +128,9 @@ Rails.application.routes.draw do end ``` -This line mounts the engine at the path +/blorgh+, which will make it accessible through the application only at that path. +This line mounts the engine at the path `/blorgh`, which will make it accessible through the application only at that path. -Also in the test directory is the +test/integration+ directory, where integration tests for the engine should be placed. Other directories can be created in the +test+ directory also. For example, you may wish to create a +test/unit+ directory for your unit tests. +Also in the test directory is the `test/integration` directory, where integration tests for the engine should be placed. Other directories can be created in the `test` directory also. For example, you may wish to create a `test/unit` directory for your unit tests. Providing engine functionality ------------------------------ @@ -139,7 +139,7 @@ The engine that this guide covers provides posting and commenting functionality ### Generating a post resource -The first thing to generate for a blog engine is the +Post+ model and related controller. To quickly generate this, you can use the Rails scaffold generator. +The first thing to generate for a blog engine is the `Post` model and related controller. To quickly generate this, you can use the Rails scaffold generator. ```bash $ rails generate scaffold post title:string text:text @@ -179,11 +179,11 @@ invoke css create app/assets/stylesheets/scaffold.css ``` -The first thing that the scaffold generator does is invoke the +active_record+ generator, which generates a migration and a model for the resource. Note here, however, that the migration is called +create_blorgh_posts+ rather than the usual +create_posts+. This is due to the +isolate_namespace+ method called in the +Blorgh::Engine+ class's definition. The model here is also namespaced, being placed at +app/models/blorgh/post.rb+ rather than +app/models/post.rb+ due to the +isolate_namespace+ call within the +Engine+ class. +The first thing that the scaffold generator does is invoke the `active_record` generator, which generates a migration and a model for the resource. Note here, however, that the migration is called `create_blorgh_posts` rather than the usual `create_posts`. This is due to the `isolate_namespace` method called in the `Blorgh::Engine` class's definition. The model here is also namespaced, being placed at `app/models/blorgh/post.rb` rather than `app/models/post.rb` due to the `isolate_namespace` call within the `Engine` class. -Next, the +test_unit+ generator is invoked for this model, generating a unit test at +test/unit/blorgh/post_test.rb+ (rather than +test/unit/post_test.rb+) and a fixture at +test/fixtures/blorgh/posts.yml+ (rather than +test/fixtures/posts.yml+). +Next, the `test_unit` generator is invoked for this model, generating a unit test at `test/unit/blorgh/post_test.rb` (rather than `test/unit/post_test.rb`) and a fixture at `test/fixtures/blorgh/posts.yml` (rather than `test/fixtures/posts.yml`). -After that, a line for the resource is inserted into the +config/routes.rb+ file for the engine. This line is simply +resources :posts+, turning the +config/routes.rb+ file for the engine into this: +After that, a line for the resource is inserted into the `config/routes.rb` file for the engine. This line is simply `resources :posts`, turning the `config/routes.rb` file for the engine into this: ```ruby Blorgh::Engine.routes.draw do @@ -191,11 +191,11 @@ Blorgh::Engine.routes.draw do end ``` -Note here that the routes are drawn upon the +Blorgh::Engine+ object rather than the +YourApp::Application+ class. This is so that the engine routes are confined to the engine itself and can be mounted at a specific point as shown in the "test directory":#test-directory section. This is also what causes the engine's routes to be isolated from those routes that are within the application. This is discussed further in the "Routes":#routes section of this guide. +Note here that the routes are drawn upon the `Blorgh::Engine` object rather than the `YourApp::Application` class. This is so that the engine routes are confined to the engine itself and can be mounted at a specific point as shown in the "test directory":#test-directory section. This is also what causes the engine's routes to be isolated from those routes that are within the application. This is discussed further in the "Routes":#routes section of this guide. -Next, the +scaffold_controller+ generator is invoked, generating a controller called +Blorgh::PostsController+ (at +app/controllers/blorgh/posts_controller.rb+) and its related views at +app/views/blorgh/posts+. This generator also generates a functional test for the controller (+test/functional/blorgh/posts_controller_test.rb+) and a helper (+app/helpers/blorgh/posts_controller.rb+). +Next, the `scaffold_controller` generator is invoked, generating a controller called `Blorgh::PostsController` (at `app/controllers/blorgh/posts_controller.rb`) and its related views at `app/views/blorgh/posts`. This generator also generates a functional test for the controller (`test/functional/blorgh/posts_controller_test.rb`) and a helper (`app/helpers/blorgh/posts_controller.rb`). -Everything this generator has created is neatly namespaced. The controller's class is defined within the +Blorgh+ module: +Everything this generator has created is neatly namespaced. The controller's class is defined within the `Blorgh` module: ```ruby module Blorgh @@ -205,9 +205,9 @@ module Blorgh end ``` -NOTE: The +ApplicationController+ class being inherited from here is the +Blorgh::ApplicationController+, not an application's +ApplicationController+. +NOTE: The `ApplicationController` class being inherited from here is the `Blorgh::ApplicationController`, not an application's `ApplicationController`. -The helper inside +app/helpers/blorgh/posts_helper.rb+ is also namespaced: +The helper inside `app/helpers/blorgh/posts_helper.rb` is also namespaced: ```ruby module Blorgh @@ -219,36 +219,36 @@ end This helps prevent conflicts with any other engine or application that may have a post resource also. -Finally, two files that are the assets for this resource are generated, +app/assets/javascripts/blorgh/posts.js+ and +app/assets/javascripts/blorgh/posts.css+. You'll see how to use these a little later. +Finally, two files that are the assets for this resource are generated, `app/assets/javascripts/blorgh/posts.js` and `app/assets/javascripts/blorgh/posts.css`. You'll see how to use these a little later. -By default, the scaffold styling is not applied to the engine as the engine's layout file, +app/views/blorgh/application.html.erb+ doesn't load it. To make this apply, insert this line into the +<head>+ tag of this layout: +By default, the scaffold styling is not applied to the engine as the engine's layout file, `app/views/blorgh/application.html.erb` doesn't load it. To make this apply, insert this line into the `<head>` tag of this layout: ```erb <%= stylesheet_link_tag "scaffold" %> ``` -You can see what the engine has so far by running +rake db:migrate+ at the root of our engine to run the migration generated by the scaffold generator, and then running +rails server+ in +test/dummy+. When you open +http://localhost:3000/blorgh/posts+ you will see the default scaffold that has been generated. Click around! You've just generated your first engine's first functions. +You can see what the engine has so far by running `rake db:migrate` at the root of our engine to run the migration generated by the scaffold generator, and then running `rails server` in `test/dummy`. When you open `http://localhost:3000/blorgh/posts` you will see the default scaffold that has been generated. Click around! You've just generated your first engine's first functions. -If you'd rather play around in the console, +rails console+ will also work just like a Rails application. Remember: the +Post+ model is namespaced, so to reference it you must call it as +Blorgh::Post+. +If you'd rather play around in the console, `rails console` will also work just like a Rails application. Remember: the `Post` model is namespaced, so to reference it you must call it as `Blorgh::Post`. ```ruby >> Blorgh::Post.find(1) => #<Blorgh::Post id: 1 ...> ``` -One final thing is that the +posts+ resource for this engine should be the root of the engine. Whenever someone goes to the root path where the engine is mounted, they should be shown a list of posts. This can be made to happen if this line is inserted into the +config/routes.rb+ file inside the engine: +One final thing is that the `posts` resource for this engine should be the root of the engine. Whenever someone goes to the root path where the engine is mounted, they should be shown a list of posts. This can be made to happen if this line is inserted into the `config/routes.rb` file inside the engine: ```ruby root :to => "posts#index" ``` -Now people will only need to go to the root of the engine to see all the posts, rather than visiting +/posts+. This means that instead of +http://localhost:3000/blorgh/posts+, you only need to go to +http://localhost:3000/blorgh+ now. +Now people will only need to go to the root of the engine to see all the posts, rather than visiting `/posts`. This means that instead of `http://localhost:3000/blorgh/posts`, you only need to go to `http://localhost:3000/blorgh` now. ### Generating a comments resource Now that the engine has the ability to create new blog posts, it only makes sense to add commenting functionality as well. To do get this, you'll need to generate a comment model, a comment controller and then modify the posts scaffold to display comments and allow people to create new ones. -Run the model generator and tell it to generate a +Comment+ model, with the related table having two columns: a +post_id+ integer and +text+ text column. +Run the model generator and tell it to generate a `Comment` model, with the related table having two columns: a `post_id` integer and `text` text column. ```bash $ rails generate model Comment post_id:integer text:text @@ -265,16 +265,16 @@ create test/unit/blorgh/comment_test.rb create test/fixtures/blorgh/comments.yml ``` -This generator call will generate just the necessary model files it needs, namespacing the files under a +blorgh+ directory and creating a model class called +Blorgh::Comment+. +This generator call will generate just the necessary model files it needs, namespacing the files under a `blorgh` directory and creating a model class called `Blorgh::Comment`. -To show the comments on a post, edit +app/views/blorgh/posts/show.html.erb+ and add this line before the "Edit" link: +To show the comments on a post, edit `app/views/blorgh/posts/show.html.erb` and add this line before the "Edit" link: ```erb <h3>Comments</h3> <%= render @post.comments %> ``` -This line will require there to be a +has_many+ association for comments defined on the +Blorgh::Post+ model, which there isn't right now. To define one, open +app/models/blorgh/post.rb+ and add this line into the model: +This line will require there to be a `has_many` association for comments defined on the `Blorgh::Post` model, which there isn't right now. To define one, open `app/models/blorgh/post.rb` and add this line into the model: ```ruby has_many :comments @@ -290,15 +290,15 @@ module Blorgh end ``` -NOTE: Because the +has_many+ is defined inside a class that is inside the +Blorgh+ module, Rails will know that you want to use the +Blorgh::Comment+ model for these objects, so there's no need to specify that using the +:class_name+ option here. +NOTE: Because the `has_many` is defined inside a class that is inside the `Blorgh` module, Rails will know that you want to use the `Blorgh::Comment` model for these objects, so there's no need to specify that using the `:class_name` option here. -Next, there needs to be a form so that comments can be created on a post. To add this, put this line underneath the call to +render @post.comments+ in +app/views/blorgh/posts/show.html.erb+: +Next, there needs to be a form so that comments can be created on a post. To add this, put this line underneath the call to `render @post.comments` in `app/views/blorgh/posts/show.html.erb`: ```erb <%= render "blorgh/comments/form" %> ``` -Next, the partial that this line will render needs to exist. Create a new directory at +app/views/blorgh/comments+ and in it a new file called +_form.html.erb+ which has this content to create the required partial: +Next, the partial that this line will render needs to exist. Create a new directory at `app/views/blorgh/comments` and in it a new file called `_form.html.erb` which has this content to create the required partial: ```erb <h3>New comment</h3> @@ -311,7 +311,7 @@ Next, the partial that this line will render needs to exist. Create a new direct <% end %> ``` -When this form is submitted, it is going to attempt to perform a +POST+ request to a route of +/posts/:post_id/comments+ within the engine. This route doesn't exist at the moment, but can be created by changing the +resources :posts+ line inside +config/routes.rb+ into these lines: +When this form is submitted, it is going to attempt to perform a `POST` request to a route of `/posts/:post_id/comments` within the engine. This route doesn't exist at the moment, but can be created by changing the `resources :posts` line inside `config/routes.rb` into these lines: ```ruby resources :posts do @@ -346,7 +346,7 @@ invoke css create app/assets/stylesheets/blorgh/comments.css ``` -The form will be making a +POST+ request to +/posts/:post_id/comments+, which will correspond with the +create+ action in +Blorgh::CommentsController+. This action needs to be created and can be done by putting the following lines inside the class definition in +app/controllers/blorgh/comments_controller.rb+: +The form will be making a `POST` request to `/posts/:post_id/comments`, which will correspond with the `create` action in `Blorgh::CommentsController`. This action needs to be created and can be done by putting the following lines inside the class definition in `app/controllers/blorgh/comments_controller.rb`: ```ruby def create @@ -365,26 +365,26 @@ Missing partial blorgh/comments/comment with {:handlers=>[:erb, :builder], :form * "/Users/ryan/Sites/side_projects/blorgh/app/views" ``` -The engine is unable to find the partial required for rendering the comments. Rails looks first in the application's (+test/dummy+) +app/views+ directory and then in the engine's +app/views+ directory. When it can't find it, it will throw this error. The engine knows to look for +blorgh/comments/comment+ because the model object it is receiving is from the +Blorgh::Comment+ class. +The engine is unable to find the partial required for rendering the comments. Rails looks first in the application's (`test/dummy`) `app/views` directory and then in the engine's `app/views` directory. When it can't find it, it will throw this error. The engine knows to look for `blorgh/comments/comment` because the model object it is receiving is from the `Blorgh::Comment` class. -This partial will be responsible for rendering just the comment text, for now. Create a new file at +app/views/blorgh/comments/_comment.html.erb+ and put this line inside it: +This partial will be responsible for rendering just the comment text, for now. Create a new file at `app/views/blorgh/comments/_comment.html.erb` and put this line inside it: ```erb <%= comment_counter + 1 %>. <%= comment.text %> ``` -The +comment_counter+ local variable is given to us by the +<%= render @post.comments %>+ call, as it will define this automatically and increment the counter as it iterates through each comment. It's used in this example to display a small number next to each comment when it's created. +The `comment_counter` local variable is given to us by the `<%= render @post.comments %>` call, as it will define this automatically and increment the counter as it iterates through each comment. It's used in this example to display a small number next to each comment when it's created. That completes the comment function of the blogging engine. Now it's time to use it within an application. Hooking into an application --------------------------- -Using an engine within an application is very easy. This section covers how to mount the engine into an application and the initial setup required, as well as linking the engine to a +User+ class provided by the application to provide ownership for posts and comments within the engine. +Using an engine within an application is very easy. This section covers how to mount the engine into an application and the initial setup required, as well as linking the engine to a `User` class provided by the application to provide ownership for posts and comments within the engine. ### Mounting the engine -First, the engine needs to be specified inside the application's +Gemfile+. If there isn't an application handy to test this out in, generate one using the +rails new+ command outside of the engine directory like this: +First, the engine needs to be specified inside the application's `Gemfile`. If there isn't an application handy to test this out in, generate one using the `rails new` command outside of the engine directory like this: ```bash $ rails new unicorn @@ -396,33 +396,33 @@ Usually, specifying the engine inside the Gemfile would be done by specifying it gem 'devise' ``` -However, because you are developing the +blorgh+ engine on your local machine, you will need to specify the +:path+ option in your +Gemfile+: +However, because you are developing the `blorgh` engine on your local machine, you will need to specify the `:path` option in your `Gemfile`: ```ruby gem 'blorgh', :path => "/path/to/blorgh" ``` -As described earlier, by placing the gem in the +Gemfile+ it will be loaded when Rails is loaded, as it will first require +lib/blorgh.rb+ in the engine and then +lib/blorgh/engine.rb+, which is the file that defines the major pieces of functionality for the engine. +As described earlier, by placing the gem in the `Gemfile` it will be loaded when Rails is loaded, as it will first require `lib/blorgh.rb` in the engine and then `lib/blorgh/engine.rb`, which is the file that defines the major pieces of functionality for the engine. -To make the engine's functionality accessible from within an application, it needs to be mounted in that application's +config/routes.rb+ file: +To make the engine's functionality accessible from within an application, it needs to be mounted in that application's `config/routes.rb` file: ```ruby mount Blorgh::Engine, :at => "/blog" ``` -This line will mount the engine at +/blog+ in the application. Making it accessible at +http://localhost:3000/blog+ when the application runs with +rails server+. +This line will mount the engine at `/blog` in the application. Making it accessible at `http://localhost:3000/blog` when the application runs with `rails server`. -NOTE: Other engines, such as Devise, handle this a little differently by making you specify custom helpers such as +devise_for+ in the routes. These helpers do exactly the same thing, mounting pieces of the engines's functionality at a pre-defined path which may be customizable. +NOTE: Other engines, such as Devise, handle this a little differently by making you specify custom helpers such as `devise_for` in the routes. These helpers do exactly the same thing, mounting pieces of the engines's functionality at a pre-defined path which may be customizable. ### Engine setup -The engine contains migrations for the +blorgh_posts+ and +blorgh_comments+ table which need to be created in the application's database so that the engine's models can query them correctly. To copy these migrations into the application use this command: +The engine contains migrations for the `blorgh_posts` and `blorgh_comments` table which need to be created in the application's database so that the engine's models can query them correctly. To copy these migrations into the application use this command: ```bash $ rake blorgh:install:migrations ``` -If you have multiple engines that need migrations copied over, use +railties:install:migrations+ instead: +If you have multiple engines that need migrations copied over, use `railties:install:migrations` instead: ```bash $ rake railties:install:migrations @@ -435,11 +435,11 @@ Copied migration [timestamp_1]_create_blorgh_posts.rb from blorgh Copied migration [timestamp_2]_create_blorgh_comments.rb from blorgh ``` -The first timestamp (+\[timestamp_1\]+) will be the current time and the second timestamp (+\[timestamp_2\]+) will be the current time plus a second. The reason for this is so that the migrations for the engine are run after any existing migrations in the application. +The first timestamp (`\[timestamp_1\]`) will be the current time and the second timestamp (`\[timestamp_2\]`) will be the current time plus a second. The reason for this is so that the migrations for the engine are run after any existing migrations in the application. -To run these migrations within the context of the application, simply run +rake db:migrate+. When accessing the engine through +http://localhost:3000/blog+, the posts will be empty. This is because the table created inside the application is different from the one created within the engine. Go ahead, play around with the newly mounted engine. You'll find that it's the same as when it was only an engine. +To run these migrations within the context of the application, simply run `rake db:migrate`. When accessing the engine through `http://localhost:3000/blog`, the posts will be empty. This is because the table created inside the application is different from the one created within the engine. Go ahead, play around with the newly mounted engine. You'll find that it's the same as when it was only an engine. -If you would like to run migrations only from one engine, you can do it by specifying +SCOPE+: +If you would like to run migrations only from one engine, you can do it by specifying `SCOPE`: ```bash rake db:migrate SCOPE=blorgh @@ -455,21 +455,21 @@ rake db:migrate SCOPE=blorgh VERSION=0 #### Using a model provided by the application -When an engine is created, it may want to use specific classes from an application to provide links between the pieces of the engine and the pieces of the application. In the case of the +blorgh+ engine, making posts and comments have authors would make a lot of sense. +When an engine is created, it may want to use specific classes from an application to provide links between the pieces of the engine and the pieces of the application. In the case of the `blorgh` engine, making posts and comments have authors would make a lot of sense. -A typical application might have a +User+ class that would be used to represent authors for a post or a comment. But there could be a case where the application calls this class something different, such as +Person+. For this reason, the engine should not hardcode associations specifically for a +User+ class. +A typical application might have a `User` class that would be used to represent authors for a post or a comment. But there could be a case where the application calls this class something different, such as `Person`. For this reason, the engine should not hardcode associations specifically for a `User` class. -To keep it simple in this case, the application will have a class called +User+ which will represent the users of the application. It can be generated using this command inside the application: +To keep it simple in this case, the application will have a class called `User` which will represent the users of the application. It can be generated using this command inside the application: ```bash rails g model user name:string ``` -The +rake db:migrate+ command needs to be run here to ensure that our application has the +users+ table for future use. +The `rake db:migrate` command needs to be run here to ensure that our application has the `users` table for future use. -Also, to keep it simple, the posts form will have a new text field called +author_name+ where users can elect to put their name. The engine will then take this name and create a new +User+ object from it or find one that already has that name, and then associate the post with it. +Also, to keep it simple, the posts form will have a new text field called `author_name` where users can elect to put their name. The engine will then take this name and create a new `User` object from it or find one that already has that name, and then associate the post with it. -First, the +author_name+ text field needs to be added to the +app/views/blorgh/posts/_form.html.erb+ partial inside the engine. This can be added above the +title+ field with this code: +First, the `author_name` text field needs to be added to the `app/views/blorgh/posts/_form.html.erb` partial inside the engine. This can be added above the `title` field with this code: ```erb <div class="field"> @@ -478,9 +478,9 @@ First, the +author_name+ text field needs to be added to the +app/views/blorgh/p </div> ``` -The +Blorgh::Post+ model should then have some code to convert the +author_name+ field into an actual +User+ object and associate it as that post's +author+ before the post is saved. It will also need to have an +attr_accessor+ setup for this field so that the setter and getter methods are defined for it. +The `Blorgh::Post` model should then have some code to convert the `author_name` field into an actual `User` object and associate it as that post's `author` before the post is saved. It will also need to have an `attr_accessor` setup for this field so that the setter and getter methods are defined for it. -To do all this, you'll need to add the +attr_accessor+ for +author_name+, the association for the author and the +before_save+ call into +app/models/blorgh/post.rb+. The +author+ association will be hard-coded to the +User+ class for the time being. +To do all this, you'll need to add the `attr_accessor` for `author_name`, the association for the author and the `before_save` call into `app/models/blorgh/post.rb`. The `author` association will be hard-coded to the `User` class for the time being. ```ruby attr_accessor :author_name @@ -494,7 +494,7 @@ private end ``` -By defining that the +author+ association's object is represented by the +User+ class a link is established between the engine and the application. There needs to be a way of associating the records in the +blorgh_posts+ table with the records in the +users+ table. Because the association is called +author+, there should be an +author_id+ column added to the +blorgh_posts+ table. +By defining that the `author` association's object is represented by the `User` class a link is established between the engine and the application. There needs to be a way of associating the records in the `blorgh_posts` table with the records in the `users` table. Because the association is called `author`, there should be an `author_id` column added to the `blorgh_posts` table. To generate this new column, run this command within the engine: @@ -524,9 +524,9 @@ Run this migration using this command: $ rake db:migrate ``` -Now with all the pieces in place, an action will take place that will associate an author -- represented by a record in the +users+ table -- with a post, represented by the +blorgh_posts+ table from the engine. +Now with all the pieces in place, an action will take place that will associate an author -- represented by a record in the `users` table -- with a post, represented by the `blorgh_posts` table from the engine. -Finally, the author's name should be displayed on the post's page. Add this code above the "Title" output inside +app/views/blorgh/posts/show.html.erb+: +Finally, the author's name should be displayed on the post's page. Add this code above the "Title" output inside `app/views/blorgh/posts/show.html.erb`: ```erb <p> @@ -535,13 +535,13 @@ Finally, the author's name should be displayed on the post's page. Add this code </p> ``` -By outputting +@post.author+ using the +<%=+ tag, the +to_s+ method will be called on the object. By default, this will look quite ugly: +By outputting `@post.author` using the `<%=` tag, the `to_s` method will be called on the object. By default, this will look quite ugly: ``` #<User:0x00000100ccb3b0> ``` -This is undesirable and it would be much better to have the user's name there. To do this, add a +to_s+ method to the +User+ class within the application: +This is undesirable and it would be much better to have the user's name there. To do this, add a `to_s` method to the `User` class within the application: ```ruby def to_s @@ -553,46 +553,46 @@ Now instead of the ugly Ruby object output the author's name will be displayed. #### Using a controller provided by the application -Because Rails controllers generally share code for things like authentication and accessing session variables, by default they inherit from `ApplicationController`. Rails engines, however are scoped to run independently from the main application, so each engine gets a scoped +ApplicationController+. This namespace prevents code collisions, but often engine controllers should access methods in the main application's +ApplicationController+. An easy way to provide this access is to change the engine's scoped +ApplicationController+ to inherit from the main application's +ApplicationController+. For our Blorgh engine this would be done by changing +app/controllers/blorgh/application_controller.rb+ to look like: +Because Rails controllers generally share code for things like authentication and accessing session variables, by default they inherit from `ApplicationController`. Rails engines, however are scoped to run independently from the main application, so each engine gets a scoped `ApplicationController`. This namespace prevents code collisions, but often engine controllers should access methods in the main application's `ApplicationController`. An easy way to provide this access is to change the engine's scoped `ApplicationController` to inherit from the main application's `ApplicationController`. For our Blorgh engine this would be done by changing `app/controllers/blorgh/application_controller.rb` to look like: ```ruby class Blorgh::ApplicationController < ApplicationController end ``` -By default, the engine's controllers inherit from `Blorgh::ApplicationController`. So, after making this change they will have access to the main applications +ApplicationController+ as though they were part of the main application. +By default, the engine's controllers inherit from `Blorgh::ApplicationController`. So, after making this change they will have access to the main applications `ApplicationController` as though they were part of the main application. -This change does require that the engine is run from a Rails application that has an +ApplicationController+. +This change does require that the engine is run from a Rails application that has an `ApplicationController`. ### Configuring an engine -This section covers how to make the +User+ class configurable, followed by general configuration tips for the engine. +This section covers how to make the `User` class configurable, followed by general configuration tips for the engine. #### Setting configuration settings in the application -The next step is to make the class that represents a +User+ in the application customizable for the engine. This is because, as explained before, that class may not always be +User+. To make this customizable, the engine will have a configuration setting called +user_class+ that will be used to specify what the class representing users is inside the application. +The next step is to make the class that represents a `User` in the application customizable for the engine. This is because, as explained before, that class may not always be `User`. To make this customizable, the engine will have a configuration setting called `user_class` that will be used to specify what the class representing users is inside the application. -To define this configuration setting, you should use a +mattr_accessor+ inside the +Blorgh+ module for the engine, located at +lib/blorgh.rb+ inside the engine. Inside this module, put this line: +To define this configuration setting, you should use a `mattr_accessor` inside the `Blorgh` module for the engine, located at `lib/blorgh.rb` inside the engine. Inside this module, put this line: ```ruby mattr_accessor :user_class ``` -This method works like its brothers +attr_accessor+ and +cattr_accessor+, but provides a setter and getter method on the module with the specified name. To use it, it must be referenced using +Blorgh.user_class+. +This method works like its brothers `attr_accessor` and `cattr_accessor`, but provides a setter and getter method on the module with the specified name. To use it, it must be referenced using `Blorgh.user_class`. -The next step is switching the +Blorgh::Post+ model over to this new setting. For the +belongs_to+ association inside this model (+app/models/blorgh/post.rb+), it will now become this: +The next step is switching the `Blorgh::Post` model over to this new setting. For the `belongs_to` association inside this model (`app/models/blorgh/post.rb`), it will now become this: ```ruby belongs_to :author, :class_name => Blorgh.user_class ``` -The +set_author+ method also located in this class should also use this class: +The `set_author` method also located in this class should also use this class: ```ruby self.author = Blorgh.user_class.constantize.find_or_create_by_name(author_name) ``` -To save having to call +constantize+ on the +user_class+ result all the time, you could instead just override the +user_class+ getter method inside the +Blorgh+ module in the +lib/blorgh.rb+ file to always call +constantize+ on the saved value before returning the result: +To save having to call `constantize` on the `user_class` result all the time, you could instead just override the `user_class` getter method inside the `Blorgh` module in the `lib/blorgh.rb` file to always call `constantize` on the saved value before returning the result: ```ruby def self.user_class @@ -600,58 +600,58 @@ def self.user_class end ``` -This would then turn the above code for +set_author+ into this: +This would then turn the above code for `set_author` into this: ```ruby self.author = Blorgh.user_class.find_or_create_by_name(author_name) ``` -Resulting in something a little shorter, and more implicit in its behaviour. The +user_class+ method should always return a +Class+ object. +Resulting in something a little shorter, and more implicit in its behaviour. The `user_class` method should always return a `Class` object. To set this configuration setting within the application, an initializer should be used. By using an initializer, the configuration will be set up before the application starts and calls the engine's models which may depend on this configuration setting existing. -Create a new initializer at +config/initializers/blorgh.rb+ inside the application where the +blorgh+ engine is installed and put this content in it: +Create a new initializer at `config/initializers/blorgh.rb` inside the application where the `blorgh` engine is installed and put this content in it: ```ruby Blorgh.user_class = "User" ``` -WARNING: It's very important here to use the +String+ version of the class, rather than the class itself. If you were to use the class, Rails would attempt to load that class and then reference the related table, which could lead to problems if the table wasn't already existing. Therefore, a +String+ should be used and then converted to a class using +constantize+ in the engine later on. +WARNING: It's very important here to use the `String` version of the class, rather than the class itself. If you were to use the class, Rails would attempt to load that class and then reference the related table, which could lead to problems if the table wasn't already existing. Therefore, a `String` should be used and then converted to a class using `constantize` in the engine later on. -Go ahead and try to create a new post. You will see that it works exactly in the same way as before, except this time the engine is using the configuration setting in +config/initializers/blorgh.rb+ to learn what the class is. +Go ahead and try to create a new post. You will see that it works exactly in the same way as before, except this time the engine is using the configuration setting in `config/initializers/blorgh.rb` to learn what the class is. -There are now no strict dependencies on what the class is, only what the API for the class must be. The engine simply requires this class to define a +find_or_create_by_name+ method which returns an object of that class to be associated with a post when it's created. This object, of course, should have some sort of identifier by which it can be referenced. +There are now no strict dependencies on what the class is, only what the API for the class must be. The engine simply requires this class to define a `find_or_create_by_name` method which returns an object of that class to be associated with a post when it's created. This object, of course, should have some sort of identifier by which it can be referenced. #### General engine configuration Within an engine, there may come a time where you wish to use things such as initializers, internationalization or other configuration options. The great news is that these things are entirely possible because a Rails engine shares much the same functionality as a Rails application. In fact, a Rails application's functionality is actually a superset of what is provided by engines! -If you wish to use an initializer -- code that should run before the engine is loaded -- the place for it is the +config/initializers+ folder. This directory's functionality is explained in the "Initializers section":http://guides.rubyonrails.org/configuring.html#initializers of the Configuring guide, and works precisely the same way as the +config/initializers+ directory inside an application. Same goes for if you want to use a standard initializer. +If you wish to use an initializer -- code that should run before the engine is loaded -- the place for it is the `config/initializers` folder. This directory's functionality is explained in the "Initializers section":http://guides.rubyonrails.org/configuring.html#initializers of the Configuring guide, and works precisely the same way as the `config/initializers` directory inside an application. Same goes for if you want to use a standard initializer. -For locales, simply place the locale files in the +config/locales+ directory, just like you would in an application. +For locales, simply place the locale files in the `config/locales` directory, just like you would in an application. Testing an engine ----------------- -When an engine is generated there is a smaller dummy application created inside it at +test/dummy+. This application is used as a mounting point for the engine to make testing the engine extremely simple. You may extend this application by generating controllers, models or views from within the directory, and then use those to test your engine. +When an engine is generated there is a smaller dummy application created inside it at `test/dummy`. This application is used as a mounting point for the engine to make testing the engine extremely simple. You may extend this application by generating controllers, models or views from within the directory, and then use those to test your engine. -The +test+ directory should be treated like a typical Rails testing environment, allowing for unit, functional and integration tests. +The `test` directory should be treated like a typical Rails testing environment, allowing for unit, functional and integration tests. ### Functional tests -A matter worth taking into consideration when writing functional tests is that the tests are going to be running on an application -- the +test/dummy+ application -- rather than your engine. This is due to the setup of the testing environment; an engine needs an application as a host for testing its main functionality, especially controllers. This means that if you were to make a typical +GET+ to a controller in a controller's functional test like this: +A matter worth taking into consideration when writing functional tests is that the tests are going to be running on an application -- the `test/dummy` application -- rather than your engine. This is due to the setup of the testing environment; an engine needs an application as a host for testing its main functionality, especially controllers. This means that if you were to make a typical `GET` to a controller in a controller's functional test like this: ```ruby get :index ``` -It may not function correctly. This is because the application doesn't know how to route these requests to the engine unless you explicitly tell it *how*. To do this, you must pass the +:use_route+ option (as a parameter) on these requests also: +It may not function correctly. This is because the application doesn't know how to route these requests to the engine unless you explicitly tell it *how*. To do this, you must pass the `:use_route` option (as a parameter) on these requests also: ```ruby get :index, :use_route => :blorgh ``` -This tells the application that you still want to perform a +GET+ request to the +index+ action of this controller, just that you want to use the engine's route to get there, rather than the application. +This tells the application that you still want to perform a `GET` request to the `index` action of this controller, just that you want to use the engine's route to get there, rather than the application. Improving engine functionality ------------------------------ @@ -662,11 +662,11 @@ This section explains how to add and/or override engine MVC functionality in the Engine model and controller classes can be extended by open classing them in the main Rails application (since model and controller classes are just Ruby classes that inherit Rails specific functionality). Open classing an Engine class redefines it for use in the main applicaiton. This is usually implemented by using the decorator pattern. -For simple class modifications use +Class#class_eval+, and for complex class modifications, consider using +ActiveSupport::Concern+. +For simple class modifications use `Class#class_eval`, and for complex class modifications, consider using `ActiveSupport::Concern`. #### Implementing Decorator Pattern Using Class#class_eval -**Adding** +Post#time_since_created+, +**Adding** `Post#time_since_created`, ```ruby # MyApp/app/decorators/models/blorgh/post_decorator.rb @@ -687,7 +687,7 @@ end ``` -**Overriding** +Post#summary+ +**Overriding** `Post#summary` ```ruby # MyApp/app/decorators/models/blorgh/post_decorator.rb @@ -713,10 +713,10 @@ end #### Implementing Decorator Pattern Using ActiveSupport::Concern -Using +Class#class_eval+ is great for simple adjustments, but for more complex class modifications, you might want to consider using +ActiveSupport::Concern+. ["**ActiveSupport::Concern**":http://edgeapi.rubyonrails.org/classes/ActiveSupport/Concern.html] helps manage the load order of interlinked dependencies at run time allowing you to significantly modularize your code. +Using `Class#class_eval` is great for simple adjustments, but for more complex class modifications, you might want to consider using `ActiveSupport::Concern`. ["**ActiveSupport::Concern**":http://edgeapi.rubyonrails.org/classes/ActiveSupport/Concern.html] helps manage the load order of interlinked dependencies at run time allowing you to significantly modularize your code. -**Adding** +Post#time_since_created+<br/> -**Overriding** +Post#summary+ +**Adding** `Post#time_since_created`<br/> +**Overriding** `Post#summary` ```ruby # MyApp/app/models/blorgh/post.rb @@ -778,13 +778,13 @@ end ### Overriding views -When Rails looks for a view to render, it will first look in the +app/views+ directory of the application. If it cannot find the view there, then it will check in the +app/views+ directories of all engines which have this directory. +When Rails looks for a view to render, it will first look in the `app/views` directory of the application. If it cannot find the view there, then it will check in the `app/views` directories of all engines which have this directory. -In the +blorgh+ engine, there is a currently a file at +app/views/blorgh/posts/index.html.erb+. When the engine is asked to render the view for +Blorgh::PostsController+'s +index+ action, it will first see if it can find it at +app/views/blorgh/posts/index.html.erb+ within the application and then if it cannot it will look inside the engine. +In the `blorgh` engine, there is a currently a file at `app/views/blorgh/posts/index.html.erb`. When the engine is asked to render the view for `Blorgh::PostsController`'s `index` action, it will first see if it can find it at `app/views/blorgh/posts/index.html.erb` within the application and then if it cannot it will look inside the engine. -You can override this view in the application by simply creating a new file at +app/views/blorgh/posts/index.html.erb+. Then you can completely change what this view would normally output. +You can override this view in the application by simply creating a new file at `app/views/blorgh/posts/index.html.erb`. Then you can completely change what this view would normally output. -Try this now by creating a new file at +app/views/blorgh/posts/index.html.erb+ and put this content in it: +Try this now by creating a new file at `app/views/blorgh/posts/index.html.erb` and put this content in it: ```erb <h1>Posts</h1> @@ -799,9 +799,9 @@ Try this now by creating a new file at +app/views/blorgh/posts/index.html.erb+ a ### Routes -Routes inside an engine are, by default, isolated from the application. This is done by the +isolate_namespace+ call inside the +Engine+ class. This essentially means that the application and its engines can have identically named routes, and that they will not clash. +Routes inside an engine are, by default, isolated from the application. This is done by the `isolate_namespace` call inside the `Engine` class. This essentially means that the application and its engines can have identically named routes, and that they will not clash. -Routes inside an engine are drawn on the +Engine+ class within +config/routes.rb+, like this: +Routes inside an engine are drawn on the `Engine` class within `config/routes.rb`, like this: ```ruby Blorgh::Engine.routes.draw do @@ -809,37 +809,37 @@ Blorgh::Engine.routes.draw do end ``` -By having isolated routes such as this, if you wish to link to an area of an engine from within an application, you will need to use the engine's routing proxy method. Calls to normal routing methods such as +posts_path+ may end up going to undesired locations if both the application and the engine both have such a helper defined. +By having isolated routes such as this, if you wish to link to an area of an engine from within an application, you will need to use the engine's routing proxy method. Calls to normal routing methods such as `posts_path` may end up going to undesired locations if both the application and the engine both have such a helper defined. -For instance, the following example would go to the application's +posts_path+ if that template was rendered from the application, or the engine's +posts_path+ if it was rendered from the engine: +For instance, the following example would go to the application's `posts_path` if that template was rendered from the application, or the engine's `posts_path` if it was rendered from the engine: ```erb <%= link_to "Blog posts", posts_path %> ``` -To make this route always use the engine's +posts_path+ routing helper method, we must call the method on the routing proxy method that shares the same name as the engine. +To make this route always use the engine's `posts_path` routing helper method, we must call the method on the routing proxy method that shares the same name as the engine. ```erb <%= link_to "Blog posts", blorgh.posts_path %> ``` -If you wish to reference the application inside the engine in a similar way, use the +main_app+ helper: +If you wish to reference the application inside the engine in a similar way, use the `main_app` helper: ```erb <%= link_to "Home", main_app.root_path %> ``` -If you were to use this inside an engine, it would *always* go to the application's root. If you were to leave off the +main_app+ "routing proxy" method call, it could potentially go to the engine's or application's root, depending on where it was called from. +If you were to use this inside an engine, it would *always* go to the application's root. If you were to leave off the `main_app` "routing proxy" method call, it could potentially go to the engine's or application's root, depending on where it was called from. -If a template is rendered from within an engine and it's attempting to use one of the application's routing helper methods, it may result in an undefined method call. If you encounter such an issue, ensure that you're not attempting to call the application's routing methods without the +main_app+ prefix from within the engine. +If a template is rendered from within an engine and it's attempting to use one of the application's routing helper methods, it may result in an undefined method call. If you encounter such an issue, ensure that you're not attempting to call the application's routing methods without the `main_app` prefix from within the engine. ### Assets -Assets within an engine work in an identical way to a full application. Because the engine class inherits from +Rails::Engine+, the application will know to look up in the engine's +app/assets+ and +lib/assets+ directories for potential assets. +Assets within an engine work in an identical way to a full application. Because the engine class inherits from `Rails::Engine`, the application will know to look up in the engine's `app/assets` and `lib/assets` directories for potential assets. -Much like all the other components of an engine, the assets should also be namespaced. This means if you have an asset called +style.css+, it should be placed at +app/assets/stylesheets/[engine name]/style.css+, rather than +app/assets/stylesheets/style.css+. If this asset wasn't namespaced, then there is a possibility that the host application could have an asset named identically, in which case the application's asset would take precedence and the engine's one would be all but ignored. +Much like all the other components of an engine, the assets should also be namespaced. This means if you have an asset called `style.css`, it should be placed at `app/assets/stylesheets/[engine name]/style.css`, rather than `app/assets/stylesheets/style.css`. If this asset wasn't namespaced, then there is a possibility that the host application could have an asset named identically, in which case the application's asset would take precedence and the engine's one would be all but ignored. -Imagine that you did have an asset located at +app/assets/stylesheets/blorgh/style.css+ To include this asset inside an application, just use +stylesheet_link_tag+ and reference the asset as if it were inside the engine: +Imagine that you did have an asset located at `app/assets/stylesheets/blorgh/style.css` To include this asset inside an application, just use `stylesheet_link_tag` and reference the asset as if it were inside the engine: ```erb <%= stylesheet_link_tag "blorgh/style.css" %> @@ -853,16 +853,16 @@ You can also specify these assets as dependencies of other assets using the Asse */ ``` -INFO. Remember that in order to use languages like Sass or CoffeeScript, you should add the relevant library to your engine's +.gemspec+. +INFO. Remember that in order to use languages like Sass or CoffeeScript, you should add the relevant library to your engine's `.gemspec`. ### Separate Assets & Precompiling There are some situations where your engine's assets are not required by the host application. For example, say that you've created -an admin functionality that only exists for your engine. In this case, the host application doesn't need to require +admin.css+ -or +admin.js+. Only the gem's admin layout needs these assets. It doesn't make sense for the host app to include +"blorg/admin.css"+ in it's stylesheets. In this situation, you should explicitly define these assets for precompilation. -This tells sprockets to add your engine assets when +rake assets:precompile+ is ran. +an admin functionality that only exists for your engine. In this case, the host application doesn't need to require `admin.css` +or `admin.js`. Only the gem's admin layout needs these assets. It doesn't make sense for the host app to include `"blorg/admin.css"` in it's stylesheets. In this situation, you should explicitly define these assets for precompilation. +This tells sprockets to add your engine assets when `rake assets:precompile` is ran. -You can define assets for precompilation in +engine.rb+ +You can define assets for precompilation in `engine.rb` ```ruby initializer "blorgh.assets.precompile" do |app| @@ -874,14 +874,14 @@ For more information, read the "Asset Pipeline guide":http://guides.rubyonrails. ### Other gem dependencies -Gem dependencies inside an engine should be specified inside the +.gemspec+ file at the root of the engine. The reason for this is because the engine may -be installed as a gem. If dependencies were to be specified inside the +Gemfile+, +Gem dependencies inside an engine should be specified inside the `.gemspec` file at the root of the engine. The reason for this is because the engine may +be installed as a gem. If dependencies were to be specified inside the `Gemfile`, these would not be recognised by a traditional gem install and so they would not be installed, causing the engine to malfunction. To specify a dependency that should be installed with the engine during a -traditional +gem install+, specify it inside the +Gem::Specification+ block -inside the +.gemspec+ file in the engine: +traditional `gem install`, specify it inside the `Gem::Specification` block +inside the `.gemspec` file in the engine: ```ruby s.add_dependency "moo" @@ -894,7 +894,7 @@ dependency of the application, specify it like this: s.add_development_dependency "moo" ``` -Both kinds of dependencies will be installed when +bundle install+ is run inside +Both kinds of dependencies will be installed when `bundle install` is run inside the application. The development dependencies for the gem will only be used when the tests for the engine are running. diff --git a/guides/source/form_helpers.md b/guides/source/form_helpers.md index 47e62f7d5b..37f83ee30f 100644 --- a/guides/source/form_helpers.md +++ b/guides/source/form_helpers.md @@ -21,7 +21,7 @@ NOTE: This guide is not intended to be a complete documentation of available for Dealing with Basic Forms ------------------------ -The most basic form helper is +form_tag+. +The most basic form helper is `form_tag`. ```erb <%= form_tag do %> @@ -29,7 +29,7 @@ The most basic form helper is +form_tag+. <% end %> ``` -When called without arguments like this, it creates a +<form>+ tag which, when submitted, will POST to the current page. For instance, assuming the current page is +/home/index+, the generated HTML will look like this (some line breaks added for readability): +When called without arguments like this, it creates a `<form>` tag which, when submitted, will POST to the current page. For instance, assuming the current page is `/home/index`, the generated HTML will look like this (some line breaks added for readability): ```html <form accept-charset="UTF-8" action="/home/index" method="post"> @@ -41,9 +41,9 @@ When called without arguments like this, it creates a +<form>+ tag which, </form> ``` -Now, you'll notice that the HTML contains something extra: a +div+ element with two hidden input elements inside. This div is important, because the form cannot be successfully submitted without it. The first input element with name +utf8+ enforces browsers to properly respect your form's character encoding and is generated for all forms whether their actions are "GET" or "POST". The second input element with name +authenticity_token+ is a security feature of Rails called *cross-site request forgery protection*, and form helpers generate it for every non-GET form (provided that this security feature is enabled). You can read more about this in the "Security Guide":./security.html#cross-site-request-forgery-csrf. +Now, you'll notice that the HTML contains something extra: a `div` element with two hidden input elements inside. This div is important, because the form cannot be successfully submitted without it. The first input element with name `utf8` enforces browsers to properly respect your form's character encoding and is generated for all forms whether their actions are "GET" or "POST". The second input element with name `authenticity_token` is a security feature of Rails called *cross-site request forgery protection*, and form helpers generate it for every non-GET form (provided that this security feature is enabled). You can read more about this in the "Security Guide":./security.html#cross-site-request-forgery-csrf. -NOTE: Throughout this guide, the +div+ with the hidden input elements will be excluded from code samples for brevity. +NOTE: Throughout this guide, the `div` with the hidden input elements will be excluded from code samples for brevity. ### A Generic Search Form @@ -54,7 +54,7 @@ One of the most basic forms you see on the web is a search form. This form conta # a text input element, and # a submit element. -To create this form you will use +form_tag+, +label_tag+, +text_field_tag+, and +submit_tag+, respectively. Like this: +To create this form you will use `form_tag`, `label_tag`, `text_field_tag`, and `submit_tag`, respectively. Like this: ```erb <%= form_tag("/search", :method => "get") do %> @@ -76,22 +76,22 @@ This will generate the following HTML: TIP: For every form input, an ID attribute is generated from its name ("q" in the example). These IDs can be very useful for CSS styling or manipulation of form controls with JavaScript. -Besides +text_field_tag+ and +submit_tag+, there is a similar helper for _every_ form control in HTML. +Besides `text_field_tag` and `submit_tag`, there is a similar helper for _every_ form control in HTML. IMPORTANT: Always use "GET" as the method for search forms. This allows users to bookmark a specific search and get back to it. More generally Rails encourages you to use the right HTTP verb for an action. ### Multiple Hashes in Form Helper Calls -The +form_tag+ helper accepts 2 arguments: the path for the action and an options hash. This hash specifies the method of form submission and HTML options such as the form element's class. +The `form_tag` helper accepts 2 arguments: the path for the action and an options hash. This hash specifies the method of form submission and HTML options such as the form element's class. -As with the +link_to+ helper, the path argument doesn't have to be a string; it can be a hash of URL parameters recognizable by Rails' routing mechanism, which will turn the hash into a valid URL. However, since both arguments to +form_tag+ are hashes, you can easily run into a problem if you would like to specify both. For instance, let's say you write this: +As with the `link_to` helper, the path argument doesn't have to be a string; it can be a hash of URL parameters recognizable by Rails' routing mechanism, which will turn the hash into a valid URL. However, since both arguments to `form_tag` are hashes, you can easily run into a problem if you would like to specify both. For instance, let's say you write this: ```ruby form_tag(:controller => "people", :action => "search", :method => "get", :class => "nifty_form") # => '<form accept-charset="UTF-8" action="/people/search?method=get&class=nifty_form" method="post">' ``` -Here, +method+ and +class+ are appended to the query string of the generated URL because even though you mean to write two hashes, you really only specified one. So you need to tell Ruby which is which by delimiting the first hash (or both) with curly brackets. This will generate the HTML you expect: +Here, `method` and `class` are appended to the query string of the generated URL because even though you mean to write two hashes, you really only specified one. So you need to tell Ruby which is which by delimiting the first hash (or both) with curly brackets. This will generate the HTML you expect: ```ruby form_tag({:controller => "people", :action => "search"}, :method => "get", :class => "nifty_form") @@ -100,9 +100,9 @@ form_tag({:controller => "people", :action => "search"}, :method => "get", :clas ### Helpers for Generating Form Elements -Rails provides a series of helpers for generating form elements such as checkboxes, text fields, and radio buttons. These basic helpers, with names ending in "_tag" (such as +text_field_tag+ and +check_box_tag+), generate just a single +<input>+ element. The first parameter to these is always the name of the input. When the form is submitted, the name will be passed along with the form data, and will make its way to the +params+ hash in the controller with the value entered by the user for that field. For example, if the form contains +<%= text_field_tag(:query) %>+, then you would be able to get the value of this field in the controller with +params[:query]+. +Rails provides a series of helpers for generating form elements such as checkboxes, text fields, and radio buttons. These basic helpers, with names ending in "_tag" (such as `text_field_tag` and `check_box_tag`), generate just a single `<input>` element. The first parameter to these is always the name of the input. When the form is submitted, the name will be passed along with the form data, and will make its way to the `params` hash in the controller with the value entered by the user for that field. For example, if the form contains `<%= text_field_tag(:query) %>`, then you would be able to get the value of this field in the controller with `params[:query]`. -When naming inputs, Rails uses certain conventions that make it possible to submit parameters with non-scalar values such as arrays or hashes, which will also be accessible in +params+. You can read more about them in "chapter 7 of this guide":#understanding-parameter-naming-conventions. For details on the precise usage of these helpers, please refer to the "API documentation":http://api.rubyonrails.org/classes/ActionView/Helpers/FormTagHelper.html. +When naming inputs, Rails uses certain conventions that make it possible to submit parameters with non-scalar values such as arrays or hashes, which will also be accessible in `params`. You can read more about them in "chapter 7 of this guide":#understanding-parameter-naming-conventions. For details on the precise usage of these helpers, please refer to the "API documentation":http://api.rubyonrails.org/classes/ActionView/Helpers/FormTagHelper.html. #### Checkboxes @@ -124,7 +124,7 @@ This generates the following: <label for="pet_cat">I own a cat</label> ``` -The first parameter to +check_box_tag+, of course, is the name of the input. The second parameter, naturally, is the value of the input. This value will be included in the form data (and be present in +params+) when the checkbox is checked. +The first parameter to `check_box_tag`, of course, is the name of the input. The second parameter, naturally, is the value of the input. This value will be included in the form data (and be present in `params`) when the checkbox is checked. #### Radio Buttons @@ -146,7 +146,7 @@ Output: <label for="age_adult">I'm over 21</label> ``` -As with +check_box_tag+, the second parameter to +radio_button_tag+ is the value of the input. Because these two radio buttons share the same name (age) the user will only be able to select one, and +params[:age]+ will contain either "child" or "adult". +As with `check_box_tag`, the second parameter to `radio_button_tag` is the value of the input. Because these two radio buttons share the same name (age) the user will only be able to select one, and `params[:age]` will contain either "child" or "adult". NOTE: Always use labels for checkbox and radio buttons. They associate text with a specific option and make it easier for users to click the inputs by expanding the clickable region. @@ -201,9 +201,9 @@ Dealing with Model Objects ### Model Object Helpers -A particularly common task for a form is editing or creating a model object. While the +*_tag+ helpers can certainly be used for this task they are somewhat verbose as for each tag you would have to ensure the correct parameter name is used and set the default value of the input appropriately. Rails provides helpers tailored to this task. These helpers lack the <notextile>_tag</notextile> suffix, for example +text_field+, +text_area+. +A particularly common task for a form is editing or creating a model object. While the `*_tag` helpers can certainly be used for this task they are somewhat verbose as for each tag you would have to ensure the correct parameter name is used and set the default value of the input appropriately. Rails provides helpers tailored to this task. These helpers lack the <notextile>_tag</notextile> suffix, for example `text_field`, `text_area`. -For these helpers the first argument is the name of an instance variable and the second is the name of a method (usually an attribute) to call on that object. Rails will set the value of the input control to the return value of that method for the object and set an appropriate input name. If your controller has defined +@person+ and that person's name is Henry then a form containing: +For these helpers the first argument is the name of an instance variable and the second is the name of a method (usually an attribute) to call on that object. Rails will set the value of the input control to the return value of that method for the object and set an appropriate input name. If your controller has defined `@person` and that person's name is Henry then a form containing: ```erb <%= text_field(:person, :name) %> @@ -215,17 +215,17 @@ will produce output similar to <input id="person_name" name="person[name]" type="text" value="Henry"/> ``` -Upon form submission the value entered by the user will be stored in +params[:person][:name]+. The +params[:person]+ hash is suitable for passing to +Person.new+ or, if +@person+ is an instance of Person, +@person.update_attributes+. While the name of an attribute is the most common second parameter to these helpers this is not compulsory. In the example above, as long as person objects have a +name+ and a +name=+ method Rails will be happy. +Upon form submission the value entered by the user will be stored in `params[:person][:name]`. The `params[:person]` hash is suitable for passing to `Person.new` or, if `@person` is an instance of Person, `@person.update_attributes`. While the name of an attribute is the most common second parameter to these helpers this is not compulsory. In the example above, as long as person objects have a `name` and a `name=` method Rails will be happy. -WARNING: You must pass the name of an instance variable, i.e. +:person+ or +"person"+, not an actual instance of your model object. +WARNING: You must pass the name of an instance variable, i.e. `:person` or `"person"`, not an actual instance of your model object. Rails provides helpers for displaying the validation errors associated with a model object. These are covered in detail by the "Active Record Validations and Callbacks":./active_record_validations_callbacks.html#displaying-validation-errors-in-the-view guide. ### Binding a Form to an Object -While this is an increase in comfort it is far from perfect. If Person has many attributes to edit then we would be repeating the name of the edited object many times. What we want to do is somehow bind a form to a model object, which is exactly what +form_for+ does. +While this is an increase in comfort it is far from perfect. If Person has many attributes to edit then we would be repeating the name of the edited object many times. What we want to do is somehow bind a form to a model object, which is exactly what `form_for` does. -Assume we have a controller for dealing with articles +app/controllers/articles_controller.rb+: +Assume we have a controller for dealing with articles `app/controllers/articles_controller.rb`: ```ruby def new @@ -233,7 +233,7 @@ def new end ``` -The corresponding view +app/views/articles/new.html.erb+ using +form_for+ looks like this: +The corresponding view `app/views/articles/new.html.erb` using `form_for` looks like this: ```erb <%= form_for @article, :url => { :action => "create" }, :html => {:class => "nifty_form"} do |f| %> @@ -245,10 +245,10 @@ The corresponding view +app/views/articles/new.html.erb+ using +form_for+ looks There are a few things to note here: -# +@article+ is the actual object being edited. -# There is a single hash of options. Routing options are passed in the +:url+ hash, HTML options are passed in the +:html+ hash. Also you can provide a +:namespace+ option for your form to ensure uniqueness of id attributes on form elements. The namespace attribute will be prefixed with underscore on the generated HTML id. -# The +form_for+ method yields a *form builder* object (the +f+ variable). -# Methods to create form controls are called *on* the form builder object +f+ +# `@article` is the actual object being edited. +# There is a single hash of options. Routing options are passed in the `:url` hash, HTML options are passed in the `:html` hash. Also you can provide a `:namespace` option for your form to ensure uniqueness of id attributes on form elements. The namespace attribute will be prefixed with underscore on the generated HTML id. +# The `form_for` method yields a *form builder* object (the `f` variable). +# Methods to create form controls are called *on* the form builder object `f` The resulting HTML is: @@ -260,11 +260,11 @@ The resulting HTML is: </form> ``` -The name passed to +form_for+ controls the key used in +params+ to access the form's values. Here the name is +article+ and so all the inputs have names of the form +article[<em>attribute_name</em>]+. Accordingly, in the +create+ action +params[:article]+ will be a hash with keys +:title+ and +:body+. You can read more about the significance of input names in the parameter_names section. +The name passed to `form_for` controls the key used in `params` to access the form's values. Here the name is `article` and so all the inputs have names of the form `article[<em>attribute_name</em>]`. Accordingly, in the `create` action `params[:article]` will be a hash with keys `:title` and `:body`. You can read more about the significance of input names in the parameter_names section. The helper methods called on the form builder are identical to the model object helpers except that it is not necessary to specify which object is being edited since this is already managed by the form builder. -You can create a similar binding without actually creating +<form>+ tags with the +fields_for+ helper. This is useful for editing additional model objects with the same form. For example if you had a Person model with an associated ContactDetail model you could create a form for creating both like so: +You can create a similar binding without actually creating `<form>` tags with the `fields_for` helper. This is useful for editing additional model objects with the same form. For example if you had a Person model with an associated ContactDetail model you could create a form for creating both like so: ```erb <%= form_for @person, :url => { :action => "create" } do |person_form| %> @@ -284,7 +284,7 @@ which produces the following output: </form> ``` -The object yielded by +fields_for+ is a form builder like the one yielded by +form_for+ (in fact +form_for+ calls +fields_for+ internally). +The object yielded by `fields_for` is a form builder like the one yielded by `form_for` (in fact `form_for` calls `fields_for` internally). ### Relying on Record Identification @@ -296,7 +296,7 @@ resources :articles TIP: Declaring a resource has a number of side-affects. See "Rails Routing From the Outside In":routing.html#resource-routing-the-rails-default for more information on setting up and using resources. -When dealing with RESTful resources, calls to +form_for+ can get significantly easier if you rely on *record identification*. In short, you can just pass the model instance and have Rails figure out model name and the rest: +When dealing with RESTful resources, calls to `form_for` can get significantly easier if you rely on *record identification*. In short, you can just pass the model instance and have Rails figure out model name and the rest: ```ruby ## Creating a new article @@ -312,21 +312,21 @@ form_for(@article, :url => article_path(@article), :html => { :method => "patch" form_for(@article) ``` -Notice how the short-style +form_for+ invocation is conveniently the same, regardless of the record being new or existing. Record identification is smart enough to figure out if the record is new by asking +record.new_record?+. It also selects the correct path to submit to and the name based on the class of the object. +Notice how the short-style `form_for` invocation is conveniently the same, regardless of the record being new or existing. Record identification is smart enough to figure out if the record is new by asking `record.new_record?`. It also selects the correct path to submit to and the name based on the class of the object. -Rails will also automatically set the +class+ and +id+ of the form appropriately: a form creating an article would have +id+ and +class+ +new_article+. If you were editing the article with id 23, the +class+ would be set to +edit_article+ and the id to +edit_article_23+. These attributes will be omitted for brevity in the rest of this guide. +Rails will also automatically set the `class` and `id` of the form appropriately: a form creating an article would have `id` and `class` `new_article`. If you were editing the article with id 23, the `class` would be set to `edit_article` and the id to `edit_article_23`. These attributes will be omitted for brevity in the rest of this guide. -WARNING: When you're using STI (single-table inheritance) with your models, you can't rely on record identification on a subclass if only their parent class is declared a resource. You will have to specify the model name, +:url+, and +:method+ explicitly. +WARNING: When you're using STI (single-table inheritance) with your models, you can't rely on record identification on a subclass if only their parent class is declared a resource. You will have to specify the model name, `:url`, and `:method` explicitly. #### Dealing with Namespaces -If you have created namespaced routes, +form_for+ has a nifty shorthand for that too. If your application has an admin namespace then +If you have created namespaced routes, `form_for` has a nifty shorthand for that too. If your application has an admin namespace then ```ruby form_for [:admin, @article] ``` -will create a form that submits to the articles controller inside the admin namespace (submitting to +admin_article_path(@article)+ in the case of an update). If you have several levels of namespacing then the syntax is similar: +will create a form that submits to the articles controller inside the admin namespace (submitting to `admin_article_path(@article)` in the case of an update). If you have several levels of namespacing then the syntax is similar: ```ruby form_for [:admin, :management, @article] @@ -339,7 +339,7 @@ For more information on Rails' routing system and the associated conventions, pl The Rails framework encourages RESTful design of your applications, which means you'll be making a lot of "PATCH" and "DELETE" requests (besides "GET" and "POST"). However, most browsers _don't support_ methods other than "GET" and "POST" when it comes to submitting forms. -Rails works around this issue by emulating other methods over POST with a hidden input named +"_method"+, which is set to reflect the desired method: +Rails works around this issue by emulating other methods over POST with a hidden input named `"_method"`, which is set to reflect the desired method: ```ruby form_tag(search_path, :method => "patch") @@ -357,12 +357,12 @@ output: ... ``` -When parsing POSTed data, Rails will take into account the special +_method+ parameter and acts as if the HTTP method was the one specified inside it ("PATCH" in this example). +When parsing POSTed data, Rails will take into account the special `_method` parameter and acts as if the HTTP method was the one specified inside it ("PATCH" in this example). Making Select Boxes with Ease ----------------------------- -Select boxes in HTML require a significant amount of markup (one +OPTION+ element for each option to choose from), therefore it makes the most sense for them to be dynamically generated. +Select boxes in HTML require a significant amount of markup (one `OPTION` element for each option to choose from), therefore it makes the most sense for them to be dynamically generated. Here is what the markup might look like: @@ -379,13 +379,13 @@ Here you have a list of cities whose names are presented to the user. Internally ### The Select and Option Tags -The most generic helper is +select_tag+, which -- as the name implies -- simply generates the +SELECT+ tag that encapsulates an options string: +The most generic helper is `select_tag`, which -- as the name implies -- simply generates the `SELECT` tag that encapsulates an options string: ```erb <%= select_tag(:city_id, '<option value="1">Lisbon</option>...') %> ``` -This is a start, but it doesn't dynamically create the option tags. You can generate option tags with the +options_for_select+ helper: +This is a start, but it doesn't dynamically create the option tags. You can generate option tags with the `options_for_select` helper: ```erb <%= options_for_select([['Lisbon', 1], ['Madrid', 2], ...]) %> @@ -397,15 +397,15 @@ output: ... ``` -The first argument to +options_for_select+ is a nested array where each element has two elements: option text (city name) and option value (city id). The option value is what will be submitted to your controller. Often this will be the id of a corresponding database object but this does not have to be the case. +The first argument to `options_for_select` is a nested array where each element has two elements: option text (city name) and option value (city id). The option value is what will be submitted to your controller. Often this will be the id of a corresponding database object but this does not have to be the case. -Knowing this, you can combine +select_tag+ and +options_for_select+ to achieve the desired, complete markup: +Knowing this, you can combine `select_tag` and `options_for_select` to achieve the desired, complete markup: ```erb <%= select_tag(:city_id, options_for_select(...)) %> ``` -+options_for_select+ allows you to pre-select an option by passing its value. +`options_for_select` allows you to pre-select an option by passing its value. ```erb <%= options_for_select([['Lisbon', 1], ['Madrid', 2], ...], 2) %> @@ -417,11 +417,11 @@ output: ... ``` -Whenever Rails sees that the internal value of an option being generated matches this value, it will add the +selected+ attribute to that option. +Whenever Rails sees that the internal value of an option being generated matches this value, it will add the `selected` attribute to that option. -TIP: The second argument to +options_for_select+ must be exactly equal to the desired internal value. In particular if the value is the integer 2 you cannot pass "2" to +options_for_select+ -- you must pass 2. Be aware of values extracted from the +params+ hash as they are all strings. +TIP: The second argument to `options_for_select` must be exactly equal to the desired internal value. In particular if the value is the integer 2 you cannot pass "2" to `options_for_select` -- you must pass 2. Be aware of values extracted from the `params` hash as they are all strings. -WARNING: when +:inlude_blank+ or +:prompt:+ are not present, +:include_blank+ is forced true if the select attribute +required+ is true, display +size+ is one and +multiple+ is not true. +WARNING: when `:inlude_blank` or `:prompt:` are not present, `:include_blank` is forced true if the select attribute `required` is true, display `size` is one and `multiple` is not true. You can add arbitrary attributes to the options using hashes: @@ -437,7 +437,7 @@ output: ### Select Boxes for Dealing with Models -In most cases form controls will be tied to a specific database model and as you might expect Rails provides helpers tailored for that purpose. Consistent with other form helpers, when dealing with models you drop the +_tag+ suffix from +select_tag+: +In most cases form controls will be tied to a specific database model and as you might expect Rails provides helpers tailored for that purpose. Consistent with other form helpers, when dealing with models you drop the `_tag` suffix from `select_tag`: ```ruby # controller: @@ -449,67 +449,67 @@ In most cases form controls will be tied to a specific database model and as you <%= select(:person, :city_id, [['Lisbon', 1], ['Madrid', 2], ...]) %> ``` -Notice that the third parameter, the options array, is the same kind of argument you pass to +options_for_select+. One advantage here is that you don't have to worry about pre-selecting the correct city if the user already has one -- Rails will do this for you by reading from the +@person.city_id+ attribute. +Notice that the third parameter, the options array, is the same kind of argument you pass to `options_for_select`. One advantage here is that you don't have to worry about pre-selecting the correct city if the user already has one -- Rails will do this for you by reading from the `@person.city_id` attribute. -As with other helpers, if you were to use the +select+ helper on a form builder scoped to the +@person+ object, the syntax would be: +As with other helpers, if you were to use the `select` helper on a form builder scoped to the `@person` object, the syntax would be: ```erb # select on a form builder <%= f.select(:city_id, ...) %> ``` -WARNING: If you are using +select+ (or similar helpers such as +collection_select+, +select_tag+) to set a +belongs_to+ association you must pass the name of the foreign key (in the example above +city_id+), not the name of association itself. If you specify +city+ instead of +city_id+ Active Record will raise an error along the lines of ` ActiveRecord::AssociationTypeMismatch: City(#17815740) expected, got String(#1138750) ` when you pass the +params+ hash to +Person.new+ or +update_attributes+. Another way of looking at this is that form helpers only edit attributes. You should also be aware of the potential security ramifications of allowing users to edit foreign keys directly. You may wish to consider the use of +attr_protected+ and +attr_accessible+. For further details on this, see the "Ruby On Rails Security Guide":security.html#mass-assignment. +WARNING: If you are using `select` (or similar helpers such as `collection_select`, `select_tag`) to set a `belongs_to` association you must pass the name of the foreign key (in the example above `city_id`), not the name of association itself. If you specify `city` instead of `city_id` Active Record will raise an error along the lines of ` ActiveRecord::AssociationTypeMismatch: City(#17815740) expected, got String(#1138750) ` when you pass the `params` hash to `Person.new` or `update_attributes`. Another way of looking at this is that form helpers only edit attributes. You should also be aware of the potential security ramifications of allowing users to edit foreign keys directly. You may wish to consider the use of `attr_protected` and `attr_accessible`. For further details on this, see the "Ruby On Rails Security Guide":security.html#mass-assignment. ### Option Tags from a Collection of Arbitrary Objects -Generating options tags with +options_for_select+ requires that you create an array containing the text and value for each option. But what if you had a City model (perhaps an Active Record one) and you wanted to generate option tags from a collection of those objects? One solution would be to make a nested array by iterating over them: +Generating options tags with `options_for_select` requires that you create an array containing the text and value for each option. But what if you had a City model (perhaps an Active Record one) and you wanted to generate option tags from a collection of those objects? One solution would be to make a nested array by iterating over them: ```erb <% cities_array = City.all.map { |city| [city.name, city.id] } %> <%= options_for_select(cities_array) %> ``` -This is a perfectly valid solution, but Rails provides a less verbose alternative: +options_from_collection_for_select+. This helper expects a collection of arbitrary objects and two additional arguments: the names of the methods to read the option *value* and *text* from, respectively: +This is a perfectly valid solution, but Rails provides a less verbose alternative: `options_from_collection_for_select`. This helper expects a collection of arbitrary objects and two additional arguments: the names of the methods to read the option *value* and *text* from, respectively: ```erb <%= options_from_collection_for_select(City.all, :id, :name) %> ``` -As the name implies, this only generates option tags. To generate a working select box you would need to use it in conjunction with +select_tag+, just as you would with +options_for_select+. When working with model objects, just as +select+ combines +select_tag+ and +options_for_select+, +collection_select+ combines +select_tag+ with +options_from_collection_for_select+. +As the name implies, this only generates option tags. To generate a working select box you would need to use it in conjunction with `select_tag`, just as you would with `options_for_select`. When working with model objects, just as `select` combines `select_tag` and `options_for_select`, `collection_select` combines `select_tag` with `options_from_collection_for_select`. ```erb <%= collection_select(:person, :city_id, City.all, :id, :name) %> ``` -To recap, +options_from_collection_for_select+ is to +collection_select+ what +options_for_select+ is to +select+. +To recap, `options_from_collection_for_select` is to `collection_select` what `options_for_select` is to `select`. -NOTE: Pairs passed to +options_for_select+ should have the name first and the id second, however with +options_from_collection_for_select+ the first argument is the value method and the second the text method. +NOTE: Pairs passed to `options_for_select` should have the name first and the id second, however with `options_from_collection_for_select` the first argument is the value method and the second the text method. ### Time Zone and Country Select -To leverage time zone support in Rails, you have to ask your users what time zone they are in. Doing so would require generating select options from a list of pre-defined TimeZone objects using +collection_select+, but you can simply use the +time_zone_select+ helper that already wraps this: +To leverage time zone support in Rails, you have to ask your users what time zone they are in. Doing so would require generating select options from a list of pre-defined TimeZone objects using `collection_select`, but you can simply use the `time_zone_select` helper that already wraps this: ```erb <%= time_zone_select(:person, :time_zone) %> ``` -There is also +time_zone_options_for_select+ helper for a more manual (therefore more customizable) way of doing this. Read the API documentation to learn about the possible arguments for these two methods. +There is also `time_zone_options_for_select` helper for a more manual (therefore more customizable) way of doing this. Read the API documentation to learn about the possible arguments for these two methods. -Rails _used_ to have a +country_select+ helper for choosing countries, but this has been extracted to the "country_select plugin":https://github.com/chrislerum/country_select. When using this, be aware that the exclusion or inclusion of certain names from the list can be somewhat controversial (and was the reason this functionality was extracted from Rails). +Rails _used_ to have a `country_select` helper for choosing countries, but this has been extracted to the "country_select plugin":https://github.com/chrislerum/country_select. When using this, be aware that the exclusion or inclusion of certain names from the list can be somewhat controversial (and was the reason this functionality was extracted from Rails). Using Date and Time Form Helpers -------------------------------- You can choose not to use the form helpers generating HTML5 date and time input fields and use the alternative date and time helpers. These date and time helpers differ from all the other form helpers in two important respects: -# Dates and times are not representable by a single input element. Instead you have several, one for each component (year, month, day etc.) and so there is no single value in your +params+ hash with your date or time. -# Other helpers use the +_tag+ suffix to indicate whether a helper is a barebones helper or one that operates on model objects. With dates and times, +select_date+, +select_time+ and +select_datetime+ are the barebones helpers, +date_select+, +time_select+ and +datetime_select+ are the equivalent model object helpers. +# Dates and times are not representable by a single input element. Instead you have several, one for each component (year, month, day etc.) and so there is no single value in your `params` hash with your date or time. +# Other helpers use the `_tag` suffix to indicate whether a helper is a barebones helper or one that operates on model objects. With dates and times, `select_date`, `select_time` and `select_datetime` are the barebones helpers, `date_select`, `time_select` and `datetime_select` are the equivalent model object helpers. Both of these families of helpers will create a series of select boxes for the different components (year, month, day etc.). ### Barebones Helpers -The +select_*+ family of helpers take as their first argument an instance of Date, Time or DateTime that is used as the currently selected value. You may omit this parameter, in which case the current date is used. For example +The `select_*` family of helpers take as their first argument an instance of Date, Time or DateTime that is used as the currently selected value. You may omit this parameter, in which case the current date is used. For example ```erb <%= select_date Date.today, :prefix => :start_date %> @@ -523,17 +523,17 @@ outputs (with actual option values omitted for brevity) <select id="start_date_day" name="start_date[day]"> ... </select> ``` -The above inputs would result in +params[:start_date]+ being a hash with keys +:year+, +:month+, +:day+. To get an actual Time or Date object you would have to extract these values and pass them to the appropriate constructor, for example +The above inputs would result in `params[:start_date]` being a hash with keys `:year`, `:month`, `:day`. To get an actual Time or Date object you would have to extract these values and pass them to the appropriate constructor, for example ```ruby Date.civil(params[:start_date][:year].to_i, params[:start_date][:month].to_i, params[:start_date][:day].to_i) ``` -The +:prefix+ option is the key used to retrieve the hash of date components from the +params+ hash. Here it was set to +start_date+, if omitted it will default to +date+. +The `:prefix` option is the key used to retrieve the hash of date components from the `params` hash. Here it was set to `start_date`, if omitted it will default to `date`. ### Model Object Helpers -+select_date+ does not work well with forms that update or create Active Record objects as Active Record expects each element of the +params+ hash to correspond to one attribute. +`select_date` does not work well with forms that update or create Active Record objects as Active Record expects each element of the `params` hash to correspond to one attribute. The model object helpers for dates and times submit parameters with special names, when Active Record sees parameters with such names it knows they must be combined with the other parameters and given to a constructor appropriate to the column type. For example: ```erb @@ -548,25 +548,25 @@ outputs (with actual option values omitted for brevity) <select id="person_birth_date_3i" name="person[birth_date(3i)]"> ... </select> ``` -which results in a +params+ hash like +which results in a `params` hash like ```ruby {:person => {'birth_date(1i)' => '2008', 'birth_date(2i)' => '11', 'birth_date(3i)' => '22'}} ``` -When this is passed to +Person.new+ (or +update_attributes+), Active Record spots that these parameters should all be used to construct the +birth_date+ attribute and uses the suffixed information to determine in which order it should pass these parameters to functions such as +Date.civil+. +When this is passed to `Person.new` (or `update_attributes`), Active Record spots that these parameters should all be used to construct the `birth_date` attribute and uses the suffixed information to determine in which order it should pass these parameters to functions such as `Date.civil`. ### Common Options -Both families of helpers use the same core set of functions to generate the individual select tags and so both accept largely the same options. In particular, by default Rails will generate year options 5 years either side of the current year. If this is not an appropriate range, the +:start_year+ and +:end_year+ options override this. For an exhaustive list of the available options, refer to the "API documentation":http://api.rubyonrails.org/classes/ActionView/Helpers/DateHelper.html. +Both families of helpers use the same core set of functions to generate the individual select tags and so both accept largely the same options. In particular, by default Rails will generate year options 5 years either side of the current year. If this is not an appropriate range, the `:start_year` and `:end_year` options override this. For an exhaustive list of the available options, refer to the "API documentation":http://api.rubyonrails.org/classes/ActionView/Helpers/DateHelper.html. -As a rule of thumb you should be using +date_select+ when working with model objects and +select_date+ in other cases, such as a search form which filters results by date. +As a rule of thumb you should be using `date_select` when working with model objects and `select_date` in other cases, such as a search form which filters results by date. NOTE: In many cases the built-in date pickers are clumsy as they do not aid the user in working out the relationship between the date and the day of the week. ### Individual Components -Occasionally you need to display just a single date component such as a year or a month. Rails provides a series of helpers for this, one for each component +select_year+, +select_month+, +select_day+, +select_hour+, +select_minute+, +select_second+. These helpers are fairly straightforward. By default they will generate an input field named after the time component (for example "year" for +select_year+, "month" for +select_month+ etc.) although this can be overridden with the +:field_name+ option. The +:prefix+ option works in the same way that it does for +select_date+ and +select_time+ and has the same default value. +Occasionally you need to display just a single date component such as a year or a month. Rails provides a series of helpers for this, one for each component `select_year`, `select_month`, `select_day`, `select_hour`, `select_minute`, `select_second`. These helpers are fairly straightforward. By default they will generate an input field named after the time component (for example "year" for `select_year`, "month" for `select_month` etc.) although this can be overridden with the `:field_name` option. The `:prefix` option works in the same way that it does for `select_date` and `select_time` and has the same default value. The first parameter specifies which value should be selected and can either be an instance of a Date, Time or DateTime, in which case the relevant component will be extracted, or a numerical value. For example @@ -575,12 +575,12 @@ The first parameter specifies which value should be selected and can either be a <%= select_year(Time.now) %> ``` -will produce the same output if the current year is 2009 and the value chosen by the user can be retrieved by +params[:date][:year]+. +will produce the same output if the current year is 2009 and the value chosen by the user can be retrieved by `params[:date][:year]`. Uploading Files --------------- -A common task is uploading some sort of file, whether it's a picture of a person or a CSV file containing data to process. The most important thing to remember with file uploads is that the rendered form's encoding *MUST* be set to "multipart/form-data". If you use +form_for+, this is done automatically. If you use +form_tag+, you must set it yourself, as per the following example. +A common task is uploading some sort of file, whether it's a picture of a person or a CSV file containing data to process. The most important thing to remember with file uploads is that the rendered form's encoding *MUST* be set to "multipart/form-data". If you use `form_for`, this is done automatically. If you use `form_tag`, you must set it yourself, as per the following example. The following two forms both upload a file. @@ -594,13 +594,13 @@ The following two forms both upload a file. <% end %> ``` -NOTE: Since Rails 3.1, forms rendered using +form_for+ have their encoding set to `multipart/form-data` automatically once a +file_field+ is used inside the block. Previous versions required you to set this explicitly. +NOTE: Since Rails 3.1, forms rendered using `form_for` have their encoding set to `multipart/form-data` automatically once a `file_field` is used inside the block. Previous versions required you to set this explicitly. -Rails provides the usual pair of helpers: the barebones +file_field_tag+ and the model oriented +file_field+. The only difference with other helpers is that you cannot set a default value for file inputs as this would have no meaning. As you would expect in the first case the uploaded file is in +params[:picture]+ and in the second case in +params[:person][:picture]+. +Rails provides the usual pair of helpers: the barebones `file_field_tag` and the model oriented `file_field`. The only difference with other helpers is that you cannot set a default value for file inputs as this would have no meaning. As you would expect in the first case the uploaded file is in `params[:picture]` and in the second case in `params[:person][:picture]`. ### What Gets Uploaded -The object in the +params+ hash is an instance of a subclass of IO. Depending on the size of the uploaded file it may in fact be a StringIO or an instance of File backed by a temporary file. In both cases the object will have an +original_filename+ attribute containing the name the file had on the user's computer and a +content_type+ attribute containing the MIME type of the uploaded file. The following snippet saves the uploaded content in +#{Rails.root}/public/uploads+ under the same name as the original file (assuming the form was the one in the previous example). +The object in the `params` hash is an instance of a subclass of IO. Depending on the size of the uploaded file it may in fact be a StringIO or an instance of File backed by a temporary file. In both cases the object will have an `original_filename` attribute containing the name the file had on the user's computer and a `content_type` attribute containing the MIME type of the uploaded file. The following snippet saves the uploaded content in `#{Rails.root}/public/uploads` under the same name as the original file (assuming the form was the one in the previous example). ```ruby def upload @@ -617,12 +617,12 @@ NOTE: If the user has not selected a file the corresponding parameter will be an ### Dealing with Ajax -Unlike other forms making an asynchronous file upload form is not as simple as providing +form_for+ with `:remote => true`. With an Ajax form the serialization is done by JavaScript running inside the browser and since JavaScript cannot read files from your hard drive the file cannot be uploaded. The most common workaround is to use an invisible iframe that serves as the target for the form submission. +Unlike other forms making an asynchronous file upload form is not as simple as providing `form_for` with `:remote => true`. With an Ajax form the serialization is done by JavaScript running inside the browser and since JavaScript cannot read files from your hard drive the file cannot be uploaded. The most common workaround is to use an invisible iframe that serves as the target for the form submission. Customizing Form Builders ------------------------- -As mentioned previously the object yielded by +form_for+ and +fields_for+ is an instance of FormBuilder (or a subclass thereof). Form builders encapsulate the notion of displaying form elements for a single object. While you can of course write helpers for your forms in the usual way you can also subclass FormBuilder and add the helpers there. For example +As mentioned previously the object yielded by `form_for` and `fields_for` is an instance of FormBuilder (or a subclass thereof). Form builders encapsulate the notion of displaying form elements for a single object. While you can of course write helpers for your forms in the usual way you can also subclass FormBuilder and add the helpers there. For example ```erb <%= form_for @person do |f| %> @@ -648,7 +648,7 @@ class LabellingFormBuilder < ActionView::Helpers::FormBuilder end ``` -If you reuse this frequently you could define a +labeled_form_for+ helper that automatically applies the +:builder => LabellingFormBuilder+ option. +If you reuse this frequently you could define a `labeled_form_for` helper that automatically applies the `:builder => LabellingFormBuilder` option. The form builder used also determines what happens when you do @@ -656,13 +656,13 @@ The form builder used also determines what happens when you do <%= render :partial => f %> ``` -If +f+ is an instance of FormBuilder then this will render the +form+ partial, setting the partial's object to the form builder. If the form builder is of class LabellingFormBuilder then the +labelling_form+ partial would be rendered instead. +If `f` is an instance of FormBuilder then this will render the `form` partial, setting the partial's object to the form builder. If the form builder is of class LabellingFormBuilder then the `labelling_form` partial would be rendered instead. Understanding Parameter Naming Conventions ------------------------------------------ -As you've seen in the previous sections, values from forms can be at the top level of the +params+ hash or nested in another hash. For example in a standard +create+ -action for a Person model, +params[:person]+ would usually be a hash of all the attributes for the person to create. The +params+ hash can also contain arrays, arrays of hashes and so on. +As you've seen in the previous sections, values from forms can be at the top level of the `params` hash or nested in another hash. For example in a standard `create` +action for a Person model, `params[:person]` would usually be a hash of all the attributes for the person to create. The `params` hash can also contain arrays, arrays of hashes and so on. Fundamentally HTML forms don't know about any sort of structured data, all they generate is name–value pairs, where pairs are just plain strings. The arrays and hashes you see in your application are the result of some parameter naming conventions that Rails uses. @@ -675,19 +675,19 @@ Rack::Utils.parse_query "name=fred&phone=0123456789" ### Basic Structures -The two basic structures are arrays and hashes. Hashes mirror the syntax used for accessing the value in +params+. For example if a form contains +The two basic structures are arrays and hashes. Hashes mirror the syntax used for accessing the value in `params`. For example if a form contains ```html <input id="person_name" name="person[name]" type="text" value="Henry"/> ``` -the +params+ hash will contain +the `params` hash will contain ```erb {'person' => {'name' => 'Henry'}} ``` -and +params[:person][:name]+ will retrieve the submitted value in the controller. +and `params[:person][:name]` will retrieve the submitted value in the controller. Hashes can be nested as many levels as required, for example @@ -695,7 +695,7 @@ Hashes can be nested as many levels as required, for example <input id="person_address_city" name="person[address][city]" type="text" value="New York"/> ``` -will result in the +params+ hash being +will result in the `params` hash being ```ruby {'person' => {'address' => {'city' => 'New York'}}} @@ -709,7 +709,7 @@ Normally Rails ignores duplicate parameter names. If the parameter name contains <input name="person[phone_number][]" type="text"/> ``` -This would result in +params[:person][:phone_number]+ being an array. +This would result in `params[:person][:phone_number]` being an array. ### Combining Them @@ -721,15 +721,15 @@ We can mix and match these two concepts. For example, one element of a hash migh <input name="addresses[][city]" type="text"/> ``` -This would result in +params[:addresses]+ being an array of hashes with keys +line1+, +line2+ and +city+. Rails decides to start accumulating values in a new hash whenever it encounters an input name that already exists in the current hash. +This would result in `params[:addresses]` being an array of hashes with keys `line1`, `line2` and `city`. Rails decides to start accumulating values in a new hash whenever it encounters an input name that already exists in the current hash. There's a restriction, however, while hashes can be nested arbitrarily, only one level of "arrayness" is allowed. Arrays can be usually replaced by hashes, for example instead of having an array of model objects one can have a hash of model objects keyed by their id, an array index or some other parameter. -WARNING: Array parameters do not play well with the +check_box+ helper. According to the HTML specification unchecked checkboxes submit no value. However it is often convenient for a checkbox to always submit a value. The +check_box+ helper fakes this by creating an auxiliary hidden input with the same name. If the checkbox is unchecked only the hidden input is submitted and if it is checked then both are submitted but the value submitted by the checkbox takes precedence. When working with array parameters this duplicate submission will confuse Rails since duplicate input names are how it decides when to start a new array element. It is preferable to either use +check_box_tag+ or to use hashes instead of arrays. +WARNING: Array parameters do not play well with the `check_box` helper. According to the HTML specification unchecked checkboxes submit no value. However it is often convenient for a checkbox to always submit a value. The `check_box` helper fakes this by creating an auxiliary hidden input with the same name. If the checkbox is unchecked only the hidden input is submitted and if it is checked then both are submitted but the value submitted by the checkbox takes precedence. When working with array parameters this duplicate submission will confuse Rails since duplicate input names are how it decides when to start a new array element. It is preferable to either use `check_box_tag` or to use hashes instead of arrays. ### Using Form Helpers -The previous sections did not use the Rails form helpers at all. While you can craft the input names yourself and pass them directly to helpers such as +text_field_tag+ Rails also provides higher level support. The two tools at your disposal here are the name parameter to +form_for+ and +fields_for+ and the +:index+ option that helpers take. +The previous sections did not use the Rails form helpers at all. While you can craft the input names yourself and pass them directly to helpers such as `text_field_tag` Rails also provides higher level support. The two tools at your disposal here are the name parameter to `form_for` and `fields_for` and the `:index` option that helpers take. You might want to render a form with a set of edit fields for each of a person's addresses. For example: @@ -754,15 +754,15 @@ Assuming the person had two addresses, with ids 23 and 45 this would create outp </form> ``` -This will result in a +params+ hash that looks like +This will result in a `params` hash that looks like ```ruby {'person' => {'name' => 'Bob', 'address' => {'23' => {'city' => 'Paris'}, '45' => {'city' => 'London'}}}} ``` -Rails knows that all these inputs should be part of the person hash because you called +fields_for+ on the first form builder. By specifying an +:index+ option you're telling Rails that instead of naming the inputs +person[address][city]+ it should insert that index surrounded by [] between the address and the city. If you pass an Active Record object as we did then Rails will call +to_param+ on it, which by default returns the database id. This is often useful as it is then easy to locate which Address record should be modified. You can pass numbers with some other significance, strings or even +nil+ (which will result in an array parameter being created). +Rails knows that all these inputs should be part of the person hash because you called `fields_for` on the first form builder. By specifying an `:index` option you're telling Rails that instead of naming the inputs `person[address][city]` it should insert that index surrounded by [] between the address and the city. If you pass an Active Record object as we did then Rails will call `to_param` on it, which by default returns the database id. This is often useful as it is then easy to locate which Address record should be modified. You can pass numbers with some other significance, strings or even `nil` (which will result in an array parameter being created). -To create more intricate nestings, you can specify the first part of the input name (+person[address]+ in the previous example) explicitly, for example +To create more intricate nestings, you can specify the first part of the input name (`person[address]` in the previous example) explicitly, for example ```erb <%= fields_for 'person[address][primary]', address, :index => address do |address_form| %> @@ -776,9 +776,9 @@ will create inputs like <input id="person_address_primary_1_city" name="person[address][primary][1][city]" type="text" value="bologna" /> ``` -As a general rule the final input name is the concatenation of the name given to +fields_for+/+form_for+, the index value and the name of the attribute. You can also pass an +:index+ option directly to helpers such as +text_field+, but it is usually less repetitive to specify this at the form builder level rather than on individual input controls. +As a general rule the final input name is the concatenation of the name given to `fields_for`/`form_for`, the index value and the name of the attribute. You can also pass an `:index` option directly to helpers such as `text_field`, but it is usually less repetitive to specify this at the form builder level rather than on individual input controls. -As a shortcut you can append [] to the name and omit the +:index+ option. This is the same as specifying +:index => address+ so +As a shortcut you can append [] to the name and omit the `:index` option. This is the same as specifying `:index => address` so ```erb <%= fields_for 'person[address][primary][]', address do |address_form| %> @@ -791,7 +791,7 @@ produces exactly the same output as the previous example. Forms to external resources --------------------------- -If you need to post some data to an external resource it is still great to build your form using rails form helpers. But sometimes you need to set an +authenticity_token+ for this resource. You can do it by passing an +:authenticity_token => 'your_external_token'+ parameter to the +form_tag+ options: +If you need to post some data to an external resource it is still great to build your form using rails form helpers. But sometimes you need to set an `authenticity_token` for this resource. You can do it by passing an `:authenticity_token => 'your_external_token'` parameter to the `form_tag` options: ```erb <%= form_tag 'http://farfar.away/form', :authenticity_token => 'external_token') do %> @@ -799,7 +799,7 @@ If you need to post some data to an external resource it is still great to build <% end %> ``` -Sometimes when you submit data to an external resource, like payment gateway, fields you can use in your form are limited by an external API. So you may want not to generate an +authenticity_token+ hidden field at all. For doing this just pass +false+ to the +:authenticity_token+ option: +Sometimes when you submit data to an external resource, like payment gateway, fields you can use in your form are limited by an external API. So you may want not to generate an `authenticity_token` hidden field at all. For doing this just pass `false` to the `:authenticity_token` option: ```erb <%= form_tag 'http://farfar.away/form', :authenticity_token => false) do %> @@ -807,7 +807,7 @@ Sometimes when you submit data to an external resource, like payment gateway, fi <% end %> ``` -The same technique is available for the +form_for+ too: +The same technique is available for the `form_for` too: ```erb <%= form_for @invoice, :url => external_url, :authenticity_token => 'external_token' do |f| @@ -815,7 +815,7 @@ The same technique is available for the +form_for+ too: <% end %> ``` -Or if you don't want to render an +authenticity_token+ field: +Or if you don't want to render an `authenticity_token` field: ```erb <%= form_for @invoice, :url => external_url, :authenticity_token => false do |f| @@ -830,7 +830,7 @@ Many apps grow beyond simple forms editing a single object. For example when cre ### Configuring the Model -Active Record provides model level support via the +accepts_nested_attributes_for+ method: +Active Record provides model level support via the `accepts_nested_attributes_for` method: ```ruby class Person < ActiveRecord::Base @@ -846,11 +846,11 @@ class Address < ActiveRecord::Base end ``` -This creates an +addresses_attributes=+ method on +Person+ that allows you to create, update and (optionally) destroy addresses. When using +attr_accessible+ or +attr_protected+ you must mark +addresses_attributes+ as accessible as well as the other attributes of +Person+ and +Address+ that should be mass assigned. +This creates an `addresses_attributes=` method on `Person` that allows you to create, update and (optionally) destroy addresses. When using `attr_accessible` or `attr_protected` you must mark `addresses_attributes` as accessible as well as the other attributes of `Person` and `Address` that should be mass assigned. ### Building the Form -The following form allows a user to create a +Person+ and its associated addresses. +The following form allows a user to create a `Person` and its associated addresses. ```erb <%= form_for @person do |f| %> @@ -871,7 +871,7 @@ The following form allows a user to create a +Person+ and its associated address ``` -When an association accepts nested attributes +fields_for+ renders its block once for every element of the association. In particular, if a person has no addresses it renders nothing. A common pattern is for the controller to build one or more empty children so that at least one set of fields is shown to the user. The example below would result in 3 sets of address fields being rendered on the new person form. +When an association accepts nested attributes `fields_for` renders its block once for every element of the association. In particular, if a person has no addresses it renders nothing. A common pattern is for the controller to build one or more empty children so that at least one set of fields is shown to the user. The example below would result in 3 sets of address fields being rendered on the new person form. ```ruby def new @@ -880,7 +880,7 @@ def new end ``` -+fields_for+ yields a form builder that names parameters in the format expected the accessor generated by +accepts_nested_attributes_for+. For example when creating a user with 2 addresses, the submitted parameters would look like +`fields_for` yields a form builder that names parameters in the format expected the accessor generated by `accepts_nested_attributes_for`. For example when creating a user with 2 addresses, the submitted parameters would look like ```ruby { @@ -900,9 +900,9 @@ end } ``` -The keys of the +:addresses_attributes+ hash are unimportant, they need merely be different for each address. +The keys of the `:addresses_attributes` hash are unimportant, they need merely be different for each address. -If the associated object is already saved, +fields_for+ autogenerates a hidden input with the +id+ of the saved record. You can disable this by passing +:include_id => false+ to +fields_for+. You may wish to do this if the autogenerated input is placed in a location where an input tag is not valid HTML or when using an ORM where children do not have an id. +If the associated object is already saved, `fields_for` autogenerates a hidden input with the `id` of the saved record. You can disable this by passing `:include_id => false` to `fields_for`. You may wish to do this if the autogenerated input is placed in a location where an input tag is not valid HTML or when using an ORM where children do not have an id. ### The Controller @@ -910,7 +910,7 @@ You do not need to write any specific controller code to use nested attributes. ### Removing Objects -You can allow users to delete associated objects by passing +allow_destroy => true+ to +accepts_nested_attributes_for+ +You can allow users to delete associated objects by passing `allow_destroy => true` to `accepts_nested_attributes_for` ```ruby class Person < ActiveRecord::Base @@ -919,7 +919,7 @@ class Person < ActiveRecord::Base end ``` -If the hash of attributes for an object contains the key +_destroy+ with a value of '1' or 'true' then the object will be destroyed. This form allows users to remove addresses: +If the hash of attributes for an object contains the key `_destroy` with a value of '1' or 'true' then the object will be destroyed. This form allows users to remove addresses: ```erb <%= form_for @person do |f| %> @@ -939,7 +939,7 @@ If the hash of attributes for an object contains the key +_destroy+ with a value ### Preventing Empty Records -It is often useful to ignore sets of fields that the user has not filled in. You can control this by passing a +:reject_if+ proc to +accepts_nested_attributes_for+. This proc will be called with each hash of attributes submitted by the form. If the proc returns +false+ then Active Record will not build an associated object for that hash. The example below only tries to build an address if the +kind+ attribute is set. +It is often useful to ignore sets of fields that the user has not filled in. You can control this by passing a `:reject_if` proc to `accepts_nested_attributes_for`. This proc will be called with each hash of attributes submitted by the form. If the proc returns `false` then Active Record will not build an associated object for that hash. The example below only tries to build an address if the `kind` attribute is set. ```ruby class Person < ActiveRecord::Base @@ -948,7 +948,7 @@ class Person < ActiveRecord::Base end ``` -As a convenience you can instead pass the symbol +:all_blank+ which will create a proc that will reject records where all the attributes are blank excluding any value for +_destroy+. +As a convenience you can instead pass the symbol `:all_blank` which will create a proc that will reject records where all the attributes are blank excluding any value for `_destroy`. ### Adding Fields on the Fly diff --git a/guides/source/generators.md b/guides/source/generators.md index 0581af2c85..cb99d1f60a 100644 --- a/guides/source/generators.md +++ b/guides/source/generators.md @@ -20,7 +20,7 @@ NOTE: This guide is about generators in Rails 3, previous versions are not cover First Contact ------------- -When you create an application using the +rails+ command, you are in fact using a Rails generator. After that, you can get a list of all available generators by just invoking +rails generate+: +When you create an application using the `rails` command, you are in fact using a Rails generator. After that, you can get a list of all available generators by just invoking `rails generate`: ```bash $ rails new myapp @@ -37,9 +37,9 @@ $ rails generate helper --help Creating Your First Generator ----------------------------- -Since Rails 3.0, generators are built on top of "Thor":https://github.com/wycats/thor. Thor provides powerful options parsing and a great API for manipulating files. For instance, let's build a generator that creates an initializer file named +initializer.rb+ inside +config/initializers+. +Since Rails 3.0, generators are built on top of "Thor":https://github.com/wycats/thor. Thor provides powerful options parsing and a great API for manipulating files. For instance, let's build a generator that creates an initializer file named `initializer.rb` inside `config/initializers`. -The first step is to create a file at +lib/generators/initializer_generator.rb+ with the following content: +The first step is to create a file at `lib/generators/initializer_generator.rb` with the following content: ```ruby class InitializerGenerator < Rails::Generators::Base @@ -49,9 +49,9 @@ class InitializerGenerator < Rails::Generators::Base end ``` -NOTE: +create_file+ is a method provided by +Thor::Actions+. Documentation for +create_file+ and other Thor methods can be found in "Thor's documentation":http://rdoc.info/github/wycats/thor/master/Thor/Actions.html +NOTE: `create_file` is a method provided by `Thor::Actions`. Documentation for `create_file` and other Thor methods can be found in "Thor's documentation":http://rdoc.info/github/wycats/thor/master/Thor/Actions.html -Our new generator is quite simple: it inherits from +Rails::Generators::Base+ and has one method definition. When a generator is invoked, each public method in the generator is executed sequentially in the order that it is defined. Finally, we invoke the +create_file+ method that will create a file at the given destination with the given content. If you are familiar with the Rails Application Templates API, you'll feel right at home with the new generators API. +Our new generator is quite simple: it inherits from `Rails::Generators::Base` and has one method definition. When a generator is invoked, each public method in the generator is executed sequentially in the order that it is defined. Finally, we invoke the `create_file` method that will create a file at the given destination with the given content. If you are familiar with the Rails Application Templates API, you'll feel right at home with the new generators API. To invoke our new generator, we just need to do: @@ -65,7 +65,7 @@ Before we go on, let's see our brand new generator description: $ rails generate initializer --help ``` -Rails is usually able to generate good descriptions if a generator is namespaced, as +ActiveRecord::Generators::ModelGenerator+, but not in this particular case. We can solve this problem in two ways. The first one is calling +desc+ inside our generator: +Rails is usually able to generate good descriptions if a generator is namespaced, as `ActiveRecord::Generators::ModelGenerator`, but not in this particular case. We can solve this problem in two ways. The first one is calling `desc` inside our generator: ```ruby class InitializerGenerator < Rails::Generators::Base @@ -76,7 +76,7 @@ class InitializerGenerator < Rails::Generators::Base end ``` -Now we can see the new description by invoking +--help+ on the new generator. The second way to add a description is by creating a file named +USAGE+ in the same directory as our generator. We are going to do that in the next step. +Now we can see the new description by invoking `--help` on the new generator. The second way to add a description is by creating a file named `USAGE` in the same directory as our generator. We are going to do that in the next step. Creating Generators with Generators ----------------------------------- @@ -99,7 +99,7 @@ class InitializerGenerator < Rails::Generators::NamedBase end ``` -First, notice that we are inheriting from +Rails::Generators::NamedBase+ instead of +Rails::Generators::Base+. This means that our generator expects at least one argument, which will be the name of the initializer, and will be available in our code in the variable +name+. +First, notice that we are inheriting from `Rails::Generators::NamedBase` instead of `Rails::Generators::Base`. This means that our generator expects at least one argument, which will be the name of the initializer, and will be available in our code in the variable `name`. We can see that by invoking the description of this new generator (don't forget to delete the old generator file): @@ -109,9 +109,9 @@ Usage: rails generate initializer NAME [options] ``` -We can also see that our new generator has a class method called +source_root+. This method points to where our generator templates will be placed, if any, and by default it points to the created directory +lib/generators/initializer/templates+. +We can also see that our new generator has a class method called `source_root`. This method points to where our generator templates will be placed, if any, and by default it points to the created directory `lib/generators/initializer/templates`. -In order to understand what a generator template means, let's create the file +lib/generators/initializer/templates/initializer.rb+ with the following content: +In order to understand what a generator template means, let's create the file `lib/generators/initializer/templates/initializer.rb` with the following content: ```ruby # Add initialization content here @@ -135,14 +135,14 @@ And let's execute our generator: $ rails generate initializer core_extensions ``` -We can see that now an initializer named core_extensions was created at +config/initializers/core_extensions.rb+ with the contents of our template. That means that +copy_file+ copied a file in our source root to the destination path we gave. The method +file_name+ is automatically created when we inherit from +Rails::Generators::NamedBase+. +We can see that now an initializer named core_extensions was created at `config/initializers/core_extensions.rb` with the contents of our template. That means that `copy_file` copied a file in our source root to the destination path we gave. The method `file_name` is automatically created when we inherit from `Rails::Generators::NamedBase`. The methods that are available for generators are covered in the "final section":#generator-methods of this guide. Generators Lookup ----------------- -When you run +rails generate initializer core_extensions+ Rails requires these files in turn until one is found: +When you run `rails generate initializer core_extensions` Rails requires these files in turn until one is found: ```bash rails/generators/initializer/initializer_generator.rb @@ -153,12 +153,12 @@ generators/initializer_generator.rb If none is found you get an error message. -INFO: The examples above put files under the application's +lib+ because said directory belongs to +$LOAD_PATH+. +INFO: The examples above put files under the application's `lib` because said directory belongs to `$LOAD_PATH`. Customizing Your Workflow ------------------------- -Rails own generators are flexible enough to let you customize scaffolding. They can be configured in +config/application.rb+, these are some defaults: +Rails own generators are flexible enough to let you customize scaffolding. They can be configured in `config/application.rb`, these are some defaults: ```ruby config.generators do |g| @@ -219,7 +219,7 @@ To demonstrate this, we are going to create a new helper generator that simply a $ rails generate generator rails/my_helper ``` -After that, we can delete both the +templates+ directory and the +source_root+ class method from our new generators, because we are not going to need them. So our new generator looks like the following: +After that, we can delete both the `templates` directory and the `source_root` class method from our new generators, because we are not going to need them. So our new generator looks like the following: ```ruby class Rails::MyHelperGenerator < Rails::Generators::NamedBase @@ -239,7 +239,7 @@ We can try out our new generator by creating a helper for users: $ rails generate my_helper products ``` -And it will generate the following helper file in +app/helpers+: +And it will generate the following helper file in `app/helpers`: ```ruby module ProductsHelper @@ -247,7 +247,7 @@ module ProductsHelper end ``` -Which is what we expected. We can now tell scaffold to use our new helper generator by editing +config/application.rb+ once again: +Which is what we expected. We can now tell scaffold to use our new helper generator by editing `config/application.rb` once again: ```ruby config.generators do |g| @@ -288,7 +288,7 @@ end end ``` -Now, when the helper generator is invoked and TestUnit is configured as the test framework, it will try to invoke both +Rails::TestUnitGenerator+ and +TestUnit::MyHelperGenerator+. Since none of those are defined, we can tell our generator to invoke +TestUnit::Generators::HelperGenerator+ instead, which is defined since it's a Rails generator. To do that, we just need to add: +Now, when the helper generator is invoked and TestUnit is configured as the test framework, it will try to invoke both `Rails::TestUnitGenerator` and `TestUnit::MyHelperGenerator`. Since none of those are defined, we can tell our generator to invoke `TestUnit::Generators::HelperGenerator` instead, which is defined since it's a Rails generator. To do that, we just need to add: ```ruby # Search for :helper instead of :my_helper @@ -300,9 +300,9 @@ And now you can re-run scaffold for another resource and see it generating tests Customizing Your Workflow by Changing Generators Templates ---------------------------------------------------------- -In the step above we simply wanted to add a line to the generated helper, without adding any extra functionality. There is a simpler way to do that, and it's by replacing the templates of already existing generators, in that case +Rails::Generators::HelperGenerator+. +In the step above we simply wanted to add a line to the generated helper, without adding any extra functionality. There is a simpler way to do that, and it's by replacing the templates of already existing generators, in that case `Rails::Generators::HelperGenerator`. -In Rails 3.0 and above, generators don't just look in the source root for templates, they also search for templates in other paths. And one of them is +lib/templates+. Since we want to customize +Rails::Generators::HelperGenerator+, we can do that by simply making a template copy inside +lib/templates/rails/helper+ with the name +helper.rb+. So let's create that file with the following content: +In Rails 3.0 and above, generators don't just look in the source root for templates, they also search for templates in other paths. And one of them is `lib/templates`. Since we want to customize `Rails::Generators::HelperGenerator`, we can do that by simply making a template copy inside `lib/templates/rails/helper` with the name `helper.rb`. So let's create that file with the following content: ```erb module <%= class_name %>Helper @@ -310,7 +310,7 @@ module <%= class_name %>Helper end ``` -and revert the last change in +config/application.rb+: +and revert the last change in `config/application.rb`: ```ruby config.generators do |g| @@ -321,14 +321,14 @@ config.generators do |g| end ``` -If you generate another resource, you can see that we get exactly the same result! This is useful if you want to customize your scaffold templates and/or layout by just creating +edit.html.erb+, +index.html.erb+ and so on inside +lib/templates/erb/scaffold+. +If you generate another resource, you can see that we get exactly the same result! This is useful if you want to customize your scaffold templates and/or layout by just creating `edit.html.erb`, `index.html.erb` and so on inside `lib/templates/erb/scaffold`. Adding Generators Fallbacks --------------------------- -One last feature about generators which is quite useful for plugin generators is fallbacks. For example, imagine that you want to add a feature on top of TestUnit like "shoulda":https://github.com/thoughtbot/shoulda does. Since TestUnit already implements all generators required by Rails and shoulda just wants to overwrite part of it, there is no need for shoulda to reimplement some generators again, it can simply tell Rails to use a +TestUnit+ generator if none was found under the +Shoulda+ namespace. +One last feature about generators which is quite useful for plugin generators is fallbacks. For example, imagine that you want to add a feature on top of TestUnit like "shoulda":https://github.com/thoughtbot/shoulda does. Since TestUnit already implements all generators required by Rails and shoulda just wants to overwrite part of it, there is no need for shoulda to reimplement some generators again, it can simply tell Rails to use a `TestUnit` generator if none was found under the `Shoulda` namespace. -We can easily simulate this behavior by changing our +config/application.rb+ once again: +We can easily simulate this behavior by changing our `config/application.rb` once again: ```ruby config.generators do |g| @@ -391,17 +391,17 @@ if yes?("Would you like to install Devise?") end ``` -In the above template we specify that the application relies on the +rspec-rails+ and +cucumber-rails+ gem so these two will be added to the +test+ group in the +Gemfile+. Then we pose a question to the user about whether or not they would like to install Devise. If the user replies "y" or "yes" to this question, then the template will add Devise to the +Gemfile+ outside of any group and then runs the +devise:install+ generator. This template then takes the users input and runs the +devise+ generator, with the user's answer from the last question being passed to this generator. +In the above template we specify that the application relies on the `rspec-rails` and `cucumber-rails` gem so these two will be added to the `test` group in the `Gemfile`. Then we pose a question to the user about whether or not they would like to install Devise. If the user replies "y" or "yes" to this question, then the template will add Devise to the `Gemfile` outside of any group and then runs the `devise:install` generator. This template then takes the users input and runs the `devise` generator, with the user's answer from the last question being passed to this generator. -Imagine that this template was in a file called +template.rb+. We can use it to modify the outcome of the +rails new+ command by using the +-m+ option and passing in the filename: +Imagine that this template was in a file called `template.rb`. We can use it to modify the outcome of the `rails new` command by using the `-m` option and passing in the filename: ```bash $ rails new thud -m template.rb ``` -This command will generate the +Thud+ application, and then apply the template to the generated output. +This command will generate the `Thud` application, and then apply the template to the generated output. -Templates don't have to be stored on the local system, the +-m+ option also supports online templates: +Templates don't have to be stored on the local system, the `-m` option also supports online templates: ```bash $ rails new thud -m https://gist.github.com/722911.txt @@ -416,7 +416,7 @@ The following are methods available for both generators and templates for Rails. NOTE: Methods provided by Thor are not covered this guide and can be found in "Thor's documentation":http://rdoc.info/github/wycats/thor/master/Thor/Actions.html -### +gem+ +### `gem` Specifies a gem dependency of the application. @@ -427,9 +427,9 @@ gem("devise", "1.1.5") Available options are: -* +:group+ - The group in the +Gemfile+ where this gem should go. -* +:version+ - The version string of the gem you want to use. Can also be specified as the second argument to the method. -* +:git+ - The URL to the git repository for this gem. +* `:group` - The group in the `Gemfile` where this gem should go. +* `:version` - The version string of the gem you want to use. Can also be specified as the second argument to the method. +* `:git` - The URL to the git repository for this gem. Any additional options passed to this method are put on the end of the line: @@ -437,13 +437,13 @@ Any additional options passed to this method are put on the end of the line: gem("devise", :git => "git://github.com/plataformatec/devise", :branch => "master") ``` -The above code will put the following line into +Gemfile+: +The above code will put the following line into `Gemfile`: ```ruby gem "devise", :git => "git://github.com/plataformatec/devise", :branch => "master" ``` -### +gem_group+ +### `gem_group` Wraps gem entries inside a group: @@ -453,15 +453,15 @@ gem_group :development, :test do end ``` -### +add_source+ +### `add_source` -Adds a specified source to +Gemfile+: +Adds a specified source to `Gemfile`: ```ruby add_source "http://gems.github.com" ``` -### +inject_into_file+ +### `inject_into_file` Injects a block of code into a defined position in your file. @@ -472,7 +472,7 @@ RUBY end ``` -### +gsub_file+ +### `gsub_file` Replaces text inside a file. @@ -482,9 +482,9 @@ gsub_file 'name_of_file.rb', 'method.to_be_replaced', 'method.the_replacing_code Regular Expressions can be used to make this method more precise. You can also use append_file and prepend_file in the same way to place code at the beginning and end of a file respectively. -### +application+ +### `application` -Adds a line to +config/application.rb+ directly after the application class definition. +Adds a line to `config/application.rb` directly after the application class definition. ```ruby application "config.asset_host = 'http://example.com'" @@ -500,7 +500,7 @@ end Available options are: -* +:env+ - Specify an environment for this configuration option. If you wish to use this option with the block syntax the recommended syntax is as follows: +* `:env` - Specify an environment for this configuration option. If you wish to use this option with the block syntax the recommended syntax is as follows: ```ruby application(nil, :env => "development") do @@ -508,7 +508,7 @@ application(nil, :env => "development") do end ``` -### +git+ +### `git` Runs the specified git command: @@ -521,9 +521,9 @@ git :add => "onefile.rb", :rm => "badfile.cxx" The values of the hash here being the arguments or options passed to the specific git command. As per the final example shown here, multiple git commands can be specified at a time, but the order of their running is not guaranteed to be the same as the order that they were specified in. -### +vendor+ +### `vendor` -Places a file into +vendor+ which contains the specified code. +Places a file into `vendor` which contains the specified code. ```ruby vendor("sekrit.rb", '#top secret stuff') @@ -537,9 +537,9 @@ vendor("seeds.rb") do end ``` -### +lib+ +### `lib` -Places a file into +lib+ which contains the specified code. +Places a file into `lib` which contains the specified code. ```ruby lib("special.rb", 'p Rails.root') @@ -553,9 +553,9 @@ lib("super_special.rb") do end ``` -### +rakefile+ +### `rakefile` -Creates a Rake file in the +lib/tasks+ directory of the application. +Creates a Rake file in the `lib/tasks` directory of the application. ```ruby rakefile("test.rake", 'hello there') @@ -573,9 +573,9 @@ rakefile("test.rake") do end ``` -### +initializer+ +### `initializer` -Creates an initializer in the +config/initializers+ directory of the application: +Creates an initializer in the `config/initializers` directory of the application: ```ruby initializer("begin.rb", "puts 'this is the beginning'") @@ -589,7 +589,7 @@ initializer("begin.rb") do end ``` -### +generate+ +### `generate` Runs the specified generator where the first argument is the generator name and the remaining arguments are passed directly to the generator. @@ -598,7 +598,7 @@ generate("scaffold", "forums title:string description:text") ``` -### +rake+ +### `rake` Runs the specified Rake task. @@ -608,28 +608,28 @@ rake("db:migrate") Available options are: -* +:env+ - Specifies the environment in which to run this rake task. -* +:sudo+ - Whether or not to run this task using +sudo+. Defaults to +false+. +* `:env` - Specifies the environment in which to run this rake task. +* `:sudo` - Whether or not to run this task using `sudo`. Defaults to `false`. -### +capify!+ +### `capify!` -Runs the +capify+ command from Capistrano at the root of the application which generates Capistrano configuration. +Runs the `capify` command from Capistrano at the root of the application which generates Capistrano configuration. ```ruby capify! ``` -### +route+ +### `route` -Adds text to the +config/routes.rb+ file: +Adds text to the `config/routes.rb` file: ```ruby route("resources :people") ``` -### +readme+ +### `readme` -Output the contents of a file in the template's +source_path+, usually a README. +Output the contents of a file in the template's `source_path`, usually a README. ```ruby readme("README") diff --git a/guides/source/getting_started.md b/guides/source/getting_started.md index 67a09b6cbd..193d11761e 100644 --- a/guides/source/getting_started.md +++ b/guides/source/getting_started.md @@ -69,7 +69,7 @@ literally follow along step by step. You can get the complete code "here":https://github.com/lifo/docrails/tree/master/guides/code/getting_started. By following along with this guide, you'll create a Rails project called -+blog+, a +`blog`, a (very) simple weblog. Before you can start building the application, you need to make sure that you have Rails itself installed. @@ -77,7 +77,7 @@ TIP: The examples below use # and $ to denote superuser and regular user termina ### Installing Rails -To install Rails, use the +gem install+ command provided by RubyGems: +To install Rails, use the `gem install` command provided by RubyGems: ```bash # gem install rails @@ -106,10 +106,10 @@ To use this generator, open a terminal, navigate to a directory where you have r $ rails new blog ``` -This will create a Rails application called Blog in a directory called blog and install the gem dependencies that are already mentioned in +Gemfile+ using +bundle install+. +This will create a Rails application called Blog in a directory called blog and install the gem dependencies that are already mentioned in `Gemfile` using `bundle install`. TIP: You can see all of the command line options that the Rails -application builder accepts by running +rails new -h+. +application builder accepts by running `rails new -h`. After you create the blog application, switch to its folder to continue work directly in that application: @@ -117,10 +117,10 @@ After you create the blog application, switch to its folder to continue work dir $ cd blog ``` -The +rails new blog+ command we ran above created a folder in your -working directory called +blog+. The +blog+ directory has a number of +The `rails new blog` command we ran above created a folder in your +working directory called `blog`. The `blog` directory has a number of auto-generated files and folders that make up the structure of a Rails -application. Most of the work in this tutorial will happen in the +app/+ folder, but here's a basic rundown on the function of each of the files and folders that Rails created by default: +application. Most of the work in this tutorial will happen in the `app/` folder, but here's a basic rundown on the function of each of the files and folders that Rails created by default: |_.File/Folder|_.Purpose| |app/|Contains the controllers, models, views, helpers, mailers and assets for your application. You'll focus on this folder for the remainder of this guide.| @@ -152,7 +152,7 @@ You actually have a functional Rails application already. To see it, you need to $ rails server ``` -TIP: Compiling CoffeeScript to JavaScript requires a JavaScript runtime and the absence of a runtime will give you an +execjs+ error. Usually Mac OS X and Windows come with a JavaScript runtime installed. Rails adds the +therubyracer+ gem to Gemfile in a commented line for new apps and you can uncomment if you need it. +therubyrhino+ is the recommended runtime for JRuby users and is added by default to Gemfile in apps generated under JRuby. You can investigate about all the supported runtimes at "ExecJS":https://github.com/sstephenson/execjs#readme. +TIP: Compiling CoffeeScript to JavaScript requires a JavaScript runtime and the absence of a runtime will give you an `execjs` error. Usually Mac OS X and Windows come with a JavaScript runtime installed. Rails adds the `therubyracer` gem to Gemfile in a commented line for new apps and you can uncomment if you need it. `therubyrhino` is the recommended runtime for JRuby users and is added by default to Gemfile in apps generated under JRuby. You can investigate about all the supported runtimes at "ExecJS":https://github.com/sstephenson/execjs#readme. This will fire up WEBrick, a webserver built into Ruby by default. To see your application in action, open a browser window and navigate to "http://localhost:3000":http://localhost:3000. You should see the Rails default information page: @@ -197,9 +197,9 @@ invoke scss create app/assets/stylesheets/welcome.css.scss ``` -Most important of these are of course the controller, located at +app/controllers/welcome_controller.rb+ and the view, located at +app/views/welcome/index.html.erb+. +Most important of these are of course the controller, located at `app/controllers/welcome_controller.rb` and the view, located at `app/views/welcome/index.html.erb`. -Open the +app/views/welcome/index.html.erb+ file in your text editor and edit it to contain a single line of code: +Open the `app/views/welcome/index.html.erb` file in your text editor and edit it to contain a single line of code: ```html <h1>Hello, Rails!</h1> @@ -209,13 +209,13 @@ Open the +app/views/welcome/index.html.erb+ file in your text editor and edit it Now that we have made the controller and view, we need to tell Rails when we want "Hello Rails!" to show up. In our case, we want it to show up when we navigate to the root URL of our site, "http://localhost:3000":http://localhost:3000. At the moment, however, the "Welcome Aboard" smoke test is occupying that spot. -To fix this, delete the +index.html+ file located inside the +public+ directory of the application. +To fix this, delete the `index.html` file located inside the `public` directory of the application. -You need to do this because Rails will serve any static file in the +public+ directory that matches a route in preference to any dynamic content you generate from the controllers. The +index.html+ file is special: it will be served if a request comes in at the root route, e.g. http://localhost:3000. If another request such as http://localhost:3000/welcome happened, a static file at `public/welcome.html` would be served first, but only if it existed. +You need to do this because Rails will serve any static file in the `public` directory that matches a route in preference to any dynamic content you generate from the controllers. The `index.html` file is special: it will be served if a request comes in at the root route, e.g. http://localhost:3000. If another request such as http://localhost:3000/welcome happened, a static file at `public/welcome.html` would be served first, but only if it existed. Next, you have to tell Rails where your actual home page is located. -Open the file +config/routes.rb+ in your editor. +Open the file `config/routes.rb` in your editor. ```ruby Blog::Application.routes.draw do @@ -229,15 +229,15 @@ Blog::Application.routes.draw do # root :to => "welcome#index" ``` -This is your application's _routing file_ which holds entries in a special DSL (domain-specific language) that tells Rails how to connect incoming requests to controllers and actions. This file contains many sample routes on commented lines, and one of them actually shows you how to connect the root of your site to a specific controller and action. Find the line beginning with +root :to+ and uncomment it. It should look something like the following: +This is your application's _routing file_ which holds entries in a special DSL (domain-specific language) that tells Rails how to connect incoming requests to controllers and actions. This file contains many sample routes on commented lines, and one of them actually shows you how to connect the root of your site to a specific controller and action. Find the line beginning with `root :to` and uncomment it. It should look something like the following: ```ruby root :to => "welcome#index" ``` -The +root :to => "welcome#index"+ tells Rails to map requests to the root of the application to the welcome controller's index action and +get "welcome/index"+ tells Rails to map requests to "http://localhost:3000/welcome/index":http://localhost:3000/welcome/index to the welcome controller's index action. This was created earlier when you ran the controller generator (+rails generate controller welcome index+). +The `root :to => "welcome#index"` tells Rails to map requests to the root of the application to the welcome controller's index action and `get "welcome/index"` tells Rails to map requests to "http://localhost:3000/welcome/index":http://localhost:3000/welcome/index to the welcome controller's index action. This was created earlier when you ran the controller generator (`rails generate controller welcome index`). -If you navigate to "http://localhost:3000":http://localhost:3000 in your browser, you'll see the +Hello, Rails!+ message you put into +app/views/welcome/index.html.erb+, indicating that this new route is indeed going to +WelcomeController+'s +index+ action and is rendering the view correctly. +If you navigate to "http://localhost:3000":http://localhost:3000 in your browser, you'll see the `Hello, Rails!` message you put into `app/views/welcome/index.html.erb`, indicating that this new route is indeed going to `WelcomeController`'s `index` action and is rendering the view correctly. NOTE. For more information about routing, refer to "Rails Routing from the Outside In":routing.html. @@ -256,53 +256,53 @@ It will look a little basic for now, but that's ok. We'll look at improving the ### Laying down the ground work -The first thing that you are going to need to create a new post within the application is a place to do that. A great place for that would be at +/posts/new+. If you attempt to navigate to that now -- by visiting "http://localhost:3000/posts/new":http://localhost:3000/posts/new -- Rails will give you a routing error: +The first thing that you are going to need to create a new post within the application is a place to do that. A great place for that would be at `/posts/new`. If you attempt to navigate to that now -- by visiting "http://localhost:3000/posts/new":http://localhost:3000/posts/new -- Rails will give you a routing error: !images/getting_started/routing_error_no_route_matches.png(A routing error, no route matches /posts/new)! -This is because there is nowhere inside the routes for the application -- defined inside +config/routes.rb+ -- that defines this route. By default, Rails has no routes configured at all, besides the root route you defined earlier, and so you must define your routes as you need them. +This is because there is nowhere inside the routes for the application -- defined inside `config/routes.rb` -- that defines this route. By default, Rails has no routes configured at all, besides the root route you defined earlier, and so you must define your routes as you need them. - To do this, you're going to need to create a route inside +config/routes.rb+ file, on a new line between the +do+ and the +end+ for the +draw+ method: + To do this, you're going to need to create a route inside `config/routes.rb` file, on a new line between the `do` and the `end` for the `draw` method: ```ruby get "posts/new" ``` -This route is a super-simple route: it defines a new route that only responds to +GET+ requests, and that the route is at +posts/new+. But how does it know where to go without the use of the +:to+ option? Well, Rails uses a sensible default here: Rails will assume that you want this route to go to the new action inside the posts controller. +This route is a super-simple route: it defines a new route that only responds to `GET` requests, and that the route is at `posts/new`. But how does it know where to go without the use of the `:to` option? Well, Rails uses a sensible default here: Rails will assume that you want this route to go to the new action inside the posts controller. -With the route defined, requests can now be made to +/posts/new+ in the application. Navigate to "http://localhost:3000/posts/new":http://localhost:3000/posts/new and you'll see another routing error: +With the route defined, requests can now be made to `/posts/new` in the application. Navigate to "http://localhost:3000/posts/new":http://localhost:3000/posts/new and you'll see another routing error: !images/getting_started/routing_error_no_controller.png(Another routing error, uninitialized constant PostsController)! -This error is happening because this route need a controller to be defined. The route is attempting to find that controller so it can serve the request, but with the controller undefined, it just can't do that. The solution to this particular problem is simple: you need to create a controller called +PostsController+. You can do this by running this command: +This error is happening because this route need a controller to be defined. The route is attempting to find that controller so it can serve the request, but with the controller undefined, it just can't do that. The solution to this particular problem is simple: you need to create a controller called `PostsController`. You can do this by running this command: ```bash $ rails g controller posts ``` -If you open up the newly generated +app/controllers/posts_controller.rb+ you'll see a fairly empty controller: +If you open up the newly generated `app/controllers/posts_controller.rb` you'll see a fairly empty controller: ```ruby class PostsController < ApplicationController end ``` -A controller is simply a class that is defined to inherit from +ApplicationController+. It's inside this class that you'll define methods that will become the actions for this controller. These actions will perform CRUD operations on the posts within our system. +A controller is simply a class that is defined to inherit from `ApplicationController`. It's inside this class that you'll define methods that will become the actions for this controller. These actions will perform CRUD operations on the posts within our system. If you refresh "http://localhost:3000/posts/new":http://localhost:3000/posts/new now, you'll get a new error: !images/getting_started/unknown_action_new_for_posts.png(Unknown action new for PostsController!)! -This error indicates that Rails cannot find the +new+ action inside the +PostsController+ that you just generated. This is because when controllers are generated in Rails they are empty by default, unless you tell it you wanted actions during the generation process. +This error indicates that Rails cannot find the `new` action inside the `PostsController` that you just generated. This is because when controllers are generated in Rails they are empty by default, unless you tell it you wanted actions during the generation process. -To manually define an action inside a controller, all you need to do is to define a new method inside the controller. Open +app/controllers/posts_controller.rb+ and inside the +PostsController+ class, define a +new+ method like this: +To manually define an action inside a controller, all you need to do is to define a new method inside the controller. Open `app/controllers/posts_controller.rb` and inside the `PostsController` class, define a `new` method like this: ```ruby def new end ``` -With the +new+ method defined in +PostsController+, if you refresh "http://localhost:3000/posts/new":http://localhost:3000/posts/new you'll see another error: +With the `new` method defined in `PostsController`, if you refresh "http://localhost:3000/posts/new":http://localhost:3000/posts/new you'll see another error: !images/getting_started/template_is_missing_posts_new.png(Template is missing for posts/new)! @@ -316,15 +316,15 @@ Missing template posts/new, application/new with {:locale=>[:en], :formats=>[:ht That's quite a lot of text! Let's quickly go through and understand what each part of it does. -The first part identifies what template is missing. In this case, it's the +posts/new+ template. Rails will first look for this template. If not found, then it will attempt to load a template called +application/new+. It looks for one here because the +PostsController+ inherits from +ApplicationController+. +The first part identifies what template is missing. In this case, it's the `posts/new` template. Rails will first look for this template. If not found, then it will attempt to load a template called `application/new`. It looks for one here because the `PostsController` inherits from `ApplicationController`. -The next part of the message contains a hash. The +:locale+ key in this hash simply indicates what spoken language template should be retrieved. By default, this is the English -- or "en" -- template. The next key, +:formats+ specifies the format of template to be served in response . The default format is +:html+, and so Rails is looking for an HTML template. The final key, +:handlers+, is telling us what _template handlers_ could be used to render our template. +:erb+ is most commonly used for HTML templates, +:builder+ is used for XML templates, and +:coffee+ uses CoffeeScript to build JavaScript templates. +The next part of the message contains a hash. The `:locale` key in this hash simply indicates what spoken language template should be retrieved. By default, this is the English -- or "en" -- template. The next key, `:formats` specifies the format of template to be served in response . The default format is `:html`, and so Rails is looking for an HTML template. The final key, `:handlers`, is telling us what _template handlers_ could be used to render our template. `:erb` is most commonly used for HTML templates, `:builder` is used for XML templates, and `:coffee` uses CoffeeScript to build JavaScript templates. The final part of this message tells us where Rails has looked for the templates. Templates within a basic Rails application like this are kept in a single location, but in more complex applications it could be many different paths. -The simplest template that would work in this case would be one located at +app/views/posts/new.html.erb+. The extension of this file name is key: the first extension is the _format_ of the template, and the second extension is the _handler_ that will be used. Rails is attempting to find a template called +posts/new+ within +app/views+ for the application. The format for this template can only be +html+ and the handler must be one of +erb+, +builder+ or +coffee+. Because you want to create a new HTML form, you will be using the +ERB+ language. Therefore the file should be called +posts/new.html.erb+ and needs to be located inside the +app/views+ directory of the application. +The simplest template that would work in this case would be one located at `app/views/posts/new.html.erb`. The extension of this file name is key: the first extension is the _format_ of the template, and the second extension is the _handler_ that will be used. Rails is attempting to find a template called `posts/new` within `app/views` for the application. The format for this template can only be `html` and the handler must be one of `erb`, `builder` or `coffee`. Because you want to create a new HTML form, you will be using the `ERB` language. Therefore the file should be called `posts/new.html.erb` and needs to be located inside the `app/views` directory of the application. -Go ahead now and create a new file at +app/views/posts/new.html.erb+ and write this content in it: +Go ahead now and create a new file at `app/views/posts/new.html.erb` and write this content in it: ```erb <h1>New Post</h1> @@ -336,7 +336,7 @@ When you refresh "http://localhost:3000/posts/new":http://localhost:3000/posts/n To create a form within this template, you will use a <em>form builder</em>. The primary form builder for Rails is provided by a helper -method called +form_for+. To use this method, add this code into +app/views/posts/new.html.erb+: +method called `form_for`. To use this method, add this code into `app/views/posts/new.html.erb`: ```erb <%= form_for :post do |f| %> @@ -358,41 +358,41 @@ method called +form_for+. To use this method, add this code into +app/views/post If you refresh the page now, you'll see the exact same form as in the example. Building forms in Rails is really just that easy! -When you call +form_for+, you pass it an identifying object for this -form. In this case, it's the symbol +:post+. This tells the +form_for+ +When you call `form_for`, you pass it an identifying object for this +form. In this case, it's the symbol `:post`. This tells the `form_for` helper what this form is for. Inside the block for this method, the -+FormBuilder+ object -- represented by +f+ -- is used to build two labels and two text fields, one each for the title and text of a post. Finally, a call to +submit+ on the +f+ object will create a submit button for the form. +`FormBuilder` object -- represented by `f` -- is used to build two labels and two text fields, one each for the title and text of a post. Finally, a call to `submit` on the `f` object will create a submit button for the form. -There's one problem with this form though. If you inspect the HTML that is generated, by viewing the source of the page, you will see that the +action+ attribute for the form is pointing at +/posts/new+. This is a problem because this route goes to the very page that you're on right at the moment, and that route should only be used to display the form for a new post. +There's one problem with this form though. If you inspect the HTML that is generated, by viewing the source of the page, you will see that the `action` attribute for the form is pointing at `/posts/new`. This is a problem because this route goes to the very page that you're on right at the moment, and that route should only be used to display the form for a new post. The form needs to use a different URL in order to go somewhere else. -This can be done quite simply with the +:url+ option of +form_for+. +This can be done quite simply with the `:url` option of `form_for`. Typically in Rails, the action that is used for new form submissions like this is called "create", and so the form should be pointed to that action. -Edit the +form_for+ line inside +app/views/posts/new.html.erb+ to look like this: +Edit the `form_for` line inside `app/views/posts/new.html.erb` to look like this: ```erb <%= form_for :post, :url => { :action => :create } do |f| %> ``` -In this example, a +Hash+ object is passed to the +:url+ option. What Rails will do with this is that it will point the form to the +create+ action of the current controller, the +PostsController+, and will send a +POST+ request to that route. For this to work, you will need to add a route to +config/routes.rb+, right underneath the one for "posts/new": +In this example, a `Hash` object is passed to the `:url` option. What Rails will do with this is that it will point the form to the `create` action of the current controller, the `PostsController`, and will send a `POST` request to that route. For this to work, you will need to add a route to `config/routes.rb`, right underneath the one for "posts/new": ```ruby post "posts" => "posts#create" ``` -By using the +post+ method rather than the +get+ method, Rails will define a route that will only respond to POST methods. The POST method is the typical method used by forms all over the web. +By using the `post` method rather than the `get` method, Rails will define a route that will only respond to POST methods. The POST method is the typical method used by forms all over the web. With the form and its associated route defined, you will be able to fill in the form and then click the submit button to begin the process of creating a new post, so go ahead and do that. When you submit the form, you should see a familiar error: !images/getting_started/unknown_action_create_for_posts.png(Unknown action create for PostsController)! -You now need to create the +create+ action within the +PostsController+ for this to work. +You now need to create the `create` action within the `PostsController` for this to work. ### Creating posts -To make the "Unknown action" go away, you can define a +create+ action within the +PostsController+ class in +app/controllers/posts_controller.rb+, underneath the +new+ action: +To make the "Unknown action" go away, you can define a `create` action within the `PostsController` class in `app/controllers/posts_controller.rb`, underneath the `new` action: ```ruby class PostsController < ApplicationController @@ -405,9 +405,9 @@ class PostsController < ApplicationController end ``` -If you re-submit the form now, you'll see another familiar error: a template is missing. That's ok, we can ignore that for now. What the +create+ action should be doing is saving our new post to a database. +If you re-submit the form now, you'll see another familiar error: a template is missing. That's ok, we can ignore that for now. What the `create` action should be doing is saving our new post to a database. -When a form is submitted, the fields of the form are sent to Rails as _parameters_. These parameters can then be referenced inside the controller actions, typically to perform a particular task. To see what these parameters look like, change the +create+ action to this: +When a form is submitted, the fields of the form are sent to Rails as _parameters_. These parameters can then be referenced inside the controller actions, typically to perform a particular task. To see what these parameters look like, change the `create` action to this: ```ruby def create @@ -415,7 +415,7 @@ def create end ``` -The +render+ method here is taking a very simple hash with a key of +text+ and value of +params[:post].inspect+. The +params+ method is the object which represents the parameters (or fields) coming in from the form. The +params+ method returns a +HashWithIndifferentAccess+ object, which allows you to access the keys of the hash using either strings or symbols. In this situation, the only parameters that matter are the ones from the form. +The `render` method here is taking a very simple hash with a key of `text` and value of `params[:post].inspect`. The `params` method is the object which represents the parameters (or fields) coming in from the form. The `params` method returns a `HashWithIndifferentAccess` object, which allows you to access the keys of the hash using either strings or symbols. In this situation, the only parameters that matter are the ones from the form. If you re-submit the form one more time you'll now no longer get the missing template error. Instead, you'll see something that looks like the following: @@ -436,14 +436,14 @@ To create the new model, run this command in your terminal: $ rails generate model Post title:string text:text ``` -With that command we told Rails that we want a +Post+ model, together +With that command we told Rails that we want a `Post` model, together with a _title_ attribute of type string, and a _text_ attribute -of type text. Those attributes are automatically added to the +posts+ -table in the database and mapped to the +Post+ model. +of type text. Those attributes are automatically added to the `posts` +table in the database and mapped to the `Post` model. Rails responded by creating a bunch of files. For -now, we're only interested in +app/models/post.rb+ and -+db/migrate/20120419084633_create_posts.rb+ (your name could be a bit +now, we're only interested in `app/models/post.rb` and +`db/migrate/20120419084633_create_posts.rb` (your name could be a bit different). The latter is responsible for creating the database structure, which is what we'll look at next. @@ -454,15 +454,15 @@ Record. ### Running a Migration -As we've just seen, +rails generate model+ created a _database -migration_ file inside the +db/migrate+ directory. +As we've just seen, `rails generate model` created a _database +migration_ file inside the `db/migrate` directory. Migrations are Ruby classes that are designed to make it simple to create and modify database tables. Rails uses rake commands to run migrations, and it's possible to undo a migration after it's been applied to your database. Migration filenames include a timestamp to ensure that they're processed in the order that they were created. -If you look in the +db/migrate/20120419084633_create_posts.rb+ file (remember, +If you look in the `db/migrate/20120419084633_create_posts.rb` file (remember, yours will have a slightly different name), here's what you'll find: ```ruby @@ -478,11 +478,11 @@ class CreatePosts < ActiveRecord::Migration end ``` -The above migration creates a method named +change+ which will be called when you +The above migration creates a method named `change` which will be called when you run this migration. The action defined in this method is also reversible, which means Rails knows how to reverse the change made by this migration, in case you want to reverse it later. When you run this migration it will create a -+posts+ table with one string column and a text column. It also creates two +`posts` table with one string column and a text column. It also creates two timestamp fields to allow Rails to track post creation and update times. More information about Rails migrations can be found in the "Rails Database Migrations":migrations.html guide. @@ -504,16 +504,16 @@ table. ``` NOTE. Because you're working in the development environment by default, this -command will apply to the database defined in the +development+ section of your -+config/database.yml+ file. If you would like to execute migrations in another +command will apply to the database defined in the `development` section of your +`config/database.yml` file. If you would like to execute migrations in another environment, for instance in production, you must explicitly pass it when -invoking the command: +rake db:migrate RAILS_ENV=production+. +invoking the command: `rake db:migrate RAILS_ENV=production`. ### Saving data in the controller -Back in +posts_controller+, we need to change the +create+ action -to use the new +Post+ model to save the data in the database. Open that file -and change the +create+ action to look like this: +Back in `posts_controller`, we need to change the `create` action +to use the new `Post` model to save the data in the database. Open that file +and change the `create` action to look like this: ```ruby def create @@ -527,31 +527,31 @@ end Here's what's going on: every Rails model can be initialized with its respective attributes, which are automatically mapped to the respective database columns. In the first line we do just that (remember that -+params[:post]+ contains the attributes we're interested in). Then, -+@post.save+ is responsible for saving the model in the database. -Finally, we redirect the user to the +show+ action, +`params[:post]` contains the attributes we're interested in). Then, +`@post.save` is responsible for saving the model in the database. +Finally, we redirect the user to the `show` action, which we'll define later. -TIP: As we'll see later, +@post.save+ returns a boolean indicating +TIP: As we'll see later, `@post.save` returns a boolean indicating wherever the model was saved or not. ### Showing Posts If you submit the form again now, Rails will complain about not finding -the +show+ action. That's not very useful though, so let's add the -+show+ action before proceeding. Open +config/routes.rb+ and add the following route: +the `show` action. That's not very useful though, so let's add the +`show` action before proceeding. Open `config/routes.rb` and add the following route: ```ruby get "posts/:id" => "posts#show" ``` -The special syntax +:id+ tells rails that this route expects an +:id+ +The special syntax `:id` tells rails that this route expects an `:id` parameter, which in our case will be the id of the post. Note that this -time we had to specify the actual mapping, +posts#show+ because +time we had to specify the actual mapping, `posts#show` because otherwise Rails would not know which action to render. -As we did before, we need to add the +show+ action in the -+posts_controller+ and its respective view. +As we did before, we need to add the `show` action in the +`posts_controller` and its respective view. ```ruby def show @@ -559,12 +559,12 @@ def show end ``` -A couple of things to note. We use +Post.find+ to find the post we're -interested in. We also use an instance variable (prefixed by +@+) to +A couple of things to note. We use `Post.find` to find the post we're +interested in. We also use an instance variable (prefixed by `@`) to hold a reference to the post object. We do this because Rails will pass all instance variables to the view. -Now, create a new file +app/view/posts/show.html.erb+ with the following +Now, create a new file `app/view/posts/show.html.erb` with the following content: ```erb @@ -588,13 +588,13 @@ be able to create a post. Try it! ### Listing all posts We still need a way to list all our posts, so let's do that. As usual, -we'll need a route placed into +config/routes.rb+: +we'll need a route placed into `config/routes.rb`: ```ruby get "posts" => "posts#index" ``` -And an action for that route inside the +PostsController+ in the +app/controllers/posts_controller.rb+ file: +And an action for that route inside the `PostsController` in the `app/controllers/posts_controller.rb` file: ```ruby def index @@ -602,7 +602,7 @@ def index end ``` -And then finally a view for this action, located at +app/views/posts/index.html.erb+: +And then finally a view for this action, located at `app/views/posts/index.html.erb`: ```erb <h1>Listing posts</h1> @@ -622,31 +622,31 @@ And then finally a view for this action, located at +app/views/posts/index.html. </table> ``` -Now if you go to +http://localhost:3000/posts+ you will see a list of all the posts that you have created. +Now if you go to `http://localhost:3000/posts` you will see a list of all the posts that you have created. ### Adding links You can now create, show, and list posts. Now let's add some links to navigate through pages. -Open +app/views/welcome/index.html.erb+ and modify it as follows: +Open `app/views/welcome/index.html.erb` and modify it as follows: ```ruby <h1>Hello, Rails!</h1> <%= link_to "My Blog", :controller => "posts" %> ``` -The +link_to+ method is one of Rails' built-in view helpers. It creates a +The `link_to` method is one of Rails' built-in view helpers. It creates a hyperlink based on text to display and where to go - in this case, to the path for posts. -Let's add links to the other views as well, starting with adding this "New Post" link to +app/views/posts/index.html.erb+, placing it above the +<table>+ tag: +Let's add links to the other views as well, starting with adding this "New Post" link to `app/views/posts/index.html.erb`, placing it above the `<table>` tag: ```erb <%= link_to 'New post', :action => :new %> ``` -This link will allow you to bring up the form that lets you create a new post. You should also add a link to this template -- +app/views/posts/new.html.erb+ -- to go back to the +index+ action. Do this by adding this underneath the form in this template: +This link will allow you to bring up the form that lets you create a new post. You should also add a link to this template -- `app/views/posts/new.html.erb` -- to go back to the `index` action. Do this by adding this underneath the form in this template: ```erb <%= form_for :post do |f| %> @@ -656,7 +656,7 @@ This link will allow you to bring up the form that lets you create a new post. Y <%= link_to 'Back', :action => :index %> ``` -Finally, add another link to the +app/views/posts/show.html.erb+ template to go back to the +index+ action as well, so that people who are viewing a single post can go back and view the whole list again: +Finally, add another link to the `app/views/posts/show.html.erb` template to go back to the `index` action as well, so that people who are viewing a single post can go back and view the whole list again: ```erb <p> @@ -673,7 +673,7 @@ Finally, add another link to the +app/views/posts/show.html.erb+ template to go ``` TIP: If you want to link to an action in the same controller, you don't -need to specify the +:controller+ option, as Rails will use the current +need to specify the `:controller` option, as Rails will use the current controller by default. TIP: In development mode (which is what you're working in by default), Rails @@ -682,21 +682,21 @@ and restart the web server when a change is made. ### Allowing the update of fields -The model file, +app/models/post.rb+ is about as simple as it can get: +The model file, `app/models/post.rb` is about as simple as it can get: ```ruby class Post < ActiveRecord::Base end ``` -There isn't much to this file - but note that the +Post+ class inherits from -+ActiveRecord::Base+. Active Record supplies a great deal of functionality to +There isn't much to this file - but note that the `Post` class inherits from +`ActiveRecord::Base`. Active Record supplies a great deal of functionality to your Rails models for free, including basic database CRUD (Create, Read, Update, Destroy) operations, data validation, as well as sophisticated search support and the ability to relate multiple models to one another. Rails includes methods to help you secure some of your model fields. -Open the +app/models/post.rb+ file and edit it: +Open the `app/models/post.rb` file and edit it: ```ruby class Post < ActiveRecord::Base @@ -711,7 +711,7 @@ Accessible attributes and the mass assignment problem is covered in details in t ### Adding Some Validation Rails includes methods to help you validate the data that you send to models. -Open the +app/models/post.rb+ file and edit it: +Open the `app/models/post.rb` file and edit it: ```ruby class Post < ActiveRecord::Base @@ -728,12 +728,12 @@ format, and the existence of associated objects. Validations are covered in deta in "Active Record Validations and Callbacks":active_record_validations_callbacks.html#validations-overview -With the validation now in place, when you call +@post.save+ on an invalid -post, it will return +false+. If you open +app/controllers/posts_controller.rb+ -again, you'll notice that we don't check the result of calling +@post.save+ -inside the +create+ action. If +@post.save+ fails in this situation, we need to -show the form back to the user. To do this, change the +new+ and +create+ -actions inside +app/controllers/posts_controller.rb+ to these: +With the validation now in place, when you call `@post.save` on an invalid +post, it will return `false`. If you open `app/controllers/posts_controller.rb` +again, you'll notice that we don't check the result of calling `@post.save` +inside the `create` action. If `@post.save` fails in this situation, we need to +show the form back to the user. To do this, change the `new` and `create` +actions inside `app/controllers/posts_controller.rb` to these: ```ruby def new @@ -751,18 +751,18 @@ def create end ``` -The +new+ action is now creating a new instance variable called +@post+, and +The `new` action is now creating a new instance variable called `@post`, and you'll see why that is in just a few moments. -Notice that inside the +create+ action we use +render+ instead of +redirect_to+ when +save+ -returns +false+. The +render+ method is used so that the +@post+ object is passed back to the +new+ template when it is rendered. This rendering is done within the same request as the form submission, whereas the +redirect_to+ will tell the browser to issue another request. +Notice that inside the `create` action we use `render` instead of `redirect_to` when `save` +returns `false`. The `render` method is used so that the `@post` object is passed back to the `new` template when it is rendered. This rendering is done within the same request as the form submission, whereas the `redirect_to` will tell the browser to issue another request. If you reload "http://localhost:3000/posts/new":http://localhost:3000/posts/new and try to save a post without a title, Rails will send you back to the form, but that's not very useful. You need to tell the user that something went wrong. To do that, you'll modify -+app/views/posts/new.html.erb+ to check for error messages: +`app/views/posts/new.html.erb` to check for error messages: ```erb <%= form_for :post, :url => { :action => :create } do |f| %> @@ -796,18 +796,18 @@ something went wrong. To do that, you'll modify ``` A few things are going on. We check if there are any errors with -+@post.errors.any?+, and in that case we show a list of all -errors with +@post.errors.full_messages+. +`@post.errors.any?`, and in that case we show a list of all +errors with `@post.errors.full_messages`. -+pluralize+ is a rails helper that takes a number and a string as its +`pluralize` is a rails helper that takes a number and a string as its arguments. If the number is greater than one, the string will be automatically pluralized. -The reason why we added +@post = Post.new+ in +posts_controller+ is that -otherwise +@post+ would be +nil+ in our view, and calling -+@post.errors.any?+ would throw an error. +The reason why we added `@post = Post.new` in `posts_controller` is that +otherwise `@post` would be `nil` in our view, and calling +`@post.errors.any?` would throw an error. TIP: Rails automatically wraps fields that contain an error with a div -with class +field_with_errors+. You can define a css rule to make them +with class `field_with_errors`. You can define a css rule to make them standout. Now you'll get a nice error message when saving a post without title when you @@ -820,10 +820,10 @@ attempt to do just that on the "new post form(http://localhost:3000/posts/new)": We've covered the "CR" part of CRUD. Now let's focus on the "U" part, updating posts. -The first step we'll take is adding a +edit+ action to -+posts_controller+. +The first step we'll take is adding a `edit` action to +`posts_controller`. -Start by adding a route to +config/routes.rb+: +Start by adding a route to `config/routes.rb`: ```ruby get "posts/:id/edit" => "posts#edit" @@ -838,7 +838,7 @@ end ``` The view will contain a form similar to the one we used when creating -new posts. Create a file called +app/views/posts/edit.html.erb+ and make +new posts. Create a file called `app/views/posts/edit.html.erb` and make it look as follows: ```erb @@ -875,23 +875,23 @@ it look as follows: <%= link_to 'Back', :action => :index %> ``` -This time we point the form to the +update+ action, which is not defined yet +This time we point the form to the `update` action, which is not defined yet but will be very soon. -The +:method => :put+ option tells Rails that we want this form to be -submitted via the +PUT+, HTTP method which is the HTTP method you're expected to use to +The `:method => :put` option tells Rails that we want this form to be +submitted via the `PUT`, HTTP method which is the HTTP method you're expected to use to *update* resources according to the REST protocol. -TIP: By default forms built with the +form_for_ helper are sent via +POST+. +TIP: By default forms built with the +form_for_ helper are sent via `POST`. -Next, we need to add the +update+ action. The file -+config/routes.rb+ will need just one more line: +Next, we need to add the `update` action. The file +`config/routes.rb` will need just one more line: ```ruby put "posts/:id" => "posts#update" ``` -And then create the +update+ action in +app/controllers/posts_controller.rb+: +And then create the `update` action in `app/controllers/posts_controller.rb`: ```ruby def update @@ -905,18 +905,18 @@ def update end ``` -The new method, +update_attributes+, is used when you want to update a record +The new method, `update_attributes`, is used when you want to update a record that already exists, and it accepts a hash containing the attributes that you want to update. As before, if there was an error updating the post we want to show the form back to the user. -TIP: you don't need to pass all attributes to +update_attributes+. For -example, if you'd call +@post.update_attributes(:title => 'A new title')+ -Rails would only update the +title+ attribute, leaving all other +TIP: you don't need to pass all attributes to `update_attributes`. For +example, if you'd call `@post.update_attributes(:title => 'A new title')` +Rails would only update the `title` attribute, leaving all other attributes untouched. -Finally, we want to show a link to the +edit+ action in the list of all the -posts, so let's add that now to +app/views/posts/index.html.erb+ to make it +Finally, we want to show a link to the `edit` action in the list of all the +posts, so let's add that now to `app/views/posts/index.html.erb` to make it appear next to the "Show" link: ```erb @@ -940,7 +940,7 @@ appear next to the "Show" link: </table> ``` -And we'll also add one to the +app/views/posts/show.html.erb+ template as well, +And we'll also add one to the `app/views/posts/show.html.erb` template as well, so that there's also an "Edit" link on a post's page. Add this at the bottom of the template: @@ -959,7 +959,7 @@ with edit link)! ### Using partials to clean up duplication in views -+partials+ are what Rails uses to remove duplication in views. Here's a +`partials` are what Rails uses to remove duplication in views. Here's a simple example: ```erb @@ -976,19 +976,19 @@ simple example: <%= @user.about_me %> ``` -The +users/show+ template will automatically include the content of the -+users/_user_details+ template. Note that partials are prefixed by an underscore, +The `users/show` template will automatically include the content of the +`users/_user_details` template. Note that partials are prefixed by an underscore, as to not be confused with regular views. However, you don't include the -underscore when including them with the +helper+ method. +underscore when including them with the `helper` method. TIP: You can read more about partials in the "Layouts and Rendering in Rails":layouts_and_rendering.html guide. -Our +edit+ action looks very similar to the +new+ action, in fact they +Our `edit` action looks very similar to the `new` action, in fact they both share the same code for displaying the form. Lets clean them up by using a partial. -Create a new file +app/views/posts/_form.html.erb+ with the following +Create a new file `app/views/posts/_form.html.erb` with the following content: ```erb @@ -1020,10 +1020,10 @@ content: <% end %> ``` -Everything except for the +form_for+ declaration remained the same. -How +form_for+ can figure out the right +action+ and +method+ attributes +Everything except for the `form_for` declaration remained the same. +How `form_for` can figure out the right `action` and `method` attributes when building the form will be explained in just a moment. For now, let's update the -+app/views/posts/new.html.erb+ view to use this new partial, rewriting it +`app/views/posts/new.html.erb` view to use this new partial, rewriting it completely: ```erb @@ -1034,7 +1034,7 @@ completely: <%= link_to 'Back', :action => :index %> ``` -Then do the same for the +app/views/posts/edit.html.erb+ view: +Then do the same for the `app/views/posts/edit.html.erb` view: ```erb <h1>Edit post</h1> @@ -1051,20 +1051,20 @@ post and you'll receive the following error: !images/getting_started/undefined_method_post_path.png(Undefined method post_path)! -To understand this error, you need to understand how +form_for+ works. -When you pass an object to +form_for+ and you don't specify a +:url+ -option, Rails will try to guess the +action+ and +method+ options by +To understand this error, you need to understand how `form_for` works. +When you pass an object to `form_for` and you don't specify a `:url` +option, Rails will try to guess the `action` and `method` options by checking if the passed object is a new record or not. Rails follows the -REST convention, so to create a new +Post+ object it will look for a -route named +posts_path+, and to update a +Post+ object it will look for -a route named +post_path+ and pass the current object. Similarly, rails +REST convention, so to create a new `Post` object it will look for a +route named `posts_path`, and to update a `Post` object it will look for +a route named `post_path` and pass the current object. Similarly, rails knows that it should create new objects via POST and update them via PUT. -If you run +rake routes+ from the console you'll see that we already -have a +posts_path+ route, which was created automatically by Rails when we +If you run `rake routes` from the console you'll see that we already +have a `posts_path` route, which was created automatically by Rails when we defined the route for the index action. -However, we don't have a +post_path+ yet, which is the reason why we +However, we don't have a `post_path` yet, which is the reason why we received an error before. ```bash @@ -1079,41 +1079,41 @@ posts_new GET /posts/new(.:format) posts#new root / welcome#index ``` -To fix this, open +config/routes.rb+ and modify the +get "posts/:id"+ +To fix this, open `config/routes.rb` and modify the `get "posts/:id"` line like this: ```ruby get "posts/:id" => "posts#show", :as => :post ``` -The +:as+ option tells the +get+ method that we want to make routing helpers -called +post_url+ and +post_path+ available to our application. These are -precisely the methods that the +form_for+ needs when editing a post, and so now +The `:as` option tells the `get` method that we want to make routing helpers +called `post_url` and `post_path` available to our application. These are +precisely the methods that the `form_for` needs when editing a post, and so now you'll be able to update posts again. -NOTE: The +:as+ option is available on the +post+, +put+, +delete+ and +match+ +NOTE: The `:as` option is available on the `post`, `put`, `delete` and `match` routing methods also. ### Deleting Posts We're now ready to cover the "D" part of CRUD, deleting posts from the database. Following the REST convention, we're going to add a route for -deleting posts to +config/routes.rb+: +deleting posts to `config/routes.rb`: ```ruby delete "posts/:id" => "posts#destroy" ``` -The +delete+ routing method should be used for routes that destroy -resources. If this was left as a typical +get+ route, it could be possible for +The `delete` routing method should be used for routes that destroy +resources. If this was left as a typical `get` route, it could be possible for people to craft malicious URLs like this: ```html <a href='http://yoursite.com/posts/1/destroy'>look at this cat!</a> ``` -We use the +delete+ method for destroying resources, and this route is mapped to -the +destroy+ action inside +app/controllers/posts_controller.rb+, which doesn't exist yet, but is +We use the `delete` method for destroying resources, and this route is mapped to +the `destroy` action inside `app/controllers/posts_controller.rb`, which doesn't exist yet, but is provided below: ```ruby @@ -1125,11 +1125,11 @@ def destroy end ``` -You can call +destroy+ on Active Record objects when you want to delete +You can call `destroy` on Active Record objects when you want to delete them from the database. Note that we don't need to add a view for this -action since we're redirecting to the +index+ action. +action since we're redirecting to the `index` action. -Finally, add a 'destroy' link to your +index+ action template +Finally, add a 'destroy' link to your `index` action template (+app/views/posts/index.html.erb) to wrap everything together. @@ -1156,13 +1156,13 @@ together. </table> ``` -Here we're using +link_to+ in a different way. We wrap the -+:action+ and +:id+ attributes in a hash so that we can pass those two keys in -first as one argument, and then the final two keys as another argument. The +:method+ and +:'data-confirm'+ +Here we're using `link_to` in a different way. We wrap the +`:action` and `:id` attributes in a hash so that we can pass those two keys in +first as one argument, and then the final two keys as another argument. The `:method` and `:'data-confirm'` options are used as HTML5 attributes so that when the link is clicked, -Rails will first show a confirm dialog to the user, and then submit the link with method +delete+. -This is done via the JavaScript file +jquery_ujs+ which is automatically included -into your application's layout (+app/views/layouts/application.html.erb+) when you +Rails will first show a confirm dialog to the user, and then submit the link with method `delete`. +This is done via the JavaScript file `jquery_ujs` which is automatically included +into your application's layout (`app/views/layouts/application.html.erb`) when you generated the application. Without this file, the confirmation dialog box wouldn't appear. !images/getting_started/confirm_dialog.png(Confirm Dialog)! @@ -1176,7 +1176,7 @@ advantage of it. We've now covered all the CRUD actions of a REST app. We did so by declaring separate routes with the appropriate verbs into -+config/routes.rb+. Here's how that file looks so far: +`config/routes.rb`. Here's how that file looks so far: ```ruby get "posts" => "posts#index" @@ -1189,8 +1189,8 @@ delete "posts/:id" => "posts#destroy" ``` That's a lot to type for covering a single *resource*. Fortunately, -Rails provides a +resources+ method which can be used to declare a -standard REST resource. Here's how +config/routes.rb+ looks after the +Rails provides a `resources` method which can be used to declare a +standard REST resource. Here's how `config/routes.rb` looks after the cleanup: ```ruby @@ -1202,7 +1202,7 @@ Blog::Application.routes.draw do end ``` -If you run +rake routes+, you'll see that all the routes that we +If you run `rake routes`, you'll see that all the routes that we declared before are still available: ```bash @@ -1234,7 +1234,7 @@ posts. ### Generating a Model We're going to see the same generator that we used before when creating -the +Post+ model. This time we'll create a +Comment+ model to hold +the `Post` model. This time we'll create a `Comment` model to hold reference of post comments. Run this command in your terminal: ```bash @@ -1249,7 +1249,7 @@ This command will generate four files: | test/unit/comment_test.rb | Unit testing harness for the comments model | | test/fixtures/comments.yml | Sample comments for use in testing | -First, take a look at +comment.rb+: +First, take a look at `comment.rb`: ```ruby class Comment < ActiveRecord::Base @@ -1258,8 +1258,8 @@ class Comment < ActiveRecord::Base end ``` -This is very similar to the +post.rb+ model that you saw earlier. The difference -is the line +belongs_to :post+, which sets up an Active Record _association_. +This is very similar to the `post.rb` model that you saw earlier. The difference +is the line `belongs_to :post`, which sets up an Active Record _association_. You'll learn a little about associations in the next section of this guide. In addition to the model, Rails has also made a migration to create the @@ -1281,8 +1281,8 @@ class CreateComments < ActiveRecord::Migration end ``` -The +t.references+ line sets up a foreign key column for the association between -the two models. And the +add_index+ line sets up an index for this association +The `t.references` line sets up a foreign key column for the association between +the two models. And the `add_index` line sets up an index for this association column. Go ahead and run the migration: ```bash @@ -1320,7 +1320,7 @@ class Comment < ActiveRecord::Base end ``` -You'll need to edit the +post.rb+ file to add the other side of the association: +You'll need to edit the `post.rb` file to add the other side of the association: ```ruby class Post < ActiveRecord::Base @@ -1332,17 +1332,17 @@ end ``` These two declarations enable a good bit of automatic behavior. For example, if -you have an instance variable +@post+ containing a post, you can retrieve all -the comments belonging to that post as an array using +@post.comments+. +you have an instance variable `@post` containing a post, you can retrieve all +the comments belonging to that post as an array using `@post.comments`. TIP: For more information on Active Record associations, see the "Active Record Associations":association_basics.html guide. ### Adding a Route for Comments -As with the +welcome+ controller, we will need to add a route so that Rails knows -where we would like to navigate to see +comments+. Open up the -+config/routes.rb+ file again, and edit it as follows: +As with the `welcome` controller, we will need to add a route so that Rails knows +where we would like to navigate to see `comments`. Open up the +`config/routes.rb` file again, and edit it as follows: ```ruby resources :posts do @@ -1350,7 +1350,7 @@ resources :posts do end ``` -This creates +comments+ as a _nested resource_ within +posts+. This is another +This creates `comments` as a _nested resource_ within `posts`. This is another part of capturing the hierarchical relationship that exists between posts and comments. @@ -1380,11 +1380,11 @@ This creates six files and one empty directory: Like with any blog, our readers will create their comments directly after reading the post, and once they have added their comment, will be sent back to the post show page to see their comment now listed. Due to this, our -+CommentsController+ is there to provide a method to create comments and delete +`CommentsController` is there to provide a method to create comments and delete spam comments when they arrive. So first, we'll wire up the Post show template -(+/app/views/posts/show.html.erb+) to let us make a new comment: +(`/app/views/posts/show.html.erb`) to let us make a new comment: ```erb <p> @@ -1416,11 +1416,11 @@ So first, we'll wire up the Post show template <%= link_to 'Back to Posts', posts_path %> ``` -This adds a form on the +Post+ show page that creates a new comment by -calling the +CommentsController+ +create+ action. The +form_for+ call here uses -an array, which will build a nested route, such as +/posts/1/comments+. +This adds a form on the `Post` show page that creates a new comment by +calling the `CommentsController` `create` action. The `form_for` call here uses +an array, which will build a nested route, such as `/posts/1/comments`. -Let's wire up the +create+: +Let's wire up the `create`: ```ruby class CommentsController < ApplicationController @@ -1435,18 +1435,18 @@ end You'll see a bit more complexity here than you did in the controller for posts. That's a side-effect of the nesting that you've set up. Each request for a comment has to keep track of the post to which the comment is attached, thus the -initial call to the +find+ method of the +Post+ model to get the post in question. +initial call to the `find` method of the `Post` model to get the post in question. In addition, the code takes advantage of some of the methods available for an -association. We use the +create+ method on +@post.comments+ to create and save +association. We use the `create` method on `@post.comments` to create and save the comment. This will automatically link the comment so that it belongs to that particular post. Once we have made the new comment, we send the user back to the original post -using the +post_path(@post)+ helper. As we have already seen, this calls the -+show+ action of the +PostsController+ which in turn renders the +show.html.erb+ +using the `post_path(@post)` helper. As we have already seen, this calls the +`show` action of the `PostsController` which in turn renders the `show.html.erb` template. This is where we want the comment to show, so let's add that to the -+app/views/posts/show.html.erb+. +`app/views/posts/show.html.erb`. ```erb <p> @@ -1500,13 +1500,13 @@ Refactoring ----------- Now that we have posts and comments working, take a look at the -+app/views/posts/show.html.erb+ template. It is getting long and awkward. We can +`app/views/posts/show.html.erb` template. It is getting long and awkward. We can use partials to clean it up. ### Rendering Partial Collections First, we will make a comment partial to extract showing all the comments for the -post. Create the file +app/views/comments/_comment.html.erb+ and put the +post. Create the file `app/views/comments/_comment.html.erb` and put the following into it: ```erb @@ -1521,7 +1521,7 @@ following into it: </p> ``` -Then you can change +app/views/posts/show.html.erb+ to look like the +Then you can change `app/views/posts/show.html.erb` to look like the following: ```erb @@ -1557,16 +1557,16 @@ following: <%= link_to 'Back to Posts', posts_path %> ``` -This will now render the partial in +app/views/comments/_comment.html.erb+ once -for each comment that is in the +@post.comments+ collection. As the +render+ +This will now render the partial in `app/views/comments/_comment.html.erb` once +for each comment that is in the `@post.comments` collection. As the `render` method iterates over the `@post.comments` collection, it assigns each comment to a local variable named the same as the partial, in this case -+comment+ which is then available in the partial for us to show. +`comment` which is then available in the partial for us to show. ### Rendering a Partial Form Let us also move that new comment section out to its own partial. Again, you -create a file +app/views/comments/_form.html.erb+ containing: +create a file `app/views/comments/_form.html.erb` containing: ```erb <%= form_for([@post, @post.comments.build]) do |f| %> @@ -1584,7 +1584,7 @@ create a file +app/views/comments/_form.html.erb+ containing: <% end %> ``` -Then you make the +app/views/posts/show.html.erb+ look like the following: +Then you make the `app/views/posts/show.html.erb` look like the following: ```erb <p> @@ -1609,18 +1609,18 @@ The second render just defines the partial template we want to render, string and realize that you want to render the `_form.html.erb` file in the `app/views/comments` directory. -The +@post+ object is available to any partials rendered in the view because we +The `@post` object is available to any partials rendered in the view because we defined it as an instance variable. Deleting Comments ----------------- Another important feature of a blog is being able to delete spam comments. To do -this, we need to implement a link of some sort in the view and a +DELETE+ action -in the +CommentsController+. +this, we need to implement a link of some sort in the view and a `DELETE` action +in the `CommentsController`. So first, let's add the delete link in the -+app/views/comments/_comment.html.erb+ partial: +`app/views/comments/_comment.html.erb` partial: ```erb <p> @@ -1641,7 +1641,7 @@ So first, let's add the delete link in the ``` Clicking this new "Destroy Comment" link will fire off a `DELETE -/posts/:id/comments/:id` to our +CommentsController+, which can then use +/posts/:id/comments/:id` to our `CommentsController`, which can then use this to find the comment we want to delete, so let's add a destroy action to our controller: @@ -1664,7 +1664,7 @@ class CommentsController < ApplicationController end ``` -The +destroy+ action will find the post we are looking at, locate the comment +The `destroy` action will find the post we are looking at, locate the comment within the `@post.comments` collection, and then remove it from the database and send us back to the show action for the post. @@ -1673,8 +1673,8 @@ database and send us back to the show action for the post. If you delete a post then its associated comments will also need to be deleted. Otherwise they would simply occupy space in the database. Rails allows you to -use the +dependent+ option of an association to achieve this. Modify the Post -model, +app/models/post.rb+, as follows: +use the `dependent` option of an association to achieve this. Modify the Post +model, `app/models/post.rb`, as follows: ```ruby class Post < ActiveRecord::Base @@ -1693,14 +1693,14 @@ delete posts or delete comments. Rails provides a very simple HTTP authentication system that will work nicely in this situation. -In the +PostsController+ we need to have a way to block access to the various +In the `PostsController` we need to have a way to block access to the various actions if the person is not authenticated, here we can use the Rails `http_basic_authenticate_with` method, allowing access to the requested action if that method allows it. To use the authentication system, we specify it at the top of our -+PostsController+, in this case, we want the user to be authenticated on every -action, except for +index+ and +show+, so we write that: +`PostsController`, in this case, we want the user to be authenticated on every +action, except for `index` and `show`, so we write that: ```ruby class PostsController < ApplicationController @@ -1713,7 +1713,7 @@ class PostsController < ApplicationController ``` We also only want to allow authenticated users to delete comments, so in the -+CommentsController+ we write: +`CommentsController` we write: ```ruby class CommentsController < ApplicationController @@ -1745,8 +1745,8 @@ free to consult these support resources: Rails also comes with built-in help that you can generate using the rake command-line utility: -* Running +rake doc:guides+ will put a full copy of the Rails Guides in the +doc/guides+ folder of your application. Open +doc/guides/index.html+ in your web browser to explore the Guides. -* Running +rake doc:rails+ will put a full copy of the API documentation for Rails in the +doc/api+ folder of your application. Open +doc/api/index.html+ in your web browser to explore the API documentation. +* Running `rake doc:guides` will put a full copy of the Rails Guides in the `doc/guides` folder of your application. Open `doc/guides/index.html` in your web browser to explore the Guides. +* Running `rake doc:rails` will put a full copy of the API documentation for Rails in the `doc/api` folder of your application. Open `doc/api/index.html` in your web browser to explore the API documentation. Configuration Gotchas --------------------- diff --git a/guides/source/i18n.md b/guides/source/i18n.md index 577efe54a1..ed604c2266 100644 --- a/guides/source/i18n.md +++ b/guides/source/i18n.md @@ -81,26 +81,26 @@ There are just a few simple steps to get up and running with I18n support for yo Following the _convention over configuration_ philosophy, Rails will set up your application with reasonable defaults. If you need different settings, you can overwrite them easily. -Rails adds all +.rb+ and +.yml+ files from the +config/locales+ directory to your *translations load path*, automatically. +Rails adds all `.rb` and `.yml` files from the `config/locales` directory to your *translations load path*, automatically. -The default +en.yml+ locale in this directory contains a sample pair of translation strings: +The default `en.yml` locale in this directory contains a sample pair of translation strings: ```ruby en: hello: "Hello world" ``` -This means, that in the +:en+ locale, the key _hello_ will map to the _Hello world_ string. Every string inside Rails is internationalized in this way, see for instance Active Record validation messages in the "+activerecord/lib/active_record/locale/en.yml+":https://github.com/rails/rails/blob/master/activerecord/lib/active_record/locale/en.yml file or time and date formats in the "+activesupport/lib/active_support/locale/en.yml+":https://github.com/rails/rails/blob/master/activesupport/lib/active_support/locale/en.yml file. You can use YAML or standard Ruby Hashes to store translations in the default (Simple) backend. +This means, that in the `:en` locale, the key _hello_ will map to the _Hello world_ string. Every string inside Rails is internationalized in this way, see for instance Active Record validation messages in the "`activerecord/lib/active_record/locale/en.yml`":https://github.com/rails/rails/blob/master/activerecord/lib/active_record/locale/en.yml file or time and date formats in the "`activesupport/lib/active_support/locale/en.yml`":https://github.com/rails/rails/blob/master/activesupport/lib/active_support/locale/en.yml file. You can use YAML or standard Ruby Hashes to store translations in the default (Simple) backend. -The I18n library will use *English* as a *default locale*, i.e. if you don't set a different locale, +:en+ will be used for looking up translations. +The I18n library will use *English* as a *default locale*, i.e. if you don't set a different locale, `:en` will be used for looking up translations. -NOTE: The i18n library takes a *pragmatic approach* to locale keys (after "some discussion":http://groups.google.com/group/rails-i18n/browse_thread/thread/14dede2c7dbe9470/80eec34395f64f3c?hl=en), including only the _locale_ ("language") part, like +:en+, +:pl+, not the _region_ part, like +:en-US+ or +:en-GB+, which are traditionally used for separating "languages" and "regional setting" or "dialects". Many international applications use only the "language" element of a locale such as +:cs+, +:th+ or +:es+ (for Czech, Thai and Spanish). However, there are also regional differences within different language groups that may be important. For instance, in the +:en-US+ locale you would have $ as a currency symbol, while in +:en-GB+, you would have £. Nothing stops you from separating regional and other settings in this way: you just have to provide full "English - United Kingdom" locale in a +:en-GB+ dictionary. Various "Rails I18n plugins":http://rails-i18n.org/wiki such as "Globalize2":https://github.com/joshmh/globalize2/tree/master may help you implement it. +NOTE: The i18n library takes a *pragmatic approach* to locale keys (after "some discussion":http://groups.google.com/group/rails-i18n/browse_thread/thread/14dede2c7dbe9470/80eec34395f64f3c?hl=en), including only the _locale_ ("language") part, like `:en`, `:pl`, not the _region_ part, like `:en-US` or `:en-GB`, which are traditionally used for separating "languages" and "regional setting" or "dialects". Many international applications use only the "language" element of a locale such as `:cs`, `:th` or `:es` (for Czech, Thai and Spanish). However, there are also regional differences within different language groups that may be important. For instance, in the `:en-US` locale you would have $ as a currency symbol, while in `:en-GB`, you would have £. Nothing stops you from separating regional and other settings in this way: you just have to provide full "English - United Kingdom" locale in a `:en-GB` dictionary. Various "Rails I18n plugins":http://rails-i18n.org/wiki such as "Globalize2":ht -The *translations load path* (+I18n.load_path+) is just a Ruby Array of paths to your translation files that will be loaded automatically and available in your application. You can pick whatever directory and translation file naming scheme makes sense for you. +The *translations load path* (`I18n.load_path`) is just a Ruby Array of paths to your translation files that will be loaded automatically and available in your application. You can pick whatever directory and translation file naming scheme makes sense for you. NOTE: The backend will lazy-load these translations when a translation is looked up for the first time. This makes it possible to just swap the backend with something else even after translations have already been announced. -The default +application.rb+ files has instructions on how to add locales from another directory and how to set a different default locale. Just uncomment and edit the specific lines. +The default `application.rb` files has instructions on how to add locales from another directory and how to set a different default locale. Just uncomment and edit the specific lines. ```ruby # The default locale is :en and all translations from config/locales/*.rb,yml are auto loaded. @@ -110,7 +110,7 @@ The default +application.rb+ files has instructions on how to add locales from a ### Optional: Custom I18n Configuration Setup -For the sake of completeness, let's mention that if you do not want to use the +application.rb+ file for some reason, you can always wire up things manually, too. +For the sake of completeness, let's mention that if you do not want to use the `application.rb` file for some reason, you can always wire up things manually, too. To tell the I18n library where it can find your custom translation files you can specify the load path anywhere in your application - just make sure it gets run before any translations are actually looked up. You might also want to change the default locale. The simplest thing possible is to put the following into an initializer: @@ -126,13 +126,13 @@ I18n.default_locale = :pt ### Setting and Passing the Locale -If you want to translate your Rails application to a *single language other than English* (the default locale), you can set I18n.default_locale to your locale in +application.rb+ or an initializer as shown above, and it will persist through the requests. +If you want to translate your Rails application to a *single language other than English* (the default locale), you can set I18n.default_locale to your locale in `application.rb` or an initializer as shown above, and it will persist through the requests. However, you would probably like to *provide support for more locales* in your application. In such case, you need to set and pass the locale between requests. WARNING: You may be tempted to store the chosen locale in a _session_ or a <em>cookie</em>, however *do not do this*. The locale should be transparent and a part of the URL. This way you won't break people's basic assumptions about the web itself: if you send a URL to a friend, they should see the same page and content as you. A fancy word for this would be that you're being "<em>RESTful</em>":http://en.wikipedia.org/wiki/Representational_State_Transfer. Read more about the RESTful approach in "Stefan Tilkov's articles":http://www.infoq.com/articles/rest-introduction. Sometimes there are exceptions to this rule and those are discussed below. -The _setting part_ is easy. You can set the locale in a +before_filter+ in the +ApplicationController+ like this: +The _setting part_ is easy. You can set the locale in a `before_filter` in the `ApplicationController` like this: ```ruby before_filter :set_locale @@ -142,20 +142,20 @@ def set_locale end ``` -This requires you to pass the locale as a URL query parameter as in +http://example.com/books?locale=pt+. (This is, for example, Google's approach.) So +http://localhost:3000?locale=pt+ will load the Portuguese localization, whereas +http://localhost:3000?locale=de+ would load the German localization, and so on. You may skip the next section and head over to the *Internationalize your application* section, if you want to try things out by manually placing the locale in the URL and reloading the page. +This requires you to pass the locale as a URL query parameter as in `http://example.com/books?locale=pt`. (This is, for example, Google's approach.) So `http://localhost:3000?locale=pt` will load the Portuguese localization, whereas `http://localhost:3000?locale=de` would load the German localization, and so on. You may skip the next section and head over to the *Internationalize your application* section, if you want to try things out by manually placing the locale in the URL and reloading the page. -Of course, you probably don't want to manually include the locale in every URL all over your application, or want the URLs look differently, e.g. the usual +http://example.com/pt/books+ versus +http://example.com/en/books+. Let's discuss the different options you have. +Of course, you probably don't want to manually include the locale in every URL all over your application, or want the URLs look differently, e.g. the usual `http://example.com/pt/books` versus `http://example.com/en/books`. Let's discuss the different options you have. ### Setting the Locale from the Domain Name -One option you have is to set the locale from the domain name where your application runs. For example, we want +www.example.com+ to load the English (or default) locale, and +www.example.es+ to load the Spanish locale. Thus the _top-level domain name_ is used for locale setting. This has several advantages: +One option you have is to set the locale from the domain name where your application runs. For example, we want `www.example.com` to load the English (or default) locale, and `www.example.es` to load the Spanish locale. Thus the _top-level domain name_ is used for locale setting. This has several advantages: * The locale is an _obvious_ part of the URL. * People intuitively grasp in which language the content will be displayed. * It is very trivial to implement in Rails. * Search engines seem to like that content in different languages lives at different, inter-linked domains. -You can implement it like this in your +ApplicationController+: +You can implement it like this in your `ApplicationController`: ```ruby before_filter :set_locale @@ -195,21 +195,21 @@ If your application includes a locale switching menu, you would then have someth link_to("Deutsch", "#{APP_CONFIG[:deutsch_website_url]}#{request.env['REQUEST_URI']}") ``` -assuming you would set +APP_CONFIG[:deutsch_website_url]+ to some value like +http://www.application.de+. +assuming you would set `APP_CONFIG[:deutsch_website_url]` to some value like `http://www.application.de`. This solution has aforementioned advantages, however, you may not be able or may not want to provide different localizations ("language versions") on different domains. The most obvious solution would be to include locale code in the URL params (or request path). ### Setting the Locale from the URL Params -The most usual way of setting (and passing) the locale would be to include it in URL params, as we did in the +I18n.locale = params[:locale]+ _before_filter_ in the first example. We would like to have URLs like +www.example.com/books?locale=ja+ or +www.example.com/ja/books+ in this case. +The most usual way of setting (and passing) the locale would be to include it in URL params, as we did in the `I18n.locale = params[:locale]` _before_filter_ in the first example. We would like to have URLs like `www.example.com/books?locale=ja` or `www.example.com/ja/books` in this case. This approach has almost the same set of advantages as setting the locale from the domain name: namely that it's RESTful and in accord with the rest of the World Wide Web. It does require a little bit more work to implement, though. -Getting the locale from +params+ and setting it accordingly is not hard; including it in every URL and thus *passing it through the requests* is. To include an explicit option in every URL (e.g. +link_to( books_url(:locale => I18n.locale))+) would be tedious and probably impossible, of course. +Getting the locale from `params` and setting it accordingly is not hard; including it in every URL and thus *passing it through the requests* is. To include an explicit option in every URL (e.g. `link_to( books_url(:locale => I18n.locale))`) would be tedious and probably impossible, of course. -Rails contains infrastructure for "centralizing dynamic decisions about the URLs" in its "+ApplicationController#default_url_options+":http://api.rubyonrails.org/classes/ActionController/Base.html#M000515, which is useful precisely in this scenario: it enables us to set "defaults" for "+url_for+":http://api.rubyonrails.org/classes/ActionController/Base.html#M000503 and helper methods dependent on it (by implementing/overriding this method). +Rails contains infrastructure for "centralizing dynamic decisions about the URLs" in its "`ApplicationController#default_url_options`":http://api.rubyonrails.org/classes/ActionController/Base.html#M000515, which is useful precisely in this scenario: it enables us to set "defaults" for "`url_for`":http://api.rubyonrails.org/classes/ActionController/Base.html#M000503 and helper methods dependent on it (by implementing/overriding this method). -We can include something like this in our +ApplicationController+ then: +We can include something like this in our `ApplicationController` then: ```ruby # app/controllers/application_controller.rb @@ -219,11 +219,11 @@ def default_url_options(options={}) end ``` -Every helper method dependent on +url_for+ (e.g. helpers for named routes like +root_path+ or +root_url+, resource routes like +books_path+ or +books_url+, etc.) will now *automatically include the locale in the query string*, like this: +http://localhost:3001/?locale=ja+. +Every helper method dependent on `url_for` (e.g. helpers for named routes like `root_path` or `root_url`, resource routes like `books_path` or `books_url`, etc.) will now *automatically include the locale in the query string*, like this: `http://localhost:3001/?locale=ja`. You may be satisfied with this. It does impact the readability of URLs, though, when the locale "hangs" at the end of every URL in your application. Moreover, from the architectural standpoint, locale is usually hierarchically above the other parts of the application domain: and URLs should reflect this. -You probably want URLs to look like this: +www.example.com/en/books+ (which loads the English locale) and +www.example.com/nl/books+ (which loads the Dutch locale). This is achievable with the "over-riding +default_url_options+" strategy from above: you just have to set up your routes with "+scoping+":http://api.rubyonrails.org/classes/ActionDispatch/Routing/Mapper/Scoping.html option in this way: +You probably want URLs to look like this: `www.example.com/en/books` (which loads the English locale) and `www.example.com/nl/books` (which loads the Dutch locale). This is achievable with the "over-riding `default_url_options`" strategy from above: you just have to set up your routes with "`scoping`":http://api.rubyonrails.org/classes/ActionDispatch/Routing/Mapper/Scoping.html option in this way: ```ruby # config/routes.rb @@ -232,7 +232,7 @@ scope "/:locale" do end ``` -Now, when you call the +books_path+ method you should get +"/en/books"+ (for the default locale). An URL like +http://localhost:3001/nl/books+ should load the Dutch locale, then, and following calls to +books_path+ should return +"/nl/books"+ (because the locale changed). +Now, when you call the `books_path` method you should get `"/en/books"` (for the default locale). An URL like `http://localhost:3001/nl/books` should load the Dutch locale, then, and following calls to `books_path` should return `"/nl/books"` (because the locale changed). If you don't want to force the use of a locale in your routes you can use an optional path scope (denoted by the parentheses) like so: @@ -243,9 +243,9 @@ scope "(:locale)", :locale => /en|nl/ do end ``` -With this approach you will not get a +Routing Error+ when accessing your resources such as +http://localhost:3001/books+ without a locale. This is useful for when you want to use the default locale when one is not specified. +With this approach you will not get a `Routing Error` when accessing your resources such as `http://localhost:3001/books` without a locale. This is useful for when you want to use the default locale when one is not specified. -Of course, you need to take special care of the root URL (usually "homepage" or "dashboard") of your application. An URL like +http://localhost:3001/nl+ will not work automatically, because the +root :to => "books#index"+ declaration in your +routes.rb+ doesn't take locale into account. (And rightly so: there's only one "root" URL.) +Of course, you need to take special care of the root URL (usually "homepage" or "dashboard") of your application. An URL like `http://localhost:3001/nl` will not work automatically, because the `root :to => "books#index"` declaration in your `routes.rb` doesn't take locale into account. (And rightly so: there's only one "root" URL.) You would probably need to map URLs like these: @@ -254,7 +254,7 @@ You would probably need to map URLs like these: match '/:locale' => 'dashboard#index' ``` -Do take special care about the *order of your routes*, so this route declaration does not "eat" other ones. (You may want to add it directly before the +root :to+ declaration.) +Do take special care about the *order of your routes*, so this route declaration does not "eat" other ones. (You may want to add it directly before the `root :to` declaration.) NOTE: Have a look at two plugins which simplify work with routes in this way: Sven Fuchs's "routing_filter":https://github.com/svenfuchs/routing-filter/tree/master and Raul Murciano's "translate_routes":https://github.com/raul/translate_routes/tree/master. @@ -263,11 +263,11 @@ NOTE: Have a look at two plugins which simplify work with routes in this way: Sv In specific cases, it would make sense to set the locale from client-supplied information, i.e. not from the URL. This information may come for example from the users' preferred language (set in their browser), can be based on the users' geographical location inferred from their IP, or users can provide it simply by choosing the locale in your application interface and saving it to their profile. This approach is more suitable for web-based applications or services, not for websites -- see the box about _sessions_, _cookies_ and RESTful architecture above. -#### Using +Accept-Language+ +#### Using `Accept-Language` -One source of client supplied information would be an +Accept-Language+ HTTP header. People may "set this in their browser":http://www.w3.org/International/questions/qa-lang-priorities or other clients (such as _curl_). +One source of client supplied information would be an `Accept-Language` HTTP header. People may "set this in their browser":http://www.w3.org/International/questions/qa-lang-priorities or other clients (such as _curl_). -A trivial implementation of using an +Accept-Language+ header would be: +A trivial implementation of using an `Accept-Language` header would be: ```ruby def set_locale @@ -322,7 +322,7 @@ end ### Adding Translations -Obviously there are *two strings that are localized to English*. In order to internationalize this code, *replace these strings* with calls to Rails' +#t+ helper with a key that makes sense for the translation: +Obviously there are *two strings that are localized to English*. In order to internationalize this code, *replace these strings* with calls to Rails' `#t` helper with a key that makes sense for the translation: ```ruby # app/controllers/home_controller.rb @@ -337,11 +337,11 @@ end <p><%= flash[:notice] %></p> ``` -When you now render this view, it will show an error message which tells you that the translations for the keys +:hello_world+ and +:hello_flash+ are missing. +When you now render this view, it will show an error message which tells you that the translations for the keys `:hello_world` and `:hello_flash` are missing. !images/i18n/demo_translation_missing.png(rails i18n demo translation missing)! -NOTE: Rails adds a +t+ (+translate+) helper method to your views so that you do not need to spell out +I18n.t+ all the time. Additionally this helper will catch missing translations and wrap the resulting error message into a +<span class="translation_missing">+. +NOTE: Rails adds a `t` (`translate`) helper method to your views so that you do not need to spell out `I18n.t` all the time. Additionally this helper will catch missing translations and wrap the resulting error message into a `<span class="translation_missing">`. So let's add the missing translations into the dictionary files (i.e. do the "localization" part): @@ -361,13 +361,13 @@ There you go. Because you haven't changed the default_locale, I18n will use Engl !images/i18n/demo_translated_en.png(rails i18n demo translated to English)! -And when you change the URL to pass the pirate locale (+http://localhost:3000?locale=pirate+), you'll get: +And when you change the URL to pass the pirate locale (`http://localhost:3000?locale=pirate`), you'll get: !images/i18n/demo_translated_pirate.png(rails i18n demo translated to pirate)! NOTE: You need to restart the server when you add new locale files. -You may use YAML (+.yml+) or plain Ruby (+.rb+) files for storing your translations in SimpleStore. YAML is the preferred option among Rails developers. However, it has one big disadvantage. YAML is very sensitive to whitespace and special characters, so the application may not load your dictionary properly. Ruby files will crash your application on first request, so you may easily find what's wrong. (If you encounter any "weird issues" with YAML dictionaries, try putting the relevant portion of your dictionary into a Ruby file.) +You may use YAML (`.yml`) or plain Ruby (`.rb`) files for storing your translations in SimpleStore. YAML is the preferred option among Rails developers. However, it has one big disadvantage. YAML is very sensitive to whitespace and special characters, so the application may not load your dictionary properly. Ruby files will crash your application on first request, so you may easily find what's wrong. (If you encounter any "weird issues" with YAML dictionaries, try putting the relevant portion of your dictionary into a Ruby file.) ### Passing variables to translations @@ -384,7 +384,7 @@ en: ### Adding Date/Time Formats -OK! Now let's add a timestamp to the view, so we can demo the *date/time localization* feature as well. To localize the time format you pass the Time object to +I18n.l+ or (preferably) use Rails' +#l+ helper. You can pick a format by passing the +:format+ option -- by default the +:default+ format is used. +OK! Now let's add a timestamp to the view, so we can demo the *date/time localization* feature as well. To localize the time format you pass the Time object to `I18n.l` or (preferably) use Rails' `#l` helper. You can pick a format by passing the `:format` option -- by default the `:default` format is used. ```ruby # app/views/home/index.html.erb @@ -407,15 +407,15 @@ So that would give you: !images/i18n/demo_localized_pirate.png(rails i18n demo localized time to pirate)! -TIP: Right now you might need to add some more date/time formats in order to make the I18n backend work as expected (at least for the 'pirate' locale). Of course, there's a great chance that somebody already did all the work by *translating Rails' defaults for your locale*. See the "rails-i18n repository at Github":https://github.com/svenfuchs/rails-i18n/tree/master/rails/locale for an archive of various locale files. When you put such file(s) in +config/locales/+ directory, they will automatically be ready for use. +TIP: Right now you might need to add some more date/time formats in order to make the I18n backend work as expected (at least for the 'pirate' locale). Of course, there's a great chance that somebody already did all the work by *translating Rails' defaults for your locale*. See the "rails-i18n repository at Github":https://github.com/svenfuchs/rails-i18n/tree/master/rails/locale for an archive of various locale files. When you put such file(s) in `config/locales/` directory, they will automatically be ready for use. ### Inflection Rules For Other Locales -Rails 4.0 allows you to define inflection rules (such as rules for singularization and pluralization) for locales other than English. In +config/initializers/inflections.rb+, you can define these rules for multiple locales. The initializer contains a default example for specifying additional rules for English; follow that format for other locales as you see fit. +Rails 4.0 allows you to define inflection rules (such as rules for singularization and pluralization) for locales other than English. In `config/initializers/inflections.rb`, you can define these rules for multiple locales. The initializer contains a default example for specifying additional rules for English; follow that format for other locales as you see fit. ### Localized Views -Rails 2.3 introduces another convenient localization feature: localized views (templates). Let's say you have a _BooksController_ in your application. Your _index_ action renders content in +app/views/books/index.html.erb+ template. When you put a _localized variant_ of this template: *+index.es.html.erb+* in the same directory, Rails will render content in this template, when the locale is set to +:es+. When the locale is set to the default locale, the generic +index.html.erb+ view will be used. (Future Rails versions may well bring this _automagic_ localization to assets in +public+, etc.) +Rails 2.3 introduces another convenient localization feature: localized views (templates). Let's say you have a _BooksController_ in your application. Your _index_ action renders content in `app/views/books/index.html.erb` template. When you put a _localized variant_ of this template: *`index.es.html.erb`* in the same directory, Rails will render content in this template, when the locale is set to `:es`. When the locale is set to the default locale, the generic `index.html.erb` view will be used. (Future Rails versions may well bring this _automagic_ localization to assets in `public`, etc.) You can make use of this feature, e.g. when working with a large amount of static content, which would be clumsy to put inside YAML or Ruby dictionaries. Bear in mind, though, that any change you would like to do later to the template must be propagated to all of them. @@ -423,7 +423,7 @@ You can make use of this feature, e.g. when working with a large amount of stati When you are using the default SimpleStore shipped with the i18n library, dictionaries are stored in plain-text files on the disc. Putting translations for all parts of your application in one file per locale could be hard to manage. You can store these files in a hierarchy which makes sense to you. -For example, your +config/locales+ directory could look like this: +For example, your `config/locales` directory could look like this: ``` |-defaults @@ -484,13 +484,13 @@ I18n.t :message I18n.t 'message' ``` -The +translate+ method also takes a +:scope+ option which can contain one or more additional keys that will be used to specify a “namespace” or scope for a translation key: +The `translate` method also takes a `:scope` option which can contain one or more additional keys that will be used to specify a “namespace” or scope for a translation key: ```ruby I18n.t :record_invalid, :scope => [:activerecord, :errors, :messages] ``` -This looks up the +:record_invalid+ message in the Active Record error messages. +This looks up the `:record_invalid` message in the Active Record error messages. Additionally, both the key and scopes can be specified as dot-separated keys as in: @@ -509,16 +509,16 @@ I18n.t :record_invalid, :scope => [:activerecord, :errors, :messages] #### Defaults -When a +:default+ option is given, its value will be returned if the translation is missing: +When a `:default` option is given, its value will be returned if the translation is missing: ```ruby I18n.t :missing, :default => 'Not here' # => 'Not here' ``` -If the +:default+ value is a Symbol, it will be used as a key and translated. One can provide multiple values as default. The first one that results in a value will be returned. +If the `:default` value is a Symbol, it will be used as a key and translated. One can provide multiple values as default. The first one that results in a value will be returned. -E.g., the following first tries to translate the key +:missing+ and then the key +:also_missing.+ As both do not yield a result, the string "Not here" will be returned: +E.g., the following first tries to translate the key `:missing` and then the key `:also_missing.` As both do not yield a result, the string "Not here" will be returned: ```ruby I18n.t :missing, :default => [:also_missing, 'Not here'] @@ -552,7 +552,7 @@ es: title: "Título" ``` -you can look up the +books.index.title+ value *inside* +app/views/books/index.html.erb+ template like this (note the dot): +you can look up the `books.index.title` value *inside* `app/views/books/index.html.erb` template like this (note the dot): ```ruby <%= t '.title' %> @@ -562,7 +562,7 @@ you can look up the +books.index.title+ value *inside* +app/views/books/index.ht In many cases you want to abstract your translations so that *variables can be interpolated into the translation*. For this reason the I18n API provides an interpolation feature. -All options besides +:default+ and +:scope+ that are passed to +#translate+ will be interpolated to the translation: +All options besides `:default` and `:scope` that are passed to `#translate` will be interpolated to the translation: ```ruby I18n.backend.store_translations :en, :thanks => 'Thanks %{name}!' @@ -570,13 +570,13 @@ I18n.translate :thanks, :name => 'Jeremy' # => 'Thanks Jeremy!' ``` -If a translation uses +:default+ or +:scope+ as an interpolation variable, an +I18n::ReservedInterpolationKey+ exception is raised. If a translation expects an interpolation variable, but this has not been passed to +#translate+, an +I18n::MissingInterpolationArgument+ exception is raised. +If a translation uses `:default` or `:scope` as an interpolation variable, an `I18n::ReservedInterpolationKey` exception is raised. If a translation expects an interpolation variable, but this has not been passed to `#translate`, an `I18n::MissingInterpolationArgument` exception is raised. ### Pluralization In English there are only one singular and one plural form for a given string, e.g. "1 message" and "2 messages". Other languages ("Arabic":http://unicode.org/repos/cldr-tmp/trunk/diff/supplemental/language_plural_rules.html#ar, "Japanese":http://unicode.org/repos/cldr-tmp/trunk/diff/supplemental/language_plural_rules.html#ja, "Russian":http://unicode.org/repos/cldr-tmp/trunk/diff/supplemental/language_plural_rules.html#ru and many more) have different grammars that have additional or fewer "plural forms":http://unicode.org/repos/cldr-tmp/trunk/diff/supplemental/language_plural_rules.html. Thus, the I18n API provides a flexible pluralization feature. -The +:count+ interpolation variable has a special role in that it both is interpolated to the translation and used to pick a pluralization from the translations according to the pluralization rules defined by CLDR: +The `:count` interpolation variable has a special role in that it both is interpolated to the translation and used to pick a pluralization from the translations according to the pluralization rules defined by CLDR: ```ruby I18n.backend.store_translations :en, :inbox => { @@ -590,21 +590,21 @@ I18n.translate :inbox, :count => 1 # => 'one message' ``` -The algorithm for pluralizations in +:en+ is as simple as: +The algorithm for pluralizations in `:en` is as simple as: ```ruby entry[count == 1 ? 0 : 1] ``` -I.e. the translation denoted as +:one+ is regarded as singular, the other is used as plural (including the count being zero). +I.e. the translation denoted as `:one` is regarded as singular, the other is used as plural (including the count being zero). -If the lookup for the key does not return a Hash suitable for pluralization, an +18n::InvalidPluralizationData+ exception is raised. +If the lookup for the key does not return a Hash suitable for pluralization, an `18n::InvalidPluralizationData` exception is raised. ### Setting and Passing a Locale -The locale can be either set pseudo-globally to +I18n.locale+ (which uses +Thread.current+ like, e.g., +Time.zone+) or can be passed as an option to +#translate+ and +#localize+. +The locale can be either set pseudo-globally to `I18n.locale` (which uses `Thread.current` like, e.g., `Time.zone`) or can be passed as an option to `#translate` and `#localize`. -If no locale is passed, +I18n.locale+ is used: +If no locale is passed, `I18n.locale` is used: ```ruby I18n.locale = :de @@ -619,7 +619,7 @@ I18n.t :foo, :locale => :de I18n.l Time.now, :locale => :de ``` -The +I18n.locale+ defaults to +I18n.default_locale+ which defaults to :+en+. The default locale can be set like this: +The `I18n.locale` defaults to `I18n.default_locale` which defaults to :`en`. The default locale can be set like this: ```ruby I18n.default_locale = :de @@ -671,9 +671,9 @@ pt: bar: baz ``` -As you see, in both cases the top level key is the locale. +:foo+ is a namespace key and +:bar+ is the key for the translation "baz". +As you see, in both cases the top level key is the locale. `:foo` is a namespace key and `:bar` is the key for the translation "baz". -Here is a "real" example from the Active Support +en.yml+ translations YAML file: +Here is a "real" example from the Active Support `en.yml` translations YAML file: ```ruby en: @@ -684,7 +684,7 @@ en: long: "%B %d, %Y" ``` -So, all of the following equivalent lookups will return the +:short+ date format +"%B %d"+: +So, all of the following equivalent lookups will return the `:short` date format `"%B %d"`: ```ruby I18n.t 'date.formats.short' @@ -697,7 +697,7 @@ Generally we recommend using YAML as a format for storing translations. There ar ### Translations for Active Record Models -You can use the methods +Model.model_name.human+ and +Model.human_attribute_name(attribute)+ to transparently look up translations for your model and attribute names. +You can use the methods `Model.model_name.human` and `Model.human_attribute_name(attribute)` to transparently look up translations for your model and attribute names. For example when you add the following translations: @@ -712,7 +712,7 @@ en: # will translate User attribute "login" as "Handle" ``` -Then +User.model_name.human+ will return "Dude" and +User.human_attribute_name("login")+ will return "Handle". +Then `User.model_name.human` will return "Dude" and `User.human_attribute_name("login")` will return "Handle". #### Error Message Scopes @@ -728,7 +728,7 @@ class User < ActiveRecord::Base end ``` -The key for the error message in this case is +:blank+. Active Record will look up this key in the namespaces: +The key for the error message in this case is `:blank`. Active Record will look up this key in the namespaces: ```ruby activerecord.errors.models.[model_name].attributes.[attribute_name] @@ -776,9 +776,9 @@ This way you can provide special translations for various error messages at diff The translated model name, translated attribute name, and value are always available for interpolation. -So, for example, instead of the default error message +"can not be blank"+ you could use the attribute name like this : +"Please fill in your %{attribute}"+. +So, for example, instead of the default error message `"can not be blank"` you could use the attribute name like this : `"Please fill in your %{attribute}"`. -* +count+, where available, can be used for pluralization if present: +* `count`, where available, can be used for pluralization if present: |_. validation |_.with option |_.message |_.interpolation| | confirmation | - | :confirmation | -| @@ -803,9 +803,9 @@ So, for example, instead of the default error message +"can not be blank"+ you c | numericality | :odd | :odd | -| | numericality | :even | :even | -| -#### Translations for the Active Record +error_messages_for+ Helper +#### Translations for the Active Record `error_messages_for` Helper -If you are using the Active Record +error_messages_for+ helper, you will want to add translations for it. +If you are using the Active Record `error_messages_for` helper, you will want to add translations for it. Rails ships with the following translations: @@ -826,23 +826,23 @@ Rails uses fixed strings and other localizations, such as format strings and oth #### Action View Helper Methods -* +distance_of_time_in_words+ translates and pluralizes its result and interpolates the number of seconds, minutes, hours, and so on. See "datetime.distance_in_words":https://github.com/rails/rails/blob/master/actionpack/lib/action_view/locale/en.yml#L51 translations. +* `distance_of_time_in_words` translates and pluralizes its result and interpolates the number of seconds, minutes, hours, and so on. See "datetime.distance_in_words":https://github.com/rails/rails/blob/master/actionpack/lib/action_view/locale/en.yml#L51 translations. -* +datetime_select+ and +select_month+ use translated month names for populating the resulting select tag. See "date.month_names":https://github.com/rails/rails/blob/master/activesupport/lib/active_support/locale/en.yml#L15 for translations. +datetime_select+ also looks up the order option from "date.order":https://github.com/rails/rails/blob/master/activesupport/lib/active_support/locale/en.yml#L18 (unless you pass the option explicitly). All date selection helpers translate the prompt using the translations in the "datetime.prompts":https://github.com/rails/rails/blob/master/actionpack/lib/action_view/locale/en.yml#L83 scope if applicable. +* `datetime_select` and `select_month` use translated month names for populating the resulting select tag. See "date.month_names":https://github.com/rails/rails/blob/master/activesupport/lib/active_support/locale/en.yml#L15 for translations. `datetime_select` also looks up the order option from "date.order":https://github.com/rails/rails/blob/master/activesupport/lib/active_support/locale/en.yml#L18 (unless you pass the option explicitly). All date selection helpers translate the prompt using the translations in the "datetime.prompts":https://github.com/rails/rails/blob/master/actionpack/lib/action_view/locale/en.yml#L83 scope if applicable. -* The +number_to_currency+, +number_with_precision+, +number_to_percentage+, +number_with_delimiter+, and +number_to_human_size+ helpers use the number format settings located in the "number":https://github.com/rails/rails/blob/master/actionpack/lib/action_view/locale/en.yml#L2 scope. +* The `number_to_currency`, `number_with_precision`, `number_to_percentage`, `number_with_delimiter`, and `number_to_human_size` helpers use the number format settings located in the "number":https://github.com/rails/rails/blob/master/actionpack/lib/action_view/locale/en.yml#L2 scope. #### Active Model Methods -* +model_name.human+ and +human_attribute_name+ use translations for model names and attribute names if available in the "activerecord.models":https://github.com/rails/rails/blob/master/activerecord/lib/active_record/locale/en.yml#L29 scope. They also support translations for inherited class names (e.g. for use with STI) as explained above in "Error message scopes". +* `model_name.human` and `human_attribute_name` use translations for model names and attribute names if available in the "activerecord.models":https://github.com/rails/rails/blob/master/activerecord/lib/active_record/locale/en.yml#L29 scope. They also support translations for inherited class names (e.g. for use with STI) as explained above in "Error message scopes". -* +ActiveModel::Errors#generate_message+ (which is used by Active Model validations but may also be used manually) uses +model_name.human+ and +human_attribute_name+ (see above). It also translates the error message and supports translations for inherited class names as explained above in "Error message scopes". +* `ActiveModel::Errors#generate_message` (which is used by Active Model validations but may also be used manually) uses `model_name.human` and `human_attribute_name` (see above). It also translates the error message and supports translations for inherited class names as explained above in "Error message scopes". -* +ActiveModel::Errors#full_messages+ prepends the attribute name to the error message using a separator that will be looked up from "errors.format":https://github.com/rails/rails/blob/master/activemodel/lib/active_model/locale/en.yml#L4 (and which defaults to +"%{attribute} %{message}"+). +* `ActiveModel::Errors#full_messages` prepends the attribute name to the error message using a separator that will be looked up from "errors.format":https://github.com/rails/rails/blob/master/activemodel/lib/active_model/locale/en.yml#L4 (and which defaults to `"%{attribute} %{message}"`). #### Active Support Methods -* +Array#to_sentence+ uses format settings as given in the "support.array":https://github.com/rails/rails/blob/master/activesupport/lib/active_support/locale/en.yml#L30 scope. +* `Array#to_sentence` uses format settings as given in the "support.array":https://github.com/rails/rails/blob/master/activesupport/lib/active_support/locale/en.yml#L30 scope. Customize your I18n Setup ------------------------- @@ -876,11 +876,11 @@ ReservedInterpolationKey # the translation contains a reserved interpolation UnknownFileType # the backend does not know how to handle a file type that was added to I18n.load_path ``` -The I18n API will catch all of these exceptions when they are thrown in the backend and pass them to the default_exception_handler method. This method will re-raise all exceptions except for +MissingTranslationData+ exceptions. When a +MissingTranslationData+ exception has been caught, it will return the exception’s error message string containing the missing key/scope. +The I18n API will catch all of these exceptions when they are thrown in the backend and pass them to the default_exception_handler method. This method will re-raise all exceptions except for `MissingTranslationData` exceptions. When a `MissingTranslationData` exception has been caught, it will return the exception’s error message string containing the missing key/scope. The reason for this is that during development you'd usually want your views to still render even though a translation is missing. -In other contexts you might want to change this behaviour, though. E.g. the default exception handling does not allow to catch missing translations during automated tests easily. For this purpose a different exception handler can be specified. The specified exception handler must be a method on the I18n module or a class with +#call+ method: +In other contexts you might want to change this behaviour, though. E.g. the default exception handling does not allow to catch missing translations during automated tests easily. For this purpose a different exception handler can be specified. The specified exception handler must be a method on the I18n module or a class with `#call` method: ```ruby module I18n @@ -898,9 +898,9 @@ end I18n.exception_handler = I18n::JustRaiseExceptionHandler.new ``` -This would re-raise only the +MissingTranslationData+ exception, passing all other input to the default exception handler. +This would re-raise only the `MissingTranslationData` exception, passing all other input to the default exception handler. -However, if you are using +I18n::Backend::Pluralization+ this handler will also raise +I18n::MissingTranslationData: translation missing: en.i18n.plural.rule+ exception that should normally be ignored to fall back to the default pluralization rule for English locale. To avoid this you may use additional check for translation key: +However, if you are using `I18n::Backend::Pluralization` this handler will also raise `I18n::MissingTranslationData: translation missing: en.i18n.plural.rule` exception that should normally be ignored to fall back to the default pluralization rule for English locale. To avoid this you may use additional check for translation key: ```ruby if exception.is_a?(MissingTranslation) && key.to_s != 'i18n.plural.rule' @@ -910,9 +910,9 @@ else end ``` -Another example where the default behaviour is less desirable is the Rails TranslationHelper which provides the method +#t+ (as well as +#translate+). When a +MissingTranslationData+ exception occurs in this context, the helper wraps the message into a span with the CSS class +translation_missing+. +Another example where the default behaviour is less desirable is the Rails TranslationHelper which provides the method `#t` (as well as `#translate`). When a `MissingTranslationData` exception occurs in this context, the helper wraps the message into a span with the CSS class `translation_missing`. -To do so, the helper forces +I18n#translate+ to raise exceptions no matter what exception handler is defined by setting the +:raise+ option: +To do so, the helper forces `I18n#translate` to raise exceptions no matter what exception handler is defined by setting the `:raise` option: ```ruby I18n.t :foo, :raise => true # always re-raises exceptions from the backend diff --git a/guides/source/initialization.md b/guides/source/initialization.md index 6fbaa6a4a7..203080cc1d 100644 --- a/guides/source/initialization.md +++ b/guides/source/initialization.md @@ -4,7 +4,7 @@ The Rails Initialization Process This guide explains the internals of the initialization process in Rails as of Rails 4. It is an extremely in-depth guide and recommended for advanced Rails developers. -* Using +rails server+ +* Using `rails server` -------------------------------------------------------------------------------- @@ -17,18 +17,18 @@ server+ to boot your app. NOTE: Paths in this guide are relative to Rails or a Rails application unless otherwise specified. TIP: If you want to follow along while browsing the Rails "source -code":https://github.com/rails/rails, we recommend that you use the +t+ +code":https://github.com/rails/rails, we recommend that you use the `t` key binding to open the file finder inside GitHub and find files quickly. Launch! ------- -A Rails application is usually started with the command +rails server+. +A Rails application is usually started with the command `rails server`. -### +bin/rails+ +### `bin/rails` -The actual +rails+ command is kept in _bin/rails_: +The actual `rails` command is kept in _bin/rails_: ```ruby #!/usr/bin/env ruby @@ -40,10 +40,10 @@ end require "rails/cli" ``` -This file will first attempt to push the +railties/lib+ directory if -present, and then requires +rails/cli+. +This file will first attempt to push the `railties/lib` directory if +present, and then requires `rails/cli`. -### +railties/lib/rails/cli.rb+ +### `railties/lib/rails/cli.rb` This file looks like this: @@ -66,7 +66,7 @@ else end ``` -The +rbconfig+ file from the Ruby standard library provides us with the +RbConfig+ class which contains detailed information about the Ruby environment, including how Ruby was compiled. We can see this in use in +railties/lib/rails/script_rails_loader+. +The `rbconfig` file from the Ruby standard library provides us with the `RbConfig` class which contains detailed information about the Ruby environment, including how Ruby was compiled. We can see this in use in `railties/lib/rails/script_rails_loader`. ```ruby require 'pathname' @@ -81,15 +81,15 @@ module Rails end ``` -The +rails/script_rails_loader+ file uses +RbConfig::Config+ to obtain the +bin_dir+ and +ruby_install_name+ values for the configuration which together form the path to the Ruby interpreter. The +RbConfig::CONFIG["EXEEXT"]+ will suffix this path with ".exe" if the script is running on Windows. This constant is used later on in +exec_script_rails!+. As for the +SCRIPT_RAILS+ constant, we'll see that when we get to the +in_rails_application?+ method. +The `rails/script_rails_loader` file uses `RbConfig::Config` to obtain the `bin_dir` and `ruby_install_name` values for the configuration which together form the path to the Ruby interpreter. The `RbConfig::CONFIG["EXEEXT"]` will suffix this path with ".exe" if the script is running on Windows. This constant is used later on in `exec_script_rails!`. As for the `SCRIPT_RAILS` constant, we'll see that when we get to the `in_rails_application?` method. -Back in +rails/cli+, the next line is this: +Back in `rails/cli`, the next line is this: ```ruby Rails::ScriptRailsLoader.exec_script_rails! ``` -This method is defined in +rails/script_rails_loader+: +This method is defined in `rails/script_rails_loader`: ```ruby def self.exec_script_rails! @@ -106,7 +106,7 @@ rescue SystemCallError end ``` -This method will first check if the current working directory (+cwd+) is a Rails application or a subdirectory of one. This is determined by the +in_rails_application?+ method: +This method will first check if the current working directory (`cwd`) is a Rails application or a subdirectory of one. This is determined by the `in_rails_application?` method: ```ruby def self.in_rails_application? @@ -114,7 +114,7 @@ def self.in_rails_application? end ``` -The +SCRIPT_RAILS+ constant defined earlier is used here, with +File.exists?+ checking for its presence in the current directory. If this method returns +false+ then +in_rails_application_subdirectory?+ will be used: +The `SCRIPT_RAILS` constant defined earlier is used here, with `File.exists?` checking for its presence in the current directory. If this method returns `false` then `in_rails_application_subdirectory?` will be used: ```ruby def self.in_rails_application_subdirectory?(path = Pathname.new(Dir.pwd)) @@ -122,24 +122,24 @@ def self.in_rails_application_subdirectory?(path = Pathname.new(Dir.pwd)) end ``` -This climbs the directory tree until it reaches a path which contains a +script/rails+ file. If a directory containing this file is reached then this line will run: +This climbs the directory tree until it reaches a path which contains a `script/rails` file. If a directory containing this file is reached then this line will run: ```ruby exec RUBY, SCRIPT_RAILS, *ARGV if in_rails_application? ``` -This is effectively the same as running +ruby script/rails [arguments]+, where +[arguments]+ at this point in time is simply "server". +This is effectively the same as running `ruby script/rails [arguments]`, where `[arguments]` at this point in time is simply "server". Rails Initialization -------------------- Only now we finally start the real initialization process, beginning -with +script/rails+. +with `script/rails`. -TIP: If you execute +script/rails+ directly from your Rails app you will +TIP: If you execute `script/rails` directly from your Rails app you will skip executing all the code that we've just described. -### +script/rails+ +### `script/rails` This file is as follows: @@ -149,11 +149,11 @@ require File.expand_path('../../config/boot', __FILE__) require 'rails/commands' ``` -The +APP_PATH+ constant will be used later in +rails/commands+. The +config/boot+ file referenced here is the +config/boot.rb+ file in our application which is responsible for loading Bundler and setting it up. +The `APP_PATH` constant will be used later in `rails/commands`. The `config/boot` file referenced here is the `config/boot.rb` file in our application which is responsible for loading Bundler and setting it up. -### +config/boot.rb+ +### `config/boot.rb` -+config/boot.rb+ contains: +`config/boot.rb` contains: ```ruby # Set up gems listed in the Gemfile. @@ -162,10 +162,10 @@ ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile', __FILE__) require 'bundler/setup' if File.exists?(ENV['BUNDLE_GEMFILE']) ``` -In a standard Rails application, there's a +Gemfile+ which declares all -dependencies of the application. +config/boot.rb+ sets -+ENV['BUNDLE_GEMFILE']+ to the location of this file. If the Gemfile -exists, +bundler/setup+ is then required. +In a standard Rails application, there's a `Gemfile` which declares all +dependencies of the application. `config/boot.rb` sets +`ENV['BUNDLE_GEMFILE']` to the location of this file. If the Gemfile +exists, `bundler/setup` is then required. The gems that a Rails 4 application depends on are as follows: @@ -197,9 +197,9 @@ TODO: change these when the Rails 4 release is near. * treetop (1.4.9) * tzinfo (0.3.23) -### +rails/commands.rb+ +### `rails/commands.rb` -Once +config/boot.rb+ has finished, the next file that is required is +rails/commands+ which will execute a command based on the arguments passed in. In this case, the +ARGV+ array simply contains +server+ which is extracted into the +command+ variable using these lines: +Once `config/boot.rb` has finished, the next file that is required is `rails/commands` which will execute a command based on the arguments passed in. In this case, the `ARGV` array simply contains `server` which is extracted into the `command` variable using these lines: ```ruby ARGV << '--help' if ARGV.empty? @@ -220,7 +220,7 @@ command = aliases[command] || command TIP: As you can see, an empty ARGV list will make Rails show the help snippet. -If we used `s` rather than +server+, Rails will use the +aliases+ defined in the file and match them to their respective commands. With the +server+ command, Rails will run this code: +If we used `s` rather than `server`, Rails will use the `aliases` defined in the file and match them to their respective commands. With the `server` command, Rails will run this code: ```ruby when 'server' @@ -239,7 +239,7 @@ when 'server' } ``` -This file will change into the root of the directory (a path two directories back from +APP_PATH+ which points at +config/application.rb+), but only if the +config.ru+ file isn't found. This then requires +rails/commands/server+ which sets up the +Rails::Server+ class. +This file will change into the root of the directory (a path two directories back from `APP_PATH` which points at `config/application.rb`), but only if the `config.ru` file isn't found. This then requires `rails/commands/server` which sets up the `Rails::Server` class. ```ruby require 'fileutils' @@ -250,16 +250,16 @@ module Rails class Server < ::Rack::Server ``` -+fileutils+ and +optparse+ are standard Ruby libraries which provide helper functions for working with files and parsing options. +`fileutils` and `optparse` are standard Ruby libraries which provide helper functions for working with files and parsing options. -### +actionpack/lib/action_dispatch.rb+ +### `actionpack/lib/action_dispatch.rb` Action Dispatch is the routing component of the Rails framework. It adds functionalities like routing, session, and common middlewares. -### +rails/commands/server.rb+ +### `rails/commands/server.rb` -The +Rails::Server+ class is defined in this file as inheriting from +Rack::Server+. When +Rails::Server.new+ is called, this calls the +initialize+ method in +rails/commands/server.rb+: +The `Rails::Server` class is defined in this file as inheriting from `Rack::Server`. When `Rails::Server.new` is called, this calls the `initialize` method in `rails/commands/server.rb`: ```ruby def initialize(*) @@ -268,13 +268,13 @@ def initialize(*) end ``` -Firstly, +super+ is called which calls the +initialize+ method on +Rack::Server+. +Firstly, `super` is called which calls the `initialize` method on `Rack::Server`. -### Rack: +lib/rack/server.rb+ +### Rack: `lib/rack/server.rb` -+Rack::Server+ is responsible for providing a common server interface for all Rack-based applications, which Rails is now a part of. +`Rack::Server` is responsible for providing a common server interface for all Rack-based applications, which Rails is now a part of. -The +initialize+ method in +Rack::Server+ simply sets a couple of variables: +The `initialize` method in `Rack::Server` simply sets a couple of variables: ```ruby def initialize(options = nil) @@ -283,9 +283,9 @@ def initialize(options = nil) end ``` -In this case, +options+ will be +nil+ so nothing happens in this method. +In this case, `options` will be `nil` so nothing happens in this method. -After +super+ has finished in +Rack::Server+, we jump back to +rails/commands/server.rb+. At this point, +set_environment+ is called within the context of the +Rails::Server+ object and this method doesn't appear to do much at first glance: +After `super` has finished in `Rack::Server`, we jump back to `rails/commands/server.rb`. At this point, `set_environment` is called within the context of the `Rails::Server` object and this method doesn't appear to do much at first glance: ```ruby def set_environment @@ -293,7 +293,7 @@ def set_environment end ``` -In fact, the +options+ method here does quite a lot. This method is defined in +Rack::Server+ like this: +In fact, the `options` method here does quite a lot. This method is defined in `Rack::Server` like this: ```ruby def options @@ -301,7 +301,7 @@ def options end ``` -Then +parse_options+ is defined like this: +Then `parse_options` is defined like this: ```ruby def parse_options(args) @@ -318,7 +318,7 @@ def parse_options(args) end ``` -With the +default_options+ set to this: +With the `default_options` set to this: ```ruby def default_options @@ -333,7 +333,7 @@ def default_options end ``` -There is no +REQUEST_METHOD+ key in +ENV+ so we can skip over that line. The next line merges in the options from +opt_parser+ which is defined plainly in +Rack::Server+ +There is no `REQUEST_METHOD` key in `ENV` so we can skip over that line. The next line merges in the options from `opt_parser` which is defined plainly in `Rack::Server` ```ruby def opt_parser @@ -341,7 +341,7 @@ def opt_parser end ``` -The class *is* defined in +Rack::Server+, but is overwritten in +Rails::Server+ to take different arguments. Its +parse!+ method begins like this: +The class *is* defined in `Rack::Server`, but is overwritten in `Rails::Server` to take different arguments. Its `parse!` method begins like this: ```ruby def parse!(args) @@ -354,20 +354,20 @@ def parse!(args) ... ``` -This method will set up keys for the +options+ which Rails will then be -able to use to determine how its server should run. After +initialize+ -has finished, we jump back into +rails/server+ where +APP_PATH+ (which was +This method will set up keys for the `options` which Rails will then be +able to use to determine how its server should run. After `initialize` +has finished, we jump back into `rails/server` where `APP_PATH` (which was set earlier) is required. -### +config/application+ +### `config/application` -When +require APP_PATH+ is executed, +config/application.rb+ is loaded. +When `require APP_PATH` is executed, `config/application.rb` is loaded. This file exists in your app and it's free for you to change based on your needs. -### +Rails::Server#start+ +### `Rails::Server#start` -After +congif/application+ is loaded, +server.start+ is called. This method is defined like this: +After `congif/application` is loaded, `server.start` is called. This method is defined like this: ```ruby def start @@ -401,14 +401,14 @@ end ``` This is where the first output of the Rails initialization happens. This -method creates a trap for +INT+ signals, so if you +CTRL-C+ the server, +method creates a trap for `INT` signals, so if you `CTRL-C` the server, it will exit the process. As we can see from the code here, it will -create the +tmp/cache+, +tmp/pids+, +tmp/sessions+ and +tmp/sockets+ -directories. It then calls +wrapped_app+ which is responsible for +create the `tmp/cache`, `tmp/pids`, `tmp/sessions` and `tmp/sockets` +directories. It then calls `wrapped_app` which is responsible for creating the Rack app, before creating and assigning an -instance of +ActiveSupport::Logger+. +instance of `ActiveSupport::Logger`. -The +super+ method will call +Rack::Server.start+ which begins its definition like this: +The `super` method will call `Rack::Server.start` which begins its definition like this: ```ruby def start &blk @@ -454,7 +454,7 @@ def start &blk end ``` -The interesting part for a Rails app is the last line, +server.run+. Here we encounter the +wrapped_app+ method again, which this time +The interesting part for a Rails app is the last line, `server.run`. Here we encounter the `wrapped_app` method again, which this time we're going to explore more (even though it was executed before, and thus memorized by now). @@ -462,7 +462,7 @@ thus memorized by now). @wrapped_app ||= build_app app ``` -The +app+ method here is defined like so: +The `app` method here is defined like so: ```ruby def app @@ -478,7 +478,7 @@ def app end ``` -The +options[:config]+ value defaults to +config.ru+ which contains this: +The `options[:config]` value defaults to `config.ru` which contains this: ```ruby # This file is used by Rack-based servers to start the application. @@ -488,41 +488,41 @@ run <%= app_const %> ``` -The +Rack::Builder.parse_file+ method here takes the content from this +config.ru+ file and parses it using this code: +The `Rack::Builder.parse_file` method here takes the content from this `config.ru` file and parses it using this code: ```ruby app = eval "Rack::Builder.new {( " <plus> cfgfile <plus> "\n )}.to_app", TOPLEVEL_BINDING, config ``` -The +initialize+ method of +Rack::Builder+ will take the block here and execute it within an instance of +Rack::Builder+. This is where the majority of the initialization process of Rails happens. The +require+ line for +config/environment.rb+ in +config.ru+ is the first to run: +The `initialize` method of `Rack::Builder` will take the block here and execute it within an instance of `Rack::Builder`. This is where the majority of the initialization process of Rails happens. The `require` line for `config/environment.rb` in `config.ru` is the first to run: ```ruby require ::File.expand_path('../config/environment', __FILE__) ``` -### +config/environment.rb+ +### `config/environment.rb` -This file is the common file required by +config.ru+ (+rails server+) and Passenger. This is where these two ways to run the server meet; everything before this point has been Rack and Rails setup. +This file is the common file required by `config.ru` (`rails server`) and Passenger. This is where these two ways to run the server meet; everything before this point has been Rack and Rails setup. -This file begins with requiring +config/application.rb+. +This file begins with requiring `config/application.rb`. -### +config/application.rb+ +### `config/application.rb` -This file requires +config/boot.rb+, but only if it hasn't been required before, which would be the case in +rails server+ but *wouldn't* be the case with Passenger. +This file requires `config/boot.rb`, but only if it hasn't been required before, which would be the case in `rails server` but *wouldn't* be the case with Passenger. Then the fun begins! Loading Rails ------------- -The next line in +config/application.rb+ is: +The next line in `config/application.rb` is: ```ruby require 'rails/all' ``` -### +railties/lib/rails/all.rb+ +### `railties/lib/rails/all.rb` This file is responsible for requiring all the individual frameworks of Rails: @@ -551,17 +551,17 @@ explore them on your own. For now, just keep in mind that common functionality like Rails engines, I18n and Rails configuration is all being defined here. -### Back to +config/environment.rb+ +### Back to `config/environment.rb` -When +config/application.rb+ has finished loading Rails, and defined -your application namespace, you go back to +config/environment.rb+, +When `config/application.rb` has finished loading Rails, and defined +your application namespace, you go back to `config/environment.rb`, where your application is initialized. For example, if you application was called -+Blog+, here you would find +Blog::Application.initialize!+, which is -defined in +rails/application.rb+ +`Blog`, here you would find `Blog::Application.initialize!`, which is +defined in `rails/application.rb` -### +railties/lib/rails/application.rb+ +### `railties/lib/rails/application.rb` -The +initialize!+ method looks like this: +The `initialize!` method looks like this: ```ruby def initialize!(group=:default) #:nodoc: @@ -577,15 +577,15 @@ As you can see, you can only initialize an app once. This is also where the init TODO: review this The initializers code itself is tricky. What Rails is doing here is it -traverses all the class ancestors looking for an +initializers+ method, -sorting them and running them. For example, the +Engine+ class will make -all the engines available by providing the +initializers+ method. +traverses all the class ancestors looking for an `initializers` method, +sorting them and running them. For example, the `Engine` class will make +all the engines available by providing the `initializers` method. -After this is done we go back to +Rack::Server+ +After this is done we go back to `Rack::Server` ### Rack: lib/rack/server.rb -Last time we left when the +app+ method was being defined: +Last time we left when the `app` method was being defined: ```ruby def app @@ -601,7 +601,7 @@ def app end ``` -At this point +app+ is the Rails app itself (a middleware), and what +At this point `app` is the Rails app itself (a middleware), and what happens next is Rack will call all the provided middlewares: ```ruby @@ -616,16 +616,16 @@ def build_app(app) end ``` -Remember, +build_app+ was called (by wrapped_app) in the last line of +Server#start+. +Remember, `build_app` was called (by wrapped_app) in the last line of `Server#start`. Here's how it looked like when we left: ```ruby server.run wrapped_app, options, &blk ``` -At this point, the implementation of +server.run+ will depend on the +At this point, the implementation of `server.run` will depend on the server you're using. For example, if you were using Mongrel, here's what -the +run+ method would look like: +the `run` method would look like: ```ruby def self.run(app, options={}) diff --git a/guides/source/layouts_and_rendering.md b/guides/source/layouts_and_rendering.md index 75be7e6c68..ccae196966 100644 --- a/guides/source/layouts_and_rendering.md +++ b/guides/source/layouts_and_rendering.md @@ -22,13 +22,13 @@ Creating Responses From the controller's point of view, there are three ways to create an HTTP response: -* Call +render+ to create a full response to send back to the browser -* Call +redirect_to+ to send an HTTP redirect status code to the browser -* Call +head+ to create a response consisting solely of HTTP headers to send back to the browser +* Call `render` to create a full response to send back to the browser +* Call `redirect_to` to send an HTTP redirect status code to the browser +* Call `head` to create a response consisting solely of HTTP headers to send back to the browser ### Rendering by Default: Convention Over Configuration in Action -You've heard that Rails promotes "convention over configuration". Default rendering is an excellent example of this. By default, controllers in Rails automatically render views with names that correspond to valid routes. For example, if you have this code in your +BooksController+ class: +You've heard that Rails promotes "convention over configuration". Default rendering is an excellent example of this. By default, controllers in Rails automatically render views with names that correspond to valid routes. For example, if you have this code in your `BooksController` class: ```ruby class BooksController < ApplicationController @@ -41,15 +41,15 @@ And the following in your routes file: resources :books ``` -And you have a view file +app/views/books/index.html.erb+: +And you have a view file `app/views/books/index.html.erb`: ```ruby <h1>Books are coming soon!</h1> ``` -Rails will automatically render +app/views/books/index.html.erb+ when you navigate to +/books+ and you will see "Books are coming soon!" on your screen. +Rails will automatically render `app/views/books/index.html.erb` when you navigate to `/books` and you will see "Books are coming soon!" on your screen. -However a coming soon screen is only minimally useful, so you will soon create your +Book+ model and add the index action to +BooksController+: +However a coming soon screen is only minimally useful, so you will soon create your `Book` model and add the index action to `BooksController`: ```ruby class BooksController < ApplicationController @@ -59,7 +59,7 @@ class BooksController < ApplicationController end ``` -Note that we don't have explicit render at the end of the index action in accordance with "convention over configuration" principle. The rule is that if you do not explicitly render something at the end of a controller action, Rails will automatically look for the +action_name.html.erb+ template in the controller's view path and render it. So in this case, Rails will render the +app/views/books/index.html.erb+ file. +Note that we don't have explicit render at the end of the index action in accordance with "convention over configuration" principle. The rule is that if you do not explicitly render something at the end of a controller action, Rails will automatically look for the `action_name.html.erb` template in the controller's view path and render it. So in this case, Rails will render the `app/views/books/index.html.erb` file. If we want to display the properties of all the books in our view, we can do so with an ERB template like this: @@ -91,17 +91,17 @@ If we want to display the properties of all the books in our view, we can do so <%= link_to "New book", new_book_path %> ``` -NOTE: The actual rendering is done by subclasses of +ActionView::TemplateHandlers+. This guide does not dig into that process, but it's important to know that the file extension on your view controls the choice of template handler. Beginning with Rails 2, the standard extensions are +.erb+ for ERB (HTML with embedded Ruby), and +.builder+ for Builder (XML generator). +NOTE: The actual rendering is done by subclasses of `ActionView::TemplateHandlers`. This guide does not dig into that process, but it's important to know that the file extension on your view controls the choice of template handler. Beginning with Rails 2, the standard extensions are `.erb` for ERB (HTML with embedded Ruby), and `.builder` for Builder (XML generator). -### Using +render+ +### Using `render` -In most cases, the +ActionController::Base#render+ method does the heavy lifting of rendering your application's content for use by a browser. There are a variety of ways to customize the behaviour of +render+. You can render the default view for a Rails template, or a specific template, or a file, or inline code, or nothing at all. You can render text, JSON, or XML. You can specify the content type or HTTP status of the rendered response as well. +In most cases, the `ActionController::Base#render` method does the heavy lifting of rendering your application's content for use by a browser. There are a variety of ways to customize the behaviour of `render`. You can render the default view for a Rails template, or a specific template, or a file, or inline code, or nothing at all. You can render text, JSON, or XML. You can specify the content type or HTTP status of the rendered response as well. -TIP: If you want to see the exact results of a call to +render+ without needing to inspect it in a browser, you can call +render_to_string+. This method takes exactly the same options as +render+, but it returns a string instead of sending a response back to the browser. +TIP: If you want to see the exact results of a call to `render` without needing to inspect it in a browser, you can call `render_to_string`. This method takes exactly the same options as `render`, but it returns a string instead of sending a response back to the browser. #### Rendering Nothing -Perhaps the simplest thing you can do with +render+ is to render nothing at all: +Perhaps the simplest thing you can do with `render` is to render nothing at all: ```ruby render :nothing => true @@ -124,13 +124,13 @@ Cache-Control: no-cache $ ``` -We see there is an empty response (no data after the +Cache-Control+ line), but the request was successful because Rails has set the response to 200 OK. You can set the +:status+ option on render to change this response. Rendering nothing can be useful for AJAX requests where all you want to send back to the browser is an acknowledgment that the request was completed. +We see there is an empty response (no data after the `Cache-Control` line), but the request was successful because Rails has set the response to 200 OK. You can set the `:status` option on render to change this response. Rendering nothing can be useful for AJAX requests where all you want to send back to the browser is an acknowledgment that the request was completed. -TIP: You should probably be using the +head+ method, discussed later in this guide, instead of +render :nothing+. This provides additional flexibility and makes it explicit that you're only generating HTTP headers. +TIP: You should probably be using the `head` method, discussed later in this guide, instead of `render :nothing`. This provides additional flexibility and makes it explicit that you're only generating HTTP headers. #### Rendering an Action's View -If you want to render the view that corresponds to a different action within the same template, you can use +render+ with the name of the view: +If you want to render the view that corresponds to a different action within the same template, you can use `render` with the name of the view: ```ruby def update @@ -143,7 +143,7 @@ def update end ``` -If the call to +update_attributes+ fails, calling the +update+ action in this controller will render the +edit.html.erb+ template belonging to the same controller. +If the call to `update_attributes` fails, calling the `update` action in this controller will render the `edit.html.erb` template belonging to the same controller. If you prefer, you can use a symbol instead of a string to specify the action to render: @@ -158,7 +158,7 @@ def update end ``` -To be explicit, you can use +render+ with the +:action+ option (though this is no longer necessary in Rails 3.0): +To be explicit, you can use `render` with the `:action` option (though this is no longer necessary in Rails 3.0): ```ruby def update @@ -171,17 +171,17 @@ def update end ``` -WARNING: Using +render+ with +:action+ is a frequent source of confusion for Rails newcomers. The specified action is used to determine which view to render, but Rails does _not_ run any of the code for that action in the controller. Any instance variables that you require in the view must be set up in the current action before calling +render+. +WARNING: Using `render` with `:action` is a frequent source of confusion for Rails newcomers. The specified action is used to determine which view to render, but Rails does _not_ run any of the code for that action in the controller. Any instance variables that you require in the view must be set up in the current action before calling `render`. #### Rendering an Action's Template from Another Controller -What if you want to render a template from an entirely different controller from the one that contains the action code? You can also do that with +render+, which accepts the full path (relative to +app/views+) of the template to render. For example, if you're running code in an +AdminProductsController+ that lives in +app/controllers/admin+, you can render the results of an action to a template in +app/views/products+ this way: +What if you want to render a template from an entirely different controller from the one that contains the action code? You can also do that with `render`, which accepts the full path (relative to `app/views`) of the template to render. For example, if you're running code in an `AdminProductsController` that lives in `app/controllers/admin`, you can render the results of an action to a template in `app/views/products` this way: ```ruby render "products/show" ``` -Rails knows that this view belongs to a different controller because of the embedded slash character in the string. If you want to be explicit, you can use the +:template+ option (which was required on Rails 2.2 and earlier): +Rails knows that this view belongs to a different controller because of the embedded slash character in the string. If you want to be explicit, you can use the `:template` option (which was required on Rails 2.2 and earlier): ```ruby render :template => "products/show" @@ -189,30 +189,30 @@ render :template => "products/show" #### Rendering an Arbitrary File -The +render+ method can also use a view that's entirely outside of your application (perhaps you're sharing views between two Rails applications): +The `render` method can also use a view that's entirely outside of your application (perhaps you're sharing views between two Rails applications): ```ruby render "/u/apps/warehouse_app/current/app/views/products/show" ``` -Rails determines that this is a file render because of the leading slash character. To be explicit, you can use the +:file+ option (which was required on Rails 2.2 and earlier): +Rails determines that this is a file render because of the leading slash character. To be explicit, you can use the `:file` option (which was required on Rails 2.2 and earlier): ```ruby render :file => "/u/apps/warehouse_app/current/app/views/products/show" ``` -The +:file+ option takes an absolute file-system path. Of course, you need to have rights to the view that you're using to render the content. +The `:file` option takes an absolute file-system path. Of course, you need to have rights to the view that you're using to render the content. -NOTE: By default, the file is rendered without using the current layout. If you want Rails to put the file into the current layout, you need to add the +:layout => true+ option. +NOTE: By default, the file is rendered without using the current layout. If you want Rails to put the file into the current layout, you need to add the `:layout => true` option. -TIP: If you're running Rails on Microsoft Windows, you should use the +:file+ option to render a file, because Windows filenames do not have the same format as Unix filenames. +TIP: If you're running Rails on Microsoft Windows, you should use the `:file` option to render a file, because Windows filenames do not have the same format as Unix filenames. #### Wrapping it up The above three ways of rendering (rendering another template within the controller, rendering a template within another controller and rendering an arbitrary file on the file system) are actually variants of the same action. -In fact, in the BooksController class, inside of the update action where we want to render the edit template if the book does not update successfully, all of the following render calls would all render the +edit.html.erb+ template in the +views/books+ directory: +In fact, in the BooksController class, inside of the update action where we want to render the edit template if the book does not update successfully, all of the following render calls would all render the `edit.html.erb` template in the `views/books` directory: ```ruby render :edit @@ -233,9 +233,9 @@ render :file => "/path/to/rails/app/views/books/edit.html.erb" Which one you use is really a matter of style and convention, but the rule of thumb is to use the simplest one that makes sense for the code you are writing. -#### Using +render+ with +:inline+ +#### Using `render` with `:inline` -The +render+ method can do without a view completely, if you're willing to use the +:inline+ option to supply ERB as part of the method call. This is perfectly valid: +The `render` method can do without a view completely, if you're willing to use the `:inline` option to supply ERB as part of the method call. This is perfectly valid: ```ruby render :inline => @@ -244,7 +244,7 @@ render :inline => WARNING: There is seldom any good reason to use this option. Mixing ERB into your controllers defeats the MVC orientation of Rails and will make it harder for other developers to follow the logic of your project. Use a separate erb view instead. -By default, inline rendering uses ERB. You can force it to use Builder instead with the +:type+ option: +By default, inline rendering uses ERB. You can force it to use Builder instead with the `:type` option: ```ruby render :inline => @@ -253,7 +253,7 @@ render :inline => #### Rendering Text -You can send plain text - with no markup at all - back to the browser by using the +:text+ option to +render+: +You can send plain text - with no markup at all - back to the browser by using the `:text` option to `render`: ```ruby render :text => "OK" @@ -261,7 +261,7 @@ render :text => "OK" TIP: Rendering pure text is most useful when you're responding to AJAX or web service requests that are expecting something other than proper HTML. -NOTE: By default, if you use the +:text+ option, the text is rendered without using the current layout. If you want Rails to put the text into the current layout, you need to add the +:layout => true+ option. +NOTE: By default, if you use the `:text` option, the text is rendered without using the current layout. If you want Rails to put the text into the current layout, you need to add the `:layout => true` option. #### Rendering JSON @@ -271,7 +271,7 @@ JSON is a JavaScript data format used by many AJAX libraries. Rails has built-in render :json => @product ``` -TIP: You don't need to call +to_json+ on the object that you want to render. If you use the +:json+ option, +render+ will automatically call +to_json+ for you. +TIP: You don't need to call `to_json` on the object that you want to render. If you use the `:json` option, `render` will automatically call `to_json` for you. #### Rendering XML @@ -281,7 +281,7 @@ Rails also has built-in support for converting objects to XML and rendering that render :xml => @product ``` -TIP: You don't need to call +to_xml+ on the object that you want to render. If you use the +:xml+ option, +render+ will automatically call +to_xml+ for you. +TIP: You don't need to call `to_xml` on the object that you want to render. If you use the `:xml` option, `render` will automatically call `to_xml` for you. #### Rendering Vanilla JavaScript @@ -291,30 +291,30 @@ Rails can render vanilla JavaScript: render :js => "alert('Hello Rails');" ``` -This will send the supplied string to the browser with a MIME type of +text/javascript+. +This will send the supplied string to the browser with a MIME type of `text/javascript`. -#### Options for +render+ +#### Options for `render` -Calls to the +render+ method generally accept four options: +Calls to the `render` method generally accept four options: -* +:content_type+ -* +:layout+ -* +:status+ -* +:location+ +* `:content_type` +* `:layout` +* `:status` +* `:location` -##### The +:content_type+ Option +##### The `:content_type` Option -By default, Rails will serve the results of a rendering operation with the MIME content-type of +text/html+ (or +application/json+ if you use the +:json+ option, or +application/xml+ for the +:xml+ option.). There are times when you might like to change this, and you can do so by setting the +:content_type+ option: +By default, Rails will serve the results of a rendering operation with the MIME content-type of `text/html` (or `application/json` if you use the `:json` option, or `application/xml` for the `:xml` option.). There are times when you might like to change this, and you can do so by setting the `:content_type` option: ```ruby render :file => filename, :content_type => "application/rss" ``` -##### The +:layout+ Option +##### The `:layout` Option -With most of the options to +render+, the rendered content is displayed as part of the current layout. You'll learn more about layouts and how to use them later in this guide. +With most of the options to `render`, the rendered content is displayed as part of the current layout. You'll learn more about layouts and how to use them later in this guide. -You can use the +:layout+ option to tell Rails to use a specific file as the layout for the current action: +You can use the `:layout` option to tell Rails to use a specific file as the layout for the current action: ```ruby render :layout => "special_layout" @@ -326,9 +326,9 @@ You can also tell Rails to render with no layout at all: render :layout => false ``` -##### The +:status+ Option +##### The `:status` Option -Rails will automatically generate a response with the correct HTTP status code (in most cases, this is +200 OK+). You can use the +:status+ option to change this: +Rails will automatically generate a response with the correct HTTP status code (in most cases, this is `200 OK`). You can use the `:status` option to change this: ```ruby render :status => 500 @@ -337,9 +337,9 @@ render :status => :forbidden Rails understands both numeric and symbolic status codes. -##### The +:location+ Option +##### The `:location` Option -You can use the +:location+ option to set the HTTP +Location+ header: +You can use the `:location` option to set the HTTP `Location` header: ```ruby render :xml => photo, :location => photo_url(photo) @@ -347,11 +347,11 @@ render :xml => photo, :location => photo_url(photo) #### Finding Layouts -To find the current layout, Rails first looks for a file in +app/views/layouts+ with the same base name as the controller. For example, rendering actions from the +PhotosController+ class will use +app/views/layouts/photos.html.erb+ (or +app/views/layouts/photos.builder+). If there is no such controller-specific layout, Rails will use +app/views/layouts/application.html.erb+ or +app/views/layouts/application.builder+. If there is no +.erb+ layout, Rails will use a +.builder+ layout if one exists. Rails also provides several ways to more precisely assign specific layouts to individual controllers and actions. +To find the current layout, Rails first looks for a file in `app/views/layouts` with the same base name as the controller. For example, rendering actions from the `PhotosController` class will use `app/views/layouts/photos.html.erb` (or `app/views/layouts/photos.builder`). If there is no such controller-specific layout, Rails will use `app/views/layouts/application.html.erb` or `app/views/layouts/application.builder`. If there is no `.erb` layout, Rails will use a `.builder` layout if one exists. Rails also provides several ways to more precisely assign specific layouts to individual controllers and actions. ##### Specifying Layouts for Controllers -You can override the default layout conventions in your controllers by using the +layout+ declaration. For example: +You can override the default layout conventions in your controllers by using the `layout` declaration. For example: ```ruby class ProductsController < ApplicationController @@ -360,9 +360,9 @@ class ProductsController < ApplicationController end ``` -With this declaration, all of the views rendered by the products controller will use +app/views/layouts/inventory.html.erb+ as their layout. +With this declaration, all of the views rendered by the products controller will use `app/views/layouts/inventory.html.erb` as their layout. -To assign a specific layout for the entire application, use a +layout+ declaration in your +ApplicationController+ class: +To assign a specific layout for the entire application, use a `layout` declaration in your `ApplicationController` class: ```ruby class ApplicationController < ActionController::Base @@ -371,7 +371,7 @@ class ApplicationController < ActionController::Base end ``` -With this declaration, all of the views in the entire application will use +app/views/layouts/main.html.erb+ for their layout. +With this declaration, all of the views in the entire application will use `app/views/layouts/main.html.erb` for their layout. ##### Choosing Layouts at Runtime @@ -395,7 +395,7 @@ end Now, if the current user is a special user, they'll get a special layout when viewing a product. -You can even use an inline method, such as a Proc, to determine the layout. For example, if you pass a Proc object, the block you give the Proc will be given the +controller+ instance, so the layout can be determined based on the current request: +You can even use an inline method, such as a Proc, to determine the layout. For example, if you pass a Proc object, the block you give the Proc will be given the `controller` instance, so the layout can be determined based on the current request: ```ruby class ProductsController < ApplicationController @@ -405,7 +405,7 @@ end ##### Conditional Layouts -Layouts specified at the controller level support the +:only+ and +:except+ options. These options take either a method name, or an array of method names, corresponding to method names within the controller: +Layouts specified at the controller level support the `:only` and `:except` options. These options take either a method name, or an array of method names, corresponding to method names within the controller: ```ruby class ProductsController < ApplicationController @@ -413,13 +413,13 @@ class ProductsController < ApplicationController end ``` -With this declaration, the +product+ layout would be used for everything but the +rss+ and +index+ methods. +With this declaration, the `product` layout would be used for everything but the `rss` and `index` methods. ##### Layout Inheritance Layout declarations cascade downward in the hierarchy, and more specific layout declarations always override more general ones. For example: -* +application_controller.rb+ +* `application_controller.rb` ```ruby class ApplicationController < ActionController::Base @@ -427,14 +427,14 @@ class ApplicationController < ActionController::Base end ``` -* +posts_controller.rb+ +* `posts_controller.rb` ```ruby class PostsController < ApplicationController end ``` -* +special_posts_controller.rb+ +* `special_posts_controller.rb` ```ruby class SpecialPostsController < PostsController @@ -442,7 +442,7 @@ class SpecialPostsController < PostsController end ``` -* +old_posts_controller.rb+ +* `old_posts_controller.rb` ```ruby class OldPostsController < SpecialPostsController @@ -462,15 +462,15 @@ end In this application: -* In general, views will be rendered in the +main+ layout -* +PostsController#index+ will use the +main+ layout -* +SpecialPostsController#index+ will use the +special+ layout -* +OldPostsController#show+ will use no layout at all -* +OldPostsController#index+ will use the +old+ layout +* In general, views will be rendered in the `main` layout +* `PostsController#index` will use the `main` layout +* `SpecialPostsController#index` will use the `special` layout +* `OldPostsController#show` will use no layout at all +* `OldPostsController#index` will use the `old` layout #### Avoiding Double Render Errors -Sooner or later, most Rails developers will see the error message "Can only render or redirect once per action". While this is annoying, it's relatively easy to fix. Usually it happens because of a fundamental misunderstanding of the way that +render+ works. +Sooner or later, most Rails developers will see the error message "Can only render or redirect once per action". While this is annoying, it's relatively easy to fix. Usually it happens because of a fundamental misunderstanding of the way that `render` works. For example, here's some code that will trigger this error: @@ -484,7 +484,7 @@ def show end ``` -If +@book.special?+ evaluates to +true+, Rails will start the rendering process to dump the +@book+ variable into the +special_show+ view. But this will _not_ stop the rest of the code in the +show+ action from running, and when Rails hits the end of the action, it will start to render the +regular_show+ view - and throw an error. The solution is simple: make sure that you have only one call to +render+ or +redirect+ in a single code path. One thing that can help is +and return+. Here's a patched version of the method: +If `@book.special?` evaluates to `true`, Rails will start the rendering process to dump the `@book` variable into the `special_show` view. But this will _not_ stop the rest of the code in the `show` action from running, and when Rails hits the end of the action, it will start to render the `regular_show` view - and throw an error. The solution is simple: make sure that you have only one call to `render` or `redirect` in a single code path. One thing that can help is `and return`. Here's a patched version of the method: ```ruby def show @@ -496,9 +496,9 @@ def show end ``` -Make sure to use +and return+ instead of +&& return+ because +&& return+ will not work due to the operator precedence in the Ruby Language. +Make sure to use `and return` instead of `&& return` because `&& return` will not work due to the operator precedence in the Ruby Language. -Note that the implicit render done by ActionController detects if +render+ has been called, so the following will work without errors: +Note that the implicit render done by ActionController detects if `render` has been called, so the following will work without errors: ```ruby def show @@ -509,17 +509,17 @@ def show end ``` -This will render a book with +special?+ set with the +special_show+ template, while other books will render with the default +show+ template. +This will render a book with `special?` set with the `special_show` template, while other books will render with the default `show` template. -### Using +redirect_to+ +### Using `redirect_to` -Another way to handle returning responses to an HTTP request is with +redirect_to+. As you've seen, +render+ tells Rails which view (or other asset) to use in constructing a response. The +redirect_to+ method does something completely different: it tells the browser to send a new request for a different URL. For example, you could redirect from wherever you are in your code to the index of photos in your application with this call: +Another way to handle returning responses to an HTTP request is with `redirect_to`. As you've seen, `render` tells Rails which view (or other asset) to use in constructing a response. The `redirect_to` method does something completely different: it tells the browser to send a new request for a different URL. For example, you could redirect from wherever you are in your code to the index of photos in your application with this call: ```ruby redirect_to photos_url ``` -You can use +redirect_to+ with any arguments that you could use with +link_to+ or +url_for+. There's also a special redirect that sends the user back to the page they just came from: +You can use `redirect_to` with any arguments that you could use with `link_to` or `url_for`. There's also a special redirect that sends the user back to the page they just came from: ```ruby redirect_to :back @@ -527,17 +527,17 @@ redirect_to :back #### Getting a Different Redirect Status Code -Rails uses HTTP status code 302, a temporary redirect, when you call +redirect_to+. If you'd like to use a different status code, perhaps 301, a permanent redirect, you can use the +:status+ option: +Rails uses HTTP status code 302, a temporary redirect, when you call `redirect_to`. If you'd like to use a different status code, perhaps 301, a permanent redirect, you can use the `:status` option: ```ruby redirect_to photos_path, :status => 301 ``` -Just like the +:status+ option for +render+, +:status+ for +redirect_to+ accepts both numeric and symbolic header designations. +Just like the `:status` option for `render`, `:status` for `redirect_to` accepts both numeric and symbolic header designations. -#### The Difference Between +render+ and +redirect_to+ +#### The Difference Between `render` and `redirect_to` -Sometimes inexperienced developers think of +redirect_to+ as a sort of +goto+ command, moving execution from one place to another in your Rails code. This is _not_ correct. Your code stops running and waits for a new request for the browser. It just happens that you've told the browser what request it should make next, by sending back an HTTP 302 status code. +Sometimes inexperienced developers think of `redirect_to` as a sort of `goto` command, moving execution from one place to another in your Rails code. This is _not_ correct. Your code stops running and waits for a new request for the browser. It just happens that you've told the browser what request it should make next, by sending back an HTTP 302 status code. Consider these actions to see the difference: @@ -554,7 +554,7 @@ def show end ``` -With the code in this form, there will likely be a problem if the +@book+ variable is +nil+. Remember, a +render :action+ doesn't run any code in the target action, so nothing will set up the +@books+ variable that the +index+ view will probably require. One way to fix this is to redirect instead of rendering: +With the code in this form, there will likely be a problem if the `@book` variable is `nil`. Remember, a `render :action` doesn't run any code in the target action, so nothing will set up the `@books` variable that the `index` view will probably require. One way to fix this is to redirect instead of rendering: ```ruby def index @@ -569,9 +569,9 @@ def show end ``` -With this code, the browser will make a fresh request for the index page, the code in the +index+ method will run, and all will be well. +With this code, the browser will make a fresh request for the index page, the code in the `index` method will run, and all will be well. -The only downside to this code is that it requires a round trip to the browser: the browser requested the show action with +/books/1+ and the controller finds that there are no books, so the controller sends out a 302 redirect response to the browser telling it to go to +/books/+, the browser complies and sends a new request back to the controller asking now for the +index+ action, the controller then gets all the books in the database and renders the index template, sending it back down to the browser which then shows it on your screen. +The only downside to this code is that it requires a round trip to the browser: the browser requested the show action with `/books/1` and the controller finds that there are no books, so the controller sends out a 302 redirect response to the browser telling it to go to `/books/`, the browser complies and sends a new request back to the controller asking now for the `index` action, the controller then gets all the books in the database and renders the index template, sending it back down to the browser which then shows it on your screen. While in a small application, this added latency might not be a problem, it is something to think about if response time is a concern. We can demonstrate one way to handle this with a contrived example: @@ -589,11 +589,11 @@ def show end ``` -This would detect that there are no books with the specified ID, populate the +@books+ instance variable with all the books in the model, and then directly render the +index.html.erb+ template, returning it to the browser with a flash alert message to tell the user what happened. +This would detect that there are no books with the specified ID, populate the `@books` instance variable with all the books in the model, and then directly render the `index.html.erb` template, returning it to the browser with a flash alert message to tell the user what happened. -### Using +head+ To Build Header-Only Responses +### Using `head` To Build Header-Only Responses -The +head+ method can be used to send responses with only headers to the browser. It provides a more obvious alternative to calling +render :nothing+. The +head+ method takes one parameter, which is interpreted as a hash of header names and values. For example, you can return only an error header: +The `head` method can be used to send responses with only headers to the browser. It provides a more obvious alternative to calling `render :nothing`. The `head` method takes one parameter, which is interpreted as a hash of header names and values. For example, you can return only an error header: ```ruby head :bad_request @@ -638,54 +638,54 @@ Structuring Layouts When Rails renders a view as a response, it does so by combining the view with the current layout, using the rules for finding the current layout that were covered earlier in this guide. Within a layout, you have access to three tools for combining different bits of output to form the overall response: * Asset tags -* +yield+ and +content_for+ +* `yield` and `content_for` * Partials ### Asset Tag Helpers Asset tag helpers provide methods for generating HTML that link views to feeds, JavaScript, stylesheets, images, videos and audios. There are six asset tag helpers available in Rails: -* +auto_discovery_link_tag+ -* +javascript_include_tag+ -* +stylesheet_link_tag+ -* +image_tag+ -* +video_tag+ -* +audio_tag+ +* `auto_discovery_link_tag` +* `javascript_include_tag` +* `stylesheet_link_tag` +* `image_tag` +* `video_tag` +* `audio_tag` -You can use these tags in layouts or other views, although the +auto_discovery_link_tag+, +javascript_include_tag+, and +stylesheet_link_tag+, are most commonly used in the +<head>+ section of a layout. +You can use these tags in layouts or other views, although the `auto_discovery_link_tag`, `javascript_include_tag`, and `stylesheet_link_tag`, are most commonly used in the `<head>` section of a layout. WARNING: The asset tag helpers do _not_ verify the existence of the assets at the specified locations; they simply assume that you know what you're doing and generate the link. -#### Linking to Feeds with the +auto_discovery_link_tag+ +#### Linking to Feeds with the `auto_discovery_link_tag` -The +auto_discovery_link_tag+ helper builds HTML that most browsers and newsreaders can use to detect the presence of RSS or Atom feeds. It takes the type of the link (+:rss+ or +:atom+), a hash of options that are passed through to url_for, and a hash of options for the tag: +The `auto_discovery_link_tag` helper builds HTML that most browsers and newsreaders can use to detect the presence of RSS or Atom feeds. It takes the type of the link (`:rss` or `:atom`), a hash of options that are passed through to url_for, and a hash of options for the tag: ```erb <%= auto_discovery_link_tag(:rss, {:action => "feed"}, {:title => "RSS Feed"}) %> ``` -There are three tag options available for the +auto_discovery_link_tag+: +There are three tag options available for the `auto_discovery_link_tag`: -* +:rel+ specifies the +rel+ value in the link. The default value is "alternate". -* +:type+ specifies an explicit MIME type. Rails will generate an appropriate MIME type automatically. -* +:title+ specifies the title of the link. The default value is the uppercased +:type+ value, for example, "ATOM" or "RSS". +* `:rel` specifies the `rel` value in the link. The default value is "alternate". +* `:type` specifies an explicit MIME type. Rails will generate an appropriate MIME type automatically. +* `:title` specifies the title of the link. The default value is the uppercased `:type` value, for example, "ATOM" or "RSS". -#### Linking to JavaScript Files with the +javascript_include_tag+ +#### Linking to JavaScript Files with the `javascript_include_tag` -The +javascript_include_tag+ helper returns an HTML +script+ tag for each source provided. +The `javascript_include_tag` helper returns an HTML `script` tag for each source provided. -If you are using Rails with the "Asset Pipeline":asset_pipeline.html enabled, this helper will generate a link to +/assets/javascripts/+ rather than +public/javascripts+ which was used in earlier versions of Rails. This link is then served by the Sprockets gem, which was introduced in Rails 3.1. +If you are using Rails with the "Asset Pipeline":asset_pipeline.html enabled, this helper will generate a link to `/assets/javascripts/` rather than `public/javascripts` which was used in earlier versions of Rails. This link is then served by the Sprockets gem, which was introduced in Rails 3.1. -A JavaScript file within a Rails application or Rails engine goes in one of three locations: +app/assets+, +lib/assets+ or +vendor/assets+. These locations are explained in detail in the "Asset Organization section in the Asset Pipeline Guide":asset_pipeline.html#asset-organization +A JavaScript file within a Rails application or Rails engine goes in one of three locations: `app/assets`, `lib/assets` or `vendor/assets`. These locations are explained in detail in the "Asset Organization section in the Asset Pipeline Guide":asset_pipeline.html#asset-organization -You can specify a full path relative to the document root, or a URL, if you prefer. For example, to link to a JavaScript file that is inside a directory called +javascripts+ inside of one of +app/assets+, +lib/assets+ or +vendor/assets+, you would do this: +You can specify a full path relative to the document root, or a URL, if you prefer. For example, to link to a JavaScript file that is inside a directory called `javascripts` inside of one of `app/assets`, `lib/assets` or `vendor/assets`, you would do this: ```erb <%= javascript_include_tag "main" %> ``` -Rails will then output a +script+ tag such as this: +Rails will then output a `script` tag such as this: ```html <script src='/assets/main.js'></script> @@ -693,42 +693,42 @@ Rails will then output a +script+ tag such as this: The request to this asset is then served by the Sprockets gem. -To include multiple files such as +app/assets/javascripts/main.js+ and +app/assets/javascripts/columns.js+ at the same time: +To include multiple files such as `app/assets/javascripts/main.js` and `app/assets/javascripts/columns.js` at the same time: ```erb <%= javascript_include_tag "main", "columns" %> ``` -To include +app/assets/javascripts/main.js+ and +app/assets/javascripts/photos/columns.js+: +To include `app/assets/javascripts/main.js` and `app/assets/javascripts/photos/columns.js`: ```erb <%= javascript_include_tag "main", "/photos/columns" %> ``` -To include +http://example.com/main.js+: +To include `http://example.com/main.js`: ```erb <%= javascript_include_tag "http://example.com/main.js" %> ``` -If the application does not use the asset pipeline, the +:defaults+ option loads jQuery by default: +If the application does not use the asset pipeline, the `:defaults` option loads jQuery by default: ```erb <%= javascript_include_tag :defaults %> ``` -Outputting +script+ tags such as this: +Outputting `script` tags such as this: ```html <script src="/javascripts/jquery.js"></script> <script src="/javascripts/jquery_ujs.js"></script> ``` -These two files for jQuery, +jquery.js+ and +jquery_ujs.js+ must be placed inside +public/javascripts+ if the application doesn't use the asset pipeline. These files can be downloaded from the "jquery-rails repository on GitHub":https://github.com/indirect/jquery-rails/tree/master/vendor/assets/javascripts +These two files for jQuery, `jquery.js` and `jquery_ujs.js` must be placed inside `public/javascripts` if the application doesn't use the asset pipeline. These files can be downloaded from the "jquery-rails repository on GitHub":https://github.com/indirect/jquery-rails/tree/master/vendor/assets/javascripts -WARNING: If you are using the asset pipeline, this tag will render a +script+ tag for an asset called +defaults.js+, which would not exist in your application unless you've explicitly created it. +WARNING: If you are using the asset pipeline, this tag will render a `script` tag for an asset called `defaults.js`, which would not exist in your application unless you've explicitly created it. -And you can in any case override the +:defaults+ expansion in `config/application.rb`: +And you can in any case override the `:defaults` expansion in `config/application.rb`: ```ruby config.action_view.javascript_expansions[:defaults] = %w(foo.js bar.js) @@ -740,7 +740,7 @@ You can also define new defaults: config.action_view.javascript_expansions[:projects] = %w(projects.js tickets.js) ``` -And use them by referencing them exactly like +:defaults+: +And use them by referencing them exactly like `:defaults`: ```erb <%= javascript_include_tag :projects %> @@ -748,7 +748,7 @@ And use them by referencing them exactly like +:defaults+: When using `:defaults`, if an `application.js` file exists in `public/javascripts` it will be included as well at the end. -Also, if the asset pipeline is disabled, the +:all+ expansion loads every JavaScript file in +public/javascripts+: +Also, if the asset pipeline is disabled, the `:all` expansion loads every JavaScript file in `public/javascripts`: ```erb <%= javascript_include_tag :all %> @@ -756,95 +756,95 @@ Also, if the asset pipeline is disabled, the +:all+ expansion loads every JavaSc Note that your defaults of choice will be included first, so they will be available to all subsequently included files. -You can supply the +:recursive+ option to load files in subfolders of +public/javascripts+ as well: +You can supply the `:recursive` option to load files in subfolders of `public/javascripts` as well: ```erb <%= javascript_include_tag :all, :recursive => true %> ``` -If you're loading multiple JavaScript files, you can create a better user experience by combining multiple files into a single download. To make this happen in production, specify +:cache => true+ in your +javascript_include_tag+: +If you're loading multiple JavaScript files, you can create a better user experience by combining multiple files into a single download. To make this happen in production, specify `:cache => true` in your `javascript_include_tag`: ```erb <%= javascript_include_tag "main", "columns", :cache => true %> ``` -By default, the combined file will be delivered as +javascripts/all.js+. You can specify a location for the cached asset file instead: +By default, the combined file will be delivered as `javascripts/all.js`. You can specify a location for the cached asset file instead: ```erb <%= javascript_include_tag "main", "columns", :cache => "cache/main/display" %> ``` -You can even use dynamic paths such as +cache/#{current_site}/main/display+. +You can even use dynamic paths such as `cache/#{current_site}/main/display`. -#### Linking to CSS Files with the +stylesheet_link_tag+ +#### Linking to CSS Files with the `stylesheet_link_tag` -The +stylesheet_link_tag+ helper returns an HTML +<link>+ tag for each source provided. +The `stylesheet_link_tag` helper returns an HTML `<link>` tag for each source provided. -If you are using Rails with the "Asset Pipeline" enabled, this helper will generate a link to +/assets/stylesheets/+. This link is then processed by the Sprockets gem. A stylesheet file can be stored in one of three locations: +app/assets+, +lib/assets+ or +vendor/assets+. +If you are using Rails with the "Asset Pipeline" enabled, this helper will generate a link to `/assets/stylesheets/`. This link is then processed by the Sprockets gem. A stylesheet file can be stored in one of three locations: `app/assets`, `lib/assets` or `vendor/assets`. -You can specify a full path relative to the document root, or a URL. For example, to link to a stylesheet file that is inside a directory called +stylesheets+ inside of one of +app/assets+, +lib/assets+ or +vendor/assets+, you would do this: +You can specify a full path relative to the document root, or a URL. For example, to link to a stylesheet file that is inside a directory called `stylesheets` inside of one of `app/assets`, `lib/assets` or `vendor/assets`, you would do this: ```erb <%= stylesheet_link_tag "main" %> ``` -To include +app/assets/stylesheets/main.css+ and +app/assets/stylesheets/columns.css+: +To include `app/assets/stylesheets/main.css` and `app/assets/stylesheets/columns.css`: ```erb <%= stylesheet_link_tag "main", "columns" %> ``` -To include +app/assets/stylesheets/main.css+ and +app/assets/stylesheets/photos/columns.css+: +To include `app/assets/stylesheets/main.css` and `app/assets/stylesheets/photos/columns.css`: ```erb <%= stylesheet_link_tag "main", "/photos/columns" %> ``` -To include +http://example.com/main.css+: +To include `http://example.com/main.css`: ```erb <%= stylesheet_link_tag "http://example.com/main.css" %> ``` -By default, the +stylesheet_link_tag+ creates links with +media="screen" rel="stylesheet"+. You can override any of these defaults by specifying an appropriate option (+:media+, +:rel+): +By default, the `stylesheet_link_tag` creates links with `media="screen" rel="stylesheet"`. You can override any of these defaults by specifying an appropriate option (`:media`, `:rel`): ```erb <%= stylesheet_link_tag "main_print", :media => "print" %> ``` -If the asset pipeline is disabled, the +all+ option links every CSS file in +public/stylesheets+: +If the asset pipeline is disabled, the `all` option links every CSS file in `public/stylesheets`: ```erb <%= stylesheet_link_tag :all %> ``` -You can supply the +:recursive+ option to link files in subfolders of +public/stylesheets+ as well: +You can supply the `:recursive` option to link files in subfolders of `public/stylesheets` as well: ```erb <%= stylesheet_link_tag :all, :recursive => true %> ``` -If you're loading multiple CSS files, you can create a better user experience by combining multiple files into a single download. To make this happen in production, specify +:cache => true+ in your +stylesheet_link_tag+: +If you're loading multiple CSS files, you can create a better user experience by combining multiple files into a single download. To make this happen in production, specify `:cache => true` in your `stylesheet_link_tag`: ```erb <%= stylesheet_link_tag "main", "columns", :cache => true %> ``` -By default, the combined file will be delivered as +stylesheets/all.css+. You can specify a location for the cached asset file instead: +By default, the combined file will be delivered as `stylesheets/all.css`. You can specify a location for the cached asset file instead: ```erb <%= stylesheet_link_tag "main", "columns", :cache => "cache/main/display" %> ``` -You can even use dynamic paths such as +cache/#{current_site}/main/display+. +You can even use dynamic paths such as `cache/#{current_site}/main/display`. -#### Linking to Images with the +image_tag+ +#### Linking to Images with the `image_tag` -The +image_tag+ helper builds an HTML +<img />+ tag to the specified file. By default, files are loaded from +public/images+. +The `image_tag` helper builds an HTML `<img />` tag to the specified file. By default, files are loaded from `public/images`. -WARNING: Note that you must specify the extension of the image. Previous versions of Rails would allow you to just use the image name and would append +.png+ if no extension was given but Rails 3.0 does not. +WARNING: Note that you must specify the extension of the image. Previous versions of Rails would allow you to just use the image name and would append `.png` if no extension was given but Rails 3.0 does not. ```erb <%= image_tag "header.png" %> @@ -875,7 +875,7 @@ You can also specify a special size tag, in the format "{width}x{height}": <%= image_tag "home.gif", :size => "50x20" %> ``` -In addition to the above special tags, you can supply a final hash of standard HTML options, such as +:class+, +:id+ or +:name+: +In addition to the above special tags, you can supply a final hash of standard HTML options, such as `:class`, `:id` or `:name`: ```erb <%= image_tag "home.gif", :alt => "Go Home", @@ -883,9 +883,9 @@ In addition to the above special tags, you can supply a final hash of standard H :class => "nav_bar" %> ``` -#### Linking to Videos with the +video_tag+ +#### Linking to Videos with the `video_tag` -The +video_tag+ helper builds an HTML 5 +<video>+ tag to the specified file. By default, files are loaded from +public/videos+. +The `video_tag` helper builds an HTML 5 `<video>` tag to the specified file. By default, files are loaded from `public/videos`. ```erb <%= video_tag "movie.ogg" %> @@ -897,17 +897,17 @@ Produces <video src="/videos/movie.ogg" /> ``` -Like an +image_tag+ you can supply a path, either absolute, or relative to the +public/videos+ directory. Additionally you can specify the +:size => "#{width}x#{height}"+ option just like an +image_tag+. Video tags can also have any of the HTML options specified at the end (+id+, +class+ et al). +Like an `image_tag` you can supply a path, either absolute, or relative to the `public/videos` directory. Additionally you can specify the `:size => "#{width}x#{height}"` option just like an `image_tag`. Video tags can also have any of the HTML options specified at the end (`id`, `class` et al). -The video tag also supports all of the +<video>+ HTML options through the HTML options hash, including: +The video tag also supports all of the `<video>` HTML options through the HTML options hash, including: -* +:poster => "image_name.png"+, provides an image to put in place of the video before it starts playing. -* +:autoplay => true+, starts playing the video on page load. -* +:loop => true+, loops the video once it gets to the end. -* +:controls => true+, provides browser supplied controls for the user to interact with the video. -* +:autobuffer => true+, the video will pre load the file for the user on page load. +* `:poster => "image_name.png"`, provides an image to put in place of the video before it starts playing. +* `:autoplay => true`, starts playing the video on page load. +* `:loop => true`, loops the video once it gets to the end. +* `:controls => true`, provides browser supplied controls for the user to interact with the video. +* `:autobuffer => true`, the video will pre load the file for the user on page load. -You can also specify multiple videos to play by passing an array of videos to the +video_tag+: +You can also specify multiple videos to play by passing an array of videos to the `video_tag`: ```erb <%= video_tag ["trailer.ogg", "movie.ogg"] %> @@ -919,9 +919,9 @@ This will produce: <video><source src="trailer.ogg" /><source src="movie.ogg" /></video> ``` -#### Linking to Audio Files with the +audio_tag+ +#### Linking to Audio Files with the `audio_tag` -The +audio_tag+ helper builds an HTML 5 +<audio>+ tag to the specified file. By default, files are loaded from +public/audios+. +The `audio_tag` helper builds an HTML 5 `<audio>` tag to the specified file. By default, files are loaded from `public/audios`. ```erb <%= audio_tag "music.mp3" %> @@ -933,17 +933,17 @@ You can supply a path to the audio file if you like: <%= audio_tag "music/first_song.mp3" %> ``` -You can also supply a hash of additional options, such as +:id+, +:class+ etc. +You can also supply a hash of additional options, such as `:id`, `:class` etc. -Like the +video_tag+, the +audio_tag+ has special options: +Like the `video_tag`, the `audio_tag` has special options: -* +:autoplay => true+, starts playing the audio on page load -* +:controls => true+, provides browser supplied controls for the user to interact with the audio. -* +:autobuffer => true+, the audio will pre load the file for the user on page load. +* `:autoplay => true`, starts playing the audio on page load +* `:controls => true`, provides browser supplied controls for the user to interact with the audio. +* `:autobuffer => true`, the audio will pre load the file for the user on page load. -### Understanding +yield+ +### Understanding `yield` -Within the context of a layout, +yield+ identifies a section where content from the view should be inserted. The simplest way to use this is to have a single +yield+, into which the entire contents of the view currently being rendered is inserted: +Within the context of a layout, `yield` identifies a section where content from the view should be inserted. The simplest way to use this is to have a single `yield`, into which the entire contents of the view currently being rendered is inserted: ```erb <html> @@ -968,11 +968,11 @@ You can also create a layout with multiple yielding regions: </html> ``` -The main body of the view will always render into the unnamed +yield+. To render content into a named +yield+, you use the +content_for+ method. +The main body of the view will always render into the unnamed `yield`. To render content into a named `yield`, you use the `content_for` method. -### Using the +content_for+ Method +### Using the `content_for` Method -The +content_for+ method allows you to insert content into a named +yield+ block in your layout. For example, this view would work with the layout that you just saw: +The `content_for` method allows you to insert content into a named `yield` block in your layout. For example, this view would work with the layout that you just saw: ```erb <% content_for :head do %> @@ -995,7 +995,7 @@ The result of rendering this page into the supplied layout would be this HTML: </html> ``` -The +content_for+ method is very helpful when your layout contains distinct regions such as sidebars and footers that should get their own blocks of content inserted. It's also useful for inserting tags that load page-specific JavaScript or css files into the header of an otherwise generic layout. +The `content_for` method is very helpful when your layout contains distinct regions such as sidebars and footers that should get their own blocks of content inserted. It's also useful for inserting tags that load page-specific JavaScript or css files into the header of an otherwise generic layout. ### Using Partials @@ -1003,19 +1003,19 @@ Partial templates - usually just called "partials" - are another device for brea #### Naming Partials -To render a partial as part of a view, you use the +render+ method within the view: +To render a partial as part of a view, you use the `render` method within the view: ```ruby <%= render "menu" %> ``` -This will render a file named +_menu.html.erb+ at that point within the view being rendered. Note the leading underscore character: partials are named with a leading underscore to distinguish them from regular views, even though they are referred to without the underscore. This holds true even when you're pulling in a partial from another folder: +This will render a file named `_menu.html.erb` at that point within the view being rendered. Note the leading underscore character: partials are named with a leading underscore to distinguish them from regular views, even though they are referred to without the underscore. This holds true even when you're pulling in a partial from another folder: ```ruby <%= render "shared/menu" %> ``` -That code will pull in the partial from +app/views/shared/_menu.html.erb+. +That code will pull in the partial from `app/views/shared/_menu.html.erb`. #### Using Partials to Simplify Views @@ -1032,7 +1032,7 @@ One way to use partials is to treat them as the equivalent of subroutines: as a <%= render "shared/footer" %> ``` -Here, the +_ad_banner.html.erb+ and +_footer.html.erb+ partials could contain content that is shared among many pages in your application. You don't need to see the details of these sections when you're concentrating on a particular page. +Here, the `_ad_banner.html.erb` and `_footer.html.erb` partials could contain content that is shared among many pages in your application. You don't need to see the details of these sections when you're concentrating on a particular page. TIP: For content that is shared among all pages in your application, you can use partials directly from layouts. @@ -1044,15 +1044,15 @@ A partial can use its own layout file, just as a view can use a layout. For exam <%= render :partial => "link_area", :layout => "graybar" %> ``` -This would look for a partial named +_link_area.html.erb+ and render it using the layout +_graybar.html.erb+. Note that layouts for partials follow the same leading-underscore naming as regular partials, and are placed in the same folder with the partial that they belong to (not in the master +layouts+ folder). +This would look for a partial named `_link_area.html.erb` and render it using the layout `_graybar.html.erb`. Note that layouts for partials follow the same leading-underscore naming as regular partials, and are placed in the same folder with the partial that they belong to (not in the master `layouts` folder). -Also note that explicitly specifying +:partial+ is required when passing additional options such as +:layout+. +Also note that explicitly specifying `:partial` is required when passing additional options such as `:layout`. #### Passing Local Variables You can also pass local variables into partials, making them even more powerful and flexible. For example, you can use this technique to reduce duplication between new and edit pages, while still keeping a bit of distinct content: -* +new.html.erb+ +* `new.html.erb` ```erb <h1>New zone</h1> @@ -1060,7 +1060,7 @@ You can also pass local variables into partials, making them even more powerful <%= render :partial => "form", :locals => { :zone => @zone } %> ``` -* +edit.html.erb+ +* `edit.html.erb` ```erb <h1>Editing zone</h1> @@ -1068,7 +1068,7 @@ You can also pass local variables into partials, making them even more powerful <%= render :partial => "form", :locals => { :zone => @zone } %> ``` -* +_form.html.erb+ +* `_form.html.erb` ```erb <%= form_for(zone) do |f| %> @@ -1084,13 +1084,13 @@ You can also pass local variables into partials, making them even more powerful Although the same partial will be rendered into both views, Action View's submit helper will return "Create Zone" for the new action and "Update Zone" for the edit action. -Every partial also has a local variable with the same name as the partial (minus the underscore). You can pass an object in to this local variable via the +:object+ option: +Every partial also has a local variable with the same name as the partial (minus the underscore). You can pass an object in to this local variable via the `:object` option: ```erb <%= render :partial => "customer", :object => @new_customer %> ``` -Within the +customer+ partial, the +customer+ variable will refer to +@new_customer+ from the parent view. +Within the `customer` partial, the `customer` variable will refer to `@new_customer` from the parent view. WARNING: In previous versions of Rails, the default local variable would look for an instance variable with the same name as the partial in the parent. This behavior was deprecated in 2.3 and has been removed in Rails 3.0. @@ -1100,28 +1100,28 @@ If you have an instance of a model to render into a partial, you can use a short <%= render @customer %> ``` -Assuming that the +@customer+ instance variable contains an instance of the +Customer+ model, this will use +_customer.html.erb+ to render it and will pass the local variable +customer+ into the partial which will refer to the +@customer+ instance variable in the parent view. +Assuming that the `@customer` instance variable contains an instance of the `Customer` model, this will use `_customer.html.erb` to render it and will pass the local variable `customer` into the partial which will refer to the `@customer` instance variable in the parent view. #### Rendering Collections -Partials are very useful in rendering collections. When you pass a collection to a partial via the +:collection+ option, the partial will be inserted once for each member in the collection: +Partials are very useful in rendering collections. When you pass a collection to a partial via the `:collection` option, the partial will be inserted once for each member in the collection: -* +index.html.erb+ +* `index.html.erb` ```erb <h1>Products</h1> <%= render :partial => "product", :collection => @products %> ``` -* +_product.html.erb+ +* `_product.html.erb` ```erb <p>Product Name: <%= product.name %></p> ``` -When a partial is called with a pluralized collection, then the individual instances of the partial have access to the member of the collection being rendered via a variable named after the partial. In this case, the partial is +_product+, and within the +_product+ partial, you can refer to +product+ to get the instance that is being rendered. +When a partial is called with a pluralized collection, then the individual instances of the partial have access to the member of the collection being rendered via a variable named after the partial. In this case, the partial is `_product`, and within the `_product` partial, you can refer to `product` to get the instance that is being rendered. -In Rails 3.0, there is also a shorthand for this. Assuming +@products+ is a collection of +product+ instances, you can simply write this in the +index.html.erb+ to produce the same result: +In Rails 3.0, there is also a shorthand for this. Assuming `@products` is a collection of `product` instances, you can simply write this in the `index.html.erb` to produce the same result: ```erb <h1>Products</h1> @@ -1130,20 +1130,20 @@ In Rails 3.0, there is also a shorthand for this. Assuming +@products+ is a coll Rails determines the name of the partial to use by looking at the model name in the collection. In fact, you can even create a heterogeneous collection and render it this way, and Rails will choose the proper partial for each member of the collection: -* +index.html.erb+ +* `index.html.erb` ```erb <h1>Contacts</h1> <%= render [customer1, employee1, customer2, employee2] %> ``` -* +customers/_customer.html.erb+ +* `customers/_customer.html.erb` ```erb <p>Customer: <%= customer.name %></p> ``` -* +employees/_employee.html.erb+ +* `employees/_employee.html.erb` ```erb <p>Employee: <%= employee.name %></p> @@ -1151,7 +1151,7 @@ Rails determines the name of the partial to use by looking at the model name in In this case, Rails will use the customer or employee partials as appropriate for each member of the collection. -In the event that the collection is empty, +render+ will return nil, so it should be fairly simple to provide alternative content. +In the event that the collection is empty, `render` will return nil, so it should be fairly simple to provide alternative content. ```erb <h1>Products</h1> @@ -1160,26 +1160,26 @@ In the event that the collection is empty, +render+ will return nil, so it shoul #### Local Variables -To use a custom local variable name within the partial, specify the +:as+ option in the call to the partial: +To use a custom local variable name within the partial, specify the `:as` option in the call to the partial: ```erb <%= render :partial => "product", :collection => @products, :as => :item %> ``` -With this change, you can access an instance of the +@products+ collection as the +item+ local variable within the partial. +With this change, you can access an instance of the `@products` collection as the `item` local variable within the partial. -You can also pass in arbitrary local variables to any partial you are rendering with the +:locals => {}+ option: +You can also pass in arbitrary local variables to any partial you are rendering with the `:locals => {}` option: ```erb <%= render :partial => "products", :collection => @products, :as => :item, :locals => {:title => "Products Page"} %> ``` -Would render a partial +_products.html.erb+ once for each instance of +product+ in the +@products+ instance variable passing the instance to the partial as a local variable called +item+ and to each partial, make the local variable +title+ available with the value +Products Page+. +Would render a partial `_products.html.erb` once for each instance of `product` in the `@products` instance variable passing the instance to the partial as a local variable called `item` and to each partial, make the local variable `title` available with the value `Products Page`. -TIP: Rails also makes a counter variable available within a partial called by the collection, named after the member of the collection followed by +_counter+. For example, if you're rendering +@products+, within the partial you can refer to +product_counter+ to tell you how many times the partial has been rendered. This does not work in conjunction with the +:as => :value+ option. +TIP: Rails also makes a counter variable available within a partial called by the collection, named after the member of the collection followed by `_counter`. For example, if you're rendering `@products`, within the partial you can refer to `product_counter` to tell you how many times the partial has been rendered. This does not work in conjunction with the `:as => :value` option. -You can also specify a second partial to be rendered between instances of the main partial by using the +:spacer_template+ option: +You can also specify a second partial to be rendered between instances of the main partial by using the `:spacer_template` option: #### Spacer Templates @@ -1187,11 +1187,11 @@ You can also specify a second partial to be rendered between instances of the ma <%= render :partial => @products, :spacer_template => "product_ruler" %> ``` -Rails will render the +_product_ruler+ partial (with no data passed in to it) between each pair of +_product+ partials. +Rails will render the `_product_ruler` partial (with no data passed in to it) between each pair of `_product` partials. #### Partial Layouts -When rendering collections it is also possible to use the +:layout+ option: +When rendering collections it is also possible to use the `:layout` option: ```erb <%= render :partial => "product", :collection => @products, :layout => "special_layout" %> @@ -1203,9 +1203,9 @@ The layout will be rendered together with the partial for each item in the colle You may find that your application requires a layout that differs slightly from your regular application layout to support one particular controller. Rather than repeating the main layout and editing it, you can accomplish this by using nested layouts (sometimes called sub-templates). Here's an example: -Suppose you have the following +ApplicationController+ layout: +Suppose you have the following `ApplicationController` layout: -* +app/views/layouts/application.html.erb+ +* `app/views/layouts/application.html.erb` ```erb <html> @@ -1222,9 +1222,9 @@ Suppose you have the following +ApplicationController+ layout: </html> ``` -On pages generated by +NewsController+, you want to hide the top menu and add a right menu: +On pages generated by `NewsController`, you want to hide the top menu and add a right menu: -* +app/views/layouts/news.html.erb+ +* `app/views/layouts/news.html.erb` ```erb <% content_for :stylesheets do %> @@ -1240,4 +1240,4 @@ On pages generated by +NewsController+, you want to hide the top menu and add a That's it. The News views will use the new layout, hiding the top menu and adding a new right menu inside the "content" div. -There are several ways of getting similar results with different sub-templating schemes using this technique. Note that there is no limit in nesting levels. One can use the +ActionView::render+ method via +render :template => 'layouts/news'+ to base a new layout on the News layout. If you are sure you will not subtemplate the +News+ layout, you can replace the +content_for?(:news_content) ? yield(:news_content) : yield+ with simply +yield+. +There are several ways of getting similar results with different sub-templating schemes using this technique. Note that there is no limit in nesting levels. One can use the `ActionView::render` method via `render :template => 'layouts/news'` to base a new layout on the News layout. If you are sure you will not subtemplate the `News` layout, you can replace the `content_for?(:news_content) ? yield(:news_content) : yield` with simply `yield`. diff --git a/guides/source/migrations.md b/guides/source/migrations.md index fde7fecebd..f3db0d4b78 100644 --- a/guides/source/migrations.md +++ b/guides/source/migrations.md @@ -8,13 +8,13 @@ You'd also have to keep track of which changes need to be run against the production machines next time you deploy. Active Record tracks which migrations have already been run so all you have to -do is update your source and run +rake db:migrate+. Active Record will work out -which migrations should be run. Active Record will also update your +db/schema.rb+ file to match the up-to-date structure of your database. +do is update your source and run `rake db:migrate`. Active Record will work out +which migrations should be run. Active Record will also update your `db/schema.rb` file to match the up-to-date structure of your database. Migrations also allow you to describe these transformations using Ruby. The great thing about this is that (like most of Active Record's functionality) it is database independent: you don't need to worry about the precise syntax of -+CREATE TABLE+ any more than you worry about variations on +SELECT *+ (you can +`CREATE TABLE` any more than you worry about variations on `SELECT *` (you can drop down to raw SQL for database specific features). For example, you could use SQLite3 in development, but MySQL in production. @@ -23,7 +23,7 @@ In this guide, you'll learn all about migrations including: * The generators you can use to create them * The methods Active Record provides to manipulate your database * The Rake tasks that manipulate them -* How they relate to +schema.rb+ +* How they relate to `schema.rb` -------------------------------------------------------------------------------- @@ -50,10 +50,10 @@ class CreateProducts < ActiveRecord::Migration end ``` -This migration adds a table called +products+ with a string column called +name+ -and a text column called +description+. A primary key column called +id+ will +This migration adds a table called `products` with a string column called `name` +and a text column called `description`. A primary key column called `id` will also be added, however since this is the default we do not need to explicitly specify it. -The timestamp columns +created_at+ and +updated_at+ which Active Record +The timestamp columns `created_at` and `updated_at` which Active Record populates automatically will also be added. Reversing this migration is as simple as dropping the table. @@ -78,9 +78,9 @@ end NOTE: Some "caveats":#using-models-in-your-migrations apply to using models in your migrations. -This migration adds a +receive_newsletter+ column to the +users+ table. We want -it to default to +false+ for new users, but existing users are considered to -have already opted in, so we use the User model to set the flag to +true+ for +This migration adds a `receive_newsletter` column to the `users` table. We want +it to default to `false` for new users, but existing users are considered to +have already opted in, so we use the User model to set the flag to `true` for existing users. ### Using the change method @@ -88,7 +88,7 @@ existing users. Rails 3.1 makes migrations smarter by providing a new `change` method. This method is preferred for writing constructive migrations (adding columns or tables). The migration knows how to migrate your database and reverse it when -the migration is rolled back without the need to write a separate +down+ method. +the migration is rolled back without the need to write a separate `down` method. ```ruby class CreateProducts < ActiveRecord::Migration @@ -106,28 +106,28 @@ end ### Migrations are Classes A migration is a subclass of `ActiveRecord::Migration` that implements -two methods: +up+ (perform the required transformations) and +down+ (revert +two methods: `up` (perform the required transformations) and `down` (revert them). Active Record provides methods that perform common data definition tasks in a database independent way (you'll read about them in detail later): -* +add_column+ -* +add_reference+ -* +add_index+ -* +change_column+ -* +change_table+ -* +create_table+ -* +create_join_table+ -* +drop_table+ -* +remove_column+ -* +remove_index+ -* +rename_column+ -* +remove_reference+ +* `add_column` +* `add_reference` +* `add_index` +* `change_column` +* `change_table` +* `create_table` +* `create_join_table` +* `drop_table` +* `remove_column` +* `remove_index` +* `rename_column` +* `remove_reference` If you need to perform tasks specific to your database (e.g., create a "foreign key":#active-record-and-referential-integrity constraint) then the -+execute+ method allows you to execute arbitrary SQL. A migration is just a +`execute` method allows you to execute arbitrary SQL. A migration is just a regular Ruby class so you're not limited to these functions. For example, after adding a column you could write code to set the value of that column for existing records (if necessary using your models). @@ -140,15 +140,15 @@ the changes that were made by hand. ### What's in a Name -Migrations are stored as files in the +db/migrate+ directory, one for each +Migrations are stored as files in the `db/migrate` directory, one for each migration class. The name of the file is of the form -+YYYYMMDDHHMMSS_create_products.rb+, that is to say a UTC timestamp +`YYYYMMDDHHMMSS_create_products.rb`, that is to say a UTC timestamp identifying the migration followed by an underscore followed by the name of the migration. The name of the migration class (CamelCased version) should match the latter part of the file name. For example -+20080906120000_create_products.rb+ should define class +CreateProducts+ and -+20080906120001_add_details_to_products.rb+ should define -+AddDetailsToProducts+. If you do feel the need to change the file name then you +`20080906120000_create_products.rb` should define class `CreateProducts` and +`20080906120001_add_details_to_products.rb` should define +`AddDetailsToProducts`. If you do feel the need to change the file name then you <em>have to</em> update the name of the class inside or Rails will complain about a missing class. @@ -158,7 +158,7 @@ each time a migration was generated. With multiple developers it was easy for these to clash requiring you to rollback migrations and renumber them. With Rails 2.1+ this is largely avoided by using the creation time of the migration to identify them. You can revert to the old numbering scheme by adding the -following line to +config/application.rb+. +following line to `config/application.rb`. ```ruby config.active_record.timestamped_migrations = false @@ -167,10 +167,10 @@ config.active_record.timestamped_migrations = false The combination of timestamps and recording which migrations have been run allows Rails to handle common situations that occur with multiple developers. -For example, Alice adds migrations +20080906120000+ and +20080906123000+ and Bob -adds +20080906124500+ and runs it. Alice finishes her changes and checks in her -migrations and Bob pulls down the latest changes. When Bob runs +rake db:migrate+, -Rails knows that it has not run Alice's two migrations so it executes the +up+ method for each migration. +For example, Alice adds migrations `20080906120000` and `20080906123000` and Bob +adds `20080906124500` and runs it. Alice finishes her changes and checks in her +migrations and Bob pulls down the latest changes. When Bob runs `rake db:migrate`, +Rails knows that it has not run Alice's two migrations so it executes the `up` method for each migration. Of course this is no substitution for communication within the team. For example, if Alice's migration removed a table that Bob's migration assumed to @@ -181,8 +181,8 @@ exist, then trouble would certainly strike. Occasionally you will make a mistake when writing a migration. If you have already run the migration then you cannot just edit the migration and run the migration again: Rails thinks it has already run the migration and so will do -nothing when you run +rake db:migrate+. You must rollback the migration (for -example with +rake db:rollback+), edit your migration and then run +rake db:migrate+ to run the corrected version. +nothing when you run `rake db:migrate`. You must rollback the migration (for +example with `rake db:rollback`), edit your migration and then run `rake db:migrate` to run the corrected version. In general, editing existing migrations is not a good idea. You will be creating extra work for yourself and your co-workers and cause major headaches if the @@ -196,21 +196,21 @@ development machine) is relatively harmless. Active Record supports the following database column types: -* +:binary+ -* +:boolean+ -* +:date+ -* +:datetime+ -* +:decimal+ -* +:float+ -* +:integer+ -* +:primary_key+ -* +:string+ -* +:text+ -* +:time+ -* +:timestamp+ +* `:binary` +* `:boolean` +* `:date` +* `:datetime` +* `:decimal` +* `:float` +* `:integer` +* `:primary_key` +* `:string` +* `:text` +* `:time` +* `:timestamp` These will be mapped onto an appropriate underlying database type. For example, -with MySQL the type +:string+ is mapped to +VARCHAR(255)+. You can create +with MySQL the type `:string` is mapped to `VARCHAR(255)`. You can create columns of types not supported by Active Record when using the non-sexy syntax such as ```ruby @@ -251,8 +251,8 @@ end ``` You can append as many column name/type pairs as you want. By default, the -generated migration will include +t.timestamps+ (which creates the -+updated_at+ and +created_at+ columns that are automatically populated +generated migration will include `t.timestamps` (which creates the +`updated_at` and `created_at` columns that are automatically populated by Active Record). ### Creating a Standalone Migration @@ -275,7 +275,7 @@ end If the migration name is of the form "AddXXXToYYY" or "RemoveXXXFromYYY" and is followed by a list of column names and types then a migration containing the -appropriate +add_column+ and +remove_column+ statements will be created. +appropriate `add_column` and `remove_column` statements will be created. ```bash $ rails generate migration AddPartNumberToProducts part_number:string @@ -333,10 +333,10 @@ or remove from it as you see fit by editing the db/migrate/YYYYMMDDHHMMSS_add_details_to_products.rb file. NOTE: The generated migration file for destructive migrations will still be -old-style using the +up+ and +down+ methods. This is because Rails needs to know +old-style using the `up` and `down` methods. This is because Rails needs to know the original data types defined when you made the original changes. -Also, the generator accepts column type as +references+(also available as +belongs_to+). For instance +Also, the generator accepts column type as `references`(also available as `belongs_to`). For instance ```bash $ rails generate migration AddUserRefToProducts user:references @@ -359,10 +359,10 @@ This migration will create a user_id column and appropriate index. You can also specify some options just after the field type between curly braces. You can use the following modifiers: -* +limit+ Sets the maximum size of the +string/text/binary/integer+ fields -* +precision+ Defines the precision for the +decimal+ fields -* +scale+ Defines the scale for the +decimal+ fields -* +polymorphic+ Adds a +type+ column for +belongs_to+ associations +* `limit` Sets the maximum size of the `string/text/binary/integer` fields +* `precision` Defines the precision for the `decimal` fields +* `scale` Defines the scale for the `decimal` fields +* `polymorphic` Adds a `type` column for `belongs_to` associations For instance, running @@ -389,7 +389,7 @@ get to work! ### Creating a Table -Migration method +create_table+ will be one of your workhorses. A typical use +Migration method `create_table` will be one of your workhorses. A typical use would be ```ruby @@ -398,8 +398,8 @@ create_table :products do |t| end ``` -which creates a +products+ table with a column called +name+ (and as discussed -below, an implicit +id+ column). +which creates a `products` table with a column called `name` (and as discussed +below, an implicit `id` column). The object yielded to the block allows you to create columns on the table. There are two ways of doing it. The first (traditional) form looks like @@ -411,7 +411,7 @@ end ``` The second form, the so called "sexy" migration, drops the somewhat redundant -+column+ method. Instead, the +string+, +integer+, etc. methods create a column +`column` method. Instead, the `string`, `integer`, etc. methods create a column of that type. Subsequent parameters are the same. ```ruby @@ -420,12 +420,12 @@ create_table :products do |t| end ``` -By default, +create_table+ will create a primary key called +id+. You can change -the name of the primary key with the +:primary_key+ option (don't forget to +By default, `create_table` will create a primary key called `id`. You can change +the name of the primary key with the `:primary_key` option (don't forget to update the corresponding model) or, if you don't want a primary key at all (for -example for a HABTM join table), you can pass the option +:id => false+. If you +example for a HABTM join table), you can pass the option `:id => false`. If you need to pass database specific options you can place an SQL fragment in the -+:options+ option. For example, +`:options` option. For example, ```ruby create_table :products, :options => "ENGINE=BLACKHOLE" do |t| @@ -433,42 +433,42 @@ create_table :products, :options => "ENGINE=BLACKHOLE" do |t| end ``` -will append +ENGINE=BLACKHOLE+ to the SQL statement used to create the table -(when using MySQL, the default is +ENGINE=InnoDB+). +will append `ENGINE=BLACKHOLE` to the SQL statement used to create the table +(when using MySQL, the default is `ENGINE=InnoDB`). ### Creating a Join Table -Migration method +create_join_table+ creates a HABTM join table. A typical use +Migration method `create_join_table` creates a HABTM join table. A typical use would be ```ruby create_join_table :products, :categories ``` -which creates a +categories_products+ table with two columns called +category_id+ and +product_id+. -These columns have the option +:null+ set to +false+ by default. +which creates a `categories_products` table with two columns called `category_id` and `product_id`. +These columns have the option `:null` set to `false` by default. -You can pass the option +:table_name+ with you want to customize the table name. For example, +You can pass the option `:table_name` with you want to customize the table name. For example, ```ruby create_join_table :products, :categories, :table_name => :categorization ``` -will create a +categorization+ table. +will create a `categorization` table. -By default, +create_join_table+ will create two columns with no options, but you can specify these -options using the +:column_options+ option. For example, +By default, `create_join_table` will create two columns with no options, but you can specify these +options using the `:column_options` option. For example, ```ruby create_join_table :products, :categories, :column_options => {:null => true} ``` -will create the +product_id+ and +category_id+ with the +:null+ option as +true+. +will create the `product_id` and `category_id` with the `:null` option as `true`. ### Changing Tables -A close cousin of +create_table+ is +change_table+, used for changing existing -tables. It is used in a similar fashion to +create_table+ but the object yielded +A close cousin of `create_table` is `change_table`, used for changing existing +tables. It is used in a similar fashion to `create_table` but the object yielded to the block knows more tricks. For example ```ruby @@ -480,13 +480,13 @@ change_table :products do |t| end ``` -removes the +description+ and +name+ columns, creates a +part_number+ string -column and adds an index on it. Finally it renames the +upccode+ column. +removes the `description` and `name` columns, creates a `part_number` string +column and adds an index on it. Finally it renames the `upccode` column. ### Special Helpers Active Record provides some shortcuts for common functionality. It is for -example very common to add both the +created_at+ and +updated_at+ columns and so +example very common to add both the `created_at` and `updated_at` columns and so there is a method that does exactly that: ```ruby @@ -495,7 +495,7 @@ create_table :products do |t| end ``` -will create a new products table with those two columns (plus the +id+ column) +will create a new products table with those two columns (plus the `id` column) whereas ```ruby @@ -505,7 +505,7 @@ end ``` adds those columns to an existing table. -Another helper is called +references+ (also available as +belongs_to+). In its +Another helper is called `references` (also available as `belongs_to`). In its simplest form it just adds some readability. ```ruby @@ -514,9 +514,9 @@ create_table :products do |t| end ``` -will create a +category_id+ column of the appropriate type. Note that you pass -the model name, not the column name. Active Record adds the +_id+ for you. If -you have polymorphic +belongs_to+ associations then +references+ will add both +will create a `category_id` column of the appropriate type. Note that you pass +the model name, not the column name. Active Record adds the `_id` for you. If +you have polymorphic `belongs_to` associations then `references` will add both of the columns required: ```ruby @@ -525,9 +525,9 @@ create_table :products do |t| end ``` -will add an +attachment_id+ column and a string +attachment_type+ column with -a default value of 'Photo'. +references+ also allows you to define an -index directly, instead of using +add_index+ after the +create_table+ call: +will add an `attachment_id` column and a string `attachment_type` column with +a default value of 'Photo'. `references` also allows you to define an +index directly, instead of using `add_index` after the `create_table` call: ```ruby create_table :products do |t| @@ -537,48 +537,48 @@ end will create an index identical to calling `add_index :products, :category_id`. -NOTE: The +references+ helper does not actually create foreign key constraints -for you. You will need to use +execute+ or a plugin that adds "foreign key +NOTE: The `references` helper does not actually create foreign key constraints +for you. You will need to use `execute` or a plugin that adds "foreign key support":#active-record-and-referential-integrity. -If the helpers provided by Active Record aren't enough you can use the +execute+ +If the helpers provided by Active Record aren't enough you can use the `execute` method to execute arbitrary SQL. For more details and examples of individual methods, check the API documentation. In particular the documentation for "`ActiveRecord::ConnectionAdapters::SchemaStatements`":http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html -(which provides the methods available in the +up+ and +down+ methods), +(which provides the methods available in the `up` and `down` methods), "`ActiveRecord::ConnectionAdapters::TableDefinition`":http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/TableDefinition.html -(which provides the methods available on the object yielded by +create_table+) +(which provides the methods available on the object yielded by `create_table`) and "`ActiveRecord::ConnectionAdapters::Table`":http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/Table.html -(which provides the methods available on the object yielded by +change_table+). +(which provides the methods available on the object yielded by `change_table`). -### When to Use the +change+ Method +### Using the `change` Method -The +change+ method removes the need to write both +up+ and +down+ methods in +The `change` method removes the need to write both `up` and `down` methods in those cases that Rails knows how to revert the changes automatically. Currently, -the +change+ method supports only these migration definitions: +the `change` method supports only these migration definitions: -* +add_column+ -* +add_index+ -* +add_timestamps+ -* +create_table+ -* +remove_timestamps+ -* +rename_column+ -* +rename_index+ -* +rename_table+ +* `add_column` +* `add_index` +* `add_timestamps` +* `create_table` +* `remove_timestamps` +* `rename_column` +* `rename_index` +* `rename_table` If you're going to need to use any other methods, you'll have to write the -+up+ and +down+ methods instead of using the +change+ method. +`up` and `down` methods instead of using the `change` method. -### Using the +up+/+down+ Methods +### Using the `up`/`down` Methods -The +down+ method of your migration should revert the transformations done by -the +up+ method. In other words, the database schema should be unchanged if you -do an +up+ followed by a +down+. For example, if you create a table in the +up+ -method, you should drop it in the +down+ method. It is wise to reverse the -transformations in precisely the reverse order they were made in the +up+ +The `down` method of your migration should revert the transformations done by +the `up` method. In other words, the database schema should be unchanged if you +do an `up` followed by a `down`. For example, if you create a table in the `up` +method, you should drop it in the `down` method. It is wise to reverse the +transformations in precisely the reverse order they were made in the `up` method. For example, ```ruby @@ -612,7 +612,7 @@ end Sometimes your migration will do something which is just plain irreversible; for example, it might destroy some data. In such cases, you can raise -+ActiveRecord::IrreversibleMigration+ from your +down+ method. If someone tries +`ActiveRecord::IrreversibleMigration` from your `down` method. If someone tries to revert your migration, an error message will be displayed saying that it can't be done. @@ -623,12 +623,12 @@ Rails provides a set of rake tasks to work with migrations which boil down to running certain sets of migrations. The very first migration related rake task you will use will probably be -+rake db:migrate+. In its most basic form it just runs the +up+ or +change+ +`rake db:migrate`. In its most basic form it just runs the `up` or `change` method for all the migrations that have not yet been run. If there are no such migrations, it exits. It will run these migrations in order based on the date of the migration. -Note that running the +db:migrate+ also invokes the +db:schema:dump+ task, which +Note that running the `db:migrate` also invokes the `db:schema:dump` task, which will update your db/schema.rb file to match the structure of your database. If you specify a target version, Active Record will run the required migrations @@ -641,9 +641,9 @@ $ rake db:migrate VERSION=20080906120000 ``` If version 20080906120000 is greater than the current version (i.e., it is -migrating upwards), this will run the +up+ method on all migrations up to and +migrating upwards), this will run the `up` method on all migrations up to and including 20080906120000, and will not execute any later migrations. If -migrating downwards, this will run the +down+ method on all the migrations +migrating downwards, this will run the `down` method on all the migrations down to, but not including, 20080906120000. ### Rolling Back @@ -656,30 +656,30 @@ number associated with the previous migration you can run $ rake db:rollback ``` -This will run the +down+ method from the latest migration. If you need to undo -several migrations you can provide a +STEP+ parameter: +This will run the `down` method from the latest migration. If you need to undo +several migrations you can provide a `STEP` parameter: ```bash $ rake db:rollback STEP=3 ``` -will run the +down+ method from the last 3 migrations. +will run the `down` method from the last 3 migrations. -The +db:migrate:redo+ task is a shortcut for doing a rollback and then migrating -back up again. As with the +db:rollback+ task, you can use the +STEP+ parameter +The `db:migrate:redo` task is a shortcut for doing a rollback and then migrating +back up again. As with the `db:rollback` task, you can use the `STEP` parameter if you need to go more than one version back, for example ```bash $ rake db:migrate:redo STEP=3 ``` -Neither of these Rake tasks do anything you could not do with +db:migrate+. They +Neither of these Rake tasks do anything you could not do with `db:migrate`. They are simply more convenient, since you do not need to explicitly specify the version to migrate to. ### Resetting the Database -The +rake db:reset+ task will drop the database, recreate it and load the +The `rake db:reset` task will drop the database, recreate it and load the current schema into it. NOTE: This is not the same as running all the migrations - see the section on @@ -687,16 +687,16 @@ NOTE: This is not the same as running all the migrations - see the section on ### Running Specific Migrations -If you need to run a specific migration up or down, the +db:migrate:up+ and -+db:migrate:down+ tasks will do that. Just specify the appropriate version and -the corresponding migration will have its +up+ or +down+ method invoked, for +If you need to run a specific migration up or down, the `db:migrate:up` and +`db:migrate:down` tasks will do that. Just specify the appropriate version and +the corresponding migration will have its `up` or `down` method invoked, for example, ```bash $ rake db:migrate:up VERSION=20080906120000 ``` -will run the +up+ method from the 20080906120000 migration. This task will first +will run the `up` method from the 20080906120000 migration. This task will first check whether the migration is already performed and will do nothing if Active Record believes that it has already been run. @@ -759,8 +759,8 @@ generates the following output == CreateProducts: migrated (10.0054s) ======================================= ``` -If you want Active Record to not output anything, then running +rake db:migrate -VERBOSE=false+ will suppress all output. +If you want Active Record to not output anything, then running `rake db:migrate +VERBOSE=false` will suppress all output. Using Models in Your Migrations ------------------------------- @@ -774,12 +774,12 @@ not currently in the database and (2) will be created by this or a subsequent migration. Consider this example, where Alice and Bob are working on the same code base -which contains a +Product+ model: +which contains a `Product` model: Bob goes on vacation. -Alice creates a migration for the +products+ table which adds a new column and -initializes it. She also adds a validation to the +Product+ model for the new +Alice creates a migration for the `products` table which adds a new column and +initializes it. She also adds a validation to the `Product` model for the new column. ```ruby @@ -802,7 +802,7 @@ end ``` Alice adds a second migration which adds and initializes another column to the -+products+ table and also adds a validation to the +Product+ model for the new +`products` table and also adds a validation to the `Product` model for the new column. ```ruby @@ -830,8 +830,8 @@ Bob comes back from vacation and: # Updates the source - which contains both migrations and the latest version of the Product model. -# Runs outstanding migrations with +rake db:migrate+, which -includes the one that updates the +Product+ model. +# Runs outstanding migrations with `rake db:migrate`, which +includes the one that updates the `Product` model. The migration crashes because when the model attempts to save, it tries to validate the second added column, which is not in the database when the _first_ @@ -848,8 +848,8 @@ A fix for this is to create a local model within the migration. This keeps Rails from running the validations, so that the migrations run to completion. When using a faux model, it's a good idea to call -+Product.reset_column_information+ to refresh the +ActiveRecord+ cache for the -+Product+ model prior to updating data in the database. +`Product.reset_column_information` to refresh the `ActiveRecord` cache for the +`Product` model prior to updating data in the database. If Alice had done this instead, there would have been no problem: @@ -889,7 +889,7 @@ Schema Dumping and You ### What are Schema Files for? Migrations, mighty as they may be, are not the authoritative source for your -database schema. That role falls to either +db/schema.rb+ or an SQL file which +database schema. That role falls to either `db/schema.rb` or an SQL file which Active Record generates by examining the database. They are not designed to be edited, they just represent the current state of the database. @@ -898,7 +898,7 @@ replaying the entire migration history. It is much simpler and faster to just load into the database a description of the current schema. For example, this is how the test database is created: the current development -database is dumped (either to +db/schema.rb+ or +db/structure.sql+) and then +database is dumped (either to `db/schema.rb` or `db/structure.sql`) and then loaded into the test database. Schema files are also useful if you want a quick look at what attributes an @@ -911,11 +911,11 @@ you desire that functionality. ### Types of Schema Dumps -There are two ways to dump the schema. This is set in +config/application.rb+ by -the +config.active_record.schema_format+ setting, which may be either +:sql+ or -+:ruby+. +There are two ways to dump the schema. This is set in `config/application.rb` by +the `config.active_record.schema_format` setting, which may be either `:sql` or +`:ruby`. -If +:ruby+ is selected then the schema is stored in +db/schema.rb+. If you look +If `:ruby` is selected then the schema is stored in `db/schema.rb`. If you look at this file you'll find that it looks an awful lot like one very big migration: ```ruby @@ -937,24 +937,24 @@ end ``` In many ways this is exactly what it is. This file is created by inspecting the -database and expressing its structure using +create_table+, +add_index+, and so +database and expressing its structure using `create_table`, `add_index`, and so on. Because this is database-independent, it could be loaded into any database that Active Record supports. This could be very useful if you were to distribute an application that is able to run against multiple databases. -There is however a trade-off: +db/schema.rb+ cannot express database specific +There is however a trade-off: `db/schema.rb` cannot express database specific items such as foreign key constraints, triggers, or stored procedures. While in a migration you can execute custom SQL statements, the schema dumper cannot reconstitute those statements from the database. If you are using features like -this, then you should set the schema format to +:sql+. +this, then you should set the schema format to `:sql`. Instead of using Active Record's schema dumper, the database's structure will be -dumped using a tool specific to the database (via the +db:structure:dump+ Rake task) -into +db/structure.sql+. For example, for the PostgreSQL RDBMS, the -+pg_dump+ utility is used. For MySQL, this file will contain the output of +SHOW -CREATE TABLE+ for the various tables. Loading these schemas is simply a question +dumped using a tool specific to the database (via the `db:structure:dump` Rake task) +into `db/structure.sql`. For example, for the PostgreSQL RDBMS, the +`pg_dump` utility is used. For MySQL, this file will contain the output of `SHOW +CREATE TABLE` for the various tables. Loading these schemas is simply a question of executing the SQL statements they contain. By definition, this will create a -perfect copy of the database's structure. Using the +:sql+ schema format will, +perfect copy of the database's structure. Using the `:sql` schema format will, however, prevent loading the schema into a RDBMS other than the one used to create it. @@ -971,15 +971,15 @@ the database. As such, features such as triggers or foreign key constraints, which push some of that intelligence back into the database, are not heavily used. -Validations such as +validates :foreign_key, :uniqueness => true+ are one way in -which models can enforce data integrity. The +:dependent+ option on associations +Validations such as `validates :foreign_key, :uniqueness => true` are one way in +which models can enforce data integrity. The `:dependent` option on associations allows models to automatically destroy child objects when the parent is destroyed. Like anything which operates at the application level, these cannot guarantee referential integrity and so some people augment them with foreign key constraints in the database. Although Active Record does not provide any tools for working directly with such -features, the +execute+ method can be used to execute arbitrary SQL. You could +features, the `execute` method can be used to execute arbitrary SQL. You could also use some plugin like "foreigner":https://github.com/matthuhiggins/foreigner which add foreign key support to Active Record (including support for dumping -foreign keys in +db/schema.rb+). +foreign keys in `db/schema.rb`). diff --git a/guides/source/nested_model_forms.md b/guides/source/nested_model_forms.md index b87f82aefe..b4256c80bb 100644 --- a/guides/source/nested_model_forms.md +++ b/guides/source/nested_model_forms.md @@ -17,15 +17,15 @@ Model setup To be able to use the nested model functionality in your forms, the model will need to support some basic operations. -First of all, it needs to define a writer method for the attribute that corresponds to the association you are building a nested model form for. The +fields_for+ form helper will look for this method to decide whether or not a nested model form should be build. +First of all, it needs to define a writer method for the attribute that corresponds to the association you are building a nested model form for. The `fields_for` form helper will look for this method to decide whether or not a nested model form should be build. If the associated object is an array a form builder will be yielded for each object, else only a single form builder will be yielded. -Consider a Person model with an associated Address. When asked to yield a nested FormBuilder for the +:address+ attribute, the +fields_for+ form helper will look for a method on the Person instance named +address_attributes=+. +Consider a Person model with an associated Address. When asked to yield a nested FormBuilder for the `:address` attribute, the `fields_for` form helper will look for a method on the Person instance named `address_attributes=`. ### ActiveRecord::Base model -For an ActiveRecord::Base model and association this writer method is commonly defined with the +accepts_nested_attributes_for+ class method: +For an ActiveRecord::Base model and association this writer method is commonly defined with the `accepts_nested_attributes_for` class method: #### has_one @@ -95,7 +95,7 @@ Views A nested model form will _only_ be built if the associated object(s) exist. This means that for a new model instance you would probably want to build the associated object(s) first. -Consider the following typical RESTful controller which will prepare a new Person instance and its +address+ and +projects+ associations before rendering the +new+ template: +Consider the following typical RESTful controller which will prepare a new Person instance and its `address` and `projects` associations before rendering the `new` template: ```ruby class PeopleController < ActionController:Base @@ -114,7 +114,7 @@ class PeopleController < ActionController:Base end ``` -NOTE: Obviously the instantiation of the associated object(s) can become tedious and not DRY, so you might want to move that into the model itself. ActiveRecord::Base provides an +after_initialize+ callback which is a good way to refactor this. +NOTE: Obviously the instantiation of the associated object(s) can become tedious and not DRY, so you might want to move that into the model itself. ActiveRecord::Base provides an `after_initialize` callback which is a good way to refactor this. ### Form code @@ -140,7 +140,7 @@ This will generate the following html: #### Nested form for a single associated object -Now add a nested form for the +address+ association: +Now add a nested form for the `address` association: ```erb <%= form_for @person do |f| %> @@ -162,7 +162,7 @@ This generates: </form> ``` -Notice that +fields_for+ recognized the +address+ as an association for which a nested model form should be built by the way it has namespaced the +name+ attribute. +Notice that `fields_for` recognized the `address` as an association for which a nested model form should be built by the way it has namespaced the `name` attribute. When this form is posted the Rails parameter parser will construct a hash like the following: @@ -177,7 +177,7 @@ When this form is posted the Rails parameter parser will construct a hash like t } ``` -That’s it. The controller will simply pass this hash on to the model from the +create+ action. The model will then handle building the +address+ association for you and automatically save it when the parent (+person+) is saved. +That’s it. The controller will simply pass this hash on to the model from the `create` action. The model will then handle building the `address` association for you and automatically save it when the parent (`person`) is saved. #### Nested form for a collection of associated objects @@ -204,7 +204,7 @@ Which generates: </form> ``` -As you can see it has generated 2 +project name+ inputs, one for each new +project+ that was built in the controller's +new+ action. Only this time the +name+ attribute of the input contains a digit as an extra namespace. This will be parsed by the Rails parameter parser as: +As you can see it has generated 2 `project name` inputs, one for each new `project` that was built in the controller's `new` action. Only this time the `name` attribute of the input contains a digit as an extra namespace. This will be parsed by the Rails parameter parser as: ```ruby { @@ -218,8 +218,8 @@ As you can see it has generated 2 +project name+ inputs, one for each new +proje } ``` -You can basically see the +projects_attributes+ hash as an array of attribute hashes, one for each model instance. +You can basically see the `projects_attributes` hash as an array of attribute hashes, one for each model instance. -NOTE: The reason that +fields_for+ constructed a form which would result in a hash instead of an array is that it won't work for any forms nested deeper than one level deep. +NOTE: The reason that `fields_for` constructed a form which would result in a hash instead of an array is that it won't work for any forms nested deeper than one level deep. -TIP: You _can_ however pass an array to the writer method generated by +accepts_nested_attributes_for+ if you're using plain Ruby or some other API access. See (TODO) for more info and example. +TIP: You _can_ however pass an array to the writer method generated by `accepts_nested_attributes_for` if you're using plain Ruby or some other API access. See (TODO) for more info and example. diff --git a/guides/source/performance_testing.md b/guides/source/performance_testing.md index 0b9429260b..2d585e5926 100644 --- a/guides/source/performance_testing.md +++ b/guides/source/performance_testing.md @@ -27,7 +27,7 @@ benchmarking and profiling the test code. With performance tests, you can determine where your application's memory or speed problems are coming from, and get a more in-depth picture of those problems. -In a freshly generated Rails application, +test/performance/browsing_test.rb+ +In a freshly generated Rails application, `test/performance/browsing_test.rb` contains an example of a performance test: ```ruby @@ -50,14 +50,14 @@ the application's homepage. ### Generating Performance Tests -Rails provides a generator called +performance_test+ for creating new +Rails provides a generator called `performance_test` for creating new performance tests: ```bash $ rails generate performance_test homepage ``` -This generates +homepage_test.rb+ in the +test/performance+ directory: +This generates `homepage_test.rb` in the `test/performance` directory: ```ruby require 'test_helper' @@ -118,10 +118,10 @@ end #### Controller Example Because performance tests are a special kind of integration test, you can use -the +get+ and +post+ methods in them. +the `get` and `post` methods in them. -Here's the performance test for +HomeController#dashboard+ and -+PostsController#create+: +Here's the performance test for `HomeController#dashboard` and +`PostsController#create`: ```ruby require 'test_helper' @@ -143,7 +143,7 @@ class PostPerformanceTest < ActionDispatch::PerformanceTest end ``` -You can find more details about the +get+ and +post+ methods in the +You can find more details about the `get` and `post` methods in the "Testing Rails Applications":testing.html guide. #### Model Example @@ -152,7 +152,7 @@ Even though the performance tests are integration tests and hence closer to the request/response cycle by nature, you can still performance test pure model code. -Performance test for +Post+ model: +Performance test for `Post` model: ```ruby require 'test_helper' @@ -262,12 +262,12 @@ GC Time measures the amount of time spent in GC for the performance test case. |_.Rubinius | yes | no | no | no | no | no | no | no | |_.JRuby | yes | no | no | no | no | no | no | no | -NOTE: To profile under JRuby you'll need to run +export JRUBY_OPTS="-Xlaunch.inproc=false --profile.api"+ +NOTE: To profile under JRuby you'll need to run `export JRUBY_OPTS="-Xlaunch.inproc=false --profile.api"` *before* the performance tests. ### Understanding the Output -Performance tests generate different outputs inside +tmp/performance+ directory +Performance tests generate different outputs inside `tmp/performance` directory depending on their mode and metric. #### Benchmarking @@ -289,8 +289,8 @@ BrowsingTest#test_homepage (31 ms warmup) ##### CSV Files -Performance test results are also appended to +.csv+ files inside +tmp/performance+. -For example, running the default +BrowsingTest#test_homepage+ will generate +Performance test results are also appended to `.csv` files inside `tmp/performance`. +For example, running the default `BrowsingTest#test_homepage` will generate following five files: * BrowsingTest#test_homepage_gc_runs.csv @@ -303,7 +303,7 @@ As the results are appended to these files each time the performance tests are run in benchmarking mode, you can collect data over a period of time. This can be very helpful in analyzing the effects of code changes. -Sample output of +BrowsingTest#test_homepage_wall_time.csv+: +Sample output of `BrowsingTest#test_homepage_wall_time.csv`: ```bash measurement,created_at,app,rails,ruby,platform @@ -362,7 +362,7 @@ and similar tools. ### Tuning Test Runs -Test runs can be tuned by setting the +profile_options+ class variable on your +Test runs can be tuned by setting the `profile_options` class variable on your test class. ```ruby @@ -382,27 +382,27 @@ In this example, the test would run 5 times and measure wall time and memory. There are a few configurable options: |_.Option |_.Description|_.Default|_.Mode| -|+:runs+ |Number of runs.|Benchmarking: 4, Profiling: 1|Both| -|+:output+ |Directory to use when writing the results.|+tmp/performance+|Both| -|+:metrics+ |Metrics to use.|See below.|Both| -|+:formats+ |Formats to output to.|See below.|Profiling| +|`:runs` |Number of runs.|Benchmarking: 4, Profiling: 1|Both| +|`:output` |Directory to use when writing the results.|`tmp/performance`|Both| +|`:metrics` |Metrics to use.|See below.|Both| +|`:formats` |Formats to output to.|See below.|Profiling| Metrics and formats have different defaults depending on the interpreter in use. |_.Interpreter|_.Mode|_.Default metrics|_.Default formats| -|/2.MRI/REE |Benchmarking|+[:wall_time, :memory, :objects, :gc_runs, :gc_time]+|N/A| -|Profiling |+[:process_time, :memory, :objects]+|+[:flat, :graph_html, :call_tree, :call_stack]+| -|/2.Rubinius|Benchmarking|+[:wall_time, :memory, :objects, :gc_runs, :gc_time]+|N/A| -|Profiling |+[:wall_time]+|+[:flat, :graph]+| -|/2.JRuby |Benchmarking|+[:wall_time, :user_time, :memory, :gc_runs, :gc_time]+|N/A| -|Profiling |+[:wall_time]+|+[:flat, :graph]+| +|/2.MRI/REE |Benchmarking|`[:wall_time, :memory, :objects, :gc_runs, :gc_time]`|N/A| +|Profiling |`[:process_time, :memory, :objects]`|`[:flat, :graph_html, :call_tree, :call_stack]`| +|/2.Rubinius|Benchmarking|`[:wall_time, :memory, :objects, :gc_runs, :gc_time]`|N/A| +|Profiling |`[:wall_time]`|`[:flat, :graph]`| +|/2.JRuby |Benchmarking|`[:wall_time, :user_time, :memory, :gc_runs, :gc_time]`|N/A| +|Profiling |`[:wall_time]`|`[:flat, :graph]`| As you've probably noticed by now, metrics and formats are specified using a symbol array with each name "underscored.":http://api.rubyonrails.org/classes/String.html#method-i-underscore ### Performance Test Environment -Performance tests are run in the +test+ environment. But running performance +Performance tests are run in the `test` environment. But running performance tests will set the following configuration parameters: ```bash @@ -411,8 +411,8 @@ ActiveSupport::Dependencies.mechanism = :require Rails.logger.level = ActiveSupport::BufferedLogger::INFO ``` -As +ActionController::Base.perform_caching+ is set to +true+, performance tests -will behave much as they do in the +production+ environment. +As `ActionController::Base.perform_caching` is set to `true`, performance tests +will behave much as they do in the `production` environment. ### Installing GC-Patched MRI @@ -480,8 +480,8 @@ $ curl http://github.com/wayneeseguin/rvm/raw/master/patches/ruby/1.8.7/ruby187g ##### Configure and Install -The following will install Ruby in your home directory's +/rubygc+ directory. -Make sure to replace +<homedir>+ with a full patch to your actual home +The following will install Ruby in your home directory's `/rubygc` directory. +Make sure to replace `<homedir>` with a full patch to your actual home directory. ```bash @@ -491,7 +491,7 @@ $ make && make install ##### Prepare Aliases -For convenience, add the following lines in your +~/.profile+: +For convenience, add the following lines in your `~/.profile`: ```bash alias gcruby='~/rubygc/bin/ruby' @@ -512,7 +512,7 @@ under MRI or REE: gem 'ruby-prof', git: 'git://github.com/wycats/ruby-prof.git' ``` -Now run +bundle install+ and you're ready to go. +Now run `bundle install` and you're ready to go. Command Line Tools ------------------ @@ -521,7 +521,7 @@ Writing performance test cases could be an overkill when you are looking for one time tests. Rails ships with two command line tools that enable quick and dirty performance testing: -### +benchmarker+ +### `benchmarker` Usage: @@ -541,7 +541,7 @@ Example: $ rails benchmarker 'Item.all' 'CouchItem.all' --runs 3 --metrics wall_time,memory ``` -### +profiler+ +### `profiler` Usage: @@ -563,7 +563,7 @@ Example: $ rails profiler 'Item.all' 'CouchItem.all' --runs 2 --metrics process_time --formats flat ``` -NOTE: Metrics and formats vary from interpreter to interpreter. Pass +--help+ to +NOTE: Metrics and formats vary from interpreter to interpreter. Pass `--help` to each tool to see the defaults for your interpreter. Helper Methods @@ -571,7 +571,7 @@ Helper Methods Rails provides various helper methods inside Active Record, Action Controller and Action View to measure the time taken by a given piece of code. The method -is called +benchmark()+ in all the three components. +is called `benchmark()` in all the three components. ### Model @@ -583,7 +583,7 @@ Project.benchmark("Creating project") do end ``` -This benchmarks the code enclosed in the +Project.benchmark("Creating project") do...end+ +This benchmarks the code enclosed in the `Project.benchmark("Creating project") do...end` block and prints the result to the log file: ```ruby @@ -591,7 +591,7 @@ Creating project (185.3ms) ``` Please refer to the "API docs":http://api.rubyonrails.org/classes/ActiveSupport/Benchmarkable.html#method-i-benchmark -for additional options to +benchmark()+. +for additional options to `benchmark()`. ### Controller @@ -606,7 +606,7 @@ def process_projects end ``` -NOTE: +benchmark+ is a class method inside controllers. +NOTE: `benchmark` is a class method inside controllers. ### View diff --git a/guides/source/plugins.md b/guides/source/plugins.md index eecd4014b4..1d60db97ae 100644 --- a/guides/source/plugins.md +++ b/guides/source/plugins.md @@ -36,7 +36,7 @@ different rails applications using RubyGems and Bundler if desired. ### Generate a gemified plugin. -Rails 3.1 ships with a +rails plugin new+ command which creates a +Rails 3.1 ships with a `rails plugin new` command which creates a skeleton for developing any kind of Rails extension with the ability to run integration tests using a dummy Rails application. See usage and options by asking for help: @@ -48,8 +48,8 @@ $ rails plugin --help Testing your newly generated plugin ----------------------------------- -You can navigate to the directory that contains the plugin, run the +bundle install+ command - and run the one generated test using the +rake+ command. +You can navigate to the directory that contains the plugin, run the `bundle install` command + and run the one generated test using the `rake` command. You should see: @@ -64,7 +64,7 @@ Extending Core Classes This section will explain how to add a method to String that will be available anywhere in your rails application. -In this example you will add a method to String named +to_squawk+. To begin, create a new test file with a few assertions: +In this example you will add a method to String named `to_squawk`. To begin, create a new test file with a few assertions: ```ruby # yaffle/test/core_ext_test.rb @@ -78,7 +78,7 @@ class CoreExtTest < Test::Unit::TestCase end ``` -Run +rake+ to run the test. This test should fail because we haven't implemented the +to_squawk+ method: +Run `rake` to run the test. This test should fail because we haven't implemented the `to_squawk` method: ```bash 1) Error: @@ -89,7 +89,7 @@ Run +rake+ to run the test. This test should fail because we haven't implemented Great - now you are ready to start development. -Then in +lib/yaffle.rb+ require +lib/core_ext+: +Then in `lib/yaffle.rb` require `lib/core_ext`: ```ruby # yaffle/lib/yaffle.rb @@ -100,7 +100,7 @@ module Yaffle end ``` -Finally, create the +core_ext.rb+ file and add the +to_squawk+ method: +Finally, create the `core_ext.rb` file and add the `to_squawk` method: ```ruby # yaffle/lib/yaffle/core_ext.rb @@ -112,7 +112,7 @@ String.class_eval do end ``` -To test that your method does what it says it does, run the unit tests with +rake+ from your plugin directory. +To test that your method does what it says it does, run the unit tests with `rake` from your plugin directory. ```bash 3 tests, 3 assertions, 0 failures, 0 errors, 0 skips @@ -189,7 +189,7 @@ class ActsAsYaffleTest < Test::Unit::TestCase end ``` -When you run +rake+, you should see the following: +When you run `rake`, you should see the following: ```bash 1) Error: @@ -264,7 +264,7 @@ end ActiveRecord::Base.send :include, Yaffle::ActsAsYaffle ``` -You can then return to the root directory (+cd ../..+) of your plugin and rerun the tests using +rake+. +You can then return to the root directory (`cd ../..`) of your plugin and rerun the tests using `rake`. ```bash 1) Error: @@ -307,7 +307,7 @@ end ActiveRecord::Base.send :include, Yaffle::ActsAsYaffle ``` -When you run +rake+ you should see the tests all pass: +When you run `rake` you should see the tests all pass: ```bash 5 tests, 5 assertions, 0 failures, 0 errors, 0 skips @@ -381,13 +381,13 @@ end ActiveRecord::Base.send :include, Yaffle::ActsAsYaffle ``` -Run +rake+ one final time and you should see: +Run `rake` one final time and you should see: ```bash 7 tests, 7 assertions, 0 failures, 0 errors, 0 skips ``` -NOTE: The use of +write_attribute+ to write to the field in model is just one example of how a plugin can interact with the model, and will not always be the right method to use. For example, you could also use `send("#{self.class.yaffle_text_field}=", string.to_squawk)`. +NOTE: The use of `write_attribute` to write to the field in model is just one example of how a plugin can interact with the model, and will not always be the right method to use. For example, you could also use `send("#{self.class.yaffle_text_field}=", string.to_squawk)`. Generators ---------- @@ -405,7 +405,7 @@ commit the code to a Git repository (like GitHub) and add a line to the Gemfile gem 'yaffle', :git => 'git://github.com/yaffle_watcher/yaffle.git' ``` -After running +bundle install+, your gem functionality will be available to the application. +After running `bundle install`, your gem functionality will be available to the application. When the gem is ready to be shared as a formal release, it can be published to "RubyGems":http://www.rubygems.org. For more information about publishing gems to RubyGems, see: "Creating and Publishing Your First Ruby Gem":http://blog.thepete.net/2010/11/creating-and-publishing-your-first-ruby.html diff --git a/guides/source/rails_application_templates.md b/guides/source/rails_application_templates.md index b28c8d5e20..f0585efb11 100644 --- a/guides/source/rails_application_templates.md +++ b/guides/source/rails_application_templates.md @@ -20,7 +20,7 @@ $ rails new blog -m ~/template.rb $ rails new blog -m http://example.com/template.rb ``` -You can use the rake task +rails:template+ to apply templates to an existing Rails application. The location of the template needs to be passed in to an environment variable named LOCATION. Again, this can either be path to a file or a URL. +You can use the rake task `rails:template` to apply templates to an existing Rails application. The location of the template needs to be passed in to an environment variable named LOCATION. Again, this can either be path to a file or a URL. ```bash $ rake rails:template LOCATION=~/template.rb @@ -48,16 +48,16 @@ The following sections outlines the primary methods provided by the API: ### gem(name, options = {}) -Adds a +gem+ entry for the supplied gem to the generated application’s +Gemfile+. +Adds a `gem` entry for the supplied gem to the generated application’s `Gemfile`. -For example, if your application depends on the gems +bj+ and +nokogiri+: +For example, if your application depends on the gems `bj` and `nokogiri`: ```ruby gem "bj" gem "nokogiri" ``` -Please note that this will NOT install the gems for you and you will have to run +bundle install+ to do that. +Please note that this will NOT install the gems for you and you will have to run `bundle install` to do that. ```ruby bundle install @@ -67,7 +67,7 @@ bundle install Wraps gem entries inside a group. -For example, if you want to load +rspec-rails+ only in +development+ and +test+ group: +For example, if you want to load `rspec-rails` only in `development` and `test` group: ```ruby gem_group :development, :test do @@ -77,7 +77,7 @@ end ### add_source(source, options = {}) -Adds the given source to the generated application's +Gemfile+. +Adds the given source to the generated application's `Gemfile`. For example, if you need to source a gem from "http://code.whytheluckystiff.net": @@ -87,9 +87,9 @@ add_source "http://code.whytheluckystiff.net" ### vendor/lib/file/initializer(filename, data = nil, &block) -Adds an initializer to the generated application’s +config/initializers+ directory. +Adds an initializer to the generated application’s `config/initializers` directory. -Lets say you like using +Object#not_nil?+ and +Object#not_blank?+: +Lets say you like using `Object#not_nil?` and `Object#not_blank?`: ```ruby initializer 'bloatlol.rb', <<-CODE @@ -105,9 +105,9 @@ end CODE ``` -Similarly +lib()+ creates a file in the +lib/+ directory and +vendor()+ creates a file in the +vendor/+ directory. +Similarly `lib()` creates a file in the `lib/` directory and `vendor()` creates a file in the `vendor/` directory. -There is even +file()+, which accepts a relative path from +Rails.root+ and creates all the directories/file needed: +There is even `file()`, which accepts a relative path from `Rails.root` and creates all the directories/file needed: ```ruby file 'app/components/foo.rb', <<-CODE @@ -116,11 +116,11 @@ end CODE ``` -That’ll create +app/components+ directory and put +foo.rb+ in there. +That’ll create `app/components` directory and put `foo.rb` in there. ### rakefile(filename, data = nil, &block) -Creates a new rake file under +lib/tasks+ with the supplied tasks: +Creates a new rake file under `lib/tasks` with the supplied tasks: ```ruby rakefile("bootstrap.rake") do @@ -134,7 +134,7 @@ rakefile("bootstrap.rake") do end ``` -The above creates +lib/tasks/bootstrap.rake+ with a +boot:strap+ rake task. +The above creates `lib/tasks/bootstrap.rake` with a `boot:strap` rake task. ### generate(what, args) @@ -146,7 +146,7 @@ generate(:scaffold, "person", "name:string", "address:text", "age:number") ### run(command) -Executes an arbitrary command. Just like the backticks. Let's say you want to remove the +public/index.html+ file: +Executes an arbitrary command. Just like the backticks. Let's say you want to remove the `public/index.html` file: ```ruby run "rm public/index.html" @@ -168,7 +168,7 @@ rake "db:migrate", :env => 'production' ### route(routing_code) -This adds a routing entry to the +config/routes.rb+ file. In above steps, we generated a person scaffold and also removed +public/index.html+. Now to make +PeopleController#index+ as the default page for the application: +This adds a routing entry to the `config/routes.rb` file. In above steps, we generated a person scaffold and also removed `public/index.html`. Now to make `PeopleController#index` as the default page for the application: ```ruby route "root :to => 'person#index'" @@ -186,7 +186,7 @@ end ### ask(question) -+ask()+ gives you a chance to get some feedback from the user and use it in your templates. Lets say you want your user to name the new shiny library you’re adding: +`ask()` gives you a chance to get some feedback from the user and use it in your templates. Lets say you want your user to name the new shiny library you’re adding: ```ruby lib_name = ask("What do you want to call the shiny library ?") diff --git a/guides/source/rails_on_rack.md b/guides/source/rails_on_rack.md index 8fe10026a5..32251f2eae 100644 --- a/guides/source/rails_on_rack.md +++ b/guides/source/rails_on_rack.md @@ -10,7 +10,7 @@ This guide covers Rails integration with Rack and interfacing with other Rack co -------------------------------------------------------------------------------- -WARNING: This guide assumes a working knowledge of Rack protocol and Rack concepts such as middlewares, url maps and +Rack::Builder+. +WARNING: This guide assumes a working knowledge of Rack protocol and Rack concepts such as middlewares, url maps and `Rack::Builder`. Introduction to Rack -------------------- @@ -26,13 +26,13 @@ Rails on Rack ### Rails Application's Rack Object -`ApplicationName::Application` is the primary Rack application object of a Rails application. Any Rack compliant web server should be using +ApplicationName::Application+ object to serve a Rails application. +`ApplicationName::Application` is the primary Rack application object of a Rails application. Any Rack compliant web server should be using `ApplicationName::Application` object to serve a Rails application. -### +rails server+ +### `rails server` -`rails server` does the basic job of creating a +Rack::Server+ object and starting the webserver. +`rails server` does the basic job of creating a `Rack::Server` object and starting the webserver. -Here's how +rails server+ creates an instance of +Rack::Server+ +Here's how `rails server` creates an instance of `Rack::Server` ```ruby Rails::Server.new.tap { |server| @@ -42,7 +42,7 @@ Rails::Server.new.tap { |server| } ``` -The +Rails::Server+ inherits from +Rack::Server+ and calls the +Rack::Server#start+ method this way: +The `Rails::Server` inherits from `Rack::Server` and calls the `Rack::Server#start` method this way: ```ruby class Server < ::Rack::Server @@ -64,15 +64,15 @@ def middleware end ``` -+Rails::Rack::Debugger+ is primarily useful only in the development environment. The following table explains the usage of the loaded middlewares: +`Rails::Rack::Debugger` is primarily useful only in the development environment. The following table explains the usage of the loaded middlewares: |_.Middleware|_.Purpose| -|+Rails::Rack::Debugger+|Starts Debugger| -|+Rack::ContentLength+|Counts the number of bytes in the response and set the HTTP Content-Length header| +|`Rails::Rack::Debugger`|Starts Debugger| +|`Rack::ContentLength`|Counts the number of bytes in the response and set the HTTP Content-Length header| -### +rackup+ +### `rackup` -To use +rackup+ instead of Rails' +rails server+, you can put the following inside +config.ru+ of your Rails application's root directory: +To use `rackup` instead of Rails' `rails server`, you can put the following inside `config.ru` of your Rails application's root directory: ```ruby # Rails.root/config.ru @@ -89,7 +89,7 @@ And start the server: $ rackup config.ru ``` -To find out more about different +rackup+ options: +To find out more about different `rackup` options: ```bash $ rackup --help @@ -98,9 +98,9 @@ $ rackup --help Action Dispatcher Middleware Stack ---------------------------------- -Many of Action Dispatchers's internal components are implemented as Rack middlewares. +Rails::Application+ uses +ActionDispatch::MiddlewareStack+ to combine various internal and external middlewares to form a complete Rails Rack application. +Many of Action Dispatchers's internal components are implemented as Rack middlewares. `Rails::Application` uses `ActionDispatch::MiddlewareStack` to combine various internal and external middlewares to form a complete Rails Rack application. -NOTE: +ActionDispatch::MiddlewareStack+ is Rails' equivalent of +Rack::Builder+, but built for better flexibility and more features to meet Rails' requirements. +NOTE: `ActionDispatch::MiddlewareStack` is Rails' equivalent of `Rack::Builder`, but built for better flexibility and more features to meet Rails' requirements. ### Inspecting Middleware Stack @@ -142,7 +142,7 @@ Purpose of each of this middlewares is explained in the "Internal Middlewares":# ### Configuring Middleware Stack -Rails provides a simple configuration interface +config.middleware+ for adding, removing and modifying the middlewares in the middleware stack via +application.rb+ or the environment specific configuration file `environments/<environment>.rb`. +Rails provides a simple configuration interface `config.middleware` for adding, removing and modifying the middlewares in the middleware stack via `application.rb` or the environment specific configuration file `environments/<environment>.rb`. #### Adding a Middleware @@ -167,7 +167,7 @@ config.middleware.insert_after ActiveRecord::QueryCache, Lifo::Cache, :page_cach #### Swapping a Middleware -You can swap an existing middleware in the middleware stack using +config.middleware.swap+. +You can swap an existing middleware in the middleware stack using `config.middleware.swap`. ```ruby # config/application.rb @@ -178,7 +178,7 @@ config.middleware.swap ActionDispatch::ShowExceptions, Lifo::ShowExceptions #### Middleware Stack is an Enumerable -The middleware stack behaves just like a normal +Enumerable+. You can use any +Enumerable+ methods to manipulate or interrogate the stack. The middleware stack also implements some +Array+ methods including `[]`, +unshift+ and +delete+. Methods described in the section above are just convenience methods. +The middleware stack behaves just like a normal `Enumerable`. You can use any `Enumerable` methods to manipulate or interrogate the stack. The middleware stack also implements some `Array` methods including `[]`, `unshift` and `delete`. Methods described in the section above are just convenience methods. Append following lines to your application configuration: @@ -187,7 +187,7 @@ Append following lines to your application configuration: config.middleware.delete "Rack::Lock" ``` -And now if you inspect the middleware stack, you'll find that +Rack::Lock+ will not be part of it. +And now if you inspect the middleware stack, you'll find that `Rack::Lock` will not be part of it. ```bash $ rake middleware @@ -220,77 +220,77 @@ config.middleware.delete "Rack::MethodOverride" Much of Action Controller's functionality is implemented as Middlewares. The following list explains the purpose of each of them: - *+ActionDispatch::Static+* + *`ActionDispatch::Static`* * Used to serve static assets. Disabled if `config.serve_static_assets` is true. - *+Rack::Lock+* -* Sets `env["rack.multithread"]` flag to +true+ and wraps the application within a Mutex. + *`Rack::Lock`* +* Sets `env["rack.multithread"]` flag to `true` and wraps the application within a Mutex. - *+ActiveSupport::Cache::Strategy::LocalCache::Middleware+* + *`ActiveSupport::Cache::Strategy::LocalCache::Middleware`* * Used for memory caching. This cache is not thread safe. - *+Rack::Runtime+* + *`Rack::Runtime`* * Sets an X-Runtime header, containing the time (in seconds) taken to execute the request. - *+Rack::MethodOverride+* + *`Rack::MethodOverride`* * Allows the method to be overridden if `params[:_method]` is set. This is the middleware which supports the PUT and DELETE HTTP method types. - *+ActionDispatch::RequestId+* -* Makes a unique +X-Request-Id+ header available to the response and enables the `ActionDispatch::Request#uuid` method. + *`ActionDispatch::RequestId`* +* Makes a unique `X-Request-Id` header available to the response and enables the `ActionDispatch::Request#uuid` method. - *+Rails::Rack::Logger+* + *`Rails::Rack::Logger`* * Notifies the logs that the request has began. After request is complete, flushes all the logs. - *+ActionDispatch::ShowExceptions+* + *`ActionDispatch::ShowExceptions`* * Rescues any exception returned by the application and calls an exceptions app that will wrap it in a format for the end user. - *+ActionDispatch::DebugExceptions+* + *`ActionDispatch::DebugExceptions`* * Responsible for logging exceptions and showing a debugging page in case the request is local. - *+ActionDispatch::RemoteIp+* + *`ActionDispatch::RemoteIp`* * Checks for IP spoofing attacks. - *+ActionDispatch::Reloader+* + *`ActionDispatch::Reloader`* * Provides prepare and cleanup callbacks, intended to assist with code reloading during development. - *+ActionDispatch::Callbacks+* + *`ActionDispatch::Callbacks`* * Runs the prepare callbacks before serving the request. - *+ActiveRecord::ConnectionAdapters::ConnectionManagement+* -* Cleans active connections after each request, unless the `rack.test` key in the request environment is set to +true+. + *`ActiveRecord::ConnectionAdapters::ConnectionManagement`* +* Cleans active connections after each request, unless the `rack.test` key in the request environment is set to `true`. - *+ActiveRecord::QueryCache+* + *`ActiveRecord::QueryCache`* * Enables the Active Record query cache. - *+ActionDispatch::Cookies+* + *`ActionDispatch::Cookies`* * Sets cookies for the request. - *+ActionDispatch::Session::CookieStore+* + *`ActionDispatch::Session::CookieStore`* * Responsible for storing the session in cookies. - *+ActionDispatch::Flash+* + *`ActionDispatch::Flash`* * Sets up the flash keys. Only available if `config.action_controller.session_store` is set to a value. - *+ActionDispatch::ParamsParser+* + *`ActionDispatch::ParamsParser`* * Parses out parameters from the request into `params`. - *+ActionDispatch::Head+* -* Converts HEAD requests to +GET+ requests and serves them as so. + *`ActionDispatch::Head`* +* Converts HEAD requests to `GET` requests and serves them as so. - *+Rack::ConditionalGet+* -* Adds support for "Conditional +GET+" so that server responds with nothing if page wasn't changed. + *`Rack::ConditionalGet`* +* Adds support for "Conditional `GET`" so that server responds with nothing if page wasn't changed. - *+Rack::ETag+* + *`Rack::ETag`* * Adds ETag header on all String bodies. ETags are used to validate cache. - *+ActionDispatch::BestStandardsSupport+* + *`ActionDispatch::BestStandardsSupport`* * Enables “best standards support” so that IE8 renders some elements correctly. TIP: It's possible to use any of the above middlewares in your custom Rack stack. ### Using Rack Builder -The following shows how to replace use +Rack::Builder+ instead of the Rails supplied +MiddlewareStack+. +The following shows how to replace use `Rack::Builder` instead of the Rails supplied `MiddlewareStack`. <strong>Clear the existing Rails middleware stack</strong> @@ -300,7 +300,7 @@ config.middleware.clear ``` <br /> -<strong>Add a +config.ru+ file to +Rails.root+</strong> +<strong>Add a `config.ru` file to `Rails.root`</strong> ```ruby # config.ru diff --git a/guides/source/routing.md b/guides/source/routing.md index 28afcfcc28..8166b165e3 100644 --- a/guides/source/routing.md +++ b/guides/source/routing.md @@ -3,7 +3,7 @@ Rails Routing from the Outside In This guide covers the user-facing features of Rails routing. By referring to this guide, you will be able to: -* Understand the code in +routes.rb+ +* Understand the code in `routes.rb` * Construct your own routes, using either the preferred resourceful style or the `match` method * Identify what parameters to expect an action to receive * Automatically create paths and URLs using route helpers @@ -30,7 +30,7 @@ it asks the router to match it to a controller action. If the first matching rou get "/patients/:id" => "patients#show" ``` -the request is dispatched to the +patients+ controller's +show+ action with `{ :id => "17" }` in +params+. +the request is dispatched to the `patients` controller's `show` action with `{ :id => "17" }` in `params`. ### Generating Paths and URLs from Code @@ -50,16 +50,16 @@ If your application contains this code: <%= link_to "Patient Record", patient_path(@patient) %> ``` -The router will generate the path +/patients/17+. This reduces the brittleness of your view and makes your code easier to understand. Note that the id does not need to be specified in the route helper. +The router will generate the path `/patients/17`. This reduces the brittleness of your view and makes your code easier to understand. Note that the id does not need to be specified in the route helper. Resource Routing: the Rails Default ----------------------------------- -Resource routing allows you to quickly declare all of the common routes for a given resourceful controller. Instead of declaring separate routes for your +index+, +show+, +new+, +edit+, +create+, +update+ and +destroy+ actions, a resourceful route declares them in a single line of code. +Resource routing allows you to quickly declare all of the common routes for a given resourceful controller. Instead of declaring separate routes for your `index`, `show`, `new`, `edit`, `create`, `update` and `destroy` actions, a resourceful route declares them in a single line of code. ### Resources on the Web -Browsers request pages from Rails by making a request for a URL using a specific HTTP method, such as +GET+, +POST+, +PATCH+, +PUT+ and +DELETE+. Each method is a request to perform an operation on the resource. A resource route maps a number of related requests to actions in a single controller. +Browsers request pages from Rails by making a request for a URL using a specific HTTP method, such as `GET`, `POST`, `PATCH`, `PUT` and `DELETE`. Each method is a request to perform an operation on the resource. A resource route maps a number of related requests to actions in a single controller. When your Rails application receives an incoming request for @@ -73,7 +73,7 @@ it asks the router to map it to a controller action. If the first matching route resources :photos ``` -Rails would dispatch that request to the +destroy+ method on the +photos+ controller with `{ :id => "17" }` in +params+. +Rails would dispatch that request to the `destroy` method on the `photos` controller with `{ :id => "17" }` in `params`. ### CRUD, Verbs, and Actions @@ -83,7 +83,7 @@ In Rails, a resourceful route provides a mapping between HTTP verbs and URLs to resources :photos ``` -creates seven different routes in your application, all mapping to the +Photos+ controller: +creates seven different routes in your application, all mapping to the `Photos` controller: |_. HTTP Verb |_.Path |_.action |_.used for | |GET |/photos |index |display a list of all photos | @@ -94,24 +94,24 @@ creates seven different routes in your application, all mapping to the +Photos+ |PATCH/PUT |/photos/:id |update |update a specific photo | |DELETE |/photos/:id |destroy |delete a specific photo | -NOTE: Rails routes are matched in the order they are specified, so if you have a +resources :photos+ above a +get 'photos/poll'+ the +show+ action's route for the +resources+ line will be matched before the +get+ line. To fix this, move the +get+ line *above* the +resources+ line so that it is matched first. +NOTE: Rails routes are matched in the order they are specified, so if you have a `resources :photos` above a `get 'photos/poll'` the `show` action's route for the `resources` line will be matched before the `get` line. To fix this, move the `get` line *above* the `resources` line so that it is matched first. ### Paths and URLs -Creating a resourceful route will also expose a number of helpers to the controllers in your application. In the case of +resources :photos+: +Creating a resourceful route will also expose a number of helpers to the controllers in your application. In the case of `resources :photos`: -* +photos_path+ returns +/photos+ -* +new_photo_path+ returns +/photos/new+ -* +edit_photo_path(:id)+ returns +/photos/:id/edit+ (for instance, +edit_photo_path(10)+ returns +/photos/10/edit+) -* +photo_path(:id)+ returns +/photos/:id+ (for instance, +photo_path(10)+ returns +/photos/10+) +* `photos_path` returns `/photos` +* `new_photo_path` returns `/photos/new` +* `edit_photo_path(:id)` returns `/photos/:id/edit` (for instance, `edit_photo_path(10)` returns `/photos/10/edit`) +* `photo_path(:id)` returns `/photos/:id` (for instance, `photo_path(10)` returns `/photos/10`) -Each of these helpers has a corresponding +_url+ helper (such as +photos_url+) which returns the same path prefixed with the current host, port and path prefix. +Each of these helpers has a corresponding `_url` helper (such as `photos_url`) which returns the same path prefixed with the current host, port and path prefix. NOTE: Because the router uses the HTTP verb and URL to match inbound requests, four URLs map to seven different actions. ### Defining Multiple Resources at the Same Time -If you need to create routes for more than one resource, you can save a bit of typing by defining them all with a single call to +resources+: +If you need to create routes for more than one resource, you can save a bit of typing by defining them all with a single call to `resources`: ```ruby resources :photos, :books, :videos @@ -127,7 +127,7 @@ resources :videos ### Singular Resources -Sometimes, you have a resource that clients always look up without referencing an ID. For example, you would like +/profile+ to always show the profile of the currently logged in user. In this case, you can use a singular resource to map +/profile+ (rather than +/profile/:id+) to the +show+ action. +Sometimes, you have a resource that clients always look up without referencing an ID. For example, you would like `/profile` to always show the profile of the currently logged in user. In this case, you can use a singular resource to map `/profile` (rather than `/profile/:id`) to the `show` action. ```ruby get "profile" => "users#show" @@ -139,7 +139,7 @@ This resourceful route resource :geocoder ``` -creates six different routes in your application, all mapping to the +Geocoders+ controller: +creates six different routes in your application, all mapping to the `Geocoders` controller: |_.HTTP Verb |_.Path |_.action |_.used for | |GET |/geocoder/new |new |return an HTML form for creating the geocoder | @@ -149,19 +149,19 @@ creates six different routes in your application, all mapping to the +Geocoders+ |PATCH/PUT |/geocoder |update |update the one and only geocoder resource | |DELETE |/geocoder |destroy |delete the geocoder resource | -NOTE: Because you might want to use the same controller for a singular route (+/account+) and a plural route (+/accounts/45+), singular resources map to plural controllers. +NOTE: Because you might want to use the same controller for a singular route (`/account`) and a plural route (`/accounts/45`), singular resources map to plural controllers. A singular resourceful route generates these helpers: -* +new_geocoder_path+ returns +/geocoder/new+ -* +edit_geocoder_path+ returns +/geocoder/edit+ -* +geocoder_path+ returns +/geocoder+ +* `new_geocoder_path` returns `/geocoder/new` +* `edit_geocoder_path` returns `/geocoder/edit` +* `geocoder_path` returns `/geocoder` -As with plural resources, the same helpers ending in +_url+ will also include the host, port and path prefix. +As with plural resources, the same helpers ending in `_url` will also include the host, port and path prefix. ### Controller Namespaces and Routing -You may wish to organize groups of controllers under a namespace. Most commonly, you might group a number of administrative controllers under an +Admin::+ namespace. You would place these controllers under the +app/controllers/admin+ directory, and you can group them together in your router: +You may wish to organize groups of controllers under a namespace. Most commonly, you might group a number of administrative controllers under an `Admin::` namespace. You would place these controllers under the `app/controllers/admin` directory, and you can group them together in your router: ```ruby namespace :admin do @@ -169,7 +169,7 @@ namespace :admin do end ``` -This will create a number of routes for each of the +posts+ and +comments+ controller. For +Admin::PostsController+, Rails will create: +This will create a number of routes for each of the `posts` and `comments` controller. For `Admin::PostsController`, Rails will create: |_.HTTP Verb |_.Path |_.action |_.named helper | |GET |/admin/posts |index | admin_posts_path | @@ -180,7 +180,7 @@ This will create a number of routes for each of the +posts+ and +comments+ contr |PATCH/PUT |/admin/posts/:id |update | admin_post_path(:id) | |DELETE |/admin/posts/:id |destroy | admin_post_path(:id) | -If you want to route +/posts+ (without the prefix +/admin+) to +Admin::PostsController+, you could use +If you want to route `/posts` (without the prefix `/admin`) to `Admin::PostsController`, you could use ```ruby scope :module => "admin" do @@ -194,7 +194,7 @@ or, for a single case resources :posts, :module => "admin" ``` -If you want to route +/admin/posts+ to +PostsController+ (without the +Admin::+ module prefix), you could use +If you want to route `/admin/posts` to `PostsController` (without the `Admin::` module prefix), you could use ```ruby scope "/admin" do @@ -208,7 +208,7 @@ or, for a single case resources :posts, :path => "/admin/posts" ``` -In each of these cases, the named routes remain the same as if you did not use +scope+. In the last case, the following paths map to +PostsController+: +In each of these cases, the named routes remain the same as if you did not use `scope`. In the last case, the following paths map to `PostsController`: |_.HTTP Verb |_.Path |_.action |_.named helper | |GET |/admin/posts |index | posts_path | @@ -241,7 +241,7 @@ resources :magazines do end ``` -In addition to the routes for magazines, this declaration will also route ads to an +AdsController+. The ad URLs require a magazine: +In addition to the routes for magazines, this declaration will also route ads to an `AdsController`. The ad URLs require a magazine: |_.HTTP Verb |_.Path |_.action |_.used for | |GET |/magazines/:magazine_id/ads |index |display a list of all ads for a specific magazine | @@ -252,7 +252,7 @@ In addition to the routes for magazines, this declaration will also route ads to |PATCH/PUT |/magazines/:magazine_id/ads/:id |update |update a specific ad belonging to a specific magazine | |DELETE |/magazines/:magazine_id/ads/:id |destroy |delete a specific ad belonging to a specific magazine | -This will also create routing helpers such as +magazine_ads_url+ and +edit_magazine_ad_path+. These helpers take an instance of Magazine as the first parameter (+magazine_ads_url(@magazine)+). +This will also create routing helpers such as `magazine_ads_url` and `edit_magazine_ad_path`. These helpers take an instance of Magazine as the first parameter (`magazine_ads_url(@magazine)`). #### Limits to Nesting @@ -272,7 +272,7 @@ Deeply-nested resources quickly become cumbersome. In this case, for example, th /publishers/1/magazines/2/photos/3 ``` -The corresponding route helper would be +publisher_magazine_photo_url+, requiring you to specify objects at all three levels. Indeed, this situation is confusing enough that a popular "article":http://weblog.jamisbuck.org/2007/2/5/nesting-resources by Jamis Buck proposes a rule of thumb for good Rails design: +The corresponding route helper would be `publisher_magazine_photo_url`, requiring you to specify objects at all three levels. Indeed, this situation is confusing enough that a popular "article":http://weblog.jamisbuck.org/2007/2/5/nesting-resources by Jamis Buck proposes a rule of thumb for good Rails design: TIP: _Resources should never be nested more than 1 level deep._ @@ -316,19 +316,19 @@ resources :magazines do end ``` -When using +magazine_ad_path+, you can pass in instances of +Magazine+ and +Ad+ instead of the numeric IDs. +When using `magazine_ad_path`, you can pass in instances of `Magazine` and `Ad` instead of the numeric IDs. ```erb <%= link_to "Ad details", magazine_ad_path(@magazine, @ad) %> ``` -You can also use +url_for+ with a set of objects, and Rails will automatically determine which route you want: +You can also use `url_for` with a set of objects, and Rails will automatically determine which route you want: ```erb <%= link_to "Ad details", url_for([@magazine, @ad]) %> ``` -In this case, Rails will see that +@magazine+ is a +Magazine+ and +@ad+ is an +Ad+ and will therefore use the +magazine_ad_path+ helper. In helpers like +link_to+, you can specify just the object in place of the full +url_for+ call: +In this case, Rails will see that `@magazine` is a `Magazine` and `@ad` is an `Ad` and will therefore use the `magazine_ad_path` helper. In helpers like `link_to`, you can specify just the object in place of the full `url_for` call: ```erb <%= link_to "Ad details", [@magazine, @ad] %> @@ -354,7 +354,7 @@ You are not limited to the seven routes that RESTful routing creates by default. #### Adding Member Routes -To add a member route, just add a +member+ block into the resource block: +To add a member route, just add a `member` block into the resource block: ```ruby resources :photos do @@ -364,9 +364,9 @@ resources :photos do end ``` -This will recognize +/photos/1/preview+ with GET, and route to the +preview+ action of +PhotosController+. It will also create the +preview_photo_url+ and +preview_photo_path+ helpers. +This will recognize `/photos/1/preview` with GET, and route to the `preview` action of `PhotosController`. It will also create the `preview_photo_url` and `preview_photo_path` helpers. -Within the block of member routes, each route name specifies the HTTP verb that it will recognize. You can use +get+, +patch+, +put+, +post+, or +delete+ here. If you don't have multiple +member+ routes, you can also pass +:on+ to a route, eliminating the block: +Within the block of member routes, each route name specifies the HTTP verb that it will recognize. You can use `get`, `patch`, `put`, `post`, or `delete` here. If you don't have multiple `member` routes, you can also pass `:on` to a route, eliminating the block: ```ruby resources :photos do @@ -386,9 +386,9 @@ resources :photos do end ``` -This will enable Rails to recognize paths such as +/photos/search+ with GET, and route to the +search+ action of +PhotosController+. It will also create the +search_photos_url+ and +search_photos_path+ route helpers. +This will enable Rails to recognize paths such as `/photos/search` with GET, and route to the `search` action of `PhotosController`. It will also create the `search_photos_url` and `search_photos_path` route helpers. -Just as with member routes, you can pass +:on+ to a route: +Just as with member routes, you can pass `:on` to a route: ```ruby resources :photos do @@ -411,31 +411,31 @@ In particular, simple routing makes it very easy to map legacy URLs to new Rails ### Bound Parameters -When you set up a regular route, you supply a series of symbols that Rails maps to parts of an incoming HTTP request. Two of these symbols are special: +:controller+ maps to the name of a controller in your application, and +:action+ maps to the name of an action within that controller. For example, consider one of the default Rails routes: +When you set up a regular route, you supply a series of symbols that Rails maps to parts of an incoming HTTP request. Two of these symbols are special: `:controller` maps to the name of a controller in your application, and `:action` maps to the name of an action within that controller. For example, consider one of the default Rails routes: ```ruby get ':controller(/:action(/:id))' ``` -If an incoming request of +/photos/show/1+ is processed by this route (because it hasn't matched any previous route in the file), then the result will be to invoke the +show+ action of the +PhotosController+, and to make the final parameter +"1"+ available as +params[:id]+. This route will also route the incoming request of +/photos+ to +PhotosController#index+, since +:action+ and +:id+ are optional parameters, denoted by parentheses. +If an incoming request of `/photos/show/1` is processed by this route (because it hasn't matched any previous route in the file), then the result will be to invoke the `show` action of the `PhotosController`, and to make the final parameter `"1"` available as `params[:id]`. This route will also route the incoming request of `/photos` to `PhotosController#index`, since `:action` and `:id` are optional parameters, denoted by parentheses. ### Dynamic Segments -You can set up as many dynamic segments within a regular route as you like. Anything other than +:controller+ or +:action+ will be available to the action as part of +params+. If you set up this route: +You can set up as many dynamic segments within a regular route as you like. Anything other than `:controller` or `:action` will be available to the action as part of `params`. If you set up this route: ```ruby get ':controller/:action/:id/:user_id' ``` -An incoming path of +/photos/show/1/2+ will be dispatched to the +show+ action of the +PhotosController+. +params[:id]+ will be +"1"+, and +params[:user_id]+ will be +"2"+. +An incoming path of `/photos/show/1/2` will be dispatched to the `show` action of the `PhotosController`. `params[:id]` will be `"1"`, and `params[:user_id]` will be `"2"`. -NOTE: You can't use +:namespace+ or +:module+ with a +:controller+ path segment. If you need to do this then use a constraint on :controller that matches the namespace you require. e.g: +NOTE: You can't use `:namespace` or `:module` with a `:controller` path segment. If you need to do this then use a constraint on :controller that matches the namespace you require. e.g: ```ruby get ':controller(/:action(/:id))', :controller => /admin\/[^\/]+/ ``` -TIP: By default dynamic segments don't accept dots - this is because the dot is used as a separator for formatted routes. If you need to use a dot within a dynamic segment, add a constraint that overrides this – for example, +:id+ => /[^\/]+/ allows anything except a slash. +TIP: By default dynamic segments don't accept dots - this is because the dot is used as a separator for formatted routes. If you need to use a dot within a dynamic segment, add a constraint that overrides this – for example, `:id` => /[^\/]+/ allows anything except a slash. ### Static Segments @@ -445,45 +445,45 @@ You can specify static segments when creating a route: get ':controller/:action/:id/with_user/:user_id' ``` -This route would respond to paths such as +/photos/show/1/with_user/2+. In this case, +params+ would be `{ :controller => "photos", :action => "show", :id => "1", :user_id => "2" }`. +This route would respond to paths such as `/photos/show/1/with_user/2`. In this case, `params` would be `{ :controller => "photos", :action => "show", :id => "1", :user_id => "2" }`. ### The Query String -The +params+ will also include any parameters from the query string. For example, with this route: +The `params` will also include any parameters from the query string. For example, with this route: ```ruby get ':controller/:action/:id' ``` -An incoming path of +/photos/show/1?user_id=2+ will be dispatched to the +show+ action of the +Photos+ controller. +params+ will be `{ :controller => "photos", :action => "show", :id => "1", :user_id => "2" }`. +An incoming path of `/photos/show/1?user_id=2` will be dispatched to the `show` action of the `Photos` controller. `params` will be `{ :controller => "photos", :action => "show", :id => "1", :user_id => "2" }`. ### Defining Defaults -You do not need to explicitly use the +:controller+ and +:action+ symbols within a route. You can supply them as defaults: +You do not need to explicitly use the `:controller` and `:action` symbols within a route. You can supply them as defaults: ```ruby get 'photos/:id' => 'photos#show' ``` -With this route, Rails will match an incoming path of +/photos/12+ to the +show+ action of +PhotosController+. +With this route, Rails will match an incoming path of `/photos/12` to the `show` action of `PhotosController`. -You can also define other defaults in a route by supplying a hash for the +:defaults+ option. This even applies to parameters that you do not specify as dynamic segments. For example: +You can also define other defaults in a route by supplying a hash for the `:defaults` option. This even applies to parameters that you do not specify as dynamic segments. For example: ```ruby get 'photos/:id' => 'photos#show', :defaults => { :format => 'jpg' } ``` -Rails would match +photos/12+ to the +show+ action of +PhotosController+, and set +params[:format]+ to +"jpg"+. +Rails would match `photos/12` to the `show` action of `PhotosController`, and set `params[:format]` to `"jpg"`. ### Naming Routes -You can specify a name for any route using the +:as+ option. +You can specify a name for any route using the `:as` option. ```ruby get 'exit' => 'sessions#destroy', :as => :logout ``` -This will create +logout_path+ and +logout_url+ as named helpers in your application. Calling +logout_path+ will return +/exit+ +This will create `logout_path` and `logout_url` as named helpers in your application. Calling `logout_path` will return `/exit` You can also use this to override routing methods defined by resources, like this: @@ -491,39 +491,39 @@ You can also use this to override routing methods defined by resources, like thi get ':username', :to => "users#show", :as => :user ``` -This will define a +user_path+ method that will be available in controllers, helpers and views that will go to a route such as +/bob+. Inside the +show+ action of +UsersController+, +params[:username]+ will contain the username for the user. Change +:username+ in the route definition if you do not want your parameter name to be +:username+. +This will define a `user_path` method that will be available in controllers, helpers and views that will go to a route such as `/bob`. Inside the `show` action of `UsersController`, `params[:username]` will contain the username for the user. Change `:username` in the route definition if you do not want your parameter name to be `:username`. ### HTTP Verb Constraints -In general, you should use the +get+, +post+, +put+ and +delete+ methods to constrain a route to a particular verb. You can use the +match+ method with the +:via+ option to match multiple verbs at once: +In general, you should use the `get`, `post`, `put` and `delete` methods to constrain a route to a particular verb. You can use the `match` method with the `:via` option to match multiple verbs at once: ```ruby match 'photos' => 'photos#show', :via => [:get, :post] ``` -You can match all verbs to a particular route using +:via => :all+: +You can match all verbs to a particular route using `:via => :all`: ```ruby match 'photos' => 'photos#show', :via => :all ``` -You should avoid routing all verbs to an action unless you have a good reason to, as routing both +GET+ requests and +POST+ requests to a single action has security implications. +You should avoid routing all verbs to an action unless you have a good reason to, as routing both `GET` requests and `POST` requests to a single action has security implications. ### Segment Constraints -You can use the +:constraints+ option to enforce a format for a dynamic segment: +You can use the `:constraints` option to enforce a format for a dynamic segment: ```ruby get 'photos/:id' => 'photos#show', :constraints => { :id => /[A-Z]\d{5}/ } ``` -This route would match paths such as +/photos/A12345+. You can more succinctly express the same route this way: +This route would match paths such as `/photos/A12345`. You can more succinctly express the same route this way: ```ruby get 'photos/:id' => 'photos#show', :id => /[A-Z]\d{5}/ ``` -+:constraints+ takes regular expressions with the restriction that regexp anchors can't be used. For example, the following route will not work: +`:constraints` takes regular expressions with the restriction that regexp anchors can't be used. For example, the following route will not work: ```ruby get '/:id' => 'posts#show', :constraints => {:id => /^\d/} @@ -531,7 +531,7 @@ get '/:id' => 'posts#show', :constraints => {:id => /^\d/} However, note that you don't need to use anchors because all routes are anchored at the start. -For example, the following routes would allow for +posts+ with +to_param+ values like +1-hello-world+ that always begin with a number and +users+ with +to_param+ values like +david+ that never begin with a number to share the root namespace: +For example, the following routes would allow for `posts` with `to_param` values like `1-hello-world` that always begin with a number and `users` with `to_param` values like `david` that never begin with a number to share the root namespace: ```ruby get '/:id' => 'posts#show', :constraints => { :id => /\d.+/ } @@ -540,7 +540,7 @@ get '/:username' => 'users#show' ### Request-Based Constraints -You can also constrain a route based on any method on the <a href="action_controller_overview.html#the-request-object">Request</a> object that returns a +String+. +You can also constrain a route based on any method on the <a href="action_controller_overview.html#the-request-object">Request</a> object that returns a `String`. You specify a request-based constraint the same way that you specify a segment constraint: @@ -560,7 +560,7 @@ end ### Advanced Constraints -If you have a more advanced constraint, you can provide an object that responds to +matches?+ that Rails should use. Let's say you wanted to route all users on a blacklist to the +BlacklistController+. You could do: +If you have a more advanced constraint, you can provide an object that responds to `matches?` that Rails should use. Let's say you wanted to route all users on a blacklist to the `BlacklistController`. You could do: ```ruby class BlacklistConstraint @@ -588,7 +588,7 @@ TwitterClone::Application.routes.draw do end ``` -Both the +matches?+ method and the lambda gets the +request+ object as an argument. +Both the `matches?` method and the lambda gets the `request` object as an argument. ### Route Globbing @@ -598,7 +598,7 @@ Route globbing is a way to specify that a particular parameter should be matched get 'photos/*other' => 'photos#unknown' ``` -This route would match +photos/12+ or +/photos/long/path/to/12+, setting +params[:other]+ to +"12"+ or +"long/path/to/12"+. +This route would match `photos/12` or `/photos/long/path/to/12`, setting `params[:other]` to `"12"` or `"long/path/to/12"`. Wildcard segments can occur anywhere in a route. For example, @@ -606,7 +606,7 @@ Wildcard segments can occur anywhere in a route. For example, get 'books/*section/:title' => 'books#show' ``` -would match +books/some/section/last-words-a-memoir+ with +params[:section]+ equals +"some/section"+, and +params[:title]+ equals +"last-words-a-memoir"+. +would match `books/some/section/last-words-a-memoir` with `params[:section]` equals `"some/section"`, and `params[:title]` equals `"last-words-a-memoir"`. Technically a route can have even more than one wildcard segment. The matcher assigns segments to parameters in an intuitive way. For example, @@ -614,7 +614,7 @@ Technically a route can have even more than one wildcard segment. The matcher as get '*a/foo/*b' => 'test#index' ``` -would match +zoo/woo/foo/bar/baz+ with +params[:a]+ equals +"zoo/woo"+, and +params[:b]+ equals +"bar/baz"+. +would match `zoo/woo/foo/bar/baz` with `params[:a]` equals `"zoo/woo"`, and `params[:b]` equals `"bar/baz"`. NOTE: Starting from Rails 3.1, wildcard routes will always match the optional format segment by default. For example if you have this route: @@ -622,13 +622,13 @@ NOTE: Starting from Rails 3.1, wildcard routes will always match the optional fo get '*pages' => 'pages#show' ``` -NOTE: By requesting +"/foo/bar.json"+, your +params[:pages]+ will be equals to +"foo/bar"+ with the request format of JSON. If you want the old 3.0.x behavior back, you could supply +:format => false+ like this: +NOTE: By requesting `"/foo/bar.json"`, your `params[:pages]` will be equals to `"foo/bar"` with the request format of JSON. If you want the old 3.0.x behavior back, you could supply `:format => false` like this: ```ruby get '*pages' => 'pages#show', :format => false ``` -NOTE: If you want to make the format segment mandatory, so it cannot be omitted, you can supply +:format => true+ like this: +NOTE: If you want to make the format segment mandatory, so it cannot be omitted, you can supply `:format => true` like this: ```ruby get '*pages' => 'pages#show', :format => true @@ -636,7 +636,7 @@ get '*pages' => 'pages#show', :format => true ### Redirection -You can redirect any path to another path using the +redirect+ helper in your router: +You can redirect any path to another path using the `redirect` helper in your router: ```ruby get "/stories" => redirect("/posts") @@ -657,32 +657,32 @@ get "/stories" => redirect {|p, req| "/posts/#{req.subdomain}" } Please note that this redirection is a 301 "Moved Permanently" redirect. Keep in mind that some web browsers or proxy servers will cache this type of redirect, making the old page inaccessible. -In all of these cases, if you don't provide the leading host (+http://www.example.com+), Rails will take those details from the current request. +In all of these cases, if you don't provide the leading host (`http://www.example.com`), Rails will take those details from the current request. ### Routing to Rack Applications -Instead of a String, like +"posts#index"+, which corresponds to the +index+ action in the +PostsController+, you can specify any <a href="rails_on_rack.html">Rack application</a> as the endpoint for a matcher. +Instead of a String, like `"posts#index"`, which corresponds to the `index` action in the `PostsController`, you can specify any <a href="rails_on_rack.html">Rack application</a> as the endpoint for a matcher. ```ruby match "/application.js" => Sprockets, :via => :all ``` -As long as +Sprockets+ responds to +call+ and returns a `[status, headers, body]`, the router won't know the difference between the Rack application and an action. This is an appropriate use of +:via => :all+, as you will want to allow your Rack application to handle all verbs as it considers appropriate. +As long as `Sprockets` responds to `call` and returns a `[status, headers, body]`, the router won't know the difference between the Rack application and an action. This is an appropriate use of `:via => :all`, as you will want to allow your Rack application to handle all verbs as it considers appropriate. -NOTE: For the curious, +"posts#index"+ actually expands out to +PostsController.action(:index)+, which returns a valid Rack application. +NOTE: For the curious, `"posts#index"` actually expands out to `PostsController.action(:index)`, which returns a valid Rack application. -### Using +root+ +### Using `root` -You can specify what Rails should route +"/"+ to with the +root+ method: +You can specify what Rails should route `"/"` to with the `root` method: ```ruby root :to => 'pages#main' root 'pages#main' # shortcut for the above ``` -You should put the +root+ route at the top of the file, because it is the most popular route and should be matched first. You also need to delete the +public/index.html+ file for the root route to take effect. +You should put the `root` route at the top of the file, because it is the most popular route and should be matched first. You also need to delete the `public/index.html` file for the root route to take effect. -NOTE: The +root+ route only routes +GET+ requests to the action. +NOTE: The `root` route only routes `GET` requests to the action. ### Unicode character routes @@ -695,17 +695,17 @@ match 'こんにちは' => 'welcome#index' Customizing Resourceful Routes ------------------------------ -While the default routes and helpers generated by +resources :posts+ will usually serve you well, you may want to customize them in some way. Rails allows you to customize virtually any generic part of the resourceful helpers. +While the default routes and helpers generated by `resources :posts` will usually serve you well, you may want to customize them in some way. Rails allows you to customize virtually any generic part of the resourceful helpers. ### Specifying a Controller to Use -The +:controller+ option lets you explicitly specify a controller to use for the resource. For example: +The `:controller` option lets you explicitly specify a controller to use for the resource. For example: ```ruby resources :photos, :controller => "images" ``` -will recognize incoming paths beginning with +/photos+ but route to the +Images+ controller: +will recognize incoming paths beginning with `/photos` but route to the `Images` controller: |_.HTTP Verb |_.Path |_.action |_.named helper | |GET |/photos |index | photos_path | @@ -716,17 +716,17 @@ will recognize incoming paths beginning with +/photos+ but route to the +Images+ |PATCH/PUT |/photos/:id |update | photo_path(:id) | |DELETE |/photos/:id |destroy | photo_path(:id) | -NOTE: Use +photos_path+, +new_photo_path+, etc. to generate paths for this resource. +NOTE: Use `photos_path`, `new_photo_path`, etc. to generate paths for this resource. ### Specifying Constraints -You can use the +:constraints+ option to specify a required format on the implicit +id+. For example: +You can use the `:constraints` option to specify a required format on the implicit `id`. For example: ```ruby resources :photos, :constraints => {:id => /[A-Z][A-Z][0-9]+/} ``` -This declaration constrains the +:id+ parameter to match the supplied regular expression. So, in this case, the router would no longer match +/photos/1+ to this route. Instead, +/photos/RR27+ would match. +This declaration constrains the `:id` parameter to match the supplied regular expression. So, in this case, the router would no longer match `/photos/1` to this route. Instead, `/photos/RR27` would match. You can specify a single constraint to apply to a number of routes by using the block form: @@ -739,17 +739,17 @@ end NOTE: Of course, you can use the more advanced constraints available in non-resourceful routes in this context. -TIP: By default the +:id+ parameter doesn't accept dots - this is because the dot is used as a separator for formatted routes. If you need to use a dot within an +:id+ add a constraint which overrides this - for example +:id+ => /[^\/]+/ allows anything except a slash. +TIP: By default the `:id` parameter doesn't accept dots - this is because the dot is used as a separator for formatted routes. If you need to use a dot within an `:id` add a constraint which overrides this - for example `:id` => /[^\/]+/ allows anything except a slash. ### Overriding the Named Helpers -The +:as+ option lets you override the normal naming for the named route helpers. For example: +The `:as` option lets you override the normal naming for the named route helpers. For example: ```ruby resources :photos, :as => "images" ``` -will recognize incoming paths beginning with +/photos+ and route the requests to +PhotosController+, but use the value of the :as option to name the helpers. +will recognize incoming paths beginning with `/photos` and route the requests to `PhotosController`, but use the value of the :as option to name the helpers. |_.HTTP verb|_.Path |_.action |_.named helper | |GET |/photos |index | images_path | @@ -760,9 +760,9 @@ will recognize incoming paths beginning with +/photos+ and route the requests to |PATCH/PUT |/photos/:id |update | image_path(:id) | |DELETE |/photos/:id |destroy | image_path(:id) | -### Overriding the +new+ and +edit+ Segments +### Overriding the `new` and `edit` Segments -The +:path_names+ option lets you override the automatically-generated "new" and "edit" segments in paths: +The `:path_names` option lets you override the automatically-generated "new" and "edit" segments in paths: ```ruby resources :photos, :path_names => { :new => 'make', :edit => 'change' } @@ -775,7 +775,7 @@ This would cause the routing to recognize paths such as /photos/1/change ``` -NOTE: The actual action names aren't changed by this option. The two paths shown would still route to the +new+ and +edit+ actions. +NOTE: The actual action names aren't changed by this option. The two paths shown would still route to the `new` and `edit` actions. TIP: If you find yourself wanting to change this option uniformly for all of your routes, you can use a scope. @@ -787,7 +787,7 @@ end ### Prefixing the Named Route Helpers -You can use the +:as+ option to prefix the named route helpers that Rails generates for a route. Use this option to prevent name collisions between routes using a path scope. +You can use the `:as` option to prefix the named route helpers that Rails generates for a route. Use this option to prevent name collisions between routes using a path scope. ```ruby scope "admin" do @@ -797,9 +797,9 @@ end resources :photos ``` -This will provide route helpers such as +admin_photos_path+, +new_admin_photo_path+ etc. +This will provide route helpers such as `admin_photos_path`, `new_admin_photo_path` etc. -To prefix a group of route helpers, use +:as+ with +scope+: +To prefix a group of route helpers, use `:as` with `scope`: ```ruby scope "admin", :as => "admin" do @@ -809,9 +809,9 @@ end resources :photos, :accounts ``` -This will generate routes such as +admin_photos_path+ and +admin_accounts_path+ which map to +/admin/photos+ and +/admin/accounts+ respectively. +This will generate routes such as `admin_photos_path` and `admin_accounts_path` which map to `/admin/photos` and `/admin/accounts` respectively. -NOTE: The +namespace+ scope will automatically add +:as+ as well as +:module+ and +:path+ prefixes. +NOTE: The `namespace` scope will automatically add `:as` as well as `:module` and `:path` prefixes. You can prefix routes with a named parameter also: @@ -821,31 +821,31 @@ scope ":username" do end ``` -This will provide you with URLs such as +/bob/posts/1+ and will allow you to reference the +username+ part of the path as +params[:username]+ in controllers, helpers and views. +This will provide you with URLs such as `/bob/posts/1` and will allow you to reference the `username` part of the path as `params[:username]` in controllers, helpers and views. ### Restricting the Routes Created -By default, Rails creates routes for the seven default actions (index, show, new, create, edit, update, and destroy) for every RESTful route in your application. You can use the +:only+ and +:except+ options to fine-tune this behavior. The +:only+ option tells Rails to create only the specified routes: +By default, Rails creates routes for the seven default actions (index, show, new, create, edit, update, and destroy) for every RESTful route in your application. You can use the `:only` and `:except` options to fine-tune this behavior. The `:only` option tells Rails to create only the specified routes: ```ruby resources :photos, :only => [:index, :show] ``` -Now, a +GET+ request to +/photos+ would succeed, but a +POST+ request to +/photos+ (which would ordinarily be routed to the +create+ action) will fail. +Now, a `GET` request to `/photos` would succeed, but a `POST` request to `/photos` (which would ordinarily be routed to the `create` action) will fail. -The +:except+ option specifies a route or list of routes that Rails should _not_ create: +The `:except` option specifies a route or list of routes that Rails should _not_ create: ```ruby resources :photos, :except => :destroy ``` -In this case, Rails will create all of the normal routes except the route for +destroy+ (a +DELETE+ request to +/photos/:id+). +In this case, Rails will create all of the normal routes except the route for `destroy` (a `DELETE` request to `/photos/:id`). -TIP: If your application has many RESTful routes, using +:only+ and +:except+ to generate only the routes that you actually need can cut down on memory use and speed up the routing process. +TIP: If your application has many RESTful routes, using `:only` and `:except` to generate only the routes that you actually need can cut down on memory use and speed up the routing process. ### Translated Paths -Using +scope+, we can alter path names generated by resources: +Using `scope`, we can alter path names generated by resources: ```ruby scope(:path_names => { :new => "neu", :edit => "bearbeiten" }) do @@ -853,7 +853,7 @@ scope(:path_names => { :new => "neu", :edit => "bearbeiten" }) do end ``` -Rails now creates routes to the +CategoriesController+. +Rails now creates routes to the `CategoriesController`. |_.HTTP verb|_.Path |_.action |_.named helper | |GET |/kategorien |index | categories_path | @@ -866,7 +866,7 @@ Rails now creates routes to the +CategoriesController+. ### Overriding the Singular Form -If you want to define the singular form of a resource, you should add additional rules to the +Inflector+. +If you want to define the singular form of a resource, you should add additional rules to the `Inflector`. ```ruby ActiveSupport::Inflector.inflections do |inflect| @@ -874,9 +874,9 @@ ActiveSupport::Inflector.inflections do |inflect| end ``` -### Using +:as+ in Nested Resources +### Using `:as` in Nested Resources -The +:as+ option overrides the automatically-generated name for the resource in nested route helpers. For example, +The `:as` option overrides the automatically-generated name for the resource in nested route helpers. For example, ```ruby resources :magazines do @@ -884,7 +884,7 @@ resources :magazines do end ``` -This will create routing helpers such as +magazine_periodical_ads_url+ and +edit_magazine_periodical_ad_path+. +This will create routing helpers such as `magazine_periodical_ads_url` and `edit_magazine_periodical_ad_path`. Inspecting and Testing Routes ----------------------------- @@ -893,16 +893,16 @@ Rails offers facilities for inspecting and testing your routes. ### Seeing Existing Routes -To get a complete list of the available routes in your application, visit +http://localhost:3000/rails/info/routes+ in your browser while your server is running in the *development* environment. You can also execute the +rake routes+ command in your terminal to produce the same output. +To get a complete list of the available routes in your application, visit `http://localhost:3000/rails/info/routes` in your browser while your server is running in the *development* environment. You can also execute the `rake routes` command in your terminal to produce the same output. -Both methods will list all of your routes, in the same order that they appear in +routes.rb+. For each route, you'll see: +Both methods will list all of your routes, in the same order that they appear in `routes.rb`. For each route, you'll see: * The route name (if any) * The HTTP verb used (if the route doesn't respond to all verbs) * The URL pattern to match * The routing parameters for the route -For example, here's a small section of the +rake routes+ output for a RESTful route: +For example, here's a small section of the `rake routes` output for a RESTful route: ``` users GET /users(.:format) users#index @@ -911,48 +911,48 @@ For example, here's a small section of the +rake routes+ output for a RESTful ro edit_user GET /users/:id/edit(.:format) users#edit ``` -You may restrict the listing to the routes that map to a particular controller setting the +CONTROLLER+ environment variable: +You may restrict the listing to the routes that map to a particular controller setting the `CONTROLLER` environment variable: ```bash $ CONTROLLER=users rake routes ``` -TIP: You'll find that the output from +rake routes+ is much more readable if you widen your terminal window until the output lines don't wrap. +TIP: You'll find that the output from `rake routes` is much more readable if you widen your terminal window until the output lines don't wrap. ### Testing Routes Routes should be included in your testing strategy (just like the rest of your application). Rails offers three "built-in assertions":http://api.rubyonrails.org/classes/ActionDispatch/Assertions/RoutingAssertions.html designed to make testing routes simpler: -* +assert_generates+ -* +assert_recognizes+ -* +assert_routing+ +* `assert_generates` +* `assert_recognizes` +* `assert_routing` -#### The +assert_generates+ Assertion +#### The `assert_generates` Assertion -+assert_generates+ asserts that a particular set of options generate a particular path and can be used with default routes or custom routes. +`assert_generates` asserts that a particular set of options generate a particular path and can be used with default routes or custom routes. ```ruby assert_generates "/photos/1", { :controller => "photos", :action => "show", :id => "1" } assert_generates "/about", :controller => "pages", :action => "about" ``` -#### The +assert_recognizes+ Assertion +#### The `assert_recognizes` Assertion -+assert_recognizes+ is the inverse of +assert_generates+. It asserts that a given path is recognized and routes it to a particular spot in your application. +`assert_recognizes` is the inverse of `assert_generates`. It asserts that a given path is recognized and routes it to a particular spot in your application. ```ruby assert_recognizes({ :controller => "photos", :action => "show", :id => "1" }, "/photos/1") ``` -You can supply a +:method+ argument to specify the HTTP verb: +You can supply a `:method` argument to specify the HTTP verb: ```ruby assert_recognizes({ :controller => "photos", :action => "create" }, { :path => "photos", :method => :post }) ``` -#### The +assert_routing+ Assertion +#### The `assert_routing` Assertion -The +assert_routing+ assertion checks the route both ways: it tests that the path generates the options, and that the options generate the path. Thus, it combines the functions of +assert_generates+ and +assert_recognizes+. +The `assert_routing` assertion checks the route both ways: it tests that the path generates the options, and that the options generate the path. Thus, it combines the functions of `assert_generates` and `assert_recognizes`. ```ruby assert_routing({ :path => "photos", :method => :post }, { :controller => "photos", :action => "create" }) diff --git a/guides/source/ruby_on_rails_guides_guidelines.md b/guides/source/ruby_on_rails_guides_guidelines.md index 1699bdad3b..133e039460 100644 --- a/guides/source/ruby_on_rails_guides_guidelines.md +++ b/guides/source/ruby_on_rails_guides_guidelines.md @@ -18,7 +18,7 @@ Each guide should start with motivational text at the top (that's the little int Titles ------ -The title of every guide uses +h2+; guide sections use +h3+; subsections +h4+; etc. +The title of every guide uses `h2`; guide sections use `h3`; subsections `h4`; etc. Capitalize all words except for internal articles, prepositions, conjunctions, and forms of the verb to be: @@ -50,7 +50,7 @@ HTML Guides ### Generation -To generate all the guides, just +cd+ into the *+guides+* directory and execute: +To generate all the guides, just `cd` into the *`guides`* directory and execute: ``` bundle exec rake guides:generate @@ -62,22 +62,22 @@ or bundle exec rake guides:generate:html ``` -(You may need to run +bundle install+ first to install the required gems.) +(You may need to run `bundle install` first to install the required gems.) -To process +my_guide.textile+ and nothing else use the +ONLY+ environment variable: +To process `my_guide.textile` and nothing else use the `ONLY` environment variable: ``` touch my_guide.textile bundle exec rake guides:generate ONLY=my_guide ``` -By default, guides that have not been modified are not processed, so +ONLY+ is rarely needed in practice. +By default, guides that have not been modified are not processed, so `ONLY` is rarely needed in practice. -To force processing all the guides, pass +ALL=1+. +To force processing all the guides, pass `ALL=1`. -It is also recommended that you work with +WARNINGS=1+. This detects duplicate IDs and warns about broken internal links. +It is also recommended that you work with `WARNINGS=1`. This detects duplicate IDs and warns about broken internal links. -If you want to generate guides in a language other than English, you can keep them in a separate directory under +source+ (eg. `source/es`) and use the +GUIDES_LANGUAGE+ environment variable: +If you want to generate guides in a language other than English, you can keep them in a separate directory under `source` (eg. `source/es`) and use the `GUIDES_LANGUAGE` environment variable: ``` bundle exec rake guides:generate GUIDES_LANGUAGE=es @@ -97,7 +97,7 @@ Please validate the generated HTML with: bundle exec rake guides:validate ``` -Particularly, titles get an ID generated from their content and this often leads to duplicates. Please set +WARNINGS=1+ when generating guides to detect them. The warning messages suggest a solution. +Particularly, titles get an ID generated from their content and this often leads to duplicates. Please set `WARNINGS=1` when generating guides to detect them. The warning messages suggest a solution. Kindle Guides ------------- diff --git a/guides/source/security.md b/guides/source/security.md index 9f2fb92331..cb4a50fe0d 100644 --- a/guides/source/security.md +++ b/guides/source/security.md @@ -84,7 +84,7 @@ This will also be a good idea, if you modify the structure of an object and old ### Session Storage -NOTE: _Rails provides several storage mechanisms for the session hashes. The most important is +ActionDispatch::Session::CookieStore+._ +NOTE: _Rails provides several storage mechanisms for the session hashes. The most important is `ActionDispatch::Session::CookieStore`._ Rails 2 introduced a new default session storage, CookieStore. CookieStore saves the session hash directly in a cookie on the client-side. The server retrieves the session hash from the cookie and eliminates the need for a session id. That will greatly increase the speed of the application, but it is a controversial storage option and you have to think about the security implications of it: @@ -105,7 +105,7 @@ There are, however, derivatives of CookieStore which encrypt the session hash, s ### Replay Attacks for CookieStore Sessions -TIP: _Another sort of attack you have to be aware of when using +CookieStore+ is the replay attack._ +TIP: _Another sort of attack you have to be aware of when using `CookieStore` is the replay attack._ It works like this: @@ -129,7 +129,7 @@ This attack focuses on fixing a user's session id known to the attacker, and for # The attacker creates a valid session id: He loads the login page of the web application where he wants to fix the session, and takes the session id in the cookie from the response (see number 1 and 2 in the image). # He possibly maintains the session. Expiring sessions, for example every 20 minutes, greatly reduces the time-frame for attack. Therefore he accesses the web application from time to time in order to keep the session alive. -# Now the attacker will force the user's browser into using this session id (see number 3 in the image). As you may not change a cookie of another domain (because of the same origin policy), the attacker has to run a JavaScript from the domain of the target web application. Injecting the JavaScript code into the application by XSS accomplishes this attack. Here is an example: +<script>
document.cookie="_session_id=16d5b78abb28e3d6206b60f22a03c8d9";
</script>+. Read more about XSS and injection later on. +# Now the attacker will force the user's browser into using this session id (see number 3 in the image). As you may not change a cookie of another domain (because of the same origin policy), the attacker has to run a JavaScript from the domain of the target web application. Injecting the JavaScript code into the application by XSS accomplishes this attack. Here is an example: `<script>
document.cookie="_session_id=16d5b78abb28e3d6206b60f22a03c8d9";
</script>`. Read more about XSS and injection later on. # The attacker lures the victim to the infected page with the JavaScript code. By viewing the page, the victim's browser will change the session id to the trap session id. # As the new trap session is unused, the web application will require the user to authenticate. # From now on, the victim and the attacker will co-use the web application with the same session: The session became valid and the victim didn't notice the attack. @@ -152,7 +152,7 @@ Another countermeasure is to _(highlight)save user-specific properties in the se NOTE: _Sessions that never expire extend the time-frame for attacks such as cross-site reference forgery (CSRF), session hijacking and session fixation._ -One possibility is to set the expiry time-stamp of the cookie with the session id. However the client can edit cookies that are stored in the web browser so expiring sessions on the server is safer. Here is an example of how to _(highlight)expire sessions in a database table_. Call +Session.sweep("20 minutes")+ to expire sessions that were used longer than 20 minutes ago. +One possibility is to set the expiry time-stamp of the cookie with the session id. However the client can edit cookies that are stored in the web browser so expiring sessions on the server is safer. Here is an example of how to _(highlight)expire sessions in a database table_. Call `Session.sweep("20 minutes")` to expire sessions that were used longer than 20 minutes ago. ```ruby class Session < ActiveRecord::Base @@ -183,7 +183,7 @@ This attack method works by including malicious code or a link in a page that ac In the <a href="#sessions">session chapter</a> you have learned that most Rails applications use cookie-based sessions. Either they store the session id in the cookie and have a server-side session hash, or the entire session hash is on the client-side. In either case the browser will automatically send along the cookie on every request to a domain, if it can find a cookie for that domain. The controversial point is, that it will also send the cookie, if the request comes from a site of a different domain. Let's start with an example: * Bob browses a message board and views a post from a hacker where there is a crafted HTML image element. The element references a command in Bob's project management application, rather than an image file. -* +<img src="http://www.webapp.com/project/1/destroy">+ +* `<img src="http://www.webapp.com/project/1/destroy">` * Bob's session at www.webapp.com is still alive, because he didn't log out a few minutes ago. * By viewing the post, the browser finds an image tag. It tries to load the suspected image from www.webapp.com. As explained before, it will also send along the cookie with the valid session id. * The web application at www.webapp.com verifies the user information in the corresponding session hash and destroys the project with the ID 1. It then returns a result page which is an unexpected result for the browser, so it will not display the image. @@ -209,7 +209,7 @@ The HTTP protocol basically provides two main types of requests - GET and POST ( * The interaction _(highlight)changes the state_ of the resource in a way that the user would perceive (e.g., a subscription to a service), or * The user is _(highlight)held accountable for the results_ of the interaction. -If your web application is RESTful, you might be used to additional HTTP verbs, such as PUT or DELETE. Most of today's web browsers, however do not support them - only GET and POST. Rails uses a hidden +_method+ field to handle this barrier. +If your web application is RESTful, you might be used to additional HTTP verbs, such as PUT or DELETE. Most of today's web browsers, however do not support them - only GET and POST. Rails uses a hidden `_method` field to handle this barrier. _(highlight)POST requests can be sent automatically, too_. Here is an example for a link which displays www.harmless.com as destination in the browser's status bar. In fact it dynamically creates a new form that sends a POST request. @@ -238,7 +238,7 @@ protect_from_forgery :secret => "123456789012345678901234567890..." This will automatically include a security token, calculated from the current session and the server-side secret, in all forms and Ajax requests generated by Rails. You won't need the secret, if you use CookieStorage as session storage. If the security token doesn't match what was expected, the session will be reset. *Note:* In Rails versions prior to 3.0.4, this raised an `ActionController::InvalidAuthenticityToken` error. -It is common to use persistent cookies to store user information, with +cookies.permanent+ for example. In this case, the cookies will not be cleared and the out of the box CSRF protection will not be effective. If you are using a different cookie store than the session for this information, you must handle what to do with it yourself: +It is common to use persistent cookies to store user information, with `cookies.permanent` for example. In this case, the cookies will not be cleared and the out of the box CSRF protection will not be effective. If you are using a different cookie store than the session for this information, you must handle what to do with it yourself: ```ruby def handle_unverified_request @@ -247,7 +247,7 @@ def handle_unverified_request end ``` -The above method can be placed in the +ApplicationController+ and will be called when a CSRF token is not present on a non-GET request. +The above method can be placed in the `ApplicationController` and will be called when a CSRF token is not present on a non-GET request. Note that _(highlight)cross-site scripting (XSS) vulnerabilities bypass all CSRF protections_. XSS gives the attacker access to all elements on a page, so he can read the CSRF security token from a form or directly submit the form. Read <a href="#cross-site-scripting-xss">more about XSS</a> later. @@ -280,7 +280,7 @@ If it is at the end of the URL it will hardly be noticed and redirects the user Another redirection and self-contained XSS attack works in Firefox and Opera by the use of the data protocol. This protocol displays its contents directly in the browser and can be anything from HTML or JavaScript to entire images: -+data:text/html;base64,PHNjcmlwdD5hbGVydCgnWFNTJyk8L3NjcmlwdD4K+ +`data:text/html;base64,PHNjcmlwdD5hbGVydCgnWFNTJyk8L3NjcmlwdD4K` This example is a Base64 encoded JavaScript which displays a simple message box. In a redirection URL, an attacker could redirect to this URL with the malicious code in it. As a countermeasure, _(highlight)do not allow the user to supply (parts of) the URL to be redirected to_. @@ -375,9 +375,9 @@ The common admin interface works like this: it's located at www.example.com/admi Mass Assignment --------------- -WARNING: _Without any precautions +Model.new(params[:model]+) allows attackers to set any database column's value._ +WARNING: _Without any precautions `Model.new(params[:model]`) allows attackers to set any database column's value._ -The mass-assignment feature may become a problem, as it allows an attacker to set any model's attributes by manipulating the hash passed to a model's +new()+ method: +The mass-assignment feature may become a problem, as it allows an attacker to set any model's attributes by manipulating the hash passed to a model's `new()` method: ```ruby def signup @@ -386,7 +386,7 @@ def signup end ``` -Mass-assignment saves you much work, because you don't have to set each value individually. Simply pass a hash to the +new+ method, or +assign_attributes=+ a hash value, to set the model's attributes to the values in the hash. The problem is that it is often used in conjunction with the parameters (params) hash available in the controller, which may be manipulated by an attacker. He may do so by changing the URL like this: +Mass-assignment saves you much work, because you don't have to set each value individually. Simply pass a hash to the `new` method, or `assign_attributes=` a hash value, to set the model's attributes to the values in the hash. The problem is that it is often used in conjunction with the parameters (params) hash available in the controller, which may be manipulated by an attacker. He may do so by changing the URL like this: ``` http://www.example.com/user/signup?user[name]=ow3ned&user[admin]=1 @@ -400,7 +400,7 @@ params[:user] # => {:name => “ow3ned”, :admin => true} So if you create a new user using mass-assignment, it may be too easy to become an administrator. -Note that this vulnerability is not restricted to database columns. Any setter method, unless explicitly protected, is accessible via the `attributes=` method. In fact, this vulnerability is extended even further with the introduction of nested mass assignment (and nested object forms) in Rails 2.3. The +accepts_nested_attributes_for+ declaration provides us the ability to extend mass assignment to model associations (+has_many+, +has_one+, +has_and_belongs_to_many+). For example: +Note that this vulnerability is not restricted to database columns. Any setter method, unless explicitly protected, is accessible via the `attributes=` method. In fact, this vulnerability is extended even further with the introduction of nested mass assignment (and nested object forms) in Rails 2.3. The `accepts_nested_attributes_for` declaration provides us the ability to extend mass assignment to model associations (`has_many`, `has_one`, `has_and_belongs_to_many`). For example: ```ruby class Person < ActiveRecord::Base @@ -418,19 +418,19 @@ As a result, the vulnerability is extended beyond simply exposing column assignm ### Countermeasures -To avoid this, Rails provides two class methods in your Active Record class to control access to your attributes. The +attr_protected+ method takes a list of attributes that will not be accessible for mass-assignment. For example: +To avoid this, Rails provides two class methods in your Active Record class to control access to your attributes. The `attr_protected` method takes a list of attributes that will not be accessible for mass-assignment. For example: ```ruby attr_protected :admin ``` -+attr_protected+ also optionally takes a role option using :as which allows you to define multiple mass-assignment groupings. If no role is defined then attributes will be added to the :default role. +`attr_protected` also optionally takes a role option using :as which allows you to define multiple mass-assignment groupings. If no role is defined then attributes will be added to the :default role. ```ruby attr_protected :last_login, :as => :admin ``` -A much better way, because it follows the whitelist-principle, is the +attr_accessible+ method. It is the exact opposite of +attr_protected+, because _(highlight)it takes a list of attributes that will be accessible_. All other attributes will be protected. This way you won't forget to protect attributes when adding new ones in the course of development. Here is an example: +A much better way, because it follows the whitelist-principle, is the `attr_accessible` method. It is the exact opposite of `attr_protected`, because _(highlight)it takes a list of attributes that will be accessible_. All other attributes will be protected. This way you won't forget to protect attributes when adding new ones in the course of development. Here is an example: ```ruby attr_accessible :name @@ -447,7 +447,7 @@ params[:user] # => {:name => "ow3ned", :admin => true} @user.admin # => true ``` -When assigning attributes in Active Record using +attributes=+ the :default role will be used. To assign attributes using different roles you should use +assign_attributes+ which accepts an optional :as options parameter. If no :as option is provided then the :default role will be used. You can also bypass mass-assignment security by using the +:without_protection+ option. Here is an example: +When assigning attributes in Active Record using `attributes=` the :default role will be used. To assign attributes using different roles you should use `assign_attributes` which accepts an optional :as options parameter. If no :as option is provided then the :default role will be used. You can also bypass mass-assignment security by using the `:without_protection` option. Here is an example: ```ruby @user = User.new @@ -465,7 +465,7 @@ When assigning attributes in Active Record using +attributes=+ the :default role @user.is_admin # => true ``` -In a similar way, +new+, +create+, `create!`, +update_attributes+, and +update_attributes!+ methods all respect mass-assignment security and accept either +:as+ or +:without_protection+ options. For example: +In a similar way, `new`, `create`, `create!`, `update_attributes`, and `update_attributes!` methods all respect mass-assignment security and accept either `:as` or `:without_protection` options. For example: ```ruby @user = User.new({ :name => 'Sebastian', :is_admin => true }, :as => :admin) @@ -483,14 +483,14 @@ A more paranoid technique to protect your whole project would be to enforce that config.active_record.whitelist_attributes = true ``` -This will create an empty whitelist of attributes available for mass-assignment for all models in your app. As such, your models will need to explicitly whitelist or blacklist accessible parameters by using an +attr_accessible+ or +attr_protected+ declaration. This technique is best applied at the start of a new project. However, for an existing project with a thorough set of functional tests, it should be straightforward and relatively quick to use this application config option; run your tests, and expose each attribute (via +attr_accessible+ or +attr_protected+) as dictated by your failing tests. +This will create an empty whitelist of attributes available for mass-assignment for all models in your app. As such, your models will need to explicitly whitelist or blacklist accessible parameters by using an `attr_accessible` or `attr_protected` declaration. This technique is best applied at the start of a new project. However, for an existing project with a thorough set of functional tests, it should be straightforward and relatively quick to use this application config option; run your tests, and expose each attribute (via `attr_accessible` or `attr_protected`) as dictated by your failing tests. User Management --------------- NOTE: _Almost every web application has to deal with authorization and authentication. Instead of rolling your own, it is advisable to use common plug-ins. But keep them up-to-date, too. A few additional precautions can make your application even more secure._ -There are a number of authentication plug-ins for Rails available. Good ones, such as the popular "devise":https://github.com/plataformatec/devise and "authlogic":https://github.com/binarylogic/authlogic, store only encrypted passwords, not plain-text passwords. In Rails 3.1 you can use the built-in +has_secure_password+ method which has similar features. +There are a number of authentication plug-ins for Rails available. Good ones, such as the popular "devise":https://github.com/plataformatec/devise and "authlogic":https://github.com/binarylogic/authlogic, store only encrypted passwords, not plain-text passwords. In Rails 3.1 you can use the built-in `has_secure_password` method which has similar features. Every new user gets an activation code to activate his account when he gets an e-mail with a link in it. After activating the account, the activation_code columns will be set to NULL in the database. If someone requested an URL like these, he would be logged in as the first activated user found in the database (and chances are that this is the administrator): @@ -635,7 +635,7 @@ Note that this only protects you against the most common mistake when using the WARNING: _Changing a single parameter may give the user unauthorized access. Remember that every parameter may be changed, no matter how much you hide or obfuscate it._ -The most common parameter that a user might tamper with, is the id parameter, as in +http://www.domain.com/project/1+, whereas 1 is the id. It will be available in params in the controller. There, you will most likely do something like this: +The most common parameter that a user might tamper with, is the id parameter, as in `http://www.domain.com/project/1`, whereas 1 is the id. It will be available in params in the controller. There, you will most likely do something like this: ```ruby @project = Project.find(params[:id]) @@ -736,7 +736,7 @@ Also, the second query renames some columns with the AS statement so that the we #### Countermeasures -Ruby on Rails has a built-in filter for special SQL characters, which will escape ' , " , NULL character and line breaks. <em class="highlight">Using +Model.find(id)+ or +Model.find_by_some thing(something)+ automatically applies this countermeasure</em>. But in SQL fragments, especially <em class="highlight">in conditions fragments (+where("...")+), the +connection.execute()+ or +Model.find_by_sql()+ methods, it has to be applied manually</em>. +Ruby on Rails has a built-in filter for special SQL characters, which will escape ' , " , NULL character and line breaks. <em class="highlight">Using `Model.find(id)` or `Model.find_by_some thing(something)` automatically applies this countermeasure</em>. But in SQL fragments, especially <em class="highlight">in conditions fragments (`where("...")`), the `connection.execute()` or `Model.find_by_sql()` methods, it has to be applied manually</em>. Instead of passing a string to the conditions option, you can pass an array to sanitize tainted strings like this: @@ -750,7 +750,7 @@ As you can see, the first part of the array is an SQL fragment with question mar Model.where(:login => entered_user_name, :password => entered_password).first ``` -The array or hash form is only available in model instances. You can try +sanitize_sql()+ elsewhere. _(highlight)Make it a habit to think about the security consequences when using an external string in SQL_. +The array or hash form is only available in model instances. You can try `sanitize_sql()` elsewhere. _(highlight)Make it a habit to think about the security consequences when using an external string in SQL_. ### Cross-Site Scripting (XSS) @@ -847,7 +847,7 @@ s = sanitize(user_input, :tags => tags, :attributes => %w(href title)) This allows only the given tags and does a good job, even against all kinds of tricks and malformed tags. -As a second step, _(highlight)it is good practice to escape all output of the application_, especially when re-displaying user input, which hasn't been input-filtered (as in the search form example earlier on). _(highlight)Use +escapeHTML()+ (or its alias +h()+) method_ to replace the HTML input characters &, ", <, > by their uninterpreted representations in HTML (+&amp;+, +&quot;+, +&lt+;, and +&gt;+). However, it can easily happen that the programmer forgets to use it, so <em class="highlight">it is recommended to use the "SafeErb":http://safe-erb.rubyforge.org/svn/plugins/safe_erb/ plugin</em>. SafeErb reminds you to escape strings from external sources. +As a second step, _(highlight)it is good practice to escape all output of the application_, especially when re-displaying user input, which hasn't been input-filtered (as in the search form example earlier on). _(highlight)Use `escapeHTML()` (or its alias `h()`) method_ to replace the HTML input characters &, ", <, > by their uninterpreted representations in HTML (`&amp;`, `&quot;`, `&lt`;, and `&gt;`). However, it can easily happen that the programmer forgets to use it, so <em class="highlight">it is recommended to use the "SafeErb":http://safe-erb.rubyforge.org/svn/plugins/safe_erb/ plugin</em>. SafeErb reminds you to escape strings from external sources. ##### Obfuscation and Encoding Injection @@ -918,13 +918,13 @@ The "moz-binding":http://www.securiteam.com/securitynews/5LP051FHPE.html CSS pro #### Countermeasures -This example, again, showed that a blacklist filter is never complete. However, as custom CSS in web applications is a quite rare feature, I am not aware of a whitelist CSS filter. _(highlight)If you want to allow custom colors or images, you can allow the user to choose them and build the CSS in the web application_. Use Rails' +sanitize()+ method as a model for a whitelist CSS filter, if you really need one. +This example, again, showed that a blacklist filter is never complete. However, as custom CSS in web applications is a quite rare feature, I am not aware of a whitelist CSS filter. _(highlight)If you want to allow custom colors or images, you can allow the user to choose them and build the CSS in the web application_. Use Rails' `sanitize()` method as a model for a whitelist CSS filter, if you really need one. ### Textile Injection If you want to provide text formatting other than HTML (due to security), use a mark-up language which is converted to HTML on the server-side. "RedCloth":http://redcloth.org/ is such a language for Ruby, but without precautions, it is also vulnerable to XSS. -For example, RedCloth translates +_test_+ to <em>test<em>, which makes the text italic. However, up to the current version 3.0.4, it is still vulnerable to XSS. Get the "all-new version 4":http://www.redcloth.org that removed serious bugs. However, even that version has "some security bugs":http://www.rorsecurity.info/journal/2008/10/13/new-redcloth-security.html, so the countermeasures still apply. Here is an example for version 3.0.4: +For example, RedCloth translates `_test_` to <em>test<em>, which makes the text italic. However, up to the current version 3.0.4, it is still vulnerable to XSS. Get the "all-new version 4":http://www.redcloth.org that removed serious bugs. However, even that version has "some security bugs":http://www.rorsecurity.info/journal/2008/10/13/new-redcloth-security.html, so the countermeasures still apply. Here is an example for version 3.0.4: ```ruby RedCloth.new('<script>alert(1)</script>').to_html @@ -961,7 +961,7 @@ NOTE: _Use user-supplied command line parameters with caution._ If your application has to execute commands in the underlying operating system, there are several methods in Ruby: exec(command), syscall(command), system(command) and `command`. You will have to be especially careful with these functions if the user may enter the whole command, or a part of it. This is because in most shells, you can execute another command at the end of the first one, concatenating them with a semicolon (;) or a vertical bar (|). -A countermeasure is to _(highlight)use the +system(command, parameters)+ method which passes command line parameters safely_. +A countermeasure is to _(highlight)use the `system(command, parameters)` method which passes command line parameters safely_. ```ruby system("/bin/echo","hello; rm *") @@ -1002,7 +1002,7 @@ HTTP/1.1 302 Moved Temporarily Location: http://www.malicious.tld ``` -So _(highlight)attack vectors for Header Injection are based on the injection of CRLF characters in a header field._ And what could an attacker do with a false redirection? He could redirect to a phishing site that looks the same as yours, but asks to login again (and sends the login credentials to the attacker). Or he could install malicious software through browser security holes on that site. Rails 2.1.2 escapes these characters for the Location field in the +redirect_to+ method. _(highlight)Make sure you do it yourself when you build other header fields with user input._ +So _(highlight)attack vectors for Header Injection are based on the injection of CRLF characters in a header field._ And what could an attacker do with a false redirection? He could redirect to a phishing site that looks the same as yours, but asks to login again (and sends the login credentials to the attacker). Or he could install malicious software through browser security holes on that site. Rails 2.1.2 escapes these characters for the Location field in the `redirect_to` method. _(highlight)Make sure you do it yourself when you build other header fields with user input._ #### Response Splitting diff --git a/guides/source/testing.md b/guides/source/testing.md index 878e2eeb87..59213ec43f 100644 --- a/guides/source/testing.md +++ b/guides/source/testing.md @@ -26,13 +26,13 @@ Testing support was woven into the Rails fabric from the beginning. It wasn't an ### The Test Environment -By default, every Rails application has three environments: development, test, and production. The database for each one of them is configured in +config/database.yml+. +By default, every Rails application has three environments: development, test, and production. The database for each one of them is configured in `config/database.yml`. A dedicated test database allows you to set up and interact with test data in isolation. Tests can mangle test data with confidence, that won't touch the data in the development or production databases. ### Rails Sets up for Testing from the Word Go -Rails creates a +test+ folder for you as soon as you create a Rails project using +rails new+ _application_name_. If you list the contents of this folder then you shall see: +Rails creates a `test` folder for you as soon as you create a Rails project using `rails new` _application_name_. If you list the contents of this folder then you shall see: ```bash $ ls -F test @@ -40,11 +40,11 @@ $ ls -F test fixtures/ functional/ integration/ performance/ test_helper.rb unit/ ``` -The +unit+ directory is meant to hold tests for your models, the +functional+ directory is meant to hold tests for your controllers, the +integration+ directory is meant to hold tests that involve any number of controllers interacting, and the +performance+ directory is meant for performance tests. +The `unit` directory is meant to hold tests for your models, the `functional` directory is meant to hold tests for your controllers, the `integration` directory is meant to hold tests that involve any number of controllers interacting, and the `performance` directory is meant for performance tests. -Fixtures are a way of organizing test data; they reside in the +fixtures+ folder. +Fixtures are a way of organizing test data; they reside in the `fixtures` folder. -The +test_helper.rb+ file holds the default configuration for your tests. +The `test_helper.rb` file holds the default configuration for your tests. ### The Low-Down on Fixtures @@ -54,11 +54,11 @@ For good tests, you'll need to give some thought to setting up test data. In Rai _Fixtures_ is a fancy word for sample data. Fixtures allow you to populate your testing database with predefined data before your tests run. Fixtures are database independent written in YAML. There is one file per model. -You'll find fixtures under your +test/fixtures+ directory. When you run +rails generate model+ to create a new model fixture stubs will be automatically created and placed in this directory. +You'll find fixtures under your `test/fixtures` directory. When you run `rails generate model` to create a new model fixture stubs will be automatically created and placed in this directory. #### YAML -YAML-formatted fixtures are a very human-friendly way to describe your sample data. These types of fixtures have the *.yml* file extension (as in +users.yml+). +YAML-formatted fixtures are a very human-friendly way to describe your sample data. These types of fixtures have the *.yml* file extension (as in `users.yml`). Here's a sample YAML fixture file: @@ -91,7 +91,7 @@ user_<%= n %>: #### Fixtures in Action -Rails by default automatically loads all fixtures from the +test/fixtures+ folder for your unit and functional test. Loading involves three steps: +Rails by default automatically loads all fixtures from the `test/fixtures` folder for your unit and functional test. Loading involves three steps: * Remove any existing data from the table corresponding to the fixture * Load the fixture data into the table @@ -121,7 +121,7 @@ For this guide we will be using Rails _scaffolding_. It will create the model, a NOTE: For more information on Rails <i>scaffolding</i>, refer to "Getting Started with Rails":getting_started.html -When you use +rails generate scaffold+, for a resource among other things it creates a test stub in the +test/unit+ folder: +When you use `rails generate scaffold`, for a resource among other things it creates a test stub in the `test/unit` folder: ```bash $ rails generate scaffold post title:string body:text @@ -132,7 +132,7 @@ create test/fixtures/posts.yml ... ``` -The default test stub in +test/unit/post_test.rb+ looks like this: +The default test stub in `test/unit/post_test.rb` looks like this: ```ruby require 'test_helper' @@ -151,17 +151,17 @@ A line by line examination of this file will help get you oriented to Rails test require 'test_helper' ``` -As you know by now, +test_helper.rb+ specifies the default configuration to run our tests. This is included with all the tests, so any methods added to this file are available to all your tests. +As you know by now, `test_helper.rb` specifies the default configuration to run our tests. This is included with all the tests, so any methods added to this file are available to all your tests. ```ruby class PostTest < ActiveSupport::TestCase ``` -The +PostTest+ class defines a _test case_ because it inherits from +ActiveSupport::TestCase+. +PostTest+ thus has all the methods available from +ActiveSupport::TestCase+. You'll see those methods a little later in this guide. +The `PostTest` class defines a _test case_ because it inherits from `ActiveSupport::TestCase`. `PostTest` thus has all the methods available from `ActiveSupport::TestCase`. You'll see those methods a little later in this guide. -Any method defined within a +Test::Unit+ test case that begins with +test+ (case sensitive) is simply called a test. So, +test_password+, +test_valid_password+ and +testValidPassword+ all are legal test names and are run automatically when the test case is run. +Any method defined within a `Test::Unit` test case that begins with `test` (case sensitive) is simply called a test. So, `test_password`, `test_valid_password` and `testValidPassword` all are legal test names and are run automatically when the test case is run. -Rails adds a +test+ method that takes a test name and a block. It generates a normal +Test::Unit+ test with method names prefixed with +test_+. So, +Rails adds a `test` method that takes a test name and a block. It generates a normal `Test::Unit` test with method names prefixed with `test_`. So, ```ruby test "the truth" do @@ -177,9 +177,9 @@ def test_the_truth end ``` -only the +test+ macro allows a more readable test name. You can still use regular method definitions though. +only the `test` macro allows a more readable test name. You can still use regular method definitions though. -NOTE: The method name is generated by replacing spaces with underscores. The result does not need to be a valid Ruby identifier though, the name may contain punctuation characters etc. That's because in Ruby technically any string may be a method name. Odd ones need +define_method+ and +send+ calls, but formally there's no restriction. +NOTE: The method name is generated by replacing spaces with underscores. The result does not need to be a valid Ruby identifier though, the name may contain punctuation characters etc. That's because in Ruby technically any string may be a method name. Odd ones need `define_method` and `send` calls, but formally there's no restriction. ```ruby assert true @@ -204,20 +204,20 @@ $ rake db:migrate $ rake db:test:load ``` -The +rake db:migrate+ above runs any pending migrations on the _development_ environment and updates +db/schema.rb+. The +rake db:test:load+ recreates the test database from the current +db/schema.rb+. On subsequent attempts, it is a good idea to first run +db:test:prepare+, as it first checks for pending migrations and warns you appropriately. +The `rake db:migrate` above runs any pending migrations on the _development_ environment and updates `db/schema.rb`. The `rake db:test:load` recreates the test database from the current `db/schema.rb`. On subsequent attempts, it is a good idea to first run `db:test:prepare`, as it first checks for pending migrations and warns you appropriately. -NOTE: +db:test:prepare+ will fail with an error if +db/schema.rb+ doesn't exist. +NOTE: `db:test:prepare` will fail with an error if `db/schema.rb` doesn't exist. #### Rake Tasks for Preparing your Application for Testing |_.Tasks |_.Description| -|+rake db:test:clone+ |Recreate the test database from the current environment's database schema| -|+rake db:test:clone_structure+ |Recreate the test database from the development structure| -|+rake db:test:load+ |Recreate the test database from the current +schema.rb+| -|+rake db:test:prepare+ |Check for pending migrations and load the test schema| -|+rake db:test:purge+ |Empty the test database.| +|`rake db:test:clone` |Recreate the test database from the current environment's database schema| +|`rake db:test:clone_structure` |Recreate the test database from the development structure| +|`rake db:test:load` |Recreate the test database from the current `schema.rb`| +|`rake db:test:prepare` |Check for pending migrations and load the test schema| +|`rake db:test:purge` |Empty the test database.| -TIP: You can see all these rake tasks and their descriptions by running +rake --tasks --describe+ +TIP: You can see all these rake tasks and their descriptions by running `rake --tasks --describe` ### Running Tests @@ -234,9 +234,9 @@ Finished in 0.023513 seconds. 1 tests, 1 assertions, 0 failures, 0 errors ``` -This will run all the test methods from the test case. Note that +test_helper.rb+ is in the +test+ directory, hence this directory needs to be added to the load path using the +-I+ switch. +This will run all the test methods from the test case. Note that `test_helper.rb` is in the `test` directory, hence this directory needs to be added to the load path using the `-I` switch. -You can also run a particular test method from the test case by using the +-n+ switch with the +test method name+. +You can also run a particular test method from the test case by using the `-n` switch with the `test method name`. ```bash $ ruby -Itest test/unit/post_test.rb -n test_the_truth @@ -249,9 +249,9 @@ Finished in 0.023513 seconds. 1 tests, 1 assertions, 0 failures, 0 errors ``` -The +.+ (dot) above indicates a passing test. When a test fails you see an +F+; when a test throws an error you see an +E+ in its place. The last line of the output is the summary. +The `.` (dot) above indicates a passing test. When a test fails you see an `F`; when a test throws an error you see an `E` in its place. The last line of the output is the summary. -To see how a test failure is reported, you can add a failing test to the +post_test.rb+ test case. +To see how a test failure is reported, you can add a failing test to the `post_test.rb` test case. ```ruby test "should not save post without title" do @@ -276,7 +276,7 @@ test_should_not_save_post_without_title(PostTest) [/test/unit/post_test.rb:6]: 1 tests, 1 assertions, 1 failures, 0 errors ``` -In the output, +F+ denotes a failure. You can see the corresponding trace shown under +1)+ along with the name of the failing test. The next few lines contain the stack trace followed by a message which mentions the actual value and the expected value by the assertion. The default assertion messages provide just enough information to help pinpoint the error. To make the assertion failure message more readable, every assertion provides an optional message parameter, as shown here: +In the output, `F` denotes a failure. You can see the corresponding trace shown under `1)` along with the name of the failing test. The next few lines contain the stack trace followed by a message which mentions the actual value and the expected value by the assertion. The default assertion messages provide just enough information to help pinpoint the error. To make the assertion failure message more readable, every assertion provides an optional message parameter, as shown here: ```ruby test "should not save post without title" do @@ -357,28 +357,28 @@ Ideally, you would like to include a test for everything which could possibly br By now you've caught a glimpse of some of the assertions that are available. Assertions are the worker bees of testing. They are the ones that actually perform the checks to ensure that things are going as planned. -There are a bunch of different types of assertions you can use. Here's the complete list of assertions that ship with +test/unit+, the default testing library used by Rails. The +[msg]+ parameter is an optional string message you can specify to make your test failure messages clearer. It's not required. +There are a bunch of different types of assertions you can use. Here's the complete list of assertions that ship with `test/unit`, the default testing library used by Rails. The `[msg]` parameter is an optional string message you can specify to make your test failure messages clearer. It's not required. |_.Assertion |_.Purpose| -|+assert( boolean, [msg] )+ |Ensures that the object/expression is true.| -|+assert_equal( expected, actual, [msg] )+ |Ensures that +expected == actual+ is true.| -|+assert_not_equal( expected, actual, [msg] )+ |Ensures that +expected != actual+ is true.| -|+assert_same( expected, actual, [msg] )+ |Ensures that +expected.equal?(actual)+ is true.| -|+assert_not_same( expected, actual, [msg] )+ |Ensures that +!expected.equal?(actual)+ is true.| -|+assert_nil( obj, [msg] )+ |Ensures that +obj.nil?+ is true.| -|+assert_not_nil( obj, [msg] )+ |Ensures that +!obj.nil?+ is true.| -|+assert_match( regexp, string, [msg] )+ |Ensures that a string matches the regular expression.| -|+assert_no_match( regexp, string, [msg] )+ |Ensures that a string doesn't match the regular expression.| -|+assert_in_delta( expecting, actual, delta, [msg] )+ |Ensures that the numbers +expecting+ and +actual+ are within +delta+ of each other.| -|+assert_throws( symbol, [msg] ) { block }+ |Ensures that the given block throws the symbol.| -|+assert_raise( exception1, exception2, ... ) { block }+ |Ensures that the given block raises one of the given exceptions.| -|+assert_nothing_raised( exception1, exception2, ... ) { block }+ |Ensures that the given block doesn't raise one of the given exceptions.| -|+assert_instance_of( class, obj, [msg] )+ |Ensures that +obj+ is of the +class+ type.| -|+assert_kind_of( class, obj, [msg] )+ |Ensures that +obj+ is or descends from +class+.| -|+assert_respond_to( obj, symbol, [msg] )+ |Ensures that +obj+ has a method called +symbol+.| -|+assert_operator( obj1, operator, obj2, [msg] )+ |Ensures that +obj1.operator(obj2)+ is true.| -|+assert_send( array, [msg] )+ |Ensures that executing the method listed in +array[1]+ on the object in +array[0]+ with the parameters of +array[2 and up]+ is true. This one is weird eh?| -|+flunk( [msg] )+ |Ensures failure. This is useful to explicitly mark a test that isn't finished yet.| +|`assert( boolean, [msg] )` |Ensures that the object/expression is true.| +|`assert_equal( expected, actual, [msg] )` |Ensures that `expected == actual` is true.| +|`assert_not_equal( expected, actual, [msg] )` |Ensures that `expected != actual` is true.| +|`assert_same( expected, actual, [msg] )` |Ensures that `expected.equal?(actual)` is true.| +|`assert_not_same( expected, actual, [msg] )` |Ensures that `!expected.equal?(actual)` is true.| +|`assert_nil( obj, [msg] )` |Ensures that `obj.nil?` is true.| +|`assert_not_nil( obj, [msg] )` |Ensures that `!obj.nil?` is true.| +|`assert_match( regexp, string, [msg] )` |Ensures that a string matches the regular expression.| +|`assert_no_match( regexp, string, [msg] )` |Ensures that a string doesn't match the regular expression.| +|`assert_in_delta( expecting, actual, delta, [msg] )` |Ensures that the numbers `expecting` and `actual` are within `delta` of each other.| +|`assert_throws( symbol, [msg] ) { block }` |Ensures that the given block throws the symbol.| +|`assert_raise( exception1, exception2, ... ) { block }` |Ensures that the given block raises one of the given exceptions.| +|`assert_nothing_raised( exception1, exception2, ... ) { block }` |Ensures that the given block doesn't raise one of the given exceptions.| +|`assert_instance_of( class, obj, [msg] )` |Ensures that `obj` is of the `class` type.| +|`assert_kind_of( class, obj, [msg] )` |Ensures that `obj` is or descends from `class`.| +|`assert_respond_to( obj, symbol, [msg] )` |Ensures that `obj` has a method called `symbol`.| +|`assert_operator( obj1, operator, obj2, [msg] )` |Ensures that `obj1.operator(obj2)` is true.| +|`assert_send( array, [msg] )` |Ensures that executing the method listed in `array[1]` on the object in `array[0]` with the parameters of `array[2 and up]` is true. This one is weird eh?| +|`flunk( [msg] )` |Ensures failure. This is useful to explicitly mark a test that isn't finished yet.| Because of the modular nature of the testing framework, it is possible to create your own assertions. In fact, that's exactly what Rails does. It includes some specialized assertions to make your life easier. @@ -386,19 +386,19 @@ NOTE: Creating your own assertions is an advanced topic that we won't cover in t ### Rails Specific Assertions -Rails adds some custom assertions of its own to the +test/unit+ framework: +Rails adds some custom assertions of its own to the `test/unit` framework: -NOTE: +assert_valid(record)+ has been deprecated. Please use +assert(record.valid?)+ instead. +NOTE: `assert_valid(record)` has been deprecated. Please use `assert(record.valid?)` instead. |_.Assertion |_.Purpose| -|+assert_valid(record)+ |Ensures that the passed record is valid by Active Record standards and returns any error messages if it is not.| -|+assert_difference(expressions, difference = 1, message = nil) {...}+ |Test numeric difference between the return value of an expression as a result of what is evaluated in the yielded block.| -|+assert_no_difference(expressions, message = nil, &block)+ |Asserts that the numeric result of evaluating an expression is not changed before and after invoking the passed in block.| -|+assert_recognizes(expected_options, path, extras={}, message=nil)+ |Asserts that the routing of the given path was handled correctly and that the parsed options (given in the expected_options hash) match path. Basically, it asserts that Rails recognizes the route given by expected_options.| -|+assert_generates(expected_path, options, defaults={}, extras = {}, message=nil)+ |Asserts that the provided options can be used to generate the provided path. This is the inverse of assert_recognizes. The extras parameter is used to tell the request the names and values of additional request parameters that would be in a query string. The message parameter allows you to specify a custom error message for assertion failures.| -|+assert_response(type, message = nil)+ |Asserts that the response comes with a specific status code. You can specify +:success+ to indicate 200-299, +:redirect+ to indicate 300-399, +:missing+ to indicate 404, or +:error+ to match the 500-599 range| -|+assert_redirected_to(options = {}, message=nil)+ |Assert that the redirection options passed in match those of the redirect called in the latest action. This match can be partial, such that +assert_redirected_to(:controller => "weblog")+ will also match the redirection of +redirect_to(:controller => "weblog", :action => "show")+ and so on.| -|+assert_template(expected = nil, message=nil)+ |Asserts that the request was rendered with the appropriate template file.| +|`assert_valid(record)` |Ensures that the passed record is valid by Active Record standards and returns any error messages if it is not.| +|`assert_difference(expressions, difference = 1, message = nil) {...}` |Test numeric difference between the return value of an expression as a result of what is evaluated in the yielded block.| +|`assert_no_difference(expressions, message = nil, &block)` |Asserts that the numeric result of evaluating an expression is not changed before and after invoking the passed in block.| +|`assert_recognizes(expected_options, path, extras={}, message=nil)` |Asserts that the routing of the given path was handled correctly and that the parsed options (given in the expected_options hash) match path. Basically, it asserts that Rails recognizes the route given by expected_options.| +|`assert_generates(expected_path, options, defaults={}, extras = {}, message=nil)` |Asserts that the provided options can be used to generate the provided path. This is the inverse of assert_recognizes. The extras parameter is used to tell the request the names and values of additional request parameters that would be in a query string. The message parameter allows you to specify a custom error message for assertion failures.| +|`assert_response(type, message = nil)` |Asserts that the response comes with a specific status code. You can specify `:success` to indicate 200-299, `:redirect` to indicate 300-399, `:missing` to indicate 404, or `:error` to match the 500-599 range| +|`assert_redirected_to(options = {}, message=nil)` |Assert that the redirection options passed in match those of the redirect called in the latest action. This match can be partial, such that `assert_redirected_to(:controller => "weblog")` will also match the redirection of `redirect_to(:controller => "weblog", :action => "show")` and so on.| +|`assert_template(expected = nil, message=nil)` |Asserts that the request was rendered with the appropriate template file.| You'll see the usage of some of these assertions in the next chapter. @@ -417,9 +417,9 @@ You should test for things such as: * was the correct object stored in the response template? * was the appropriate message displayed to the user in the view? -Now that we have used Rails scaffold generator for our +Post+ resource, it has already created the controller code and functional tests. You can take look at the file +posts_controller_test.rb+ in the +test/functional+ directory. +Now that we have used Rails scaffold generator for our `Post` resource, it has already created the controller code and functional tests. You can take look at the file `posts_controller_test.rb` in the `test/functional` directory. -Let me take you through one such test, +test_should_get_index+ from the file +posts_controller_test.rb+. +Let me take you through one such test, `test_should_get_index` from the file `posts_controller_test.rb`. ```ruby test "should get index" do @@ -429,30 +429,30 @@ test "should get index" do end ``` -In the +test_should_get_index+ test, Rails simulates a request on the action called +index+, making sure the request was successful and also ensuring that it assigns a valid +posts+ instance variable. +In the `test_should_get_index` test, Rails simulates a request on the action called `index`, making sure the request was successful and also ensuring that it assigns a valid `posts` instance variable. -The +get+ method kicks off the web request and populates the results into the response. It accepts 4 arguments: +The `get` method kicks off the web request and populates the results into the response. It accepts 4 arguments: * The action of the controller you are requesting. This can be in the form of a string or a symbol. * An optional hash of request parameters to pass into the action (eg. query string parameters or post variables). * An optional hash of session variables to pass along with the request. * An optional hash of flash values. -Example: Calling the +:show+ action, passing an +id+ of 12 as the +params+ and setting a +user_id+ of 5 in the session: +Example: Calling the `:show` action, passing an `id` of 12 as the `params` and setting a `user_id` of 5 in the session: ```ruby get(:show, {'id' => "12"}, {'user_id' => 5}) ``` -Another example: Calling the +:view+ action, passing an +id+ of 12 as the +params+, this time with no session, but with a flash message. +Another example: Calling the `:view` action, passing an `id` of 12 as the `params`, this time with no session, but with a flash message. ```ruby get(:view, {'id' => '12'}, nil, {'message' => 'booya!'}) ``` -NOTE: If you try running +test_should_create_post+ test from +posts_controller_test.rb+ it will fail on account of the newly added model level validation and rightly so. +NOTE: If you try running `test_should_create_post` test from `posts_controller_test.rb` it will fail on account of the newly added model level validation and rightly so. -Let us modify +test_should_create_post+ test in +posts_controller_test.rb+ so that all our test pass: +Let us modify `test_should_create_post` test in `posts_controller_test.rb` so that all our test pass: ```ruby test "should create post" do @@ -468,14 +468,14 @@ Now you can try running all the tests and they should pass. ### Available Request Types for Functional Tests -If you're familiar with the HTTP protocol, you'll know that +get+ is a type of request. There are 6 request types supported in Rails functional tests: +If you're familiar with the HTTP protocol, you'll know that `get` is a type of request. There are 6 request types supported in Rails functional tests: -* +get+ -* +post+ -* +patch+ -* +put+ -* +head+ -* +delete+ +* `get` +* `post` +* `patch` +* `put` +* `head` +* `delete` All of request types are methods that you can use, however, you'll probably end up using the first two more often than the others. @@ -483,14 +483,14 @@ NOTE: Functional tests do not verify whether the specified request type should b ### The Four Hashes of the Apocalypse -After a request has been made by using one of the 5 methods (+get+, +post+, etc.) and processed, you will have 4 Hash objects ready for use: +After a request has been made by using one of the 5 methods (`get`, `post`, etc.) and processed, you will have 4 Hash objects ready for use: -* +assigns+ - Any objects that are stored as instance variables in actions for use in views. -* +cookies+ - Any cookies that are set. -* +flash+ - Any objects living in the flash. -* +session+ - Any object living in session variables. +* `assigns` - Any objects that are stored as instance variables in actions for use in views. +* `cookies` - Any cookies that are set. +* `flash` - Any objects living in the flash. +* `session` - Any object living in session variables. -As is the case with normal Hash objects, you can access the values by referencing the keys by string. You can also reference them by symbol name, except for +assigns+. For example: +As is the case with normal Hash objects, you can access the values by referencing the keys by string. You can also reference them by symbol name, except for `assigns`. For example: ```ruby flash["gordon"] flash[:gordon] @@ -505,13 +505,13 @@ assigns["something"] assigns(:something) You also have access to three instance variables in your functional tests: -* +@controller+ - The controller processing the request -* +@request+ - The request -* +@response+ - The response +* `@controller` - The controller processing the request +* `@request` - The request +* `@response` - The response ### Testing Templates and Layouts -If you want to make sure that the response rendered the correct template and layout, you can use the +assert_template+ +If you want to make sure that the response rendered the correct template and layout, you can use the `assert_template` method: ```ruby @@ -522,8 +522,8 @@ test "index should render correct template and layout" do end ``` -Note that you cannot test for template and layout at the same time, with one call to +assert_template+ method. -Also, for the +layout+ test, you can give a regular expression instead of a string, but using the string, makes +Note that you cannot test for template and layout at the same time, with one call to `assert_template` method. +Also, for the `layout` test, you can give a regular expression instead of a string, but using the string, makes things clearer. On the other hand, you have to include the "layouts" directory name even if you save your layout file in this standard layout directory. Hence, @@ -545,11 +545,11 @@ test "new should render correct layout" do end ``` -is the correct way to assert for the layout when the view renders a partial with name +_form+. Omitting the +:partial+ key in your +assert_template+ call will complain. +is the correct way to assert for the layout when the view renders a partial with name `_form`. Omitting the `:partial` key in your `assert_template` call will complain. ### A Fuller Functional Test Example -Here's another example that uses +flash+, +assert_redirected_to+, and +assert_difference+: +Here's another example that uses `flash`, `assert_redirected_to`, and `assert_difference`: ```ruby test "should create post" do @@ -563,15 +563,15 @@ end ### Testing Views -Testing the response to your request by asserting the presence of key HTML elements and their content is a useful way to test the views of your application. The +assert_select+ assertion allows you to do this by using a simple yet powerful syntax. +Testing the response to your request by asserting the presence of key HTML elements and their content is a useful way to test the views of your application. The `assert_select` assertion allows you to do this by using a simple yet powerful syntax. -NOTE: You may find references to +assert_tag+ in other documentation, but this is now deprecated in favor of +assert_select+. +NOTE: You may find references to `assert_tag` in other documentation, but this is now deprecated in favor of `assert_select`. -There are two forms of +assert_select+: +There are two forms of `assert_select`: -+assert_select(selector, [equality], [message])+ ensures that the equality condition is met on the selected elements through the selector. The selector may be a CSS selector expression (String), an expression with substitution values, or an +HTML::Selector+ object. +`assert_select(selector, [equality], [message])` ensures that the equality condition is met on the selected elements through the selector. The selector may be a CSS selector expression (String), an expression with substitution values, or an `HTML::Selector` object. -+assert_select(element, selector, [equality], [message])+ ensures that the equality condition is met on all the selected elements through the selector starting from the _element_ (instance of +HTML::Node+) and its descendants. +`assert_select(element, selector, [equality], [message])` ensures that the equality condition is met on all the selected elements through the selector starting from the _element_ (instance of `HTML::Node`) and its descendants. For example, you could verify the contents on the title element in your response with: @@ -579,7 +579,7 @@ For example, you could verify the contents on the title element in your response assert_select 'title', "Welcome to Rails Testing Guide" ``` -You can also use nested +assert_select+ blocks. In this case the inner +assert_select+ runs the assertion on the complete collection of elements selected by the outer +assert_select+ block: +You can also use nested `assert_select` blocks. In this case the inner `assert_select` runs the assertion on the complete collection of elements selected by the outer `assert_select` block: ```ruby assert_select 'ul.navigation' do @@ -587,7 +587,7 @@ assert_select 'ul.navigation' do end ``` -Alternatively the collection of elements selected by the outer +assert_select+ may be iterated through so that +assert_select+ may be called separately for each element. Suppose for example that the response contains two ordered lists, each with four list elements then the following tests will both pass. +Alternatively the collection of elements selected by the outer `assert_select` may be iterated through so that `assert_select` may be called separately for each element. Suppose for example that the response contains two ordered lists, each with four list elements then the following tests will both pass. ```ruby assert_select "ol" do |elements| @@ -601,18 +601,18 @@ assert_select "ol" do end ``` -The +assert_select+ assertion is quite powerful. For more advanced usage, refer to its "documentation":http://api.rubyonrails.org/classes/ActionDispatch/Assertions/SelectorAssertions.html. +The `assert_select` assertion is quite powerful. For more advanced usage, refer to its "documentation":http://api.rubyonrails.org/classes/ActionDispatch/Assertions/SelectorAssertions.html. #### Additional View-Based Assertions There are more assertions that are primarily used in testing views: |_.Assertion |_.Purpose| -|+assert_select_email+ |Allows you to make assertions on the body of an e-mail. | -|+assert_select_encoded+ |Allows you to make assertions on encoded HTML. It does this by un-encoding the contents of each element and then calling the block with all the un-encoded elements.| -|+css_select(selector)+ or +css_select(element, selector)+ |Returns an array of all the elements selected by the _selector_. In the second variant it first matches the base _element_ and tries to match the _selector_ expression on any of its children. If there are no matches both variants return an empty array.| +|`assert_select_email` |Allows you to make assertions on the body of an e-mail. | +|`assert_select_encoded` |Allows you to make assertions on encoded HTML. It does this by un-encoding the contents of each element and then calling the block with all the un-encoded elements.| +|`css_select(selector)` or `css_select(element, selector)` |Returns an array of all the elements selected by the _selector_. In the second variant it first matches the base _element_ and tries to match the _selector_ expression on any of its children. If there are no matches both variants return an empty array.| -Here's an example of using +assert_select_email+: +Here's an example of using `assert_select_email`: ```ruby assert_select_email do @@ -648,25 +648,25 @@ class UserFlowsTest < ActionDispatch::IntegrationTest end ``` -Integration tests inherit from +ActionDispatch::IntegrationTest+. This makes available some additional helpers to use in your integration tests. Also you need to explicitly include the fixtures to be made available to the test. +Integration tests inherit from `ActionDispatch::IntegrationTest`. This makes available some additional helpers to use in your integration tests. Also you need to explicitly include the fixtures to be made available to the test. ### Helpers Available for Integration Tests In addition to the standard testing helpers, there are some additional helpers available to integration tests: |_.Helper |_.Purpose| -|+https?+ |Returns +true+ if the session is mimicking a secure HTTPS request.| -|+https!+ |Allows you to mimic a secure HTTPS request.| -|+host!+ |Allows you to set the host name to use in the next request.| -|+redirect?+ |Returns +true+ if the last request was a redirect.| -|+follow_redirect!+ |Follows a single redirect response.| -|+request_via_redirect(http_method, path, [parameters], [headers])+ |Allows you to make an HTTP request and follow any subsequent redirects.| -|+post_via_redirect(path, [parameters], [headers])+ |Allows you to make an HTTP POST request and follow any subsequent redirects.| -|+get_via_redirect(path, [parameters], [headers])+ |Allows you to make an HTTP GET request and follow any subsequent redirects.| -|+patch_via_redirect(path, [parameters], [headers])+ |Allows you to make an HTTP PATCH request and follow any subsequent redirects.| -|+put_via_redirect(path, [parameters], [headers])+ |Allows you to make an HTTP PUT request and follow any subsequent redirects.| -|+delete_via_redirect(path, [parameters], [headers])+ |Allows you to make an HTTP DELETE request and follow any subsequent redirects.| -|+open_session+ |Opens a new session instance.| +|`https?` |Returns `true` if the session is mimicking a secure HTTPS request.| +|`https!` |Allows you to mimic a secure HTTPS request.| +|`host!` |Allows you to set the host name to use in the next request.| +|`redirect?` |Returns `true` if the last request was a redirect.| +|`follow_redirect!` |Follows a single redirect response.| +|`request_via_redirect(http_method, path, [parameters], [headers])` |Allows you to make an HTTP request and follow any subsequent redirects.| +|`post_via_redirect(path, [parameters], [headers])` |Allows you to make an HTTP POST request and follow any subsequent redirects.| +|`get_via_redirect(path, [parameters], [headers])` |Allows you to make an HTTP GET request and follow any subsequent redirects.| +|`patch_via_redirect(path, [parameters], [headers])` |Allows you to make an HTTP PATCH request and follow any subsequent redirects.| +|`put_via_redirect(path, [parameters], [headers])` |Allows you to make an HTTP PUT request and follow any subsequent redirects.| +|`delete_via_redirect(path, [parameters], [headers])` |Allows you to make an HTTP DELETE request and follow any subsequent redirects.| +|`open_session` |Opens a new session instance.| ### Integration Testing Examples @@ -754,28 +754,28 @@ Rake Tasks for Running your Tests You don't need to set up and run your tests by hand on a test-by-test basis. Rails comes with a number of rake tasks to help in testing. The table below lists all rake tasks that come along in the default Rakefile when you initiate a Rails project. |_.Tasks |_.Description| -|+rake test+ |Runs all unit, functional and integration tests. You can also simply run +rake+ as the _test_ target is the default.| -|+rake test:benchmark+ |Benchmark the performance tests| -|+rake test:functionals+ |Runs all the functional tests from +test/functional+| -|+rake test:integration+ |Runs all the integration tests from +test/integration+| -|+rake test:profile+ |Profile the performance tests| -|+rake test:recent+ |Tests recent changes| -|+rake test:uncommitted+ |Runs all the tests which are uncommitted. Supports Subversion and Git| -|+rake test:units+ |Runs all the unit tests from +test/unit+| +|`rake test` |Runs all unit, functional and integration tests. You can also simply run `rake` as the _test_ target is the default.| +|`rake test:benchmark` |Benchmark the performance tests| +|`rake test:functionals` |Runs all the functional tests from `test/functional`| +|`rake test:integration` |Runs all the integration tests from `test/integration`| +|`rake test:profile` |Profile the performance tests| +|`rake test:recent` |Tests recent changes| +|`rake test:uncommitted` |Runs all the tests which are uncommitted. Supports Subversion and Git| +|`rake test:units` |Runs all the unit tests from `test/unit`| -Brief Note About +Test::Unit+ +Brief Note About `Test::Unit` ----------------------------- -Ruby ships with a boat load of libraries. One little gem of a library is +Test::Unit+, a framework for unit testing in Ruby. All the basic assertions discussed above are actually defined in +Test::Unit::Assertions+. The class +ActiveSupport::TestCase+ which we have been using in our unit and functional tests extends +Test::Unit::TestCase+, allowing +Ruby ships with a boat load of libraries. One little gem of a library is `Test::Unit`, a framework for unit testing in Ruby. All the basic assertions discussed above are actually defined in `Test::Unit::Assertions`. The class `ActiveSupport::TestCase` which we have been using in our unit and functional tests extends `Test::Unit::TestCase`, allowing us to use all of the basic assertions in our tests. -NOTE: For more information on +Test::Unit+, refer to "test/unit Documentation":http://ruby-doc.org/stdlib/libdoc/test/unit/rdoc/ +NOTE: For more information on `Test::Unit`, refer to "test/unit Documentation":http://ruby-doc.org/stdlib/libdoc/test/unit/rdoc/ Setup and Teardown ------------------ -If you would like to run a block of code before the start of each test and another block of code after the end of each test you have two special callbacks for your rescue. Let's take note of this by looking at an example for our functional test in +Posts+ controller: +If you would like to run a block of code before the start of each test and another block of code after the end of each test you have two special callbacks for your rescue. Let's take note of this by looking at an example for our functional test in `Posts` controller: ```ruby require 'test_helper' @@ -811,14 +811,14 @@ class PostsControllerTest < ActionController::TestCase end ``` -Above, the +setup+ method is called before each test and so +@post+ is available for each of the tests. Rails implements +setup+ and +teardown+ as +ActiveSupport::Callbacks+. Which essentially means you need not only use +setup+ and +teardown+ as methods in your tests. You could specify them by using: +Above, the `setup` method is called before each test and so `@post` is available for each of the tests. Rails implements `setup` and `teardown` as `ActiveSupport::Callbacks`. Which essentially means you need not only use `setup` and `teardown` as methods in your tests. You could specify them by using: * a block * a method (like in the earlier example) * a method name as a symbol * a lambda -Let's see the earlier example by specifying +setup+ callback by specifying a method name as a symbol: +Let's see the earlier example by specifying `setup` callback by specifying a method name as a symbol: ```ruby require '../test_helper' @@ -863,7 +863,7 @@ end Testing Routes -------------- -Like everything else in your Rails application, it is recommended that you test your routes. An example test for a route in the default +show+ action of +Posts+ controller above should look like: +Like everything else in your Rails application, it is recommended that you test your routes. An example test for a route in the default `show` action of `Posts` controller above should look like: ```ruby test "should route to post" do @@ -896,13 +896,13 @@ In order to test that your mailer is working as expected, you can use unit tests #### Revenge of the Fixtures -For the purposes of unit testing a mailer, fixtures are used to provide an example of how the output _should_ look. Because these are example emails, and not Active Record data like the other fixtures, they are kept in their own subdirectory apart from the other fixtures. The name of the directory within +test/fixtures+ directly corresponds to the name of the mailer. So, for a mailer named +UserMailer+, the fixtures should reside in +test/fixtures/user_mailer+ directory. +For the purposes of unit testing a mailer, fixtures are used to provide an example of how the output _should_ look. Because these are example emails, and not Active Record data like the other fixtures, they are kept in their own subdirectory apart from the other fixtures. The name of the directory within `test/fixtures` directly corresponds to the name of the mailer. So, for a mailer named `UserMailer`, the fixtures should reside in `test/fixtures/user_mailer` directory. When you generated your mailer, the generator creates stub fixtures for each of the mailers actions. If you didn't use the generator you'll have to make those files yourself. #### The Basic Test Case -Here's a unit test to test a mailer named +UserMailer+ whose action +invite+ is used to send an invitation to a friend. It is an adapted version of the base test created by the generator for an +invite+ action. +Here's a unit test to test a mailer named `UserMailer` whose action `invite` is used to send an invitation to a friend. It is an adapted version of the base test created by the generator for an `invite` action. ```ruby require 'test_helper' @@ -922,9 +922,9 @@ class UserMailerTest < ActionMailer::TestCase end ``` -In this test, +@expected+ is an instance of +TMail::Mail+ that you can use in your tests. It is defined in +ActionMailer::TestCase+. The test above uses +@expected+ to construct an email, which it then asserts with email created by the custom mailer. The +invite+ fixture is the body of the email and is used as the sample content to assert against. The helper +read_fixture+ is used to read in the content from this file. +In this test, `@expected` is an instance of `TMail::Mail` that you can use in your tests. It is defined in `ActionMailer::TestCase`. The test above uses `@expected` to construct an email, which it then asserts with email created by the custom mailer. The `invite` fixture is the body of the email and is used as the sample content to assert against. The helper `read_fixture` is used to read in the content from this file. -Here's the content of the +invite+ fixture: +Here's the content of the `invite` fixture: ``` Hi friend@example.com, @@ -934,7 +934,7 @@ You have been invited. Cheers! ``` -This is the right time to understand a little more about writing tests for your mailers. The line +ActionMailer::Base.delivery_method = :test+ in +config/environments/test.rb+ sets the delivery method to test mode so that email will not actually be delivered (useful to avoid spamming your users while testing) but instead it will be appended to an array (+ActionMailer::Base.deliveries+). +This is the right time to understand a little more about writing tests for your mailers. The line `ActionMailer::Base.delivery_method = :test` in `config/environments/test.rb` sets the delivery method to test mode so that email will not actually be delivered (useful to avoid spamming your users while testing) but instead it will be appended to an array (`ActionMailer::Base.deliveries`). However often in unit tests, mails will not actually be sent, simply constructed, as in the example above, where the precise content of the email is checked against what it should be. @@ -962,10 +962,10 @@ end Other Testing Approaches ------------------------ -The built-in +test/unit+ based testing is not the only way to test Rails applications. Rails developers have come up with a wide variety of other approaches and aids for testing, including: +The built-in `test/unit` based testing is not the only way to test Rails applications. Rails developers have come up with a wide variety of other approaches and aids for testing, including: * "NullDB":http://avdi.org/projects/nulldb/, a way to speed up testing by avoiding database use. * "Factory Girl":https://github.com/thoughtbot/factory_girl/tree/master, a replacement for fixtures. * "Machinist":https://github.com/notahat/machinist/tree/master, another replacement for fixtures. -* "Shoulda":http://www.thoughtbot.com/projects/shoulda, an extension to +test/unit+ with additional helpers, macros, and assertions. +* "Shoulda":http://www.thoughtbot.com/projects/shoulda, an extension to `test/unit` with additional helpers, macros, and assertions. * "RSpec":http://relishapp.com/rspec, a behavior-driven development framework diff --git a/guides/source/upgrading_ruby_on_rails.md b/guides/source/upgrading_ruby_on_rails.md index 5bcc49cc55..384bb7c71e 100644 --- a/guides/source/upgrading_ruby_on_rails.md +++ b/guides/source/upgrading_ruby_on_rails.md @@ -57,21 +57,17 @@ Rails 4.0 has changed how errors attach with the `ActiveModel::Validations::Conf Rails 4.0 changed how `assert_generates`, `assert_recognizes`, and `assert_routing` work. Now all these assertions raise `Assertion` instead of `ActionController::RoutingError`. -<<<<<<< HEAD Rails 4.0 also changed the way unicode character routes are drawn. Now you can draw unicode character routes directly. If you already draw such routes, you must change them, for example: -<ruby> +```ruby get Rack::Utils.escape('こんにちは'), :controller => 'welcome', :action => 'index' -</ruby> +``` becomes -<ruby> +```ruby get 'こんにちは', :controller => 'welcome', :action => 'index' -</ruby> -======= -Rails 4.0 also changed the way unicode character routes are drawn. Now you can draw unicode character routes directly. If you already draw such routes, you must change them, e.g. `get Rack::Utils.escape('こんにちは'), :controller => 'welcome', :action => 'index'` to `get 'こんにちは', :controller => 'welcome', :action => 'index'`. ->>>>>>> Convert inline code tags to Markdown +``` ### Active Support |