diff options
| author | Karel Minarik <karmi@karmi.cz> | 2009-01-17 19:12:13 +0100 |
|---|---|---|
| committer | Karel Minarik <karmi@karmi.cz> | 2009-01-17 19:12:13 +0100 |
| commit | 4dd764207cce57ae4f592b383620b2f49fe2c727 (patch) | |
| tree | f3af9edd407de8cfe77a1d69a44d0ba7a73cd55f | |
| parent | 3ad392f6f98e2726c4e5e62d3f45b16ae1c1d89c (diff) | |
| download | rails-4dd764207cce57ae4f592b383620b2f49fe2c727.tar.gz rails-4dd764207cce57ae4f592b383620b2f49fe2c727.tar.bz2 rails-4dd764207cce57ae4f592b383620b2f49fe2c727.zip | |
Clarifications and additions to the introduction part of Internationalization (I18n) guide
21 files changed, 861 insertions, 806 deletions
diff --git a/railties/doc/guides/html/2_2_release_notes.html b/railties/doc/guides/html/2_2_release_notes.html index 0dec014c3e..46d73fa96e 100644 --- a/railties/doc/guides/html/2_2_release_notes.html +++ b/railties/doc/guides/html/2_2_release_notes.html @@ -243,7 +243,7 @@ More information : <div class="paragraph"><p>All told, the Guides provide tens of thousands of words of guidance for beginning and intermediate Rails developers.</p></div>
<div class="paragraph"><p>If you want to generate these guides locally, inside your application:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -283,7 +283,7 @@ More information: <div class="sectionbody">
<div class="paragraph"><p>Supporting the etag and last modified timestamp in HTTP headers means that Rails can now send back an empty response if it gets a request for a resource that hasn’t been modified lately. This allows you to check whether a response needs to be sent at all.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -322,7 +322,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>The work done to make Rails thread-safe is rolling out in Rails 2.2. Depending on your web server infrastructure, this means you can handle more requests with fewer copies of Rails in memory, leading to better server performance and higher utilization of multiple cores.</p></div>
<div class="paragraph"><p>To enable multithreaded dispatching in production mode of your application, add the following line in your <tt>config/environments/production.rb</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -384,7 +384,7 @@ More information: <h3 id="_connection_pooling">5.2. Connection Pooling</h3>
<div class="paragraph"><p>Connection pooling lets Rails distribute database requests across a pool of database connections that will grow to a maximum size (by default 5, but you can add a <tt>pool</tt> key to your <tt>database.yml</tt> to adjust this). This helps remove bottlenecks in applications that support many concurrent users. There’s also a <tt>wait_timeout</tt> that defaults to 5 seconds before giving up. <tt>ActiveRecord::Base.connection_pool</tt> gives you direct access to the pool if you need it.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -416,7 +416,7 @@ More information: <h3 id="_hashes_for_join_table_conditions">5.3. Hashes for Join Table Conditions</h3>
<div class="paragraph"><p>You can now specify conditions on join tables using a hash. This is a big help if you need to query across complex joins.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -449,7 +449,7 @@ More information: <h4 id="_tt_find_last_by_lt_attribute_gt_tt">5.4.1. <tt>find_last_by_<attribute></tt></h4>
<div class="paragraph"><p>The <tt>find_last_by_<attribute></tt> method is equivalent to <tt>Model.last(:conditions => {:attribute => value})</tt></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -465,7 +465,7 @@ Lead Contributor: <a href="http://www.workingwithrails.com/person/9147-emilio-ta <h4 id="_tt_find_by_lt_attribute_gt_tt">5.4.2. <tt>find_by_<attribute>!</tt></h4>
<div class="paragraph"><p>The new bang! version of <tt>find_by_<attribute>!</tt> is equivalent to <tt>Model.first(:conditions => {:attribute => value}) || raise ActiveRecord::RecordNotFound</tt> Instead of returning <tt>nil</tt> if it can’t find a matching record, this method will raise an exception if it cannot find a match.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -529,7 +529,7 @@ Counter cache columns (for associations declared with <tt>:counter_cache => t <h3 id="_shallow_route_nesting">6.1. Shallow Route Nesting</h3>
<div class="paragraph"><p>Shallow route nesting provides a solution to the well-known difficulty of using deeply-nested resources. With shallow nesting, you need only supply enough information to uniquely identify the resource that you want to work with.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -574,7 +574,7 @@ More information: <h3 id="_method_arrays_for_member_or_collection_routes">6.2. Method Arrays for Member or Collection Routes</h3>
<div class="paragraph"><p>You can now supply an array of methods for new member or collection routes. This removes the annoyance of having to define a route as accepting any verb as soon as you need it to handle more than one. With Rails 2.2, this is a legitimate route declaration:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -589,7 +589,7 @@ Lead Contributor: <a href="http://brennandunn.com/">Brennan Dunn</a> <h3 id="_resources_with_specific_actions">6.3. Resources With Specific Actions</h3>
<div class="paragraph"><p>By default, when you use <tt>map.resources</tt> to create a route, Rails generates routes for seven default actions (index, show, create, new, edit, update, and destroy). But each of these routes takes up memory in your application, and causes Rails to generate additional routing logic. Now you can use the <tt>:only</tt> and <tt>:except</tt> options to fine-tune the routes that Rails will generate for resources. You can supply a single action, an array of actions, or the special <tt>:all</tt> or <tt>:none</tt> options. These options are inherited by nested resources.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -696,7 +696,7 @@ More information: <h3 id="_memoization">9.1. Memoization</h3>
<div class="paragraph"><p>Memoization is a pattern of initializing a method once and then stashing its value away for repeat use. You’ve probably used this pattern in your own applications:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -705,7 +705,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>Memoization lets you handle this task in a declarative fashion:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -743,7 +743,7 @@ More information: <h3 id="_tt_each_with_object_tt">9.2. <tt>each_with_object</tt></h3>
<div class="paragraph"><p>The <tt>each_with_object</tt> method provides an alternative to <tt>inject</tt>, using a method backported from Ruby 1.9. It iterates over a collection, passing the current element and the memo into the block.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -752,7 +752,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_delegates_with_prefixes">9.3. Delegates With Prefixes</h3>
<div class="paragraph"><p>If you delegate behavior from one class to another, you can now specify a prefix that will be used to identify the delegated methods. For example:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -762,7 +762,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>This will produce delegated methods <tt>vendor#account_email</tt> and <tt>vendor#account_password</tt>. You can also specify a custom prefix:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -953,7 +953,7 @@ Implicit local assignments when rendering partials has been deprecated. </li>
</ul></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
diff --git a/railties/doc/guides/html/actioncontroller_basics.html b/railties/doc/guides/html/actioncontroller_basics.html index f5b25a4d7a..76d7ee0588 100644 --- a/railties/doc/guides/html/actioncontroller_basics.html +++ b/railties/doc/guides/html/actioncontroller_basics.html @@ -181,7 +181,7 @@ Deal with exceptions that may be raised during request processing <div class="sectionbody">
<div class="paragraph"><p>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 public method with the same name as the action.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -205,7 +205,7 @@ private <div class="paragraph"><p>There’s no rule saying a method on a controller has to be an action; they may well be used for other purposes such as filters, which will be covered later in this guide.</p></div>
<div class="paragraph"><p>As an example, if a user goes to <tt>/clients/new</tt> in your application to add a new client, Rails will create an instance of ClientsController and run the <tt>new</tt> method. Note that the empty method from the example above could work just fine because Rails will by default render the <tt>new.html.erb</tt> view unless the action says otherwise. The <tt>new</tt> method could make available to the view a <tt>@client</tt> instance variable by creating a new Client:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -219,7 +219,7 @@ http://www.gnu.org/software/src-highlite --> <div class="sectionbody">
<div class="paragraph"><p>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 a 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 <tt>params</tt> hash in your controller:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -282,7 +282,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_routing_parameters">3.2. Routing Parameters</h3>
<div class="paragraph"><p>The <tt>params</tt> hash will always contain the <tt>:controller</tt> and <tt>:action</tt> keys, but you should use the methods <tt>controller_name</tt> and <tt>action_name</tt> instead to access these values. Any other parameters defined by the routing, such as <tt>:id</tt> 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 <tt>:status</tt> parameter in a "pretty" URL:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -335,7 +335,7 @@ ActiveRecordStore - Stores the data in a database using Active Record. <div class="paragraph"><p>Read more about session storage in the <a href="../security.html">Security Guide</a>.</p></div>
<div class="paragraph"><p>If you need a different session storage mechanism, you can change it in the <tt>config/environment.rb</tt> file:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -353,7 +353,7 @@ config<span style="color: #990000">.</span>action_controller<span style="color: </div>
<div class="paragraph"><p>Session values are stored using key/value pairs like a hash:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -371,7 +371,7 @@ private <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>To store something in the session, just assign it to the key like a hash:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -389,7 +389,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>To remove something from the session, assign that key to be <tt>nil</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -407,7 +407,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_the_flash">4.2. The flash</h3>
<div class="paragraph"><p>The flash is a special part of the session which is cleared with each request. This means that values stored there will only be available in the next request, which is useful for storing error messages etc. It is accessed in much the same way as the session, like a hash. Let’s use the act of logging out as an example. The controller can send a message which will be displayed to the user on the next request:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -439,7 +439,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>This way, if an action sets an error or a notice message, the layout will display it automatically.</p></div>
<div class="paragraph"><p>If you want a flash value to be carried over to another request, use the <tt>keep</tt> method:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -457,7 +457,7 @@ http://www.gnu.org/software/src-highlite --> <h4 id="_tt_flash_now_tt">4.2.1. <tt>flash.now</tt></h4>
<div class="paragraph"><p>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 <tt>create</tt> action fails to save a resource and you render the <tt>new</tt> 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 <tt>flash.now</tt> in the same way you use the normal <tt>flash</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -479,7 +479,7 @@ http://www.gnu.org/software/src-highlite --> <div class="sectionbody">
<div class="paragraph"><p>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 <tt>cookies</tt> method, which - much like the <tt>session</tt> - works like a hash:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -514,7 +514,7 @@ http://www.gnu.org/software/src-highlite --> <div class="sectionbody">
<div class="paragraph"><p>Filters are methods that are run before, after or "around" a controller action. For example, one filter might check to see if the logged in user has the right credentials to access that particular controller or action. Filters are inherited, so if you set a filter on ApplicationController, it will be run on every controller in your application. A common, simple 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:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -541,7 +541,7 @@ private <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>The method simply stores an error message in the flash and redirects to the login form if the user is not logged in. If a before filter (a filter which is run before the action) renders or redirects, the action will not run. If there are additional filters scheduled to run after the rendering or redirecting filter, they are also cancelled. To use this filter in a controller, use the <tt>before_filter</tt> method:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -552,7 +552,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>In this example, the filter is added to ApplicationController and thus all controllers in the application. This will make everything in the application require the user to be logged in in order to use it. For obvious reasons (the user wouldn’t be able to log in in the first place!), not all controllers or actions should require this. You can prevent this filter from running before particular actions with <tt>skip_before_filter</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -565,7 +565,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_after_filters_and_around_filters">6.1. After Filters and Around Filters</h3>
<div class="paragraph"><p>In addition to the before filters, you can run filters after an action has run or both before and after. The after filter is similar to the before filter, but because the action has already been run it has access to the response data that’s about to be sent to the client. Obviously, after filters can not stop the action from running. Around filters are responsible for running the action, but they can choose not to, which is the around filter’s way of stopping it.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -589,7 +589,7 @@ private <div class="paragraph"><p>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.</p></div>
<div class="paragraph"><p>The first is to use a block directly with the *_filter methods. The block receives the controller as an argument, and the <tt>require_login</tt> filter from above could be rewritten to use a block:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -601,7 +601,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>Note that the filter in this case uses <tt>send</tt> because the <tt>logged_in?</tt> 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.</p></div>
<div class="paragraph"><p>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 than 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:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -629,7 +629,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>Verifications make sure certain criteria are met in order for a controller or action to run. They can specify that a certain key (or several keys in the form of an array) is present in the <tt>params</tt>, <tt>session</tt> or <tt>flash</tt> hashes or that a certain HTTP method was used or that the request was made using XMLHTTPRequest (Ajax). The default action taken when these criteria are not met is to render a 400 Bad Request response, but you can customize this by specifying a redirect URL or rendering something else and you can also add flash messages and HTTP headers to the response. It is described in the <a href="http://api.rubyonrails.org/classes/ActionController/Verification/ClassMethods.html">API documentation</a> as "essentially a special kind of before_filter".</p></div>
<div class="paragraph"><p>Here’s an example of using verification to make sure the user supplies a username and a password in order to log in:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -652,7 +652,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>Now the <tt>create</tt> action won’t run unless the "username" and "password" parameters are present, and if they’re not, an error message will be added to the flash and the <tt>new</tt> action will be rendered. But there’s something rather important missing from the verification above: It will be used for <strong>every</strong> action in LoginsController, which is not what we want. You can limit which actions it will be used for with the <tt>:only</tt> and <tt>:except</tt> options just like a filter:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -670,7 +670,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>Cross-site request forgery is a type of attack in which a site tricks a user into making requests on another site, possibly adding, modifying or deleting data on that site without the user’s knowledge or permission. The first step to avoid this is to make sure all "destructive" actions (create, update and destroy) can only be accessed with non-GET requests. If you’re following RESTful conventions you’re already doing this. However, a malicious site can still send a non-GET request to your site quite easily, and that’s where the request forgery protection comes in. As the name says, it protects from forged requests. The way this is done is to add a non-guessable token which is only known to your server to each request. This way, if a request comes in without the proper token, it will be denied access.</p></div>
<div class="paragraph"><p>If you generate a form like this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -680,7 +680,7 @@ http://www.gnu.org/software/src-highlite --> <span style="color: #FF0000"><% end -%></span></tt></pre></div></div>
<div class="paragraph"><p>You will see how the token gets added as a hidden field:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -797,7 +797,7 @@ headers - Headers used for the response. <h4 id="_setting_custom_headers">9.2.1. Setting Custom Headers</h4>
<div class="paragraph"><p>If you want to set custom headers for a response then <tt>response.headers</tt> 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 - like "Content-Type" - automatically. If you want to add or change a header, just assign it to <tt>headers</tt> with the name and value:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -807,7 +807,7 @@ http://www.gnu.org/software/src-highlite --> <div class="sectionbody">
<div class="paragraph"><p>Rails comes with built-in HTTP Basic authentication. This is an authentication scheme that is supported by the majority of browsers and other HTTP clients. As an example, 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, <tt>authenticate_or_request_with_http_basic</tt>.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -833,7 +833,7 @@ private <div class="paragraph"><p>Sometimes you may want to send a file to the user instead of rendering an HTML page. All controllers in Rails have the <tt>send_data</tt> and the <tt>send_file</tt> methods, that will both stream data to the client. <tt>send_file</tt> is a convenience method which lets you provide the name of a file on the disk and it will stream the contents of that file for you.</p></div>
<div class="paragraph"><p>To stream data to the client, use <tt>send_data</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -862,7 +862,7 @@ private <h3 id="_sending_files">11.1. Sending Files</h3>
<div class="paragraph"><p>If you want to send a file that already exists on disk, use the <tt>send_file</tt> method. This is usually not recommended, but can be useful if you want to perform some authentication before letting the user download the file.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -895,7 +895,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_restful_downloads">11.2. RESTful Downloads</h3>
<div class="paragraph"><p>While <tt>send_data</tt> 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 <tt>show</tt> action, without any streaming:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -914,7 +914,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>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 <tt>config/initializers/mime_types.rb</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -937,7 +937,7 @@ http://www.gnu.org/software/src-highlite --> <div class="sectionbody">
<div class="paragraph"><p>Rails keeps a log file for each environment (development, test and production) in the <tt>log</tt> folder. These are extremely useful when debugging what’s actually going on in your application, but in a live application you may not want every bit of information to be stored in the log file. The <tt>filter_parameter_logging</tt> method can be used to filter out sensitive information from the log. It works by replacing certain values in the <tt>params</tt> hash with "[FILTERED]" as they are written to the log. As an example, let’s see how to filter all parameters with keys that include "password":</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -957,7 +957,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>If you want to do something a bit more elaborate when catching errors, you can use <tt>rescue_from</tt>, 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 <tt>rescue_from</tt> directive, the exception object is passed to the handler. The handler can be a method or a Proc object passed to the <tt>:with</tt> option. You can also use a block directly instead of an explicit Proc object.</p></div>
<div class="paragraph"><p>Here’s how you can use <tt>rescue_from</tt> to intercept all ActiveRecord::RecordNotFound errors and do something with them.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -974,7 +974,7 @@ private <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>Of course, this example is anything but elaborate and doesn’t improve on the default exception handling at all, but once you can catch all those exceptions you’re free to do whatever you want with them. For example, you could create custom exception classes that will be thrown when a user doesn’t have access to a certain section of your application:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
diff --git a/railties/doc/guides/html/active_record_querying.html b/railties/doc/guides/html/active_record_querying.html index e42bd80e2b..d5b0c42dca 100644 --- a/railties/doc/guides/html/active_record_querying.html +++ b/railties/doc/guides/html/active_record_querying.html @@ -174,7 +174,7 @@ Perform various calculations on Active Record models <div class="paragraph"><p>If you’re used to using raw SQL to find database records then, generally, you will find that there are better ways to carry out the same operations in Rails. Active Record insulates you from the need to use SQL in most cases.</p></div>
<div class="paragraph"><p>Code examples throughout this guide will refer to one or more of the following models:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -185,7 +185,7 @@ http://www.gnu.org/software/src-highlite --> has_and_belongs_to_many <span style="color: #990000">:</span>roles
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -193,14 +193,14 @@ http://www.gnu.org/software/src-highlite --> belongs_to <span style="color: #990000">:</span>client
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> MailingAddress <span style="color: #990000"><</span> Address
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -208,7 +208,7 @@ http://www.gnu.org/software/src-highlite --> belongs_to <span style="color: #990000">:</span>client<span style="color: #990000">,</span> <span style="color: #990000">:</span>counter_cache <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #0000FF">true</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -225,7 +225,7 @@ http://www.gnu.org/software/src-highlite --> <div class="sectionbody">
<div class="paragraph"><p>To retrieve objects from the database, Active Record provides a primary method called <tt>find</tt>. This method allows you to pass arguments into it to perform certain queries on your database without the need of SQL. If you wanted to find the record with the id of 1, you could type <tt>Client.find(1)</tt> which would execute this query on your database:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -240,7 +240,7 @@ http://www.gnu.org/software/src-highlite --> </div>
<div class="paragraph"><p>If you wanted to find clients with id 1 or 2, you call <tt>Client.find([1,2])</tt> or <tt>Client.find(1,2)</tt> and then this will be executed as:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -271,7 +271,7 @@ http://www.gnu.org/software/src-highlite --> </div></div>
<div class="paragraph"><p>If you were reading your log file (the default is log/development.log) you may see something like this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -286,7 +286,7 @@ http://www.gnu.org/software/src-highlite --> </div></div>
<div class="paragraph"><p>If you were reading your log file (the default is log/development.log) you may see something like this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -300,7 +300,7 @@ http://www.gnu.org/software/src-highlite --> </tr></table>
</div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -334,14 +334,14 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>Now what if that number could vary, say as a argument from somewhere, or perhaps from the user’s level status somewhere? The find then becomes something like <tt>Client.first(:conditions => ["orders_count = ?", params[:orders]])</tt>. 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 two conditions, you can do it like <tt>Client.first(:conditions => ["orders_count = ? AND locked = ?", params[:orders], false])</tt>. In this example, the first question mark will be replaced with the value in <tt>params[:orders]</tt> and the second will be replaced with the SQL representation of <tt>false</tt>, which depends on the adapter.</p></div>
<div class="paragraph"><p>The reason for doing code like:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>Client<span style="color: #990000">.</span>first<span style="color: #990000">(:</span>conditions <span style="color: #990000">=></span> <span style="color: #990000">[</span><span style="color: #FF0000">"orders_count = ?"</span><span style="color: #990000">,</span> params<span style="color: #990000">[:</span>orders<span style="color: #990000">]])</span></tt></pre></div></div>
<div class="paragraph"><p>instead of:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -357,7 +357,7 @@ http://www.gnu.org/software/src-highlite --> </div>
<div class="paragraph"><p>If you’re looking for a range inside of a table (for example, users created in a certain timeframe) you can use the conditions option coupled with the IN sql statement for this. If you had two dates coming in from a controller you could do something like this to look for a range:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -365,7 +365,7 @@ http://www.gnu.org/software/src-highlite --> <span style="color: #990000">(</span>params<span style="color: #990000">[:</span>start_date<span style="color: #990000">].</span>to_date<span style="color: #990000">)..(</span>params<span style="color: #990000">[:</span>end_date<span style="color: #990000">].</span>to_date<span style="color: #990000">)])</span></tt></pre></div></div>
<div class="paragraph"><p>This would generate the proper query which is great for small ranges but not so good for larger ranges. For example if you pass in a range of date objects spanning a year that’s 365 (or possibly 366, depending on the year) strings it will attempt to match your field against.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -379,14 +379,14 @@ http://www.gnu.org/software/src-highlite --> <span style="color: #FF0000"> '</span><span style="color: #993399">2008</span><span style="color: #990000">-</span><span style="color: #993399">12</span><span style="color: #990000">-</span><span style="color: #993399">27</span><span style="color: #FF0000">','</span><span style="color: #993399">2008</span><span style="color: #990000">-</span><span style="color: #993399">12</span><span style="color: #990000">-</span><span style="color: #993399">28</span><span style="color: #FF0000">','</span><span style="color: #993399">2008</span><span style="color: #990000">-</span><span style="color: #993399">12</span><span style="color: #990000">-</span><span style="color: #993399">29</span><span style="color: #FF0000">','</span><span style="color: #993399">2008</span><span style="color: #990000">-</span><span style="color: #993399">12</span><span style="color: #990000">-</span><span style="color: #993399">30</span><span style="color: #FF0000">','</span><span style="color: #993399">2008</span><span style="color: #990000">-</span><span style="color: #993399">12</span><span style="color: #990000">-</span><span style="color: #993399">31</span><span style="color: #FF0000">'))</span></tt></pre></div></div>
<div class="paragraph"><p>Things can get <strong>really</strong> messy if you pass in Time objects as it will attempt to compare your field to <strong>every second</strong> in that range:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>Client<span style="color: #990000">.</span>all<span style="color: #990000">(:</span>conditions <span style="color: #990000">=></span> <span style="color: #990000">[</span><span style="color: #FF0000">"created_at IN (?)"</span><span style="color: #990000">,</span>
<span style="color: #990000">(</span>params<span style="color: #990000">[:</span>start_date<span style="color: #990000">].</span>to_date<span style="color: #990000">.</span>to_time<span style="color: #990000">)..(</span>params<span style="color: #990000">[:</span>end_date<span style="color: #990000">].</span>to_date<span style="color: #990000">.</span>to_time<span style="color: #990000">)])</span></tt></pre></div></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -401,7 +401,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>Where <em>query</em> is the actual query used to get that error.</p></div>
<div class="paragraph"><p>In this example it would be better to use greater-than and less-than operators in SQL, like so:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -409,7 +409,7 @@ http://www.gnu.org/software/src-highlite --> <span style="color: #990000">[</span><span style="color: #FF0000">"created_at > ? AND created_at < ?"</span><span style="color: #990000">,</span> params<span style="color: #990000">[:</span>start_date<span style="color: #990000">],</span> params<span style="color: #990000">[:</span>end_date<span style="color: #990000">]])</span></tt></pre></div></div>
<div class="paragraph"><p>You can also use the greater-than-or-equal-to and less-than-or-equal-to like this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -419,7 +419,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_placeholder_conditions">2.3. Placeholder Conditions</h3>
<div class="paragraph"><p>Similar to the array style of params you can also specify keys in your conditions:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -429,28 +429,28 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_hash_conditions">2.4. Hash Conditions</h3>
<div class="paragraph"><p>Rails also allows you to pass in a hash conditions which can increase the readability of your conditions syntax. With hash conditions, you pass in a hash with keys of the fields you want conditionalised and the values of how you want to conditionalise them:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>Client<span style="color: #990000">.</span>all<span style="color: #990000">(:</span>conditions <span style="color: #990000">=></span> <span style="color: #FF0000">{</span> <span style="color: #990000">:</span>locked <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #0000FF">true</span></span> <span style="color: #FF0000">}</span><span style="color: #990000">)</span></tt></pre></div></div>
<div class="paragraph"><p>The field name does not have to be a symbol it can also be a string:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>Client<span style="color: #990000">.</span>all<span style="color: #990000">(:</span>conditions <span style="color: #990000">=></span> <span style="color: #FF0000">{</span> <span style="color: #FF0000">'locked'</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #0000FF">true</span></span> <span style="color: #FF0000">}</span><span style="color: #990000">)</span></tt></pre></div></div>
<div class="paragraph"><p>The good thing about this is that we can pass in a range for our fields without it generating a large query as shown in the preamble of this section.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>Client<span style="color: #990000">.</span>all<span style="color: #990000">(:</span>conditions <span style="color: #990000">=></span> <span style="color: #FF0000">{</span> <span style="color: #990000">:</span>created_at <span style="color: #990000">=></span> <span style="color: #990000">(</span>Time<span style="color: #990000">.</span>now<span style="color: #990000">.</span>midnight <span style="color: #990000">-</span> <span style="color: #993399">1</span><span style="color: #990000">.</span>day<span style="color: #990000">)..</span>Time<span style="color: #990000">.</span>now<span style="color: #990000">.</span>midnight<span style="color: #FF0000">}</span><span style="color: #990000">)</span></tt></pre></div></div>
<div class="paragraph"><p>This will find all clients created yesterday by using a BETWEEN sql statement:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -458,14 +458,14 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>This demonstrates a shorter syntax for the examples in <a href="#_array_conditions">Array Conditions</a></p></div>
<div class="paragraph"><p>You can also join in tables and specify their columns in the hash:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>Client<span style="color: #990000">.</span>all<span style="color: #990000">(:</span><span style="font-weight: bold"><span style="color: #0000FF">include</span></span> <span style="color: #990000">=></span> <span style="color: #FF0000">"orders"</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>conditions <span style="color: #990000">=></span> <span style="color: #FF0000">{</span> <span style="color: #FF0000">'orders.created_at'</span> <span style="color: #990000">=></span> <span style="color: #990000">(</span>Time<span style="color: #990000">.</span>now<span style="color: #990000">.</span>midnight <span style="color: #990000">-</span> <span style="color: #993399">1</span><span style="color: #990000">.</span>day<span style="color: #990000">)..</span>Time<span style="color: #990000">.</span>now<span style="color: #990000">.</span>midnight <span style="color: #FF0000">}</span><span style="color: #990000">)</span></tt></pre></div></div>
<div class="paragraph"><p>An alternative and cleaner syntax to this is:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -473,14 +473,14 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>This will find all clients who have orders that were created yesterday, again using a BETWEEN expression.</p></div>
<div class="paragraph"><p>If you want to find records using the IN expression you can pass an array to the conditions hash:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>Client<span style="color: #990000">.</span>all<span style="color: #990000">(:</span><span style="font-weight: bold"><span style="color: #0000FF">include</span></span> <span style="color: #990000">=></span> <span style="color: #FF0000">"orders"</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>conditions <span style="color: #990000">=></span> <span style="color: #FF0000">{</span> <span style="color: #990000">:</span>orders_count <span style="color: #990000">=></span> <span style="color: #990000">[</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">3</span><span style="color: #990000">,</span><span style="color: #993399">5</span><span style="color: #990000">]</span> <span style="color: #FF0000">}</span></tt></pre></div></div>
<div class="paragraph"><p>This code will generate SQL like this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -505,27 +505,27 @@ http://www.gnu.org/software/src-highlite --> <div class="sectionbody">
<div class="paragraph"><p>If you want to limit the amount of records to a certain subset of all the records retrieved you usually use limit for this, sometimes coupled with offset. Limit is the maximum number of records that will be retrieved from a query, and offset is the number of records it will start reading from from the first record of the set. Take this code for example:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>Client<span style="color: #990000">.</span>all<span style="color: #990000">(:</span>limit <span style="color: #990000">=></span> <span style="color: #993399">5</span><span style="color: #990000">)</span></tt></pre></div></div>
<div class="paragraph"><p>This code will return a maximum of 5 clients and because it specifies no offset it will return the first 5 clients in the table. The SQL it executes will look like this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">SELECT</span></span> <span style="color: #990000">*</span> <span style="font-weight: bold"><span style="color: #0000FF">FROM</span></span> clients <span style="font-weight: bold"><span style="color: #0000FF">LIMIT</span></span> <span style="color: #993399">5</span></tt></pre></div></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>Client<span style="color: #990000">.</span>all<span style="color: #990000">(:</span>limit <span style="color: #990000">=></span> <span style="color: #993399">5</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>offset <span style="color: #990000">=></span> <span style="color: #993399">5</span><span style="color: #990000">)</span></tt></pre></div></div>
<div class="paragraph"><p>This code will return a maximum of 5 clients and because it specifies an offset this time, it will return these records starting from the 5th client in the clients table. The SQL looks like:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -535,7 +535,7 @@ http://www.gnu.org/software/src-highlite --> <div class="sectionbody">
<div class="paragraph"><p>The group option for find is useful, for example, if you want to find a collection of the dates orders were created on. You could use the option in this context:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -543,7 +543,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>And this will give you a single <tt>Order</tt> object for each date where there are orders in the database.</p></div>
<div class="paragraph"><p>The SQL that would be executed would be something like this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -554,7 +554,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>The <tt>:having</tt> option allows you to specify SQL and acts as a kind of a filter on the group option. <tt>:having</tt> can only be specified when <tt>:group</tt> is specified.</p></div>
<div class="paragraph"><p>An example of using it would be:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -565,14 +565,14 @@ http://www.gnu.org/software/src-highlite --> <div class="sectionbody">
<div class="paragraph"><p><tt>readonly</tt> is a <tt>find</tt> option that you can set in order to make that instance of the record read-only. Any attempt to alter or destroy the record will not succeed, raising an ActiveRecord::ReadOnlyRecord exception. To set this option, specify it like this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>Client<span style="color: #990000">.</span>first<span style="color: #990000">(:</span>readonly <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #0000FF">true</span></span><span style="color: #990000">)</span></tt></pre></div></div>
<div class="paragraph"><p>If you assign this record to a variable client, calling the following code will raise an ActiveRecord::ReadOnlyRecord exception:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -584,7 +584,7 @@ client<span style="color: #990000">.</span>save</tt></pre></div></div> <div class="sectionbody">
<div class="paragraph"><p>If you’re wanting to stop race conditions for a specific record (for example, you’re incrementing a single field for a record, potentially from multiple simultaneous connections) you can use the lock option to ensure that the record is updated correctly. For safety, you should use this inside a transaction.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -594,7 +594,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>You can also pass SQL to this option to allow 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:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -611,7 +611,7 @@ http://www.gnu.org/software/src-highlite --> <div class="sectionbody">
<div class="paragraph"><p>Eager loading is loading associated records along with any number of records in as few queries as possible. For example, if you wanted to load all the addresses associated with all the clients in a single query you could use <tt>Client.all(:include => :address)</tt>. If you wanted to include both the address and mailing address for the client you would use <tt>Client.find(:all, :include => [:address, :mailing_address])</tt>. Include will first find the client records and then load the associated address records. Running script/server in one window, and executing the code through script/console in another window, the output should look similar to this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -624,7 +624,7 @@ MailingAddress <span style="font-weight: bold"><span style="color: #0000FF">Load <div class="paragraph"><p>If you wanted to get all the addresses for a client in the same query you would do <tt>Client.all(:joins => :address)</tt>.
If you wanted to find the address and mailing address for that client you would do <tt>Client.all(:joins => [:address, :mailing_address])</tt>. This is more efficient because it does all the SQL in one query, as shown by this example:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -633,7 +633,7 @@ http://www.gnu.org/software/src-highlite --> mailing_addresses<span style="color: #990000">.</span>client_id <span style="color: #990000">=</span> client<span style="color: #990000">.</span>id</tt></pre></div></div>
<div class="paragraph"><p>This query is more efficent, but there’s a gotcha: if you have a client who does not have an address or a mailing address they will not be returned in this query at all. If you have any association as an optional association, you may want to use include rather than joins. Alternatively, you can use a SQL join clause to specify exactly the join you need (Rails always assumes an inner join):</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -642,7 +642,7 @@ http://www.gnu.org/software/src-highlite --> client<span style="color: #990000">.</span>id <span style="color: #990000">=</span> mailing_addresses<span style="color: #990000">.</span>client_id”<span style="color: #990000">)</span></tt></pre></div></div>
<div class="paragraph"><p>When using eager loading you can specify conditions for the columns of the tables inside the eager loading to get back a smaller subset. If, for example, you want to find a client and all their orders within the last two weeks you could use eager loading with conditions for this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -657,7 +657,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>If you want to find both by name and locked, you can chain these finders together by simply typing <tt>and</tt> between the fields for example <tt>Client.find_by_name_and_locked("Ryan", true)</tt>.</p></div>
<div class="paragraph"><p>There’s another set of dynamic finders that let you find or create/initialize objects if they aren’t found. These work in a similar fashion to the other finders and can be used like <tt>find_or_create_by_name(params[:name])</tt>. Using this will firstly perform a find and then create if the find returns nil. The SQL looks like this for <tt>Client.find_or_create_by_name("Ryan")</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -668,7 +668,7 @@ BEGIN COMMIT</tt></pre></div></div>
<div class="paragraph"><p><tt>find_or_create</tt>'s sibling, <tt>find_or_initialize</tt>, will find an object and if it does not exist will act similar to calling <tt>new</tt> with the arguments you passed in. For example:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -679,7 +679,7 @@ http://www.gnu.org/software/src-highlite --> <div class="sectionbody">
<div class="paragraph"><p>If you’d like to use your own SQL to find records in a table you can use <tt>find_by_sql</tt>. The <tt>find_by_sql</tt> method will return an array of objects even the underlying query returns just a single record. For example you could run this query:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -690,7 +690,7 @@ http://www.gnu.org/software/src-highlite --> <div class="sectionbody">
<div class="paragraph"><p><tt>find_by_sql</tt> has a close relative called <tt>connection#select_all</tt>. <tt>select_all</tt> will retrieve objects from the database using custom SQL just like <tt>find_by_sql</tt> but will not instantiate them. Instead, you will get an array of hashes where each hash indicates a record.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -706,7 +706,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_simple_named_scopes">16.1. Simple Named Scopes</h3>
<div class="paragraph"><p>Suppose we want to find all clients who are male. You could use this code:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -716,7 +716,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>Then you could call <tt>Client.males.all</tt> to get all the clients who are male. Please note that if you do not specify the <tt>all</tt> on the end you will get a <tt>Scope</tt> object back, not a set of records which you do get back if you put the <tt>all</tt> on the end.</p></div>
<div class="paragraph"><p>If you wanted to find all the clients who are active, you could use this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -727,14 +727,14 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_combining_named_scopes">16.2. Combining Named Scopes</h3>
<div class="paragraph"><p>If you wanted to find all the clients who are active and male you can stack the named scopes like this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>Client<span style="color: #990000">.</span>males<span style="color: #990000">.</span>active<span style="color: #990000">.</span>all</tt></pre></div></div>
<div class="paragraph"><p>If you would then like to do a <tt>all</tt> on that scope, you can. Just like an association, named scopes allow you to call <tt>all</tt> on them:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -742,7 +742,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_runtime_evaluation_of_named_scope_conditions">16.3. Runtime Evaluation of Named Scope Conditions</h3>
<div class="paragraph"><p>Consider the following code:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -751,7 +751,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>This looks like a standard named scope that defines a method called <tt>recent</tt> which gathers all records created any time between now and 2 weeks ago. That’s correct for the first time the model is loaded but for any time after that, <tt>2.weeks.ago</tt> is set to that same value, so you will consistently get records from a certain date until your model is reloaded by something like your application restarting. The way to fix this is to put the code in a lambda block:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -762,7 +762,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_named_scopes_with_multiple_models">16.4. Named Scopes with Multiple Models</h3>
<div class="paragraph"><p>In a named scope you can use <tt>:include</tt> and <tt>:joins</tt> options just like in <tt>find</tt>.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -774,7 +774,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_arguments_to_named_scopes">16.5. Arguments to Named Scopes</h3>
<div class="paragraph"><p>If you want to pass to a named scope a required arugment, just specify it as a block argument like this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -783,7 +783,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>This will work if you call <tt>Client.recent(2.weeks.ago).all</tt> but not if you call <tt>Client.recent</tt>. If you want to add an optional argument for this, you have to use prefix the arugment with an *.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -795,7 +795,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_anonymous_scopes">16.6. Anonymous Scopes</h3>
<div class="paragraph"><p>All Active Record models come with a named scope named <tt>scoped</tt>, which allows you to create anonymous scopes. For example:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -806,7 +806,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>Anonymous scopes are most useful to create scopes "on the fly":</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -817,14 +817,14 @@ http://www.gnu.org/software/src-highlite --> <div class="sectionbody">
<div class="paragraph"><p>If you simply want to check for the existence of the object there’s a method called <tt>exists?</tt>. This method will query the database using the same query as <tt>find</tt>, but instead of returning an object or collection of objects it will return either <tt>true</tt> or false+.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>Client<span style="color: #990000">.</span>exists?<span style="color: #990000">(</span><span style="color: #993399">1</span><span style="color: #990000">)</span></tt></pre></div></div>
<div class="paragraph"><p>The <tt>exists?</tt> method also takes multiple ids, but the catch is that it will return true if any one of those records exists.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -833,7 +833,7 @@ http://www.gnu.org/software/src-highlite --> Client<span style="color: #990000">.</span>exists?<span style="color: #990000">([</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">3</span><span style="color: #990000">])</span></tt></pre></div></div>
<div class="paragraph"><p>Further more, <tt>exists</tt> takes a <tt>conditions</tt> option much like find:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -844,28 +844,28 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>This section uses count as an example method in this preamble, but the options described apply to all sub-sections.</p></div>
<div class="paragraph"><p><tt>count</tt> takes conditions much in the same way <tt>exists?</tt> does:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>Client<span style="color: #990000">.</span>count<span style="color: #990000">(:</span>conditions <span style="color: #990000">=></span> <span style="color: #FF0000">"first_name = 'Ryan'"</span><span style="color: #990000">)</span></tt></pre></div></div>
<div class="paragraph"><p>Which will execute:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">SELECT</span></span> count<span style="color: #990000">(*)</span> <span style="font-weight: bold"><span style="color: #0000FF">AS</span></span> count_all <span style="font-weight: bold"><span style="color: #0000FF">FROM</span></span> clients <span style="font-weight: bold"><span style="color: #0000FF">WHERE</span></span> <span style="color: #990000">(</span>first_name <span style="color: #990000">=</span> <span style="color: #FF0000">'Ryan'</span><span style="color: #990000">)</span></tt></pre></div></div>
<div class="paragraph"><p>You can also use <tt>:include</tt> or <tt>:joins</tt> for this to do something a little more complex:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>Client<span style="color: #990000">.</span>count<span style="color: #990000">(:</span>conditions <span style="color: #990000">=></span> <span style="color: #FF0000">"clients.first_name = 'Ryan' AND orders.status = 'received'"</span><span style="color: #990000">,</span> <span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #0000FF">include</span></span> <span style="color: #990000">=></span> <span style="color: #FF0000">"orders"</span><span style="color: #990000">)</span></tt></pre></div></div>
<div class="paragraph"><p>Which will execute:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -879,7 +879,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_average">18.2. Average</h3>
<div class="paragraph"><p>If you want to see the average of a certain number in one of your tables you can call the <tt>average</tt> method on the class that relates to the table. This method call will look something like this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -889,7 +889,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_minimum">18.3. Minimum</h3>
<div class="paragraph"><p>If you want to find the minimum value of a field in your table you can call the <tt>minimum</tt> method on the class that relates to the table. This method call will look something like this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -898,7 +898,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_maximum">18.4. Maximum</h3>
<div class="paragraph"><p>If you want to find the maximum value of a field in your table you can call the <tt>maximum</tt> method on the class that relates to the table. This method call will look something like this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -907,7 +907,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_sum">18.5. Sum</h3>
<div class="paragraph"><p>If you want to find the sum of a field for all records in your table you can call the <tt>sum</tt> method on the class that relates to the table. This method call will look something like this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
diff --git a/railties/doc/guides/html/activerecord_validations_callbacks.html b/railties/doc/guides/html/activerecord_validations_callbacks.html index be556283c1..2153979d7b 100644 --- a/railties/doc/guides/html/activerecord_validations_callbacks.html +++ b/railties/doc/guides/html/activerecord_validations_callbacks.html @@ -236,7 +236,7 @@ Using validation directly in your Active Record classes ensures that only valid <h3 id="_when_does_validation_happen">1.2. When Does Validation Happen?</h3>
<div class="paragraph"><p>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, using the <tt>new</tt> method, that object does not belong to the database yet. Once you call <tt>save</tt> upon that object it will be saved into the appropriate database table. Active Record uses the <tt>new_record?</tt> instance method to determine whether an object is already in the database or not. Consider the following simple Active Record class:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -274,7 +274,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_the_tt_validates_acceptance_of_tt_helper">2.1. The <tt>validates_acceptance_of</tt> helper</h3>
<div class="paragraph"><p>Validates that a checkbox on the user interface was checked when a form was submitted. This is normally 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 actually this <em>acceptance</em> 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).</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -284,7 +284,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>The default error message for <tt>validates_acceptance_of</tt> is "<em>must be accepted</em>"</p></div>
<div class="paragraph"><p><tt>validates_acceptance_of</tt> can receive an <tt>:accept</tt> option, which determines the value that will be considered acceptance. It defaults to "1", but you can change this.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -294,7 +294,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_the_tt_validates_associated_tt_helper">2.2. The <tt>validates_associated</tt> helper</h3>
<div class="paragraph"><p>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, <tt>valid?</tt> will be called upon each one of the associated objects.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -315,7 +315,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_the_tt_validates_confirmation_of_tt_helper">2.3. The <tt>validates_confirmation_of</tt> helper</h3>
<div class="paragraph"><p>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, using the name of the field that has to be confirmed with <em>_confirmation</em> appended.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -324,7 +324,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>In your view template you could use something like</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -339,7 +339,7 @@ http://www.gnu.org/software/src-highlite --> </tr></table>
</div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -351,7 +351,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_the_tt_validates_exclusion_of_tt_helper">2.4. The <tt>validates_exclusion_of</tt> helper</h3>
<div class="paragraph"><p>This helper validates that the attributes' values are not included in a given set. In fact, this set can be any enumerable object.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -364,7 +364,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_the_tt_validates_format_of_tt_helper">2.5. The <tt>validates_format_of</tt> helper</h3>
<div class="paragraph"><p>This helper validates the attributes' values by testing whether they match a given pattern. This pattern must be specified using a Ruby regular expression, which is specified using the <tt>:with</tt> option.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -376,7 +376,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_the_tt_validates_inclusion_of_tt_helper">2.6. The <tt>validates_inclusion_of</tt> helper</h3>
<div class="paragraph"><p>This helper validates that the attributes' values are included in a given set. In fact, this set can be any enumerable object.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -389,7 +389,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_the_tt_validates_length_of_tt_helper">2.7. The <tt>validates_length_of</tt> helper</h3>
<div class="paragraph"><p>This helper validates the length of your attribute’s value. It includes a variety of different options, so you can specify length constraints in different ways:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -424,7 +424,7 @@ http://www.gnu.org/software/src-highlite --> </ul></div>
<div class="paragraph"><p>The default error messages depend on the type of length validation being performed. You can personalize these messages, using the <tt>:wrong_length</tt>, <tt>:too_long</tt> and <tt>:too_short</tt> options and the <tt>%d</tt> format mask as a placeholder for the number corresponding to the length constraint being used. You can still use the <tt>:message</tt> option to specify an error message.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -436,7 +436,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>This helper validates that your attributes have only numeric values. By default, it will match an optional sign followed by a integral or floating point number. Using the <tt>:integer_only</tt> option set to true, you can specify that only integral numbers are allowed.</p></div>
<div class="paragraph"><p>If you set <tt>:integer_only</tt> to <tt>true</tt>, then it will use the <tt>$$/\A[</tt>\-]?\d+\Z/<tt> regular expression to validate the attribute’s value. Otherwise, it will try to convert the value to a number using +Kernel.Float</tt>.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -486,7 +486,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_the_tt_validates_presence_of_tt_helper">2.9. The <tt>validates_presence_of</tt> helper</h3>
<div class="paragraph"><p>This helper validates that the specified attributes are not empty. It uses the <tt>blank?</tt> method to check if the value is either <tt>nil</tt> or an empty string (if the string has only spaces, it will still be considered empty).</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -502,7 +502,7 @@ http://www.gnu.org/software/src-highlite --> </tr></table>
</div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -522,7 +522,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_the_tt_validates_uniqueness_of_tt_helper">2.10. The <tt>validates_uniqueness_of</tt> helper</h3>
<div class="paragraph"><p>This helper validates that the attribute’s value is unique right before the object gets saved. It does not create a uniqueness constraint directly into your 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 an unique index in your database.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -532,7 +532,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>The validation happens by performing a SQL query into the model’s table, searching for a record where the attribute that must be validated is equal to the value in the object being validated.</p></div>
<div class="paragraph"><p>There is a <tt>:scope</tt> option that you can use to specify other attributes that are used to limit the uniqueness check:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -542,7 +542,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>There is also a <tt>:case_sensitive</tt> option that you can use to define whether the uniqueness constraint will be case sensitive or not. This option defaults to true.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -553,7 +553,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_the_tt_validates_each_tt_helper">2.11. The <tt>validates_each</tt> helper</h3>
<div class="paragraph"><p>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 <tt>validates_each</tt> will be tested against it. In the following example, we don’t want names and surnames to begin with lower case.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -570,7 +570,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_the_tt_allow_nil_tt_option">3.1. The <tt>:allow_nil</tt> option</h3>
<div class="paragraph"><p>The <tt>:allow_nil</tt> option skips the validation when the value being validated is <tt>nil</tt>. You may be asking yourself if it makes any sense to use <tt>:allow_nil</tt> and <tt>validates_presence_of</tt> together. Well, it does. Remember, the validation will be skipped only for <tt>nil</tt> attributes, but empty strings are not considered <tt>nil</tt>.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -581,7 +581,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_the_tt_allow_blank_tt_option">3.2. The <tt>:allow_blank</tt> option</h3>
<div class="paragraph"><p>The <tt>:allow_blank: option is similar to the +:allow_nil</tt> option. This option will let validation pass if the attribute’s value is <tt>nil</tt> or an empty string, i.e., any value that returns <tt>true</tt> for <tt>blank?</tt>.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -596,7 +596,7 @@ Topic<span style="color: #990000">.</span>create<span style="color: #990000">(</ <h3 id="_the_tt_on_tt_option">3.4. The <tt>:on</tt> option</h3>
<div class="paragraph"><p>The <tt>:on</tt> option lets you specify when the validation should happen. The default behavior for all the built-in validation helpers is to be ran 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 <tt>:on => :create</tt> to run the validation only when a new record is created or <tt>:on => :update</tt> to run the validation only when a record is updated.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -617,7 +617,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_using_a_symbol_with_the_tt_if_tt_and_tt_unless_tt_options">4.1. Using a symbol with the <tt>:if</tt> and <tt>:unless</tt> options</h3>
<div class="paragraph"><p>You can associate the <tt>:if</tt> and <tt>:unless</tt> 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.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -631,7 +631,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_using_a_string_with_the_tt_if_tt_and_tt_unless_tt_options">4.2. Using a string with the <tt>:if</tt> and <tt>:unless</tt> options</h3>
<div class="paragraph"><p>You can also use a string that will be evaluated using <tt>:eval</tt> and needs to contain valid Ruby code. You should use this option only when the string represents a really short condition.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -641,7 +641,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_using_a_proc_object_with_the_tt_if_tt_and_tt_unless_tt_options">4.3. Using a Proc object with the <tt>:if</tt> and :<tt>unless</tt> options</h3>
<div class="paragraph"><p>Finally, it’s possible to associate <tt>:if</tt> and <tt>:unless</tt> with a Ruby Proc object which will be called. Using a Proc object can give you the hability to write a condition that will be executed only when the validation happens and not when your code is loaded by the Ruby interpreter. This option is best suited when writing short validation methods, usually one-liners.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -654,7 +654,7 @@ http://www.gnu.org/software/src-highlite --> <div class="sectionbody">
<div class="paragraph"><p>When the built-in validation helpers are not enough for your needs, you can write your own validation methods. You can do that by implementing methods that verify the state of your models and add messages to their <tt>errors</tt> collection when they are invalid. You must then register those methods by using one or more of the <tt>validate</tt>, <tt>validate_on_create</tt> or <tt>validate_on_update</tt> class methods, 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 ran in the same order as they were registered.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -674,7 +674,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>You can even create your own validation helpers and reuse them in several different models. Here is an example where we create a custom validation helper to validate the format of fields that represent email addresses:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -692,7 +692,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>The recipe is simple: just create a new validation method inside the <tt>ActiveRecord::Validations::ClassMethods</tt> module. You can put this code in a file inside your application’s <strong>lib</strong> folder, and then requiring it from your <strong>environment.rb</strong> or any other file inside <strong>config/initializers</strong>. You can use this helper like this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -711,7 +711,7 @@ http://www.gnu.org/software/src-highlite --> </li>
</ul></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -728,7 +728,7 @@ http://www.gnu.org/software/src-highlite --> </li>
</ul></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -745,7 +745,7 @@ http://www.gnu.org/software/src-highlite --> </li>
</ul></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -763,7 +763,7 @@ person<span style="color: #990000">.</span>invalid?<span style="color: #990000"> </li>
</ul></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -793,7 +793,7 @@ person<span style="color: #990000">.</span>errors<span style="color: #990000">.< </li>
</ul></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -817,7 +817,7 @@ p<span style="color: #990000">.</span>errors<span style="color: #990000">.</span <div class="sectionbody">
<div class="paragraph"><p>Rails provides built-in helpers to display the error messages of your models in your view templates. 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.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -898,7 +898,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_changing_the_way_form_fields_with_errors_are_displayed">7.1. Changing the way form fields with errors are displayed</h3>
<div class="paragraph"><p>By default, form fields with errors are displayed enclosed by a <tt>div</tt> element with the <tt>fieldWithErrors</tt> CSS class. However, we can write some Ruby code to override the way Rails treats those fields by default. Here is a simple example where we change the Rails behaviour to always display the error messages in front of each of the form fields with errors. The error messages will be enclosed by a <tt>span</tt> element with a <tt>validation-error</tt> CSS class. There will be no <tt>div</tt> element enclosing the <tt>input</tt> element, so we get rid of that red border around the text field. You can use the <tt>validation-error</tt> CSS class to style it anyway you want.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -937,7 +937,7 @@ An object of the <tt>ActionView::Helpers::InstanceTag</tt> class. <h3 id="_callbacks_registration">8.1. Callbacks registration</h3>
<div class="paragraph"><p>In order to use the available callbacks, you need to registrate them. You can do that by implementing them as an ordinary methods, and then using a macro-style class method to register then as callbacks.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -955,7 +955,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>The macro-style class methods can also receive a block. Rails best practices say that you should only use this style of registration if the code inside your block is so short that it fits in just one line.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -979,7 +979,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_using_a_symbol_with_the_tt_if_tt_and_tt_unless_tt_options_2">9.1. Using a symbol with the <tt>:if</tt> and <tt>:unless</tt> options</h3>
<div class="paragraph"><p>You can associate the <tt>:if</tt> and <tt>:unless</tt> options with a symbol corresponding to the name of a method that will get called right before the callback. If this method returns <tt>false</tt> the callback won’t be executed. This is the most common option. Using this form of registration it’s also possible to register several different methods that should be called to check the if the callback should be executed.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -989,7 +989,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_using_a_string_with_the_tt_if_tt_and_tt_unless_tt_options_2">9.2. Using a string with the <tt>:if</tt> and <tt>:unless</tt> options</h3>
<div class="paragraph"><p>You can also use a string that will be evaluated using <tt>:eval</tt> and needs to contain valid Ruby code. You should use this option only when the string represents a really short condition.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -999,7 +999,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_using_a_proc_object_with_the_tt_if_tt_and_tt_unless_tt_options_2">9.3. Using a Proc object with the <tt>:if</tt> and :<tt>unless</tt> options</h3>
<div class="paragraph"><p>Finally, it’s possible to associate <tt>:if</tt> and <tt>:unless</tt> with a Ruby Proc object. This option is best suited when writing short validation methods, usually one-liners.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1010,7 +1010,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_multiple_conditions_for_callbacks">9.4. Multiple Conditions for Callbacks</h3>
<div class="paragraph"><p>When writing conditional callbacks, it’s possible to mix both <tt>:if</tt> and <tt>:unless</tt> in the same callback declaration.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1139,7 +1139,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>Sometimes the callback methods that you’ll write will be useful enough to be reused at other models. Active Record makes it possible to create classes that encapsulate the callback methods, so it becomes very easy to reuse them.</p></div>
<div class="paragraph"><p>Here’s an example where we create a class with a after_destroy callback for a PictureFile model.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1150,7 +1150,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>When declared inside a class the callback method will receive the model object as a parameter. We can now use it this way:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1159,7 +1159,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>Note that we needed to instantiate a new PictureFileCallbacks object, since we declared our callback as an instance method. Sometimes it will make more sense to have it as a class method.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1170,7 +1170,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>If the callback method is declared this way, it won’t be necessary to instantiate a PictureFileCallbacks object.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1186,7 +1186,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>Observer classes are subclasses of the ActiveRecord::Observer class. When this class is subclassed, Active Record will look at the name of the new class and then strip the <em>Observer</em> part to find the name of the Active Record class to observe.</p></div>
<div class="paragraph"><p>Consider a Registration model, where we want to send an email every time a new registration is created. Since sending emails is not directly related to our model’s purpose, we could create an Observer to do just that:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1198,7 +1198,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>Like in callback classes, the observer’s methods receive the observed model as a parameter.</p></div>
<div class="paragraph"><p>Sometimes using the ModelName + Observer naming convention won’t be the best choice, mainly when you want to use the same observer for more than one model class. It’s possible to explicity specify the models that our observer should observe.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1208,7 +1208,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_registering_observers">13.1. Registering observers</h3>
<div class="paragraph"><p>If you paid attention, you may be wondering where Active Record Observers are referenced in our applications, so they get instantiated and begin to interact with our models. For observers to work we need to register them somewhere. The usual place to do that is in our application’s <strong>config/environment.rb</strong> file. In this file there is a commented-out line where we can define the observers that our application should load at start-up.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
diff --git a/railties/doc/guides/html/association_basics.html b/railties/doc/guides/html/association_basics.html index bfe8f3f341..8d03bdddba 100644 --- a/railties/doc/guides/html/association_basics.html +++ b/railties/doc/guides/html/association_basics.html @@ -125,7 +125,7 @@ Use the methods added to your models by creating associations <div class="sectionbody">
<div class="paragraph"><p>Why do we need associations between models? Because they make common operations simpler and easier in your code. For example, consider a simple Rails application that includes a model for customers and a model for orders. Each customer can have many orders. Without associations, the model declarations would look like this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -136,14 +136,14 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>Now, suppose we wanted to add a new order for an existing customer. We’d need to do something like this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #009900">@order</span> <span style="color: #990000">=</span> Order<span style="color: #990000">.</span>create<span style="color: #990000">(:</span>order_date <span style="color: #990000">=></span> Time<span style="color: #990000">.</span>now<span style="color: #990000">,</span> <span style="color: #990000">:</span>customer_id <span style="color: #990000">=></span> <span style="color: #009900">@customer</span><span style="color: #990000">.</span>id<span style="color: #990000">)</span></tt></pre></div></div>
<div class="paragraph"><p>Or consider deleting a customer, and ensuring that all of its orders get deleted as well:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -154,7 +154,7 @@ http://www.gnu.org/software/src-highlite --> <span style="color: #009900">@customer</span><span style="color: #990000">.</span>destroy</tt></pre></div></div>
<div class="paragraph"><p>With Active Record associations, we can streamline these - and other - operations by declaratively telling Rails that there is a connection between the two models. Here’s the revised code for setting up customers and orders:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -167,14 +167,14 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>With this change, creating a new order for a particular customer is easier:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #009900">@order</span> <span style="color: #990000">=</span> <span style="color: #009900">@customer</span><span style="color: #990000">.</span>orders<span style="color: #990000">.</span>create<span style="color: #990000">(:</span>order_date <span style="color: #990000">=></span> Time<span style="color: #990000">.</span>now<span style="color: #990000">)</span></tt></pre></div></div>
<div class="paragraph"><p>Deleting a customer and all of its orders is <em>much</em> easier:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -220,7 +220,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_the_tt_belongs_to_tt_association">2.1. The <tt>belongs_to</tt> Association</h3>
<div class="paragraph"><p>A <tt>belongs_to</tt> 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:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -233,7 +233,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_the_tt_has_one_tt_association">2.2. The <tt>has_one</tt> Association</h3>
<div class="paragraph"><p>A <tt>has_one</tt> 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:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -246,7 +246,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_the_tt_has_many_tt_association">2.3. The <tt>has_many</tt> Association</h3>
<div class="paragraph"><p>A <tt>has_many</tt> association indicates a one-to-many connection with another model. You’ll often find this association on the "other side" of a <tt>belongs_to</tt> 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:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -267,7 +267,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_the_tt_has_many_through_tt_association">2.4. The <tt>has_many :through</tt> Association</h3>
<div class="paragraph"><p>A <tt>has_many :through</tt> 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 <em>through</em> a third model. For example, consider a medical practice where patients make appointments to see physicians. The relevant association declarations could look like this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -290,7 +290,7 @@ http://www.gnu.org/software/src-highlite --> </span></p></div>
<div class="paragraph"><p>The <tt>has_many :through</tt> association is also useful for setting up "shortcuts" through nested :<tt>has_many</tt> 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:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -310,7 +310,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_the_tt_has_one_through_tt_association">2.5. The <tt>has_one :through</tt> Association</h3>
<div class="paragraph"><p>A <tt>has_one :through</tt> 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 <em>through</em> 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:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -333,7 +333,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_the_tt_has_and_belongs_to_many_tt_association">2.6. The <tt>has_and_belongs_to_many</tt> Association</h3>
<div class="paragraph"><p>A <tt>has_and_belongs_to_many</tt> 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:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -351,7 +351,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>If you want to set up a 1-1 relationship between two models, you’ll need to add <tt>belongs_to</tt> to one, and <tt>has_one</tt> to the other. How do you know which is which?</p></div>
<div class="paragraph"><p>The distinction is in where you place the foreign key (it goes on the table for the class declaring the <tt>belongs_to</tt> association), but you should give some thought to the actual meaning of the data as well. The <tt>has_one</tt> 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:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -364,7 +364,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>The corresponding migration might look like this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -398,7 +398,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_choosing_between_tt_has_many_through_tt_and_tt_has_and_belongs_to_many_tt">2.8. Choosing Between <tt>has_many :through</tt> and <tt>has_and_belongs_to_many</tt></h3>
<div class="paragraph"><p>Rails offers two different ways to declare a many-to-many relationship between models. The simpler way is to use <tt>has_and_belongs_to_many</tt>, which allows you to make the association directly:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -411,7 +411,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>The second way to declare a many-to-many relationship is to use <tt>has_many :through</tt>. This makes the association indirectly, through a join model:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -434,7 +434,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_polymorphic_associations">2.9. Polymorphic Associations</h3>
<div class="paragraph"><p>A slightly more advanced twist on associations is the <em>polymorphic association</em>. With polymorphic associations, a model can belong to more than one other model, on a single association. For example, you might have a picture model that belongs to either an employee model or a product model. Here’s how this could be declared:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -451,7 +451,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>You can think of a polymorphic <tt>belongs_to</tt> declaration as setting up an interface that any other model can use. From an instance of the <tt>Employee</tt> model, you can retrieve a collection of pictures: <tt>@employee.pictures</tt>. Similarly, you can retrieve <tt>@product.pictures</tt>. If you have an instance of the <tt>Picture</tt> model, you can get to its parent via <tt>@picture.imageable</tt>. 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:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -471,7 +471,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>This migration can be simplified by using the <tt>t.references</tt> form:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -494,7 +494,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_self_joins">2.10. Self Joins</h3>
<div class="paragraph"><p>In designing a data model, you will sometimes find a model that should have a relation to itself. For example, you may want to store all employees in a single database model, but be able to trace relationships such as manager and subordinates. This situation can be modeled with self-joining associations:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -532,7 +532,7 @@ Controlling association scope <h3 id="_controlling_caching">3.1. Controlling Caching</h3>
<div class="paragraph"><p>All of the association methods are built around caching that keeps the result of the most recent query available for further operations. The cache is even shared across methods. For example:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -541,7 +541,7 @@ customer<span style="color: #990000">.</span>orders<span style="color: #990000"> customer<span style="color: #990000">.</span>orders<span style="color: #990000">.</span>empty? <span style="font-style: italic"><span style="color: #9A1900"># uses the cached copy of orders</span></span></tt></pre></div></div>
<div class="paragraph"><p>But what if you want to reload the cache, because data might have been changed by some other part of the application? Just pass <tt>true</tt> to the association call:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -555,7 +555,7 @@ customer<span style="color: #990000">.</span>orders<span style="color: #990000"> <h4 id="_creating_foreign_keys_for_tt_belongs_to_tt_associations">3.3.1. Creating Foreign Keys for <tt>belongs_to</tt> Associations</h4>
<div class="paragraph"><p>When you declare a <tt>belongs_to</tt> association, you need to create foreign keys as appropriate. For example, consider this model:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -564,7 +564,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>This declaration needs to be backed up by the proper foreign key declaration on the orders table:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -594,7 +594,7 @@ http://www.gnu.org/software/src-highlite --> </div>
<div class="paragraph"><p>Whatever the name, you must manually generate the join table with an appropriate migration. For example, consider these associations:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -607,7 +607,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>These need to be backed up by a migration to create the <tt>assemblies_parts</tt> table. This table should be created without a primary key:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -626,7 +626,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_controlling_association_scope">3.4. Controlling Association Scope</h3>
<div class="paragraph"><p>By default, associations look for objects only within the current module’s scope. This can be important when you declare Active Record models within a module. For example:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -643,7 +643,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>This will work fine, because both the <tt>Supplier</tt> and the <tt>Account</tt> class are defined within the same scope. But this will not work, because <tt>Supplier</tt> and <tt>Account</tt> are defined in different scopes:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -662,7 +662,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>To associate a model with a model in a different scope, you must specify the complete class name in your association declaration:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -716,7 +716,7 @@ http://www.gnu.org/software/src-highlite --> </ul></div>
<div class="paragraph"><p>In all of these methods, <tt><em>association</em></tt> is replaced with the symbol passed as the first argument to <tt>belongs_to</tt>. For example, given the declaration:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -725,7 +725,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>Each instance of the order model will have these methods:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -737,7 +737,7 @@ create_customer</tt></pre></div></div> <h5 id="_tt_em_association_em_force_reload_false_tt"><tt><em>association</em>(force_reload = false)</tt></h5>
<div class="paragraph"><p>The <tt><em>association</em></tt> method returns the associated object, if any. If no associated object is found, it returns <tt>nil</tt>.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -746,7 +746,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_em_association_em_associate_tt"><tt><em>association</em>=(associate)</tt></h5>
<div class="paragraph"><p>The <tt><em>association</em>=</tt> method assigns an associated object to this object. Behind the scenes, this means extracting the primary key from the associate object and setting this object’s foreign key to the same value.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -754,7 +754,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_em_association_em_nil_tt"><tt><em>association</em>.nil?</tt></h5>
<div class="paragraph"><p>The <tt><em>association</em>.nil?</tt> method returns <tt>true</tt> if there is no associated object.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -764,7 +764,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_build_em_association_em_attributes_tt"><tt>build<em>_association</em>(attributes = {})</tt></h5>
<div class="paragraph"><p>The <tt>build<em>_association</em></tt> method returns a new object of the associated type. This object will be instantiated from the passed attributes, and the link through this object’s foreign key will be set, but the associated object will <em>not</em> yet be saved.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -772,7 +772,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_create_em_association_em_attributes_tt"><tt>create<em>_association</em>(attributes = {})</tt></h5>
<div class="paragraph"><p>The <tt>create<em>_association</em></tt> method returns a new object of the associated type. This object will be instantiated from the passed attributes, and the link through this object’s foreign key will be set. In addition, the associated object <em>will</em> be saved (assuming that it passes any validations).</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -780,7 +780,7 @@ http://www.gnu.org/software/src-highlite --> <h4 id="_options_for_tt_belongs_to_tt">4.1.2. Options for <tt>belongs_to</tt></h4>
<div class="paragraph"><p>In many situations, you can use the default behavior of <tt>belongs_to</tt> without any customization. But despite Rails' emphasis of convention over customization, you can alter that behavior in a number of ways. This section covers the options that you can pass when you create a <tt>belongs_to</tt> association. For example, an association with several options might look like this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -843,7 +843,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_class_name_tt"><tt>:class_name</tt></h5>
<div class="paragraph"><p>If the name of the other model cannot be derived from the association name, you can use the <tt>:class_name</tt> 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 <tt>Patron</tt>, you’d set things up this way:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -853,7 +853,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_conditions_tt"><tt>:conditions</tt></h5>
<div class="paragraph"><p>The <tt>:conditions</tt> option lets you specify the conditions that the associated object must meet (in the syntax used by a SQL <tt>WHERE</tt> clause).</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -863,7 +863,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_counter_cache_tt"><tt>:counter_cache</tt></h5>
<div class="paragraph"><p>The <tt>:counter_cache</tt> option can be used to make finding the number of belonging objects more efficient. Consider these models:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -875,7 +875,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>With these declarations, asking for the value of <tt>@customer.orders.size</tt> requires making a call to the database to perform a <tt>COUNT(*)</tt> query. To avoid this call, you can add a counter cache to the <em>belonging</em> model:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -888,7 +888,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>With this declaration, Rails will keep the cache value up to date, and then return that value in response to the <tt>.size</tt> method.</p></div>
<div class="paragraph"><p>Although the <tt>:counter_cache</tt> option is specified on the model that includes the <tt>belongs_to</tt> declaration, the actual column must be added to the <em>associated</em> model. In the case above, you would need to add a column named <tt>orders_count</tt> to the <tt>Customer</tt> model. You can override the default column name if you need to:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -912,7 +912,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_foreign_key_tt"><tt>:foreign_key</tt></h5>
<div class="paragraph"><p>By convention, Rails guesses that the column used to hold the foreign key on this model is the name of the association with the suffix <tt>_id</tt> added. The <tt>:foreign_key</tt> option lets you set the name of the foreign key directly:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -930,7 +930,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_include_tt"><tt>:include</tt></h5>
<div class="paragraph"><p>You can use the :include option to specify second-order associations that should be eager-loaded when this association is used. For example, consider these models:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -946,7 +946,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>If you frequently retrieve customers directly from line items (<tt>@line_item.order.customer</tt>), then you can make your code somewhat more efficient by including customers in the association from line items to orders:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1019,7 +1019,7 @@ http://www.gnu.org/software/src-highlite --> </ul></div>
<div class="paragraph"><p>In all of these methods, <tt><em>association</em></tt> is replaced with the symbol passed as the first argument to <tt>has_one</tt>. For example, given the declaration:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1028,7 +1028,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>Each instance of the <tt>Supplier</tt> model will have these methods:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1040,7 +1040,7 @@ create_account</tt></pre></div></div> <h5 id="_tt_em_association_em_force_reload_false_tt_2"><tt><em>association</em>(force_reload = false)</tt></h5>
<div class="paragraph"><p>The <tt><em>association</em></tt> method returns the associated object, if any. If no associated object is found, it returns <tt>nil</tt>.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1049,7 +1049,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_em_association_em_associate_tt_2"><tt><em>association</em>=(associate)</tt></h5>
<div class="paragraph"><p>The <tt><em>association</em>=</tt> method assigns an associated object to this object. Behind the scenes, this means extracting the primary key from this object and setting the associate object’s foreign key to the same value.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1057,7 +1057,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_em_association_em_nil_tt_2"><tt><em>association</em>.nil?</tt></h5>
<div class="paragraph"><p>The <tt><em>association</em>.nil?</tt> method returns <tt>true</tt> if there is no associated object.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1067,7 +1067,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_build_em_association_em_attributes_tt_2"><tt>build<em>_association</em>(attributes = {})</tt></h5>
<div class="paragraph"><p>The <tt>build<em>_association</em></tt> method returns a new object of the associated type. This object will be instantiated from the passed attributes, and the link through its foreign key will be set, but the associated object will <em>not</em> yet be saved.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1075,7 +1075,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_create_em_association_em_attributes_tt_2"><tt>create<em>_association</em>(attributes = {})</tt></h5>
<div class="paragraph"><p>The <tt>create<em>_association</em></tt> method returns a new object of the associated type. This object will be instantiated from the passed attributes, and the link through its foreign key will be set. In addition, the associated object <em>will</em> be saved (assuming that it passes any validations).</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1083,7 +1083,7 @@ http://www.gnu.org/software/src-highlite --> <h4 id="_options_for_tt_has_one_tt">4.2.2. Options for <tt>has_one</tt></h4>
<div class="paragraph"><p>In many situations, you can use the default behavior of <tt>has_one</tt> without any customization. But despite Rails' emphasis of convention over customization, you can alter that behavior in a number of ways. This section covers the options that you can pass when you create a <tt>has_one</tt> association. For example, an association with several options might look like this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1168,7 +1168,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_class_name_tt_2"><tt>:class_name</tt></h5>
<div class="paragraph"><p>If the name of the other model cannot be derived from the association name, you can use the <tt>:class_name</tt> 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:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1178,7 +1178,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_conditions_tt_2"><tt>:conditions</tt></h5>
<div class="paragraph"><p>The <tt>:conditions</tt> option lets you specify the conditions that the associated object must meet (in the syntax used by a SQL <tt>WHERE</tt> clause).</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1190,7 +1190,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_foreign_key_tt_2"><tt>:foreign_key</tt></h5>
<div class="paragraph"><p>By convention, Rails guesses that the column used to hold the foreign key on the other model is the name of this model with the suffix <tt>_id</tt> added. The <tt>:foreign_key</tt> option lets you set the name of the foreign key directly:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1208,7 +1208,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_include_tt_2"><tt>:include</tt></h5>
<div class="paragraph"><p>You can use the :include option to specify second-order associations that should be eager-loaded when this association is used. For example, consider these models:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1224,7 +1224,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>If you frequently retrieve representatives directly from suppliers (<tt>@supplier.account.representative</tt>), then you can make your code somewhat more efficient by including representatives in the association from suppliers to accounts:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1332,7 +1332,7 @@ http://www.gnu.org/software/src-highlite --> </ul></div>
<div class="paragraph"><p>In all of these methods, <tt><em>collection</em></tt> is replaced with the symbol passed as the first argument to <tt>has_many</tt>, and <tt><em>collection\_singular</em></tt> is replaced with the singularized version of that symbol.. For example, given the declaration:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1341,7 +1341,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>Each instance of the customer model will have these methods:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1361,7 +1361,7 @@ orders<span style="color: #990000">.</span>create<span style="color: #990000">(< <h5 id="_tt_em_collection_em_force_reload_false_tt"><tt><em>collection</em>(force_reload = false)</tt></h5>
<div class="paragraph"><p>The <tt><em>collection</em></tt> method returns an array of all of the associated objects. If there are no associated objects, it returns an empty array.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1369,7 +1369,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_em_collection_em_lt_lt_object_tt"><tt><em>collection</em><<(object, ...)</tt></h5>
<div class="paragraph"><p>The <tt><em>collection</em><<</tt> method adds one or more objects to the collection by setting their foreign keys to the primary key of the calling model.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1377,7 +1377,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_em_collection_em_delete_object_tt"><tt><em>collection</em>.delete(object, ...)</tt></h5>
<div class="paragraph"><p>The <tt><em>collection</em>.delete</tt> method removes one or more objects from the collection by setting their foreign keys to <tt>NULL</tt>.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1395,7 +1395,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_em_collection_singular_em_ids_tt"><tt><em>collection\_singular</em>\_ids</tt></h5>
<div class="paragraph"><p>The <tt><em>collection\_singular</em>\_ids</tt> method returns an array of the ids of the objects in the collection.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1407,7 +1407,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_em_collection_em_empty_tt"><tt><em>collection</em>.empty?</tt></h5>
<div class="paragraph"><p>The <tt><em>collection</em>.empty?</tt> method returns <tt>true</tt> if the collection does not contain any associated objects.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1417,7 +1417,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_em_collection_em_size_tt"><tt><em>collection</em>.size</tt></h5>
<div class="paragraph"><p>The <tt><em>collection</em>.size</tt> method returns the number of objects in the collection.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1425,7 +1425,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_em_collection_em_find_tt"><tt><em>collection</em>.find(...)</tt></h5>
<div class="paragraph"><p>The <tt><em>collection</em>.find</tt> method finds objects within the collection. It uses the same syntax and options as <tt>ActiveRecord::Base.find</tt>.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1435,7 +1435,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_em_collection_em_build_attributes_tt"><tt><em>collection</em>.build(attributes = {}, ...)</tt></h5>
<div class="paragraph"><p>The <tt><em>collection</em>.build</tt> method returns one or more new objects of the associated type. These objects will be instantiated from the passed attributes, and the link through their foreign key will be created, but the associated objects will <em>not</em> yet be saved.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1443,7 +1443,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_em_collection_em_create_attributes_tt"><tt><em>collection</em>.create(attributes = {})</tt></h5>
<div class="paragraph"><p>The <tt><em>collection</em>.create</tt> method returns a new object of the associated type. This object will be instantiated from the passed attributes, the link through its foreign key will be created, and the associated object <em>will</em> be saved (assuming that it passes any validations).</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1451,7 +1451,7 @@ http://www.gnu.org/software/src-highlite --> <h4 id="_options_for_has_many">4.3.2. Options for has_many</h4>
<div class="paragraph"><p>In many situations, you can use the default behavior for <tt>has_many</tt> without any customization. But you can alter that behavior in a number of ways. This section covers the options that you can pass when you create a <tt>has_many</tt> association. For example, an association with several options might look like this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1571,7 +1571,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_class_name_tt_3"><tt>:class_name</tt></h5>
<div class="paragraph"><p>If the name of the other model cannot be derived from the association name, you can use the <tt>:class_name</tt> option to supply the model name. For example, if a customer has many orders, but the actual name of the model containing orders is <tt>Transaction</tt>, you’d set things up this way:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1581,7 +1581,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_conditions_tt_3"><tt>:conditions</tt></h5>
<div class="paragraph"><p>The <tt>:conditions</tt> option lets you specify the conditions that the associated object must meet (in the syntax used by a SQL <tt>WHERE</tt> clause).</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1590,7 +1590,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>You can also set conditions via a hash:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1625,7 +1625,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_foreign_key_tt_3"><tt>:foreign_key</tt></h5>
<div class="paragraph"><p>By convention, Rails guesses that the column used to hold the foreign key on the other model is the name of this model with the suffix <tt>_id</tt> added. The <tt>:foreign_key</tt> option lets you set the name of the foreign key directly:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1643,7 +1643,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_group_tt"><tt>:group</tt></h5>
<div class="paragraph"><p>The <tt>:group</tt> option supplies an attribute name to group the result set by, using a <tt>GROUP BY</tt> clause in the finder SQL.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1653,7 +1653,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_include_tt_3"><tt>:include</tt></h5>
<div class="paragraph"><p>You can use the :include option to specify second-order associations that should be eager-loaded when this association is used. For example, consider these models:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1669,7 +1669,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>If you frequently retrieve line items directly from customers (<tt>@customer.orders.line_items</tt>), then you can make your code somewhat more efficient by including line items in the association from customers to orders:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1686,7 +1686,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_limit_tt"><tt>:limit</tt></h5>
<div class="paragraph"><p>The <tt>:limit</tt> option lets you restrict the total number of objects that will be fetched through an association.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1698,7 +1698,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_order_tt_2"><tt>:order</tt></h5>
<div class="paragraph"><p>The <tt>:order</tt> option dictates the order in which associated objects will be received (in the syntax used by a SQL <tt>ORDER BY</tt> clause).</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1807,7 +1807,7 @@ http://www.gnu.org/software/src-highlite --> </ul></div>
<div class="paragraph"><p>In all of these methods, <tt><em>collection</em></tt> is replaced with the symbol passed as the first argument to <tt>has_many</tt>, and <tt><em>collection</em>\_singular</tt> is replaced with the singularized version of that symbol.. For example, given the declaration:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1816,7 +1816,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>Each instance of the part model will have these methods:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1846,7 +1846,7 @@ assemblies<span style="color: #990000">.</span>create<span style="color: #990000 <h5 id="_tt_em_collection_em_force_reload_false_tt_2"><tt><em>collection</em>(force_reload = false)</tt></h5>
<div class="paragraph"><p>The <tt><em>collection</em></tt> method returns an array of all of the associated objects. If there are no associated objects, it returns an empty array.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1854,7 +1854,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_em_collection_em_lt_lt_object_tt_2"><tt><em>collection</em><<(object, ...)</tt></h5>
<div class="paragraph"><p>The <tt><em>collection</em><<</tt> method adds one or more objects to the collection by creating records in the join table.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1870,7 +1870,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_em_collection_em_delete_object_tt_2"><tt><em>collection</em>.delete(object, ...)</tt></h5>
<div class="paragraph"><p>The <tt><em>collection</em>.delete</tt> method removes one or more objects from the collection by deleting records in the join table. This does not destroy the objects.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1881,7 +1881,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p># Returns an array of the associated objects' ids</p></div>
<div class="paragraph"><p>The <tt><em>collection\_singular</em>\_ids</tt> method returns an array of the ids of the objects in the collection.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1893,7 +1893,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_em_collection_em_empty_tt_2"><tt><em>collection</em>.empty?</tt></h5>
<div class="paragraph"><p>The <tt><em>collection</em>.empty?</tt> method returns <tt>true</tt> if the collection does not contain any associated objects.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1903,7 +1903,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_em_collection_em_size_tt_2"><tt><em>collection</em>.size</tt></h5>
<div class="paragraph"><p>The <tt><em>collection</em>.size</tt> method returns the number of objects in the collection.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1911,7 +1911,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_em_collection_em_find_tt_2"><tt><em>collection</em>.find(...)</tt></h5>
<div class="paragraph"><p>The <tt><em>collection</em>.find</tt> method finds objects within the collection. It uses the same syntax and options as <tt>ActiveRecord::Base.find</tt>. It also adds the additional condition that the object must be in the collection.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1921,7 +1921,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_em_collection_em_build_attributes_tt_2"><tt><em>collection</em>.build(attributes = {})</tt></h5>
<div class="paragraph"><p>The <tt><em>collection</em>.build</tt> method returns a new object of the associated type. This object will be instantiated from the passed attributes, and the link through the join table will be created, but the associated object will <em>not</em> yet be saved.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1929,7 +1929,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_em_collection_em_create_attributes_tt_2"><tt><em>collection</em>.create(attributes = {})</tt></h5>
<div class="paragraph"><p>The <tt><em>collection</em>.create</tt> method returns a new object of the associated type. This objects will be instantiated from the passed attributes, the link through the join table will be created, and the associated object <em>will</em> be saved (assuming that it passes any validations).</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1937,7 +1937,7 @@ http://www.gnu.org/software/src-highlite --> <h4 id="_options_for_has_and_belongs_to_many">4.4.2. Options for has_and_belongs_to_many</h4>
<div class="paragraph"><p>In many situations, you can use the default behavior for <tt>has_and_belongs_to_many</tt> without any customization. But you can alter that behavior in a number of ways. This section cover the options that you can pass when you create a <tt>has_and_belongs_to_many</tt> association. For example, an association with several options might look like this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -2053,7 +2053,7 @@ http://www.gnu.org/software/src-highlite --> </tr></table>
</div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -2064,7 +2064,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_class_name_tt_4"><tt>:class_name</tt></h5>
<div class="paragraph"><p>If the name of the other model cannot be derived from the association name, you can use the <tt>:class_name</tt> option to supply the model name. For example, if a part has many assemblies, but the actual name of the model containing assemblies is <tt>Gadget</tt>, you’d set things up this way:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -2074,7 +2074,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_conditions_tt_4"><tt>:conditions</tt></h5>
<div class="paragraph"><p>The <tt>:conditions</tt> option lets you specify the conditions that the associated object must meet (in the syntax used by a SQL <tt>WHERE</tt> clause).</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -2083,7 +2083,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>You can also set conditions via a hash:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -2110,7 +2110,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_foreign_key_tt_4"><tt>:foreign_key</tt></h5>
<div class="paragraph"><p>By convention, Rails guesses 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 <tt>_id</tt> added. The <tt>:foreign_key</tt> option lets you set the name of the foreign key directly:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -2121,7 +2121,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_group_tt_2"><tt>:group</tt></h5>
<div class="paragraph"><p>The <tt>:group</tt> option supplies an attribute name to group the result set by, using a <tt>GROUP BY</tt> clause in the finder SQL.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -2137,7 +2137,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_limit_tt_2"><tt>:limit</tt></h5>
<div class="paragraph"><p>The <tt>:limit</tt> option lets you restrict the total number of objects that will be fetched through an association.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -2149,7 +2149,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_tt_order_tt_3"><tt>:order</tt></h5>
<div class="paragraph"><p>The <tt>:order</tt> option dictates the order in which associated objects will be received (in the syntax used by a SQL <tt>ORDER BY</tt> clause).</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -2196,7 +2196,7 @@ http://www.gnu.org/software/src-highlite --> </ul></div>
<div class="paragraph"><p>You define association callbacks by adding options to the association declaration. For example:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -2210,7 +2210,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>Rails passes the object being added or removed to the callback.</p></div>
<div class="paragraph"><p>You can stack callbacks on a single event by passing them as an array:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -2229,7 +2229,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_association_extensions">4.6. Association Extensions</h3>
<div class="paragraph"><p>You’re not limited to the functionality that Rails automatically builds into association proxy objects. You can also extend these objects through anonymous modules, adding new finders, creators, or other methods. For example:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -2242,7 +2242,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>If you have an extension that should be shared by many associations, you can use a named extension module. For example:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -2261,7 +2261,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>To include more than one extension module in a single association, specify an array of names:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
diff --git a/railties/doc/guides/html/caching_with_rails.html b/railties/doc/guides/html/caching_with_rails.html index 02cc981b0e..04498f268f 100644 --- a/railties/doc/guides/html/caching_with_rails.html +++ b/railties/doc/guides/html/caching_with_rails.html @@ -75,7 +75,7 @@ to <tt>true</tt> for your environment. This flag is normally set in the corresponding config/environments/*.rb and caching is disabled by default
there for development and test, and enabled for production.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -91,7 +91,7 @@ expiration is an issue that needs to be dealt with.</p></div> have a controller called ProductsController and a <em>list</em> action that lists all
the products</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -119,7 +119,7 @@ configuration setting <tt>config.action_controller.page_cache_extension</tt>.</p <div class="paragraph"><p>In order to expire this page when a new product is added we could extend our
example controler like this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -148,7 +148,7 @@ result of the output from a cached copy.</p></div> <div class="paragraph"><p>Let’s say you only wanted authenticated users to edit or create a Product
object, but still cache those pages:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -191,7 +191,7 @@ in real time and didn’t want to cache that part of the page, but did want to cache the part of the page which lists all products available, you
could use this piece of code:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -209,7 +209,7 @@ http://www.gnu.org/software/src-highlite --> 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 <tt>action_suffix</tt> to the cache call:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -217,7 +217,7 @@ http://www.gnu.org/software/src-highlite --> All available products<span style="color: #990000">:</span></tt></pre></div></div>
<div class="paragraph"><p>and you can expire it using the <tt>expire_fragment</tt> method, like so:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -226,7 +226,7 @@ http://www.gnu.org/software/src-highlite --> also use globally keyed fragments by calling the cache method with a key, like
so:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -235,7 +235,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>This fragment is then available to all actions in the ProductsController using
the key and can be expired the same way:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -250,7 +250,7 @@ an around or after filter.</p></div> <div class="paragraph"><p>Continuing with our Product controller example, we could rewrite it with a
sweeper such as the following:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -286,7 +286,7 @@ actions are called. So, if we wanted to expire the cached content for the list and edit actions when the create action was called, we could do the
following:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -314,7 +314,7 @@ will used the cached result set as opposed to running the query against the database again.</p></div>
<div class="paragraph"><p>For example:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -360,7 +360,7 @@ caches. Page caches are always stored on disk.</p></div> take up a lot of memory since each process keeps all the
caches in memory.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -371,7 +371,7 @@ http://www.gnu.org/software/src-highlite --> running from the same application directory to access the
cached content.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -381,7 +381,7 @@ http://www.gnu.org/software/src-highlite --> only keeps one cache around for all processes, but requires
that you run and manage a separate DRb process.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -389,14 +389,14 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>4) MemCached store: Works like DRbStore, but uses Danga’s MemCache instead.
Rails uses the bundled memcached-client gem by default.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>ActionController<span style="color: #990000">::</span>Base<span style="color: #990000">.</span>cache_store <span style="color: #990000">=</span> <span style="color: #990000">:</span>mem_cache_store<span style="color: #990000">,</span> <span style="color: #FF0000">"localhost"</span></tt></pre></div></div>
<div class="paragraph"><p>5) Custom store: You can define your own cache store (new in Rails 2.1)</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -421,7 +421,7 @@ 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:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -447,7 +447,7 @@ http://www.gnu.org/software/src-highlite --> rendering mechanism (i.e. you’re not using respond_to or calling render
yourself) then you’ve got an easy helper in fresh_when:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
diff --git a/railties/doc/guides/html/command_line.html b/railties/doc/guides/html/command_line.html index 226a68e105..7f925bc10a 100644 --- a/railties/doc/guides/html/command_line.html +++ b/railties/doc/guides/html/command_line.html @@ -135,7 +135,7 @@ rails </tr></table>
</div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -171,7 +171,7 @@ http://www.gnu.org/software/src-highlite --> </div>
<div class="paragraph"><p>Here we’ll flex our <tt>server</tt> command, which without any prodding of any kind will run our new shiny Rails app:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -188,7 +188,7 @@ $ <span style="color: #990000">.</span>/script/server <h3 id="_generate">1.3. generate</h3>
<div class="paragraph"><p>The <tt>generate</tt> command uses templates to create a whole lot of things. You can always find out what’s available by running <tt>generate</tt> by itself. Let’s do that:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -222,7 +222,7 @@ Installed Generators </tr></table>
</div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -251,7 +251,7 @@ Modules Example<span style="color: #990000">:</span> Test<span style="color: #990000">:</span> test/functional/admin/credit_card_controller_test<span style="color: #990000">.</span>rb</tt></pre></div></div>
<div class="paragraph"><p>Ah, the controller generator is expecting parameters in the form of <tt>generate controller ControllerName action1 action2</tt>. Let’s make a <tt>Greetings</tt> controller with an action of <strong>hello</strong>, which will say something nice to us.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -267,7 +267,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>Look there! Now what all did this generate? It looks like it made sure a bunch of directories were in our application, and created a controller file, a functional test file, a helper for the view, and a view file.</p></div>
<div class="paragraph"><p>Let’s check out the controller and modify it a little (in <tt>app/controllers/greeting_controller.rb</tt>):</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -279,7 +279,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>Then the view, to display our nice message (in <tt>app/views/greeting/hello.html.erb</tt>):</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -287,7 +287,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF"><p></span></span><%= @message %><span style="font-weight: bold"><span style="color: #0000FF"></p></span></span></tt></pre></div></div>
<div class="paragraph"><p>Deal. Go check it out in your browser. Fire up your server. Remember? <tt>./script/server</tt> at the root of your Rails application should do it.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -304,7 +304,7 @@ http://www.gnu.org/software/src-highlite --> </div>
<div class="paragraph"><p>"What about data, though?", you ask over a cup of coffee. Rails comes with a generator for data models too. Can you guess its generator name?</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -328,7 +328,7 @@ Examples<span style="color: #990000">:</span> <div class="paragraph"><p>But instead of generating a model directly (which we’ll be doing later), let’s set up a scaffold. A <strong>scaffold</strong> 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.</p></div>
<div class="paragraph"><p>Let’s set up a simple resource called "HighScore" that will keep track of our highest score on video games we play.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -371,7 +371,7 @@ dependency model </tr></table>
</div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -400,7 +400,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>Let’s say you’re creating a website for a client who wants a small accounting system. Every event having to do with money must be logged, and must never be deleted. Wouldn’t it be great if we could override the behavior of a model to never actually take its record out of the database, but <strong>instead</strong>, just set a field?</p></div>
<div class="paragraph"><p>There is such a thing! The plugin we’re installing is called "acts_as_paranoid", and it lets models implement a "deleted_at" column that gets set when you call destroy. Later, when calling find, the plugin will tack on a database check to filter out "deleted" things.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -412,7 +412,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_runner">1.7. runner</h3>
<div class="paragraph"><p><tt>runner</tt> runs Ruby code in the context of Rails non-interactively. For instance:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -420,7 +420,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_destroy">1.8. destroy</h3>
<div class="paragraph"><p>Think of <tt>destroy</tt> as the opposite of <tt>generate</tt>. It’ll figure out what generate did, and undo it. Believe you-me, the creation of this tutorial used this command many times!</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -449,7 +449,7 @@ $ <span style="color: #990000">.</span>/script/destroy model Oops <h3 id="_about">1.9. about</h3>
<div class="paragraph"><p>Check it: 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! <tt>about</tt> is useful when you need to ask help, check if a security patch might affect you, or when you need some stats for an existing Rails installation.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
diff --git a/railties/doc/guides/html/configuring.html b/railties/doc/guides/html/configuring.html index 3cd41f100e..7bbb849b90 100644 --- a/railties/doc/guides/html/configuring.html +++ b/railties/doc/guides/html/configuring.html @@ -137,14 +137,14 @@ After-Initializers <div class="sectionbody">
<div class="paragraph"><p>In general, the work of configuring Rails means configuring the components of Rails, as well as configuring Rails itself. The <tt>environment.rb</tt> and environment-specific configuration files (such as <tt>config/environments/production.rb</tt>) allow you to specify the various settings that you want to pass down to all of the components. For example, the default Rails 2.3 <tt>environment.rb</tt> file includes one setting:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>config<span style="color: #990000">.</span>time_zone <span style="color: #990000">=</span> <span style="color: #FF0000">'UTC'</span></tt></pre></div></div>
<div class="paragraph"><p>This is a setting for Rails itself. If you want to pass settings to individual Rails components, you can do so via the same <tt>config</tt> object:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -304,7 +304,7 @@ and appear last in the mime encoded message.</p></div> <div class="sectionbody">
<div class="paragraph"><p>After-initializers are run (as you might guess) after any initializers are loaded. You can supply an <tt>after_initialize</tt> block (or an array of such blocks) by setting up <tt>config.after_initialize</tt> in any of the Rails configuration files:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
diff --git a/railties/doc/guides/html/creating_plugins.html b/railties/doc/guides/html/creating_plugins.html index 3347f77228..c34bbef2f7 100644 --- a/railties/doc/guides/html/creating_plugins.html +++ b/railties/doc/guides/html/creating_plugins.html @@ -299,7 +299,7 @@ create vendor/plugins/yaffle/generators/yaffle/USAGE</tt></pre> </div></div>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/rails/init.rb</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -355,7 +355,7 @@ mysql: <div class="paragraph"><p>For this guide you’ll need 2 tables/models, Hickwalls and Wickwalls, so add the following:</p></div>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/test/schema.rb:</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -376,7 +376,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/test/test_helper.rb:</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -419,7 +419,7 @@ ENV<span style="color: #990000">[</span><span style="color: #FF0000">'RAILS_ROOT <div class="paragraph"><p>Once you have these files in place, you can write your first test to ensure that your plugin-testing setup is correct. By default rails generates a file in <em>vendor/plugins/yaffle/test/yaffle_test.rb</em> with a sample test. Replace the contents of that file with:</p></div>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/test/yaffle_test.rb:</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -481,7 +481,7 @@ rake DB=postgresql</tt></pre> <div class="paragraph"><p>In this example you will add a method to String named <tt>to_squawk</tt>. To begin, create a new test file with a few assertions:</p></div>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/test/core_ext_test.rb</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -510,7 +510,7 @@ NoMethodError: undefined method `to_squawk' for "Hello World":String <div class="paragraph"><p>Then in <em>lib/yaffle.rb</em> require <em>lib/core_ext.rb</em>:</p></div>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/lib/yaffle.rb</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -518,7 +518,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>Finally, create the <em>core_ext.rb</em> file and add the <em>to_squawk</em> method:</p></div>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/lib/yaffle/core_ext.rb</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -540,7 +540,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>If you must reopen a class in <tt>init.rb</tt> you can use <tt>module_eval</tt> or <tt>class_eval</tt> to avoid any issues:</p></div>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/rails/init.rb</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -552,7 +552,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>Another way is to explicitly define the top-level module space for all modules and classes, like <tt>::Hash</tt>:</p></div>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/rails/init.rb</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -568,7 +568,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>To begin, set up your files so that you have:</p></div>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/test/acts_as_yaffle_test.rb</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -578,14 +578,14 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/lib/yaffle.rb</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #000080">require</span></span> <span style="color: #FF0000">'yaffle/acts_as_yaffle'</span></tt></pre></div></div>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/lib/yaffle/acts_as_yaffle.rb</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -596,7 +596,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>One of the most common plugin patterns for <em>acts_as_yaffle</em> plugins is to structure your file like so:</p></div>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/lib/yaffle/acts_as_yaffle.rb</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -622,7 +622,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>To start out, write a failing test that shows the behavior you’d like:</p></div>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/test/acts_as_yaffle_test.rb</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -650,7 +650,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>To make these tests pass, you could modify your <tt>acts_as_yaffle</tt> file like so:</p></div>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/lib/yaffle/acts_as_yaffle.rb</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -673,7 +673,7 @@ ActiveRecord<span style="color: #990000">::</span>Base<span style="color: #99000 <div class="paragraph"><p>To start out, write a failing test that shows the behavior you’d like:</p></div>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/test/acts_as_yaffle_test.rb</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -713,7 +713,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>Run this test to make sure the last two tests fail, then update <em>acts_as_yaffle.rb</em> to look like this:</p></div>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/lib/yaffle/acts_as_yaffle.rb</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -770,7 +770,7 @@ ActiveRecord<span style="color: #990000">::</span>Base<span style="color: #99000 <div class="paragraph"><p>As always, start with a test:</p></div>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/yaffle/woodpecker_test.rb:</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -786,7 +786,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>This is just a simple test to make sure the class is being loaded correctly. After watching it fail with <tt>rake</tt>, you can make it pass like so:</p></div>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/lib/yaffle.rb:</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -799,7 +799,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>Adding directories to the load path makes them appear just like files in the the main app directory - except that they are only loaded once, so you have to restart the web server to see the changes in the browser. Removing directories from the <em>load_once_paths</em> allow those changes to picked up as soon as you save the file - without having to restart the web server. This is particularly useful as you develop the plugin.</p></div>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/lib/app/models/woodpecker.rb:</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -808,7 +808,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>Finally, add the following to your plugin’s <em>schema.rb</em>:</p></div>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/test/schema.rb:</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -823,7 +823,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>You can test your plugin’s controller as you would test any other controller:</p></div>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/test/woodpeckers_controller_test.rb:</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -852,7 +852,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>This is just a simple test to make sure the controller is being loaded correctly. After watching it fail with <tt>rake</tt>, you can make it pass like so:</p></div>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/lib/yaffle.rb:</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -864,7 +864,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/lib/app/controllers/woodpeckers_controller.rb:</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -883,7 +883,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>You can test your plugin’s helper as you would test any other helper:</p></div>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/test/woodpeckers_helper_test.rb</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -898,7 +898,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>This is just a simple test to make sure the helper is being loaded correctly. After watching it fail with <tt>rake</tt>, you can make it pass like so:</p></div>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/lib/yaffle.rb:</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -910,7 +910,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/lib/app/helpers/woodpeckers_helper.rb:</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -929,7 +929,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>Testing routes from plugins is slightly different from testing routes in a standard rails app. To begin, add a test like this:</p></div>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/test/routing_test.rb</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -957,14 +957,14 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>Once you see the tests fail by running <em>rake</em>, you can make them pass with:</p></div>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/lib/yaffle.rb</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #000080">require</span></span> <span style="color: #FF0000">"yaffle/routing"</span></tt></pre></div></div>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/lib/yaffle/routing.rb</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -981,7 +981,7 @@ http://www.gnu.org/software/src-highlite --> ActionController<span style="color: #990000">::</span>Routing<span style="color: #990000">::</span>RouteSet<span style="color: #990000">::</span>Mapper<span style="color: #990000">.</span>send <span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #0000FF">include</span></span><span style="color: #990000">,</span> Yaffle<span style="color: #990000">::</span>Routing<span style="color: #990000">::</span>MapperExtensions</tt></pre></div></div>
<div class="paragraph"><p><strong>config/routes.rb</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1021,7 +1021,7 @@ Removes the fake rails root <div class="paragraph"><p>This section will describe how to create a simple generator that adds a file. For the generator in this section, the test could look something like this:</p></div>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/test/definition_generator_test.rb</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1061,7 +1061,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>To make it pass, create the generator:</p></div>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/generators/yaffle_definition/yaffle_definition_generator.rb</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1101,7 +1101,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>To start, add the following test method:</p></div>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/test/route_generator_test.rb</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1161,14 +1161,14 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>Run <tt>rake</tt> to watch the test fail, then make the test pass add the following:</p></div>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/lib/yaffle.rb</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #000080">require</span></span> <span style="color: #FF0000">"yaffle/commands"</span></tt></pre></div></div>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/lib/yaffle/commands.rb</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1214,7 +1214,7 @@ Rails<span style="color: #990000">::</span>Generator<span style="color: #990000" Rails<span style="color: #990000">::</span>Generator<span style="color: #990000">::</span>Commands<span style="color: #990000">::</span>Update<span style="color: #990000">.</span>send <span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #0000FF">include</span></span><span style="color: #990000">,</span> Yaffle<span style="color: #990000">::</span>Generator<span style="color: #990000">::</span>Commands<span style="color: #990000">::</span>Update</tt></pre></div></div>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/generators/yaffle/yaffle_route_generator.rb</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1248,7 +1248,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>Let’s say you have the following migration in your plugin:</p></div>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/lib/db/migrate/20081116181115_create_birdhouses.rb:</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1268,7 +1268,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_create_a_custom_rake_task">11.1. Create a custom rake task</h3>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/lib/db/migrate/20081116181115_create_birdhouses.rb:</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1286,7 +1286,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/tasks/yaffle.rake:</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1303,7 +1303,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_call_migrations_directly">11.2. Call migrations directly</h3>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/lib/yaffle.rb:</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1312,7 +1312,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p><strong>db/migrate/20081116181115_create_birdhouses.rb:</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1351,7 +1351,7 @@ examine the generated migration, adding/removing columns or other options as nec <div class="paragraph"><p>This example will demonstrate how to use one of the built-in generator methods named <em>migration_template</em> to create a migration file. Extending the rails migration generator requires a somewhat intimate knowledge of the migration generator internals, so it’s best to write a test first:</p></div>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/test/yaffle_migration_generator_test.rb</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1408,7 +1408,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>After running the test with <em>rake</em> you can make it pass with:</p></div>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/generators/yaffle/yaffle_generator.rb</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1447,7 +1447,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>and you will see a new file:</p></div>
<div class="paragraph"><p><strong>db/migrate/20080529225649_add_yaffle_fields_to_birds.rb</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1467,7 +1467,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>Many plugin authors put all of their rake tasks into a common namespace that is the same as the plugin, like so:</p></div>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/tasks/yaffle.rake</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1492,7 +1492,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>It’s common practice to put any developer-centric rake tasks (such as tests, rdoc and gem package tasks) in <em>Rakefile</em>. A rake task that packages the gem might look like this:</p></div>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/Rakefile:</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1604,7 +1604,7 @@ Warning, gotchas or tips that might help save users time <h3 id="_contents_of_em_lib_yaffle_rb_em">15.2. Contents of <em>lib/yaffle.rb</em></h3>
<div class="paragraph"><p><strong>vendor/plugins/yaffle/lib/yaffle.rb:</strong></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
diff --git a/railties/doc/guides/html/debugging_rails_applications.html b/railties/doc/guides/html/debugging_rails_applications.html index 07557b9e99..51db11eb4e 100644 --- a/railties/doc/guides/html/debugging_rails_applications.html +++ b/railties/doc/guides/html/debugging_rails_applications.html @@ -160,7 +160,7 @@ Analyze the stack trace <h3 id="_debug">1.1. debug</h3>
<div class="paragraph"><p>The <tt>debug</tt> 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:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -188,7 +188,7 @@ Title: Rails debugging guide</tt></pre> <h3 id="_to_yaml">1.2. to_yaml</h3>
<div class="paragraph"><p>Displaying an instance variable, or any other object or method, in yaml format can be achieved this way:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -216,7 +216,7 @@ Title: Rails debugging guide</tt></pre> <h3 id="_inspect">1.3. inspect</h3>
<div class="paragraph"><p>Another useful method for displaying object values is <tt>inspect</tt>, especially when working with arrays or hashes. This will print the object value as a string. For example:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -236,14 +236,14 @@ Title: Rails debugging guide</tt></pre> <div class="paragraph"><p>Rails has built-in support to debug RJS, to active it, set <tt>ActionView::Base.debug_rjs</tt> to <em>true</em>, this will specify whether RJS responses should be wrapped in a try/catch block that alert()s the caught exception (and then re-raises it).</p></div>
<div class="paragraph"><p>To enable it, add the following in the <tt>Rails::Initializer do |config|</tt> block inside <tt>environment.rb</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>config<span style="color: #990000">.</span>action_view<span style="color: #990000">[:</span>debug_rjs<span style="color: #990000">]</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #0000FF">true</span></span></tt></pre></div></div>
<div class="paragraph"><p>Or, at any time, setting <tt>ActionView::Base.debug_rjs</tt> to <em>true</em>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -264,7 +264,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>Rails makes use of Ruby’s standard <tt>logger</tt> to write log information. You can also substitute another logger such as <tt>Log4R</tt> if you wish.</p></div>
<div class="paragraph"><p>You can specify an alternative logger in your <tt>environment.rb</tt> or any environment file:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -272,7 +272,7 @@ http://www.gnu.org/software/src-highlite --> ActiveRecord<span style="color: #990000">::</span>Base<span style="color: #990000">.</span>logger <span style="color: #990000">=</span> Log4r<span style="color: #990000">::</span>Logger<span style="color: #990000">.</span>new<span style="color: #990000">(</span><span style="color: #FF0000">"Application Log"</span><span style="color: #990000">)</span></tt></pre></div></div>
<div class="paragraph"><p>Or in the <tt>Initializer</tt> section, add <em>any</em> of the following</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -290,7 +290,7 @@ config<span style="color: #990000">.</span>logger <span style="color: #990000">= <div class="paragraph"><p>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 <tt>ActiveRecord::Base.logger.level</tt> method.</p></div>
<div class="paragraph"><p>The available log levels are: <tt>:debug</tt>, <tt>:info</tt>, <tt>:warn</tt>, <tt>:error</tt>, and <tt>:fatal</tt>, corresponding to the log level numbers from 0 up to 4 respectively. To change the default log level, use</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -308,7 +308,7 @@ ActiveRecord<span style="color: #990000">::</span>Base<span style="color: #99000 <h3 id="_sending_messages">2.3. Sending Messages</h3>
<div class="paragraph"><p>To write in the current log use the <tt>logger.(debug|info|warn|error|fatal)</tt> method from within a controller, model or mailer:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -317,7 +317,7 @@ logger<span style="color: #990000">.</span>info <span style="color: #FF0000">"Pr logger<span style="color: #990000">.</span>fatal <span style="color: #FF0000">"Terminating application, raised unrecoverable error!!!"</span></tt></pre></div></div>
<div class="paragraph"><p>Here’s an example of a method instrumented with extra logging:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -368,7 +368,7 @@ Completed in 0.01224 (81 reqs/sec) | DB: 0.00044 (3%) | 302 Found [http://localh <h3 id="_setup">3.1. Setup</h3>
<div class="paragraph"><p>The debugger used by Rails, <tt>ruby-debug</tt>, comes as a gem. To install it, just run:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -377,7 +377,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>Rails has had built-in support for ruby-debug since Rails 2.0. Inside any Rails application you can invoke the debugger by calling the <tt>debugger</tt> method.</p></div>
<div class="paragraph"><p>Here’s an example:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -394,7 +394,7 @@ http://www.gnu.org/software/src-highlite --> </div></div>
<div class="paragraph"><p>Make sure you have started your web server with the option <tt>--debugger</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -620,7 +620,7 @@ true</tt></pre> <div class="paragraph"><p>The difference between <tt>next</tt> and <tt>step</tt> is that <tt>step</tt> stops at the next line of code executed, doing just a single step, while <tt>next</tt> moves to the next line without descending inside methods.</p></div>
<div class="paragraph"><p>For example, consider this block of code with an included <tt>debugger</tt> statement:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -833,7 +833,7 @@ set listsize 25</tt></pre> </div></div>
<div class="paragraph"><p>Then setup you application for profiling. Then add the following at the bottom of config/environment.rb:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
diff --git a/railties/doc/guides/html/form_helpers.html b/railties/doc/guides/html/form_helpers.html index 1054aa8ff5..0834cdd15a 100644 --- a/railties/doc/guides/html/form_helpers.html +++ b/railties/doc/guides/html/form_helpers.html @@ -196,7 +196,7 @@ Learn what makes a file upload form different; </div>
<h3 id="_generic_search_form">1.1. Generic search form</h3>
<div class="paragraph"><p>Probably the most minimal form often seen on the web is a search form with a single text input for search terms. This form consists of:</p></div>
-<div class="olist"><ol>
+<div class="olist arabic"><ol class="arabic">
<li>
<p>
a form element with "GET" method,
@@ -433,7 +433,7 @@ end</tt></pre> <% end %></tt></pre>
</div></div>
<div class="paragraph"><p>There are a few things to note here:</p></div>
-<div class="olist"><ol>
+<div class="olist arabic"><ol class="arabic">
<li>
<p>
<tt>:article</tt> is the name of the model and <tt>@article</tt> is the record.
@@ -633,7 +633,7 @@ output: <h2 id="_date_and_time_select_boxes">5. Date and time select boxes</h2>
<div class="sectionbody">
<div class="paragraph"><p>The date and time helpers differ from all the other form helpers in two important respects:</p></div>
-<div class="olist"><ol>
+<div class="olist arabic"><ol class="arabic">
<li>
<p>
Unlike other attributes you might typically have, dates and times are not representable by a single input element. Instead you have several, one for each component (year, month, day etc...). So in particular, there is no single value in your params hash with your date or time.
@@ -715,7 +715,7 @@ The model object helpers for dates and times submit parameters with special name </div></div>
<div class="paragraph"><p>by defining a LabellingFormBuilder class similar to the following:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -769,7 +769,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_what_gets_uploaded">7.1. What gets uploaded</h3>
<div class="paragraph"><p>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 <tt>original_filename</tt> attribute containing the name the file had on the user’s computer and a <tt>content_type</tt> attribute containing the MIME type of the uploaded file. The following snippet saves the uploaded content in <tt>#{RAILS_ROOT}/public/uploads</tt> under the same name as the original file (assuming the form was the one in the previous example).</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -819,7 +819,7 @@ action for a Person model, <tt>params[:model]</tt> would usually be a hash of al </div></div>
<div class="paragraph"><p>the params hash will contain</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -832,7 +832,7 @@ http://www.gnu.org/software/src-highlite --> </div></div>
<div class="paragraph"><p>will result in the params hash being</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -888,7 +888,7 @@ http://www.gnu.org/software/src-highlite --> </div></div>
<div class="paragraph"><p>This will result in a params hash that looks like</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
diff --git a/railties/doc/guides/html/getting_started_with_rails.html b/railties/doc/guides/html/getting_started_with_rails.html index a79d9903aa..56a7ff6b3e 100644 --- a/railties/doc/guides/html/getting_started_with_rails.html +++ b/railties/doc/guides/html/getting_started_with_rails.html @@ -347,7 +347,7 @@ Transferring representations of the state of that resource between system compon <h3 id="_installing_rails">3.1. Installing Rails</h3>
<div class="paragraph"><p>In most cases, the easiest way to install Rails is to take advantage of RubyGems:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -375,28 +375,28 @@ If you want to keep up with cutting-edge changes to Rails, you’ll want to <h3 id="_creating_the_blog_application">3.2. Creating the Blog Application</h3>
<div class="paragraph"><p>Open a terminal, navigate to a folder where you have rights to create files, and type:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>$ rails blog</tt></pre></div></div>
<div class="paragraph"><p>This will create a Rails application that uses a SQLite database for data storage. If you prefer to use MySQL, run this command instead:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>$ rails blog -d mysql</tt></pre></div></div>
<div class="paragraph"><p>And if you’re using PostgreSQL for data storage, run this command:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>$ rails blog -d postgresql</tt></pre></div></div>
<div class="paragraph"><p>After you create the blog application, switch to its folder to continue work directly in that application:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -495,7 +495,7 @@ The <tt>production</tt> environment is used when you deploy your application for <div class="paragraph"><p>Rails comes with built-in support for <a href="http://www.sqlite.org/">SQLite</a>, which is a lightweight serverless database application. While a busy production environment may overload SQLite, it works well for development and testing. Rails defaults to using a SQLite database when creating a new project, but you can always change it later.</p></div>
<div class="paragraph"><p>Here’s the section of the default configuration file with connection information for the development environment:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -506,7 +506,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>If you don’t have any database set up, SQLite is the easiest to get installed. If you’re on OS X 10.5 or greater on a Mac, you already have it. Otherwise, you can install it using RubyGems:</p></div>
<div class="paragraph"><p>If you’re not running OS X 10.5 or greater, you’ll need to install the SQLite gem. Similar to installing Rails you just need to run:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -514,7 +514,7 @@ http://www.gnu.org/software/src-highlite --> <h4 id="_configuring_a_mysql_database">3.3.2. Configuring a MySQL Database</h4>
<div class="paragraph"><p>If you choose to use MySQL, your <tt>config/database.yml</tt> will look a little different. Here’s the development section:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -529,7 +529,7 @@ http://www.gnu.org/software/src-highlite --> <h4 id="_configuring_a_postgresql_database">3.3.3. Configuring a PostgreSQL Database</h4>
<div class="paragraph"><p>If you choose to use PostgreSQL, your <tt>config/database.yml</tt> will be customized to use PostgreSQL databases:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -543,7 +543,7 @@ http://www.gnu.org/software/src-highlite --> <h4 id="_creating_the_database">3.3.4. Creating the Database</h4>
<div class="paragraph"><p>Now that you have your database configured, it’s time to have Rails create an empty database for you. You can do this by running a rake command:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -553,7 +553,7 @@ http://www.gnu.org/software/src-highlite --> <div class="sectionbody">
<div class="paragraph"><p>One of the traditional places to start with a new language is by getting some text up on screen quickly. To do that in Rails, you need to create at minimum a controller and a view. Fortunately, you can do that in a single command. Enter this command in your terminal:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -568,7 +568,7 @@ http://www.gnu.org/software/src-highlite --> </div>
<div class="paragraph"><p>Rails will create several files for you, including <tt>app/views/home/index.html.erb</tt>. This is the template that will be used to display the results of the <tt>index</tt> action (method) in the <tt>home</tt> controller. Open this file in your text editor and edit it to contain a single line of code:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -576,7 +576,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_starting_up_the_web_server">4.1. Starting up the Web Server</h3>
<div class="paragraph"><p>You actually have a functional Rails application already - after running only two commands! To see it, you need to start a web server on your development machine. You can do this by running another command:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -597,14 +597,14 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_setting_the_application_home_page">4.2. Setting the Application Home Page</h3>
<div class="paragraph"><p>You’d probably like to replace the "Welcome Aboard" page with your own application’s home page. The first step to doing this is to delete the default page from your application:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>$ rm public/index<span style="color: #990000">.</span>html</tt></pre></div></div>
<div class="paragraph"><p>Now, you have to tell Rails where your actual home page is located. Open the file <tt>config/routes.rb</tt> in your editor. This is your application’s, <em>routing file</em>, which holds entries in a special DSL (domain-specific language) that tells Rails how to connect incoming requests to controllers and actions. At the bottom of the file you’ll see the <em>default routes</em>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -613,7 +613,7 @@ map<span style="color: #990000">.</span>connect <span style="color: #FF0000">':c <div class="paragraph"><p>The default routes handle simple requests such as <tt>/home/index</tt>: Rails translates that into a call to the <tt>index</tt> action in the <tt>home</tt> controller. As another example, <tt>/posts/edit/1</tt> would run the <tt>edit</tt> action in the <tt>posts</tt> controller with an <tt>id</tt> of 1.</p></div>
<div class="paragraph"><p>To hook up your home page, you need to add another line to the routing file, above the default routes:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -637,7 +637,7 @@ http://www.gnu.org/software/src-highlite --> <div class="sectionbody">
<div class="paragraph"><p>In the case of the blog application, you can start by generating a scaffolded Post resource: this will represent a single blog posting. To do this, enter this command in your terminal:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -728,7 +728,7 @@ cellspacing="0" cellpadding="4"> <div class="paragraph"><p>One of the products of the <tt>script/generate scaffold</tt> command is a <em>database migration</em>. 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.</p></div>
<div class="paragraph"><p>If you look in the <tt>db/migrate/20081013124235_create_posts.rb</tt> file (remember, yours will have a slightly different name), here’s what you’ll find:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -750,7 +750,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>If you were to translate that into words, it says something like: when this migration is run, create a table named <tt>posts</tt> with two string columns (<tt>name</tt> and <tt>title</tt>) and a text column (<tt>content</tt>), and generate timestamp fields to track record creation and updating. You can learn the detailed syntax for migrations in the <a href="../migrations.html">Rails Database Migrations</a> guide.</p></div>
<div class="paragraph"><p>At this point, you can use a rake command to run the migration:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -767,7 +767,7 @@ $ rake db<span style="color: #990000">:</span>migrate</tt></pre></div></div> <h3 id="_adding_a_link">6.2. Adding a Link</h3>
<div class="paragraph"><p>To hook the posts up to the home page you’ve already created, you can add a link to the home page. Open <tt>/app/views/home/index.html.erb</tt> and modify it as follows:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -793,7 +793,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_the_model">6.4. The Model</h3>
<div class="paragraph"><p>The model file, <tt>app/models/post.rb</tt> is about as simple as it can get:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -803,7 +803,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_adding_some_validation">6.5. Adding Some Validation</h3>
<div class="paragraph"><p>Rails includes methods to help you validate the data that you send to models. Open the <tt>app/models/post.rb</tt> file and edit it:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -815,14 +815,14 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_using_the_console">6.6. Using the Console</h3>
<div class="paragraph"><p>To see your validations in action, you can use the console. The console is a command-line tool that lets you execute Ruby code in the context of your application:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>$ script/console</tt></pre></div></div>
<div class="paragraph"><p>After the console loads, you can use it to work with your application’s models:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -848,7 +848,7 @@ title<span style="color: #990000">:</span> nil<span style="color: #990000">,</sp <h3 id="_listing_all_posts">6.7. Listing All Posts</h3>
<div class="paragraph"><p>The easiest place to start looking at functionality is with the code that lists all posts. Open the file <tt>app/controllers/posts_controller.rb + and look at the +index</tt> action:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -871,7 +871,7 @@ http://www.gnu.org/software/src-highlite --> </div>
<div class="paragraph"><p>The <tt>respond_to</tt> block handles both HTML and XML calls to this action. If you browse to <tt>http://localhost:3000/posts.xml</tt>, you’ll see all of the posts in XML format. The HTML format looks for a view in <tt>app/views/posts/</tt> with a name that corresponds to the action name. Rails makes all of the instance variables from the action available to the view. Here’s <tt>app/view/posts/index.html.erb</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -928,7 +928,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_customizing_the_layout">6.8. Customizing the Layout</h3>
<div class="paragraph"><p>The view is only part of the story of how HTML is displayed in your web browser. Rails also has the concept of <tt>layouts</tt>, which are containers for views. When Rails renders a view to the browser, it does so by putting the view’s HTML into a layout’s HTML. The <tt>script/generate scaffold</tt> command automatically created a default layout, <tt>app/views/layouts/posts.html.erb</tt>, for the posts. Open this layout in your editor and modify the <tt>body</tt> tag:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -953,7 +953,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_creating_new_posts">6.9. Creating New Posts</h3>
<div class="paragraph"><p>Creating a new post involves two actions. The first is the <tt>new</tt> action, which instantiates an empty <tt>Post</tt> object:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -967,7 +967,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>The <tt>new.html.erb</tt> view displays this empty Post to the user:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1005,7 +1005,7 @@ http://www.gnu.org/software/src-highlite --> </div>
<div class="paragraph"><p>When the user clicks the <tt>Create</tt> button on this form, the browser will send information back to the <tt>create</tt> method of the controller (Rails knows to call the <tt>create</tt> method because the form is sent with an HTTP POST request; that’s one of the conventions that I mentioned earlier):</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1028,7 +1028,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_showing_an_individual_post">6.10. Showing an Individual Post</h3>
<div class="paragraph"><p>When you click the <tt>show</tt> link for a post on the index page, it will bring you to a URL like <tt>http://localhost:3000/posts/1</tt>. Rails interprets this as a call to the <tt>show</tt> action for the resource, and passes in <tt>1</tt> as the <tt>:id</tt> parameter. Here’s the <tt>show</tt> action:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1042,7 +1042,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>The <tt>show</tt> action uses <tt>Post.find</tt> to search for a single record in the database by its id value. After finding the record, Rails displays it by using <tt>show.html.erb</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1067,7 +1067,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_editing_posts">6.11. Editing Posts</h3>
<div class="paragraph"><p>Like creating a new post, editing a post is a two-part process. The first step is a request to <tt>edit_post_path(@post)</tt> with a particular post. This calls the <tt>edit</tt> action in the controller:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1076,7 +1076,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>After finding the requested post, Rails uses the <tt>edit.html.erb</tt> view to display it:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1106,7 +1106,7 @@ http://www.gnu.org/software/src-highlite --> <span style="color: #FF0000"><%= link_to 'Back', posts_path %></span></tt></pre></div></div>
<div class="paragraph"><p>Submitting the form created by this view will invoke the <tt>update</tt> action within the controller:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1136,7 +1136,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_destroying_a_post">6.12. Destroying a Post</h3>
<div class="paragraph"><p>Finally, clicking one of the <tt>destroy</tt> links sends the associated id to the <tt>destroy</tt> action:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1158,7 +1158,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>As you saw earlier, the scaffold-generated views for the <tt>new</tt> and <tt>edit</tt> actions are largely identical. You can pull the shared code out into a <tt>partial</tt> template. This requires editing the new and edit views, and adding a new template. The new <tt>_form.html.erb</tt> template should be saved in the same <tt>app/views/posts</tt> folder as the files from which it is being extracted:</p></div>
<div class="paragraph"><p><tt>new.html.erb</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1169,7 +1169,7 @@ http://www.gnu.org/software/src-highlite --> <span style="color: #FF0000"><%= link_to 'Back', posts_path %></span></tt></pre></div></div>
<div class="paragraph"><p><tt>edit.html.erb</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1181,7 +1181,7 @@ http://www.gnu.org/software/src-highlite --> <span style="color: #FF0000"><%= link_to 'Back', posts_path %></span></tt></pre></div></div>
<div class="paragraph"><p><tt>_form.html.erb</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1209,7 +1209,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_using_filters_to_eliminate_controller_duplication">7.2. Using Filters to Eliminate Controller Duplication</h3>
<div class="paragraph"><p>At this point, if you look at the controller for posts, you’ll see some duplication:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1236,7 +1236,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>Four instances of the exact same line of code doesn’t seem very DRY. Rails provides <em>filters</em> as a way to address this sort of repeated code. In this case, you can DRY things up by using a <tt>before_filter</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1272,7 +1272,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_generating_a_model">8.1. Generating a Model</h3>
<div class="paragraph"><p>Models in Rails use a singular name, and their corresponding database tables use a plural name. For the model to hold comments, the convention is to use the name Comment. Even if you don’t want to use the entire apparatus set up by scaffolding, most Rails developers still use generators to make things like models and controllers. To create the new model, run this command in your terminal:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1297,7 +1297,7 @@ http://www.gnu.org/software/src-highlite --> </ul></div>
<div class="paragraph"><p>First, take a look at <tt>comment.rb</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1307,7 +1307,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>This is very similar to the <tt>post.rb</tt> model that you saw earlier. The difference is the line <tt>belongs_to :post</tt>, which sets up an Active Record <em>association</em>. You’ll learn a little about associations in the next section of this guide.</p></div>
<div class="paragraph"><p>In addition to the model, Rails has also made a migration to create the corresponding database table:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1328,7 +1328,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>The <tt>t.references</tt> line sets up a foreign key column for the association between the two models. Go ahead and run the migration:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1350,7 +1350,7 @@ One post can have many comments </ul></div>
<div class="paragraph"><p>In fact, this is very close to the syntax that Rails uses to declare this association. You’ve already seen the line of code inside the Comment model that makes each comment belong to a Post:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1359,7 +1359,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>You’ll need to edit the <tt>post.rb</tt> file to add the other side of the association:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1380,7 +1380,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_adding_a_route">8.3. Adding a Route</h3>
<div class="paragraph"><p><em>Routes</em> are entries in the <tt>config/routes.rb</tt> file that tell Rails how to match incoming HTTP requests to controller actions. Open up that file and find the existing line referring to <tt>posts</tt>. Then edit it as follows:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1399,7 +1399,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_generating_a_controller">8.4. Generating a Controller</h3>
<div class="paragraph"><p>With the model in hand, you can turn your attention to creating a matching controller. Again, there’s a generator for this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1444,7 +1444,7 @@ http://www.gnu.org/software/src-highlite --> </ul></div>
<div class="paragraph"><p>The controller will be generated with empty methods for each action that you specified in the call to <tt>script/generate controller</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1464,7 +1464,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>You’ll need to flesh this out with code to actually process requests appropriately in each method. Here’s a version that (for simplicity’s sake) only responds to requests that require HTML:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1513,7 +1513,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>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.</p></div>
<div class="paragraph"><p>In addition, the code takes advantage of some of the methods available for an association. For example, in the <tt>new</tt> method, it calls</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1523,7 +1523,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>Because you skipped scaffolding, you’ll need to build views for comments "by hand." Invoking <tt>script/generate controller</tt> will give you skeleton views, but they’ll be devoid of actual content. Here’s a first pass at fleshing out the comment views.</p></div>
<div class="paragraph"><p>The <tt>index.html.erb</tt> view:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1552,7 +1552,7 @@ http://www.gnu.org/software/src-highlite --> <span style="color: #FF0000"><%= link_to 'Back to Post', @post %></span></tt></pre></div></div>
<div class="paragraph"><p>The <tt>new.html.erb</tt> view:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1577,7 +1577,7 @@ http://www.gnu.org/software/src-highlite --> <span style="color: #FF0000"><%= link_to 'Back', post_comments_path(@post) %></span></tt></pre></div></div>
<div class="paragraph"><p>The <tt>show.html.erb</tt> view:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1597,7 +1597,7 @@ http://www.gnu.org/software/src-highlite --> <span style="color: #FF0000"><%= link_to 'Back', post_comments_path(@post) %></span></tt></pre></div></div>
<div class="paragraph"><p>The <tt>edit.html.erb</tt> view:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1625,7 +1625,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_hooking_comments_to_posts">8.6. Hooking Comments to Posts</h3>
<div class="paragraph"><p>As a final step, I’ll modify the <tt>show.html.erb</tt> view for a post to show the comments on that post, and to allow managing those comments:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
diff --git a/railties/doc/guides/html/i18n.html b/railties/doc/guides/html/i18n.html index 7326244ce0..0297475d87 100644 --- a/railties/doc/guides/html/i18n.html +++ b/railties/doc/guides/html/i18n.html @@ -2,7 +2,7 @@ <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> - <title>The Rails Internationalization API</title> + <title>The Rails Internationalization (I18n) API</title> <!--[if lt IE 8]> <script src="http://ie7-js.googlecode.com/svn/version/2.0(beta3)/IE8.js" type="text/javascript"></script> <![endif]--> @@ -41,14 +41,14 @@ </ul> </li> <li> - <a href="#_walkthrough_setup_a_simple_i18n_8217_ed_rails_application">Walkthrough: setup a simple I18n’ed Rails application</a> + <a href="#_setup_the_rails_application_for_internationalization">Setup the Rails application for internationalization</a> <ul> <li><a href="#_configure_the_i18n_module">Configure the I18n module</a></li> <li><a href="#_optional_custom_i18n_configuration_setup">Optional: custom I18n configuration setup</a></li> - <li><a href="#_set_the_locale_in_each_request">Set the locale in each request</a></li> + <li><a href="#_setting_and_passing_the_locale">Setting and passing the locale</a></li> </ul> </li> @@ -112,15 +112,23 @@ </div> <div id="content"> - <h1>The Rails Internationalization API</h1> + <h1>The Rails Internationalization (I18n) API</h1> <div id="preamble">
<div class="sectionbody">
-<div class="paragraph"><p>The Ruby I18n gem which is shipped with Ruby on Rails (starting from Rails 2.2) provides an easy-to-use and extensible framework for translating your application to a single custom language other than English or providing multi-language support in your application.</p></div>
+<div class="paragraph"><p>The Ruby I18n (shorthand for <em>internationalization</em>) gem which is shipped with Ruby on Rails (starting from Rails 2.2) provides an easy-to-use and extensible framework for translating your application to a single custom language other than English or providing multi-language support in your application.</p></div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<img src="./images/icons/note.png" alt="Note" />
+</td>
+<td class="content">The Ruby I18n framework provides you with all neccessary means for internationalization/localization of your Rails application. You may, however, use any of various plugins and extensions available. See Rails <a href="http://rails-i18n.org/wiki">I18n Wiki</a> for more information.</td>
+</tr></table>
+</div>
</div>
</div>
<h2 id="_how_i18n_in_ruby_on_rails_works">1. How I18n in Ruby on Rails works</h2>
<div class="sectionbody">
-<div class="paragraph"><p>Internationalization is a complex problem. Natural languages differ in so many ways that it is hard to provide tools for solving all problems at once. For that reason the Rails I18n API focusses on:</p></div>
+<div class="paragraph"><p>Internationalization is a complex problem. Natural languages differ in so many ways (eg. in pluralization rules) that it is hard to provide tools for solving all problems at once. For that reason the Rails I18n API focuses on:</p></div>
<div class="ulist"><ul>
<li>
<p>
@@ -133,33 +141,42 @@ making it easy to customize and extend everything for other languages </p>
</li>
</ul></div>
+<div class="paragraph"><p>As part of this solution, <strong>every static string in the Rails framework</strong> — eg. ActiveRecord validation messages, time and date formats — <strong>has been internationalized</strong>, so <em>localization</em> of a Rails application means "over-riding" these defaults.</p></div>
<h3 id="_the_overall_architecture_of_the_library">1.1. The overall architecture of the library</h3>
<div class="paragraph"><p>Thus, the Ruby I18n gem is split into two parts:</p></div>
<div class="ulist"><ul>
<li>
<p>
-The public API which is just a Ruby module with a bunch of public methods and definitions how the library works.
+The public API of the i18n framework — a Ruby module with public methods and definitions how the library works
</p>
</li>
<li>
<p>
-A shipped backend (which is intentionally named the Simple backend) that implements these methods.
+A default backend (which is intentionally named <em>Simple</em> backend) that implements these methods
</p>
</li>
</ul></div>
-<div class="paragraph"><p>As a user you should always only access the public methods on the I18n module but it is useful to know about the capabilities of the backend you use and maybe exchange the shipped Simple backend with a more powerful one.</p></div>
+<div class="paragraph"><p>As a user you should always only access the public methods on the I18n module, but it is useful to know about the capabilities of the backend.</p></div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<img src="./images/icons/note.png" alt="Note" />
+</td>
+<td class="content">It is possible (or even desirable) to swap the shipped Simple backend with a more powerful one, which would store translation data in a relational database, GetText dictionary, or similar. See section <a href="#_using_different_backends">Using different backends</a> below.</td>
+</tr></table>
+</div>
<h3 id="_the_public_i18n_api">1.2. The public I18n API</h3>
-<div class="paragraph"><p>We will go into more detail about the public methods later but here’s a quick overview. The most important methods are:</p></div>
+<div class="paragraph"><p>The most important methods of the I18n API are:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt>translate <span style="font-style: italic"><span style="color: #9A1900"># lookup translations</span></span>
-localize <span style="font-style: italic"><span style="color: #9A1900"># localize Date and Time objects to local formats</span></span></tt></pre></div></div>
+<pre><tt>translate <span style="font-style: italic"><span style="color: #9A1900"># Lookup text translations</span></span>
+localize <span style="font-style: italic"><span style="color: #9A1900"># Localize Date and Time objects to local formats</span></span></tt></pre></div></div>
<div class="paragraph"><p>These have the aliases #t and #l so you can use them like this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -167,27 +184,45 @@ http://www.gnu.org/software/src-highlite --> I18n<span style="color: #990000">.</span>l Time<span style="color: #990000">.</span>now</tt></pre></div></div>
<div class="paragraph"><p>There are also attribute readers and writers for the following attributes:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt>load_path <span style="font-style: italic"><span style="color: #9A1900"># announce your custom translation files</span></span>
-locale <span style="font-style: italic"><span style="color: #9A1900"># get and set the current locale</span></span>
-default_locale <span style="font-style: italic"><span style="color: #9A1900"># get and set the default locale</span></span>
-exception_handler <span style="font-style: italic"><span style="color: #9A1900"># use a different exception_handler</span></span>
-backend <span style="font-style: italic"><span style="color: #9A1900"># use a different backend</span></span></tt></pre></div></div>
+<pre><tt>load_path <span style="font-style: italic"><span style="color: #9A1900"># Announce your custom translation files</span></span>
+locale <span style="font-style: italic"><span style="color: #9A1900"># Get and set the current locale</span></span>
+default_locale <span style="font-style: italic"><span style="color: #9A1900"># Get and set the default locale</span></span>
+exception_handler <span style="font-style: italic"><span style="color: #9A1900"># Use a different exception_handler</span></span>
+backend <span style="font-style: italic"><span style="color: #9A1900"># Use a different backend</span></span></tt></pre></div></div>
+<div class="paragraph"><p>So, let’s internationalize a simple Rails application from the ground up in the next chapters!</p></div>
</div>
-<h2 id="_walkthrough_setup_a_simple_i18n_8217_ed_rails_application">2. Walkthrough: setup a simple I18n’ed Rails application</h2>
+<h2 id="_setup_the_rails_application_for_internationalization">2. Setup the Rails application for internationalization</h2>
<div class="sectionbody">
-<div class="paragraph"><p>There are just a few, simple steps to get up and running with a I18n support for your application.</p></div>
+<div class="paragraph"><p>There are just a few, simple steps to get up and running with I18n support for your application.</p></div>
<h3 id="_configure_the_i18n_module">2.1. Configure the I18n module</h3>
-<div class="paragraph"><p>Rails will wire up all required settings for you with sane defaults. If you need different settings you can overwrite them easily.</p></div>
-<div class="paragraph"><p>The I18n library will use English (:en) as a <strong>default locale</strong> by default. I.e if you don’t set a different locale, :en will be used for looking up translations. Also, Rails adds all files from config/locales/*.rb,yml to your translations load path.</p></div>
-<div class="paragraph"><p>The <strong>translations load path</strong> (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.</p></div>
-<div class="paragraph"><p>(Hint: 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.)</p></div>
-<div class="paragraph"><p>The default environment.rb says:</p></div>
+<div class="paragraph"><p>Following the <em>convention over configuration</em> philosophy, Rails will set-up your application with reasonable defaults. If you need different settings, you can overwrite them easily.</p></div>
+<div class="paragraph"><p>Rails adds all <tt>.rb</tt> and <tt>.yml</tt> files from <tt>config/locales</tt> directory to your <strong>translations load path</strong>, automatically.</p></div>
+<div class="paragraph"><p>See the default <tt>en.yml</tt> locale in this directory, containing a sample pair of translation strings:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>en<span style="color: #990000">:</span>
+ hello<span style="color: #990000">:</span> <span style="color: #FF0000">"Hello world"</span></tt></pre></div></div>
+<div class="paragraph"><p>This means, that in the <tt>:en</tt> locale, the key <em>hello</em> will map to <em>Hello world</em> string. Every string inside Rails is internationalized in this way, see for instance ActiveRecord validation messages in the <a href="http://github.com/rails/rails/blob/master/activerecord/lib/active_record/locale/en.yml"><tt>activerecord/lib/active_record/locale/en.yml</tt></a> file or time and date formats in the <a href="http://github.com/rails/rails/blob/master/activesupport/lib/active_support/locale/en.yml"><tt>activesupport/lib/active_support/locale/en.yml</tt></a> file. You can use YAML or standard Ruby Hashes to store translations in the default (Simple) backend.</p></div>
+<div class="paragraph"><p>The I18n library will use <strong>English</strong> as a <strong>default locale</strong>, ie. if you don’t set a different locale, <tt>:en</tt> will be used for looking up translations.</p></div>
+<div class="paragraph"><p>The <strong>translations load path</strong> (<tt>I18n.load_path</tt>) 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.</p></div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<img src="./images/icons/note.png" alt="Note" />
+</td>
+<td class="content">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.</td>
+</tr></table>
+</div>
+<div class="paragraph"><p>The default <tt>environment.rb</tt> files has instruction how to add locales from another directory and how to set different default locale. Just uncomment and edit the specific lines.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -197,25 +232,25 @@ http://www.gnu.org/software/src-highlite --> <span style="font-style: italic"><span style="color: #9A1900"># config.i18n.load_path << Dir[File.join(RAILS_ROOT, 'my', 'locales', '*.{rb,yml}')]</span></span>
<span style="font-style: italic"><span style="color: #9A1900"># config.i18n.default_locale = :de</span></span></tt></pre></div></div>
<h3 id="_optional_custom_i18n_configuration_setup">2.2. Optional: custom I18n configuration setup</h3>
-<div class="paragraph"><p>For the sake of completeness let’s mention that if you do not want to use the environment for some reason you can always wire up things manually, too.</p></div>
-<div class="paragraph"><p>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:</p></div>
+<div class="paragraph"><p>For the sake of completeness, let’s mention that if you do not want to use the <tt>environment.rb</tt> file for some reason, you can always wire up things manually, too.</p></div>
+<div class="paragraph"><p>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 <strong>initializer</strong>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-style: italic"><span style="color: #9A1900"># in config/initializer/locale.rb</span></span>
<span style="font-style: italic"><span style="color: #9A1900"># tell the I18n library where to find your translations</span></span>
-I18n<span style="color: #990000">.</span>load_path <span style="color: #990000">+=</span> Dir<span style="color: #990000">[</span> File<span style="color: #990000">.</span>join<span style="color: #990000">(</span>RAILS_ROOT<span style="color: #990000">,</span> <span style="color: #FF0000">'lib'</span><span style="color: #990000">,</span> <span style="color: #FF0000">'locale'</span><span style="color: #990000">,</span> <span style="color: #FF0000">'*.{rb,yml}'</span><span style="color: #990000">)</span> <span style="color: #990000">]</span>
+I18n<span style="color: #990000">.</span>load_path <span style="color: #990000"><<</span> Dir<span style="color: #990000">[</span> File<span style="color: #990000">.</span>join<span style="color: #990000">(</span>RAILS_ROOT<span style="color: #990000">,</span> <span style="color: #FF0000">'lib'</span><span style="color: #990000">,</span> <span style="color: #FF0000">'locale'</span><span style="color: #990000">,</span> <span style="color: #FF0000">'*.{rb,yml}'</span><span style="color: #990000">)</span> <span style="color: #990000">]</span>
-<span style="font-style: italic"><span style="color: #9A1900"># you can omit this if you're happy with English as a default locale</span></span>
+<span style="font-style: italic"><span style="color: #9A1900"># set default locale to something else then :en</span></span>
I18n<span style="color: #990000">.</span>default_locale <span style="color: #990000">=</span> <span style="color: #990000">:</span>pt</tt></pre></div></div>
-<h3 id="_set_the_locale_in_each_request">2.3. Set the locale in each request</h3>
+<h3 id="_setting_and_passing_the_locale">2.3. Setting and passing the locale</h3>
<div class="paragraph"><p>By default the I18n library will use :en (English) as a I18n.default_locale for looking up translations (if you do not specify a locale for a lookup).</p></div>
<div class="paragraph"><p>If you want to translate your Rails application to a single language other than English you can set I18n.default_locale to your locale. If you want to change the locale on a per-request basis though you can set it in a before_filter on the ApplicationController like this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -240,7 +275,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>The process of "internationalization" usually means to abstract all strings and other locale specific bits out of your application. The process of "localization" means to then provide translations and localized formats for these bits. <a href="#1">[1]</a></p></div>
<div class="paragraph"><p>So, let’s internationalize something. You most probably have something like this in one of your applications:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -265,7 +300,7 @@ ActionController<span style="color: #990000">::</span>Routing<span style="color: <h3 id="_adding_translations">3.1. Adding Translations</h3>
<div class="paragraph"><p>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:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -293,7 +328,7 @@ http://www.gnu.org/software/src-highlite --> </div>
<div class="paragraph"><p>So let’s add the missing translations (i.e. do the "localization" part):</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -318,7 +353,7 @@ pirate<span style="color: #990000">:</span> <h3 id="_adding_date_time_formats">3.2. Adding Date/Time formats</h3>
<div class="paragraph"><p>Ok, 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.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -328,7 +363,7 @@ http://www.gnu.org/software/src-highlite --> <span style="color: #FF0000"><p><%= l Time.now, :format =></span> <span style="color: #990000">:</span>short <span style="color: #990000">%></span><span style="color: #FF0000"></p></span></tt></pre></div></div>
<div class="paragraph"><p>And in our pirate translations file let’s add a time format (it’s already there in Rails' defaults for English):</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -372,7 +407,7 @@ localize dates, numbers, currency etc. <h4 id="_basic_lookup_scopes_and_nested_keys">4.1.1. Basic lookup, scopes and nested keys</h4>
<div class="paragraph"><p>Translations are looked up by keys which can be both Symbols or Strings, so these calls are equivalent:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -380,7 +415,7 @@ http://www.gnu.org/software/src-highlite --> I18n<span style="color: #990000">.</span>t <span style="color: #FF0000">'message'</span></tt></pre></div></div>
<div class="paragraph"><p>translate also takes a :scope option which can contain one or many additional keys that will be used to specify a “namespace” or scope for a translation key:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -388,14 +423,14 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>This looks up the :invalid message in the ActiveRecord error messages.</p></div>
<div class="paragraph"><p>Additionally, both the key and scopes can be specified as dot separated keys as in:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>I18n<span style="color: #990000">.</span>translate <span style="color: #990000">:</span><span style="color: #FF0000">"active_record.error_messages.invalid"</span></tt></pre></div></div>
<div class="paragraph"><p>Thus the following calls are equivalent:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -406,7 +441,7 @@ I18n<span style="color: #990000">.</span>t <span style="color: #990000">:</span> <h4 id="_defaults">4.1.2. Defaults</h4>
<div class="paragraph"><p>When a default option is given its value will be returned if the translation is missing:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -415,7 +450,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>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.</p></div>
<div class="paragraph"><p>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:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -424,7 +459,7 @@ http://www.gnu.org/software/src-highlite --> <h4 id="_bulk_and_namespace_lookup">4.1.3. Bulk and namespace lookup</h4>
<div class="paragraph"><p>To lookup multiple translations at once an array of keys can be passed:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -432,7 +467,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-style: italic"><span style="color: #9A1900"># => ["must be odd", "must be even"]</span></span></tt></pre></div></div>
<div class="paragraph"><p>Also, a key can translate to a (potentially nested) hash as grouped translations. E.g. one can receive all ActiveRecord error messages as a Hash with:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -442,7 +477,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>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.</p></div>
<div class="paragraph"><p>All options besides :default and :scope that are passed to #translate will be interpolated to the translation:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -454,7 +489,7 @@ I18n<span style="color: #990000">.</span>translate <span style="color: #990000"> <div class="paragraph"><p>In English there’s only a singular and a plural form for a given string, e.g. "1 message" and "2 messages". Other languages (<a href="http://www.unicode.org/cldr/data/charts/supplemental/language_plural_rules.html#ar">Arabic</a>, <a href="http://www.unicode.org/cldr/data/charts/supplemental/language_plural_rules.html#ja">Japanese</a>, <a href="http://www.unicode.org/cldr/data/charts/supplemental/language_plural_rules.html#ru">Russian</a> and many more) have different grammars that have additional or less <a href="http://www.unicode.org/cldr/data/charts/supplemental/language_plural_rules.html">plural forms</a>. Thus, the I18n API provides a flexible pluralization feature.</p></div>
<div class="paragraph"><p>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:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -466,7 +501,7 @@ I18n<span style="color: #990000">.</span>translate <span style="color: #990000"> <span style="font-style: italic"><span style="color: #9A1900"># => '2 messages'</span></span></tt></pre></div></div>
<div class="paragraph"><p>The algorithm for pluralizations in :en is as simple as:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -477,7 +512,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>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.</p></div>
<div class="paragraph"><p>If no locale is passed I18n.locale is used:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -486,7 +521,7 @@ I18n<span style="color: #990000">.</span>t <span style="color: #990000">:</span> I18n<span style="color: #990000">.</span>l Time<span style="color: #990000">.</span>now</tt></pre></div></div>
<div class="paragraph"><p>Explicitely passing a locale:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -494,7 +529,7 @@ http://www.gnu.org/software/src-highlite --> I18n<span style="color: #990000">.</span>l Time<span style="color: #990000">.</span>now<span style="color: #990000">,</span> <span style="color: #990000">:</span>locale <span style="color: #990000">=></span> <span style="color: #990000">:</span>de</tt></pre></div></div>
<div class="paragraph"><p>I18n.locale defaults to I18n.default_locale which defaults to :en. The default locale can be set like this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -505,7 +540,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>The shipped Simple backend allows you to store translations in both plain Ruby and YAML format. <a href="#2">[2]</a></p></div>
<div class="paragraph"><p>For example a Ruby Hash providing translations can look like this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -518,7 +553,7 @@ http://www.gnu.org/software/src-highlite --> <span style="color: #FF0000">}</span></tt></pre></div></div>
<div class="paragraph"><p>The equivalent YAML file would look like this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -528,7 +563,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>As you see in both cases the toplevel key is the locale. :foo is a namespace key and :bar is the key for the translation "baz".</p></div>
<div class="paragraph"><p>Here is a "real" example from the ActiveSupport en.yml translations YAML file:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -540,7 +575,7 @@ http://www.gnu.org/software/src-highlite --> long<span style="color: #990000">:</span> <span style="color: #FF0000">"%B %d, %Y"</span></tt></pre></div></div>
<div class="paragraph"><p>So, all of the following equivalent lookups will return the :short date format "%B %d":</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -553,7 +588,7 @@ I18n<span style="color: #990000">.</span>t <span style="color: #990000">:</span> <div class="paragraph"><p>You can use the methods Model.human_name and Model.human_attribute_name(attribute) to transparently lookup translations for your model and attribute names.</p></div>
<div class="paragraph"><p>For example when you add the following translations:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -571,7 +606,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>This gives you quite powerful means to flexibly adjust your messages to your application’s needs.</p></div>
<div class="paragraph"><p>Consider a User model with a validates_presence_of validation for the name attribute like this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -580,7 +615,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>The key for the error message in this case is :blank. ActiveRecord will lookup this key in the namespaces:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -589,7 +624,7 @@ activerecord<span style="color: #990000">.</span>errors<span style="color: #9900 activerecord<span style="color: #990000">.</span>errors<span style="color: #990000">.</span>messages</tt></pre></div></div>
<div class="paragraph"><p>Thus, in our example it will try the following keys in this order and return the first result:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -599,7 +634,7 @@ activerecord<span style="color: #990000">.</span>errors<span style="color: #9900 <div class="paragraph"><p>When your models are additionally using inheritance then the messages are looked up for the inherited model class names are looked up.</p></div>
<div class="paragraph"><p>For example, you might have an Admin model inheriting from User:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -608,7 +643,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>Then ActiveRecord will look for messages in this order:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -741,7 +776,7 @@ cellspacing="0" cellpadding="4"> <div class="paragraph"><p>If you are using the ActiveRecord error_messages_for helper you will want to add translations for it.</p></div>
<div class="paragraph"><p>Rails ships with the following translations:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -763,7 +798,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>For several reasons the shipped Simple backend only does the "simplest thing that ever could work" <em>for Ruby on Rails</em> <a href="#3">[3]</a> ... which means that it is only guaranteed to work for English and, as a side effect, languages that are very similar to English. Also, the simple backend is only capable of reading translations but can not dynamically store them to any format.</p></div>
<div class="paragraph"><p>That does not mean you’re stuck with these limitations though. The Ruby I18n gem makes it very easy to exchange the Simple backend implementation with something else that fits better for your needs. E.g. you could exchange it with Globalize’s Static backend:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -771,7 +806,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_using_different_exception_handlers">6.2. Using different exception handlers</h3>
<div class="paragraph"><p>The I18n API defines the following exceptions that will be raised by backends when the corresponding unexpected conditions occur:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -785,7 +820,7 @@ UnknownFileType <span style="font-style: italic"><span style="color <div class="paragraph"><p>The reason for this is that during development you’d usually want your views to still render even though a translation is missing.</p></div>
<div class="paragraph"><p>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:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -800,7 +835,7 @@ I18n<span style="color: #990000">.</span>exception_handler <span style="color: # <div class="paragraph"><p>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.</p></div>
<div class="paragraph"><p>To do so the helper forces I18n#translate to raise exceptions no matter what exception handler is defined by setting the :raise option:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
diff --git a/railties/doc/guides/html/layouts_and_rendering.html b/railties/doc/guides/html/layouts_and_rendering.html index 037714db78..8d9cbad381 100644 --- a/railties/doc/guides/html/layouts_and_rendering.html +++ b/railties/doc/guides/html/layouts_and_rendering.html @@ -127,7 +127,7 @@ Call <tt>head</tt> to create a response consisting solely of HTTP headers to sen <h3 id="_rendering_by_default_convention_over_configuration_in_action">2.1. Rendering by Default: Convention Over Configuration in Action</h3>
<div class="paragraph"><p>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 actions. For example, if you have this code in your <tt>BooksController</tt> class:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -156,7 +156,7 @@ http://www.gnu.org/software/src-highlite --> <h4 id="_rendering_nothing">2.2.1. Rendering Nothing</h4>
<div class="paragraph"><p>Perhaps the simplest thing you can do with <tt>render</tt> is to render nothing at all:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -173,7 +173,7 @@ http://www.gnu.org/software/src-highlite --> <h4 id="_rendering_an_action_8217_s_view">2.2.2. Rendering an Action’s View</h4>
<div class="paragraph"><p>If you want to render the view that corresponds to a different action within the same template, you can use <tt>render</tt> with the name of the view:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -189,7 +189,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>If the call to <tt>update_attributes</tt> fails, calling the <tt>update</tt> action in this controller will render the <tt>edit.html.erb</tt> template belonging to the same controller.</p></div>
<div class="paragraph"><p>If you prefer, you can use a symbol instead of a string to specify the action to render:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -204,7 +204,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>To be explicit, you can use <tt>render</tt> with the <tt>:action</tt> option (though this is no longer necessary as of Rails 2.3):</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -228,14 +228,14 @@ http://www.gnu.org/software/src-highlite --> <h4 id="_rendering_an_action_8217_s_template_from_another_controller">2.2.3. Rendering an Action’s Template from Another Controller</h4>
<div class="paragraph"><p>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 <tt>render</tt>, which accepts the full path (relative to <tt>app/views</tt>) of the template to render. For example, if you’re running code in an <tt>AdminProductsController</tt> that lives in <tt>app/controllers/admin</tt>, you can render the results of an action to a template in <tt>app/views/products</tt> this way:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>render <span style="color: #FF0000">'products/show'</span></tt></pre></div></div>
<div class="paragraph"><p>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 <tt>:template</tt> option (which was required on Rails 2.2 and earlier):</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -243,14 +243,14 @@ http://www.gnu.org/software/src-highlite --> <h4 id="_rendering_an_arbitrary_file">2.2.4. Rendering an Arbitrary File</h4>
<div class="paragraph"><p>The <tt>render</tt> method can also use a view that’s entirely outside of your application (perhaps you’re sharing views between two Rails applications):</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>render <span style="color: #FF0000">"/u/apps/warehouse_app/current/app/views/products/show"</span></tt></pre></div></div>
<div class="paragraph"><p>Rails determines that this is a file render because of the leading slash character. To be explicit, you can use the <tt>:file</tt> option (which was required on Rails 2.2 and earlier):</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -275,7 +275,7 @@ http://www.gnu.org/software/src-highlite --> <h4 id="_using_tt_render_tt_with_tt_inline_tt">2.2.5. Using <tt>render</tt> with <tt>:inline</tt></h4>
<div class="paragraph"><p>The <tt>render</tt> method can do without a view completely, if you’re willing to use the <tt>:inline</tt> option to supply ERB as part of the method call. This is perfectly valid:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -290,7 +290,7 @@ http://www.gnu.org/software/src-highlite --> </div>
<div class="paragraph"><p>By default, inline rendering uses ERb. You can force it to use Builder instead with the <tt>:type</tt> option:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -298,7 +298,7 @@ http://www.gnu.org/software/src-highlite --> <h4 id="_using_tt_render_tt_with_tt_update_tt">2.2.6. Using <tt>render</tt> with <tt>:update</tt></h4>
<div class="paragraph"><p>You can also render javascript-based page updates inline using the <tt>:update</tt> option to <tt>render</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -316,7 +316,7 @@ http://www.gnu.org/software/src-highlite --> <h4 id="_rendering_text">2.2.7. Rendering Text</h4>
<div class="paragraph"><p>You can send plain text - with no markup at all - back to the browser by using the <tt>:text</tt> option to <tt>render</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -340,7 +340,7 @@ http://www.gnu.org/software/src-highlite --> <h4 id="_rendering_json">2.2.8. Rendering JSON</h4>
<div class="paragraph"><p>JSON is a javascript data format used by many AJAX libraries. Rails has built-in support for converting objects to JSON and rendering that JSON back to the browser:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -356,7 +356,7 @@ http://www.gnu.org/software/src-highlite --> <h4 id="_rendering_xml">2.2.9. Rendering XML</h4>
<div class="paragraph"><p>Rails also has built-in support for converting objects to XML and rendering that XML back to the caller:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -372,7 +372,7 @@ http://www.gnu.org/software/src-highlite --> <h4 id="_rendering_vanilla_javascript">2.2.10. Rendering Vanilla JavaScript</h4>
<div class="paragraph"><p>Rails can render vanilla JavaScript (as an alternative to using <tt>update</tt> with n <tt>.rjs</tt> file):</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -405,7 +405,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_the_tt_content_type_tt_option">The <tt>:content_type</tt> Option</h5>
<div class="paragraph"><p>By default, Rails will serve the results of a rendering operation with the MIME content-type of <tt>text/html</tt> (or <tt>application/json</tt> if you use the <tt>:json</tt> option, or <tt>application/xml</tt> for the <tt>:xml</tt> option.). There are times when you might like to change this, and you can do so by setting the <tt>:content_type</tt> option:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -414,14 +414,14 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>With most of the options to <tt>render</tt>, 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.</p></div>
<div class="paragraph"><p>You can use the <tt>:layout</tt> option to tell Rails to use a specific file as the layout for the current action:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>render <span style="color: #990000">:</span>layout <span style="color: #990000">=></span> <span style="color: #FF0000">'special_layout'</span></tt></pre></div></div>
<div class="paragraph"><p>You can also tell Rails to render with no layout at all:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -429,7 +429,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_the_tt_status_tt_option">The <tt>:status</tt> Option</h5>
<div class="paragraph"><p>Rails will automatically generate a response with the correct HTML status code (in most cases, this is <tt>200 OK</tt>). You can use the <tt>:status</tt> option to change this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -439,7 +439,7 @@ render <span style="color: #990000">:</span>status <span style="color: #990000"> <h5 id="_the_tt_location_tt_option">The <tt>:location</tt> Option</h5>
<div class="paragraph"><p>You can use the <tt>:location</tt> option to set the HTTP <tt>Location</tt> header:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -449,7 +449,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_specifying_layouts_on_a_per_controller_basis">Specifying Layouts on a per-Controller Basis</h5>
<div class="paragraph"><p>You can override the automatic layout conventions in your controllers by using the <tt>layout</tt> declaration in the controller. For example:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -460,7 +460,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>With this declaration, all methods within <tt>ProductsController</tt> will use <tt>app/views/layouts/inventory.html.erb</tt> for their layout.</p></div>
<div class="paragraph"><p>To assign a specific layout for the entire application, use a declaration in your <tt>ApplicationController</tt> class:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -472,7 +472,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_choosing_layouts_at_runtime">Choosing Layouts at Runtime</h5>
<div class="paragraph"><p>You can use a symbol to defer the choice of layout until a request is processed:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -491,7 +491,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>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 to determine the layout:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -514,7 +514,7 @@ end</tt></pre> <div class="paragraph"><p>Layouts are shared downwards in the hierarchy, and more specific layouts always override more general ones. For example:</p></div>
<div class="paragraph"><p><tt>application_controller.rb</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -524,7 +524,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p><tt>posts_controller.rb</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -533,7 +533,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p><tt>special_posts_controller.rb</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -543,7 +543,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p><tt>old_posts_controller.rb</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -592,7 +592,7 @@ In general, views will be rendered in the <tt>main</tt> layout <div class="paragraph"><p>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 <tt>render</tt> works.</p></div>
<div class="paragraph"><p>For example, here’s some code that will trigger this error:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -604,7 +604,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>If <tt>@book.special?</tt> evaluates to <tt>true</tt>, Rails will start the rendering process to dump the <tt>@book</tt> variable into the <tt>special_show</tt> view. But this will <em>not</em> stop the rest of the code in the <tt>show</tt> action from running, and when Rails hits the end of the action, it will start to render the <tt>show</tt> view - and throw an error. The solution is simple: make sure that you only have one call to <tt>render</tt> or <tt>redirect</tt> in a single code path. One thing that can help is <tt>and return</tt>. Here’s a patched version of the method:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -617,7 +617,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_using_tt_redirect_to_tt">2.3. Using <tt>redirect_to</tt></h3>
<div class="paragraph"><p>Another way to handle returning responses to a HTTP request is with <tt>redirect_to</tt>. As you’ve seen, <tt>render</tt> tells Rails which view (or other asset) to use in constructing a response. The <tt>redirect_to</tt> 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:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -638,7 +638,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>Sometimes inexperienced developers conceive of <tt>redirect_to</tt> as a sort of <tt>goto</tt> command, moving execution from one place to another in your Rails code. This is <em>not</em> 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 a HTTP 302 status code.</p></div>
<div class="paragraph"><p>Consider these actions to see the difference:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -654,7 +654,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>With the code in this form, there will be likely be a problem if the <tt>@book</tt> variable is <tt>nil</tt>. Remember, a <tt>render :action</tt> doesn’t run any code in the target action, so nothing will set up the <tt>@books</tt> variable that the <tt>index</tt> view is presumably depending on. One way to fix this is to redirect instead of rendering:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -672,14 +672,14 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_using_tt_head_tt_to_build_header_only_responses">2.4. Using <tt>head</tt> To Build Header-Only Responses</h3>
<div class="paragraph"><p>The <tt>head</tt> method exists to let you send back responses to the browser that have only headers. It provides a more obvious alternative to calling <tt>render :nothing</tt>. The <tt>head</tt> method takes one response, which is interpreted as a hash of header names and values. For example, you can return only an error header:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>head <span style="color: #990000">:</span>bad_request</tt></pre></div></div>
<div class="paragraph"><p>Or you can use other HTTP headers to convey additional information:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -742,7 +742,7 @@ image_tag <h4 id="_linking_to_feeds_with_tt_auto_discovery_link_tag_tt">3.1.1. Linking to Feeds with <tt>auto_discovery_link_tag</tt></h4>
<div class="paragraph"><p>The <tt>auto_discovery_link_tag helper builds HTML that most browsers and newsreaders can use to detect the presences of RSS or ATOM feeds. It takes the type of the link (</tt>:rss+ or <tt>:atom</tt>), a hash of options that are passed through to url_for, and a hash of options for the tag:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -768,63 +768,63 @@ http://www.gnu.org/software/src-highlite --> <h4 id="_linking_to_javascript_files_with_tt_javascript_include_tag_tt">3.1.2. Linking to Javascript Files with <tt>javascript_include_tag</tt></h4>
<div class="paragraph"><p>The <tt>javascript_include_tag</tt> helper returns an HTML <tt><script></tt> tag for each source provided. Rails looks in <tt>public/javascripts</tt> for these files by default, but you can specify a full path relative to the document root, or a URL, if you prefer. For example, to include <tt>public/javascripts/main.js</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #FF0000"><%= javascript_include_tag "main" %></span></tt></pre></div></div>
<div class="paragraph"><p>To include <tt>public/javascripts/main.js</tt> and <tt>public/javascripts/columns.js</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #FF0000"><%= javascript_include_tag "main", "columns" %></span></tt></pre></div></div>
<div class="paragraph"><p>To include <tt>public/javascripts/main.js</tt> and <tt>public/photos/columns.js</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #FF0000"><%= javascript_include_tag "main", "/photos/columns" %></span></tt></pre></div></div>
<div class="paragraph"><p>To include <tt>http://example.com/main.js</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #FF0000"><%= javascript_include_tag "http://example.com/main.js" %></span></tt></pre></div></div>
<div class="paragraph"><p>The <tt>defaults</tt> option loads the Prototype and Scriptaculous libraries:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #FF0000"><%= javascript_include_tag :defaults %></span></tt></pre></div></div>
<div class="paragraph"><p>The <tt>all</tt> option loads every javascript file in <tt>public/javascripts</tt>, starting with the Prototype and Scriptaculous libraries:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #FF0000"><%= javascript_include_tag :all %></span></tt></pre></div></div>
<div class="paragraph"><p>You can supply the <tt>:recursive</tt> option to load files in subfolders of <tt>public/javascripts</tt> as well:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #FF0000"><%= javascript_include_tag :all, :recursive =></span> <span style="font-weight: bold"><span style="color: #0000FF">true</span></span> <span style="color: #990000">%></span></tt></pre></div></div>
<div class="paragraph"><p>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 <tt>:cache => true</tt> in your <tt>javascript_include_tag</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #FF0000"><%= javascript_include_tag "main", "columns", :cache =></span> <span style="font-weight: bold"><span style="color: #0000FF">true</span></span> <span style="color: #990000">%></span></tt></pre></div></div>
<div class="paragraph"><p>By default, the combined file will be delivered as <tt>javascripts/all.js</tt>. You can specify a location for the cached asset file instead:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -833,63 +833,63 @@ http://www.gnu.org/software/src-highlite --> <h4 id="_linking_to_css_files_with_tt_stylesheet_link_tag_tt">3.1.3. Linking to CSS Files with <tt>stylesheet_link_tag</tt></h4>
<div class="paragraph"><p>The <tt>stylesheet_link_tag</tt> helper returns an HTML <tt><link></tt> tag for each source provided. Rails looks in <tt>public/stylesheets</tt> for these files by default, but you can specify a full path relative to the document root, or a URL, if you prefer. For example, to include <tt>public/stylesheets/main.cs</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #FF0000"><%= stylesheet_link_tag "main" %></span></tt></pre></div></div>
<div class="paragraph"><p>To include <tt>public/stylesheets/main.css</tt> and <tt>public/stylesheets/columns.css</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #FF0000"><%= stylesheet_link_tag "main", "columns" %></span></tt></pre></div></div>
<div class="paragraph"><p>To include <tt>public/stylesheets/main.css</tt> and <tt>public/photos/columns.css</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #FF0000"><%= stylesheet_link_tag "main", "/photos/columns" %></span></tt></pre></div></div>
<div class="paragraph"><p>To include <tt>http://example.com/main.cs</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #FF0000"><%= stylesheet_link_tag "http://example.com/main.cs" %></span></tt></pre></div></div>
<div class="paragraph"><p>By default, <tt>stylesheet_link_tag</tt> creates links with <tt>media="screen" rel="stylesheet" type="text/css"</tt>. You can override any of these defaults by specifying an appropriate option (:media, :rel, or :type):</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #FF0000"><%= stylesheet_link_tag "main_print", media =></span> <span style="color: #FF0000">"print"</span> <span style="color: #990000">%></span></tt></pre></div></div>
<div class="paragraph"><p>The <tt>all</tt> option links every CSS file in <tt>public/stylesheets</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #FF0000"><%= stylesheet_link_tag :all %></span></tt></pre></div></div>
<div class="paragraph"><p>You can supply the <tt>:recursive</tt> option to link files in subfolders of <tt>public/stylesheets</tt> as well:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #FF0000"><%= stylesheet_link_tag :all, :recursive =></span> <span style="font-weight: bold"><span style="color: #0000FF">true</span></span> <span style="color: #990000">%></span></tt></pre></div></div>
<div class="paragraph"><p>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 <tt>:cache => true</tt> in your <tt>stylesheet_link_tag</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #FF0000"><%= stylesheet_link_tag "main", "columns", :cache =></span> <span style="font-weight: bold"><span style="color: #0000FF">true</span></span> <span style="color: #990000">%></span></tt></pre></div></div>
<div class="paragraph"><p>By default, the combined file will be delivered as <tt>stylesheets/all.css</tt>. You can specify a location for the cached asset file instead:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -898,21 +898,21 @@ http://www.gnu.org/software/src-highlite --> <h4 id="_linking_to_images_with_tt_image_tag_tt">3.1.4. Linking to Images with <tt>image_tag</tt></h4>
<div class="paragraph"><p>The <tt>image_tag</tt> helper builds an HTML <tt><image></tt> tag to the specified file. By default, files are loaded from <tt>public/images</tt>. If you don’t specify an extension, .png is assumed by default:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #FF0000"><%= image_tag "header" %></span></tt></pre></div></div>
<div class="paragraph"><p>You can supply a path to the image if you like:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #FF0000"><%= image_tag "icons/delete.gif" %></span></tt></pre></div></div>
<div class="paragraph"><p>You can supply a hash of additional HTML options:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -937,7 +937,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_understanding_tt_yield_tt">3.2. Understanding <tt>yield</tt></h3>
<div class="paragraph"><p>Within the context of a layout, <tt>yield</tt> identifies a section where content from the view should be inserted. The simplest way to use this is to have a single <tt>yield</tt>, into which the entire contents of the view currently being rendered is inserted:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -950,7 +950,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF"></html></span></span></tt></pre></div></div>
<div class="paragraph"><p>You can also create a layout with multiple yielding regions:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -966,7 +966,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_using_tt_content_for_tt">3.3. Using <tt>content_for</tt></h3>
<div class="paragraph"><p>The <tt>content_for</tt> method allows you to insert content into a <tt>yield</tt> block in your layout. You only use <tt>content_for</tt> to insert content in named yields. For example, this view would work with the layout that you just saw:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -977,7 +977,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF"><p></span></span>Hello, Rails!<span style="font-weight: bold"><span style="color: #0000FF"></p></span></span></tt></pre></div></div>
<div class="paragraph"><p>The result of rendering this page into the supplied layout would be this HTML:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -995,14 +995,14 @@ http://www.gnu.org/software/src-highlite --> <h4 id="_naming_partials">3.4.1. Naming Partials</h4>
<div class="paragraph"><p>To render a partial as part of a view, you use the <tt>render</tt> method within the view, and include the <tt>:partial</tt> option:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #FF0000"><%= render :partial =></span> <span style="color: #FF0000">"menu"</span> <span style="color: #990000">%></span></tt></pre></div></div>
<div class="paragraph"><p>This will render a file named <tt>_menu.html.erb</tt> 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:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1011,7 +1011,7 @@ http://www.gnu.org/software/src-highlite --> <h4 id="_using_partials_to_simplify_views">3.4.2. Using Partials to Simplify Views</h4>
<div class="paragraph"><p>One way to use partials is to treat them as the equivalent of subroutines: as a way to move details out of a view so that you can grasp what’s going on more easily. For example, you might have a view that looked like this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1035,7 +1035,7 @@ http://www.gnu.org/software/src-highlite --> <h4 id="_partial_layouts">3.4.3. Partial Layouts</h4>
<div class="paragraph"><p>A partial can use its own layout file, just as a view can use a layout. For example, you might call a partial like this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1045,7 +1045,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>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:</p></div>
<div class="paragraph"><p><tt>new.html.erb</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1054,7 +1054,7 @@ http://www.gnu.org/software/src-highlite --> <%= render :partial => "form", :locals => { :button_label => "Create zone", :zone => @zone } %></tt></pre></div></div>
<div class="paragraph"><p><tt>edit.html.erb</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1063,7 +1063,7 @@ http://www.gnu.org/software/src-highlite --> <%= render :partial => "form", :locals => { :button_label => "Update zone", :zone => @zone } %></tt></pre></div></div>
<div class="paragraph"><p><tt>_form.html.erb:</tt></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1079,7 +1079,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>Although the same partial will be rendered into both views, the label on the submit button is controlled by a local variable passed into the partial.</p></div>
<div class="paragraph"><p>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 <tt>:object</tt> option:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1095,7 +1095,7 @@ http://www.gnu.org/software/src-highlite --> </div>
<div class="paragraph"><p>If you have an instance of a model to render into a partial, you can use a shorthand syntax:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1105,7 +1105,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>Partials are very useful in rendering collections. When you pass a collection to a partial via the <tt>:collection</tt> option, the partial will be inserted once for each member in the collection:</p></div>
<div class="paragraph"><p><tt>index.html.erb</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1113,14 +1113,14 @@ http://www.gnu.org/software/src-highlite --> <%= render :partial => "product", :collection => @products %></tt></pre></div></div>
<div class="paragraph"><p><tt>_product.html.erb</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF"><p></span></span>Product Name: <%= product.name %><span style="font-weight: bold"><span style="color: #0000FF"></p></span></span></tt></pre></div></div>
<div class="paragraph"><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 <tt>_product, and within the +_product</tt> partial, you can refer to <tt>product</tt> to get the instance that is being rendered. To use a custom local variable name within the partial, specify the <tt>:as</tt> option in the call to the partial:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1136,7 +1136,7 @@ http://www.gnu.org/software/src-highlite --> </div>
<div class="paragraph"><p>You can also specify a second partial to be rendered between instances of the main partial by using the <tt>:spacer_template</tt> option:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1145,7 +1145,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>There’s also a shorthand syntax available for rendering collections. For example, if <tt>@products</tt> is a collection of products, you can render the collection this way:</p></div>
<div class="paragraph"><p><tt>index.html.erb</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1153,7 +1153,7 @@ http://www.gnu.org/software/src-highlite --> <%= render :partial => @products %></tt></pre></div></div>
<div class="paragraph"><p><tt>_product.html.erb</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1161,7 +1161,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>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:</p></div>
<div class="paragraph"><p><tt>index.html.erb</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1169,14 +1169,14 @@ http://www.gnu.org/software/src-highlite --> <%= render :partial => [customer1, employee1, customer2, employee2] %></tt></pre></div></div>
<div class="paragraph"><p><tt>_customer.html.erb</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF"><p></span></span>Name: <%= customer.name %><span style="font-weight: bold"><span style="color: #0000FF"></p></span></span></tt></pre></div></div>
<div class="paragraph"><p><tt>_employee.html.erb</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1187,7 +1187,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>Suppose you have the follow ApplicationController layout:</p></div>
<div class="paragraph"><p><tt>app/views/layouts/application.erb</tt></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1206,7 +1206,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>On pages generated by NewsController, you want to hide the top menu and add a right menu:</p></div>
<div class="paragraph"><p><tt>app/views/layouts/news.erb</tt></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
diff --git a/railties/doc/guides/html/migrations.html b/railties/doc/guides/html/migrations.html index 0a8b85c77c..47fddb4caf 100644 --- a/railties/doc/guides/html/migrations.html +++ b/railties/doc/guides/html/migrations.html @@ -142,7 +142,7 @@ How they relate to <tt>schema.rb</tt> <div class="sectionbody">
<div class="paragraph"><p>Before I dive into the details of a migration, here are a few examples of the sorts of things you can do:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -163,7 +163,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>This migration adds a table called <tt>products</tt> with a string column called <tt>name</tt> and a text column called <tt>description</tt>. A primary key column called <tt>id</tt> will also be added, however since this is the default we do not need to ask for this. The timestamp columns <tt>created_at</tt> and <tt>updated_at</tt> which Active Record populates automatically will also be added. Reversing this migration is as simple as dropping the table.</p></div>
<div class="paragraph"><p>Migrations are not limited to changing the schema. You can also use them to fix bad data in the database or populate new fields:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -258,7 +258,7 @@ write code to set the value of that column for existing records (if necessary us <div class="paragraph"><p>The model and scaffold generators will create migrations appropriate for adding a new model. This migration will already contain instructions for creating the relevant table. If you tell Rails what columns you want then statements for adding those will also be created. For example, running</p></div>
<div class="paragraph"><p><tt>ruby script/generate model Product name:string description:text</tt> will create a migration that looks like this</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -283,7 +283,7 @@ are automatically populated by Active Record) will be added for you.</p></div> <div class="paragraph"><p><tt>ruby script/generate migration AddPartNumberToProducts</tt></p></div>
<div class="paragraph"><p>This will create an empty but appropriately named migration:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -299,7 +299,7 @@ the appropriate add and remove column statements will be created.</p></div> <div class="paragraph"><p><tt>ruby script/generate migration AddPartNumberToProducts part_number:string</tt></p></div>
<div class="paragraph"><p>will generate</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -316,7 +316,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p><tt>ruby script/generate migration RemovePartNumberFromProducts part_number:string</tt></p></div>
<div class="paragraph"><p>generates</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -333,7 +333,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p><tt>ruby script/generate migration AddDetailsToProducts part_number:string price:decimal</tt></p></div>
<div class="paragraph"><p>generates</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -356,7 +356,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_creating_a_table">3.1. Creating a table</h3>
<div class="paragraph"><p><tt>create_table</tt> will be one of your workhorses. A typical use would be</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -366,7 +366,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>which creates a <tt>products</tt> table with a column called <tt>name</tt> (and as discussed below, an implicit <tt>id</tt> column).</p></div>
<div class="paragraph"><p>The object yielded to the block allows you create columns on the table. There are two ways of doing this. The first looks like</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -375,7 +375,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>the second form, the so called "sexy" migrations, drops the somewhat redundant column method. Instead, the <tt>string</tt>, <tt>integer</tt> etc. methods create a column of that type. Subsequent parameters are identical.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -384,7 +384,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>By default <tt>create_table</tt> will create a primary key called <tt>id</tt>. You can change the name of the primary key with the <tt>:primary_key</tt> 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 <tt>:id => false</tt>. If you need to pass database specific options you can place an sql fragment in the <tt>:options</tt> option. For example</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -396,7 +396,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>These will be mapped onto an appropriate underlying database type, for example with MySQL <tt>:string</tt> is mapped to <tt>VARCHAR(255)</tt>. You can create columns of
types not supported by Active Record when using the non sexy syntax, for example</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -407,7 +407,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_changing_tables">3.2. Changing tables</h3>
<div class="paragraph"><p><tt>create_table</tt>'s close cousin is <tt>change_table</tt>. Used for changing existing tables, it is used in a similar fashion to <tt>create_table</tt> but the object yielded to the block knows more tricks. For example</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -419,7 +419,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>removes the <tt>description</tt> column, creates a <tt>part_number</tt> column and adds an index on it. Finally it renames the <tt>upccode</tt> column. This is the same as doing</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -432,7 +432,7 @@ rename_column <span style="color: #990000">:</span>products<span style="color: # <h3 id="_special_helpers">3.3. Special helpers</h3>
<div class="paragraph"><p>Active Record provides some shortcuts for common functionality. It is for example very common to add both the <tt>created_at</tt> and <tt>updated_at</tt> columns and so there is a method that does exactly that:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -441,7 +441,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>will create a new products table with those two columns whereas</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -451,7 +451,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>adds those columns to an existing table.</p></div>
<div class="paragraph"><p>The other helper is called <tt>references</tt> (also available as <tt>belongs_to</tt>). In its simplest form it just adds some readability</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -460,7 +460,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>will create a <tt>category_id</tt> column of the appropriate type. Note that you pass the model name, not the column name. Active Record adds the <tt>_id</tt> for you. If you have polymorphic belongs_to associations then <tt>references</tt> will add both of the columns required:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -481,7 +481,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_writing_your_down_method">3.4. Writing your down method</h3>
<div class="paragraph"><p>The <tt>down</tt> method of your migration should revert the transformations done by the <tt>up</tt> method. In other words the database should be unchanged if you do an <tt>up</tt> followed by a <tt>down</tt>. For example if you create a table in the up you should drop it in the <tt>down</tt> method. It is wise to do things in precisely the reverse order to in the <tt>up</tt> method. For example</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -586,7 +586,7 @@ A migration creating a table and adding an index might produce output like this< </ul></div>
<div class="paragraph"><p>For example, this migration</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -631,7 +631,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>Consider for example a migration that uses the Product model to update a row in the corresponding table. Alice later updates the Product model, adding a new column and a validation on it. Bob comes back from holiday, updates the source and runs outstanding migrations with <tt>rake db:migrate</tt>, including the one that used the Product model. When the migration runs the source is up to date and so the Product model has the validation added by Alice. The database however is still old and so does not have that column and an error ensues because that validation is on a column that does not yet exist.</p></div>
<div class="paragraph"><p>Frequently I just want to update rows in the database without writing out the SQL by hand: I’m not using anything specific to the model. One pattern for this is to define a copy of the model inside the migration itself, for example:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -651,7 +651,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_dealing_with_changing_models">5.1. Dealing with changing models</h3>
<div class="paragraph"><p>For performance reasons information about the columns a model has is cached. For example if you add a column to a table and then try and use the corresponding model to insert a new row it may try and use the old column information. You can force Active Record to re-read the column information with the <tt>reset_column_information</tt> method, for example</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -681,7 +681,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>There are two ways to dump the schema. This is set in <tt>config/environment.rb</tt> by the <tt>config.active_record.schema_format</tt> setting, which may be either <tt>:sql</tt> or <tt>:ruby</tt>.</p></div>
<div class="paragraph"><p>If <tt>:ruby</tt> is selected then the schema is stored in <tt>db/schema.rb</tt>. If you look at this file you’ll find that it looks an awful lot like one very big migration:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
diff --git a/railties/doc/guides/html/performance_testing.html b/railties/doc/guides/html/performance_testing.html index 858076008d..95bfd5f980 100644 --- a/railties/doc/guides/html/performance_testing.html +++ b/railties/doc/guides/html/performance_testing.html @@ -138,7 +138,7 @@ Learn about various tools facilitating benchmarking and profiling <div class="paragraph"><p>Rails performance tests are a special type of integration tests, designed for 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.</p></div>
<div class="paragraph"><p>In a freshly generated Rails application, <tt>test/performance/browsing_test.rb</tt> contains an example of a performance test:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -155,14 +155,14 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_generating_performance_tests">1.1. Generating performance tests</h3>
<div class="paragraph"><p>Rails provides a generator called <tt>performance_test</tt> for creating new performance tests:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>script/generate performance_test homepage</tt></pre></div></div>
<div class="paragraph"><p>This generates <tt>homepage_test.rb</tt> in the <tt>test/performance</tt> directory:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -178,7 +178,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_examples">1.2. Examples</h3>
<div class="paragraph"><p>Let’s assume your application has the following controller and model:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -220,7 +220,7 @@ map<span style="color: #990000">.</span>resources <span style="color: #990000">: <div class="paragraph"><p>Because performance tests are a special kind of integration test, you can use the <tt>get</tt> and <tt>post</tt> methods in them.</p></div>
<div class="paragraph"><p>Here’s the performance test for <tt>HomeController#dashboard</tt> and <tt>PostsController#create</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -246,7 +246,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>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.</p></div>
<div class="paragraph"><p>Performance test for <tt>Post</tt> model:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -269,7 +269,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>Benchmarking helps find out how fast each performance test runs. Each test case is run <tt>4 times</tt> in benchmarking mode.</p></div>
<div class="paragraph"><p>To run performance tests in benchmarking mode:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -278,7 +278,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>Profiling helps you see the details of a performance test and provide an in-depth picture of the slow and memory hungry parts. Each test case is run <tt>1 time</tt> in profiling mode.</p></div>
<div class="paragraph"><p>To run performance tests in profiling mode:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -310,7 +310,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_command_line">Command line</h5>
<div class="paragraph"><p>This is the primary form of output in benchmarking mode. Example :</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -352,7 +352,7 @@ BrowsingTest#test_homepage_wall_time.csv <div class="paragraph"><p>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.</p></div>
<div class="paragraph"><p>Sample output of <tt>BrowsingTest#test_homepage_wall_time.csv</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -372,7 +372,7 @@ http://www.gnu.org/software/src-highlite --> <h5 id="_command_line_2">Command line</h5>
<div class="paragraph"><p>This is a very basic form of output in profiling mode:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -399,7 +399,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_performance_test_environment">1.7. Performance Test Environment</h3>
<div class="paragraph"><p>Performance tests are run in the <tt>development</tt> environment. But running performance tests will set the following configuration parameters:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -414,7 +414,7 @@ Rails<span style="color: #990000">.</span>logger<span style="color: #990000">.</ <div class="paragraph"><p>Compile Ruby and apply this <a href="http://rubyforge.org/tracker/download.php/1814/7062/17676/3291/ruby186gc.patch">GC Patch</a>:</p></div>
<h4 id="_download_and_extract">1.8.2. Download and Extract</h4>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -424,7 +424,7 @@ http://www.gnu.org/software/src-highlite --> <span style="color: #990000">[</span>lifo@null <span style="color: #990000">~]</span>$ cd <span style="color: #990000"><</span>ruby-version<span style="color: #990000">></span></tt></pre></div></div>
<h4 id="_apply_the_patch">1.8.3. Apply the patch</h4>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -432,7 +432,7 @@ http://www.gnu.org/software/src-highlite --> <h4 id="_configure_and_install">1.8.4. Configure and Install</h4>
<div class="paragraph"><p>The following will install ruby in your home directory’s <tt>/rubygc</tt> directory. Make sure to replace <tt><homedir></tt> with a full patch to your actual home directory.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -480,7 +480,7 @@ alias gcrails='~/rubygc/bin/rails'</tt></pre> </ul></div>
<div class="paragraph"><p>If installing <tt>mysql</tt> fails, you can try to install it manually:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -495,21 +495,21 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p><tt>benchmarker</tt> is a wrapper around Ruby’s <a href="http://ruby-doc.org/core/classes/Benchmark.html">Benchmark</a> module.</p></div>
<div class="paragraph"><p>Usage:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>$ script/performance/benchmarker <span style="color: #990000">[</span><span style="font-weight: bold"><span style="color: #0000FF">times</span></span><span style="color: #990000">]</span> <span style="color: #FF0000">'Person.expensive_way'</span> <span style="color: #FF0000">'Person.another_expensive_way'</span> <span style="color: #990000">...</span></tt></pre></div></div>
<div class="paragraph"><p>Examples:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>$ script/performance/benchmarker <span style="color: #993399">10</span> <span style="color: #FF0000">'Item.all'</span> <span style="color: #FF0000">'CouchItem.all'</span></tt></pre></div></div>
<div class="paragraph"><p>If the <tt>[times]</tt> argument is omitted, supplied methods are run just once:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -518,21 +518,21 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p><tt>profiler</tt> is a wrapper around <a href="http://ruby-prof.rubyforge.org/">ruby-prof</a> gem.</p></div>
<div class="paragraph"><p>Usage:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>$ script/performance/profiler <span style="color: #FF0000">'Person.expensive_method(10)'</span> <span style="color: #990000">[</span><span style="font-weight: bold"><span style="color: #0000FF">times</span></span><span style="color: #990000">]</span> <span style="color: #990000">[</span>flat<span style="color: #990000">|</span>graph<span style="color: #990000">|</span>graph_html<span style="color: #990000">]</span></tt></pre></div></div>
<div class="paragraph"><p>Examples:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>$ script/performance/profiler <span style="color: #FF0000">'Item.all'</span></tt></pre></div></div>
<div class="paragraph"><p>This will profile <tt>Item.all</tt> in <tt>RubyProf::WALL_TIME</tt> measure mode. By default, it prints flat output to the shell.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -540,7 +540,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>This will profile <tt>10.times { Item.all }</tt> with <tt>RubyProf::WALL_TIME</tt> measure mode and print graph output to the shell.</p></div>
<div class="paragraph"><p>If you want to store the output in a file:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -551,7 +551,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>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 <tt>benchmark()</tt> in all the three components.</p></div>
<h3 id="_model">3.1. Model</h3>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -562,7 +562,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>This benchmarks the code enclosed in the <tt>Project.benchmark("Creating project") do..end</tt> block and prints the result to the log file:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -579,7 +579,7 @@ http://www.gnu.org/software/src-highlite --> </tr></table>
</div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -592,7 +592,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_view">3.3. View</h3>
<div class="paragraph"><p>And in <a href="http://api.rubyonrails.com/classes/ActionController/Benchmarking/ClassMethods.html#M000715">views</a>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -604,7 +604,7 @@ http://www.gnu.org/software/src-highlite --> <div class="sectionbody">
<div class="paragraph"><p>Rails log files contain very useful information about the time taken to serve each request. Here’s a typical log file entry:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -614,7 +614,7 @@ Rendering items<span style="color: #990000">/</span>index Completed <span style="font-weight: bold"><span style="color: #0000FF">in</span></span> 5ms <span style="color: #990000">(</span>View<span style="color: #990000">:</span> <span style="color: #993399">2</span><span style="color: #990000">,</span> DB<span style="color: #990000">:</span> <span style="color: #993399">0</span><span style="color: #990000">)</span> <span style="color: #990000">|</span> <span style="color: #993399">200</span> OK <span style="color: #990000">[</span>http<span style="color: #990000">:</span><span style="color: #FF6600">//0.0.0.0/</span>items<span style="color: #990000">]</span></tt></pre></div></div>
<div class="paragraph"><p>For this section, we’re only interested in the last line:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
diff --git a/railties/doc/guides/html/rails_on_rack.html b/railties/doc/guides/html/rails_on_rack.html index eb1ff6ef1b..411411cb41 100644 --- a/railties/doc/guides/html/rails_on_rack.html +++ b/railties/doc/guides/html/rails_on_rack.html @@ -165,7 +165,7 @@ Understand the best practices for developing a middleware aimed at Rails applica <div class="paragraph"><p><tt>script/server</tt> does the basic job of creating a <tt>Rack::Builder</tt> object and starting the webserver. This is Rails equivalent of Rack’s <tt>rackup</tt> script.</p></div>
<div class="paragraph"><p>Here’s how <tt>script/server</tt> creates an instance of <tt>Rack::Builder</tt></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -208,7 +208,7 @@ cellspacing="0" cellpadding="4"> <h3 id="_rackup">2.3. rackup</h3>
<div class="paragraph"><p>To use <tt>rackup</tt> instead of Rails' <tt>script/server</tt>, you can put the following inside <tt>config.ru</tt> of your Rails application’s root directory:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -220,14 +220,14 @@ use Rails<span style="color: #990000">::</span>Rack<span style="color: #990000"> run ActionController<span style="color: #990000">::</span>Dispatcher<span style="color: #990000">.</span>new</tt></pre></div></div>
<div class="paragraph"><p>And start the server:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #990000">[</span>lifo@null application<span style="color: #990000">]</span>$ rackup</tt></pre></div></div>
<div class="paragraph"><p>To find out more about different <tt>rackup</tt> options:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -248,14 +248,14 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_inspecting_middleware_stack">3.1. Inspecting Middleware Stack</h3>
<div class="paragraph"><p>Rails has a handy rake task for inspecting the middleware stack in use:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>$ rake middleware</tt></pre></div></div>
<div class="paragraph"><p>For a freshly generated Rails application, this will produce:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -270,7 +270,7 @@ run ActionController<span style="color: #990000">::</span>Dispatcher<span style= <div class="paragraph"><p>Rails provides a very simple configuration interface for adding generic Rack middlewares to a Rails applications.</p></div>
<div class="paragraph"><p>Here’s how you can add middlewares via <tt>environment.rb</tt></p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -279,7 +279,7 @@ http://www.gnu.org/software/src-highlite --> config<span style="color: #990000">.</span>middleware<span style="color: #990000">.</span>use Rack<span style="color: #990000">::</span>BounceFavicon</tt></pre></div></div>
<h3 id="_internal_middleware_stack">3.3. Internal Middleware Stack</h3>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -353,7 +353,7 @@ cellspacing="0" cellpadding="4"> <div class="paragraph"><p>VERIFY THIS WORKS. Just a code dump at the moment.</p></div>
<div class="paragraph"><p>Put the following in an initializer.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -380,14 +380,14 @@ or something like that</p></div> <h3 id="_generating_a_metal_application">4.1. Generating a Metal Application</h3>
<div class="paragraph"><p>Rails provides a generator called <tt>performance_test</tt> for creating new performance tests:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>script/generate metal poller</tt></pre></div></div>
<div class="paragraph"><p>This generates <tt>poller.rb</tt> in the <tt>app/metal</tt> directory:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -408,7 +408,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>All Metal Applications are executed by <tt>Rails::Rack::Metal</tt> middleware, which is a part of the <tt>ActionController::MiddlewareStack</tt> chain.</p></div>
<div class="paragraph"><p>Here’s the primary method responsible for running the Metal applications:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
diff --git a/railties/doc/guides/html/routing_outside_in.html b/railties/doc/guides/html/routing_outside_in.html index 22477e18e7..03ad1c1eca 100644 --- a/railties/doc/guides/html/routing_outside_in.html +++ b/railties/doc/guides/html/routing_outside_in.html @@ -193,7 +193,7 @@ Identify how a route will map to a controller and action <h3 id="_generating_urls_from_code">1.2. Generating URLs from Code</h3>
<div class="paragraph"><p>Routing also works in reverse. If your application contains this code:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -246,7 +246,7 @@ Default Routes <h3 id="_restful_routes">2.2. RESTful Routes</h3>
<div class="paragraph"><p>RESTful routes take advantage of the built-in REST orientation of Rails to wrap up a lot of routing information in a single declaration. A RESTful route looks like this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -254,7 +254,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_named_routes">2.3. Named Routes</h3>
<div class="paragraph"><p>Named routes give you very readable links in your code, as well as handling incoming requests. Here’s a typical named route:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -262,7 +262,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_nested_routes">2.4. Nested Routes</h3>
<div class="paragraph"><p>Nested routes let you declare that one resource is contained within another resource. You’ll see later on how this translates to URLs and paths in your code. For example, if your application includes parts, each of which belongs to an assembly, you might have this nested route declaration:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -272,7 +272,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_regular_routes">2.5. Regular Routes</h3>
<div class="paragraph"><p>In many applications, you’ll also see non-RESTful routing, which explicitly connects the parts of a URL to a particular action. For example,</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -280,7 +280,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_default_routes">2.6. Default Routes</h3>
<div class="paragraph"><p>The default routes are a safety net that catch otherwise-unrouted requests. Many Rails applications will contain this pair of default routes:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -311,7 +311,7 @@ Transferring representations of the state of that resource between system compon <h3 id="_crud_verbs_and_actions">3.2. CRUD, Verbs, and Actions</h3>
<div class="paragraph"><p>In Rails, a RESTful route provides a mapping between HTTP verbs, controller actions, and (implicitly) CRUD operations in a database. A single entry in the routing file, such as</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -432,7 +432,7 @@ cellspacing="0" cellpadding="4"> </div>
<div class="paragraph"><p>In each case, the <tt>_url</tt> helper generates a string containing the entire URL that the application will understand, while the <tt>_path</tt> helper generates a string containing the relative path from the root of the application. For example:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -441,14 +441,14 @@ photos_path <span style="font-style: italic"><span style="color: #9A1900"># => <h3 id="_defining_multiple_resources_at_the_same_time">3.4. Defining Multiple Resources at the Same Time</h3>
<div class="paragraph"><p>If you need to create routes for more than one RESTful resource, you can save a bit of typing by defining them all with a single call to <tt>map.resources</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>map<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>photos<span style="color: #990000">,</span> <span style="color: #990000">:</span>books<span style="color: #990000">,</span> <span style="color: #990000">:</span>videos</tt></pre></div></div>
<div class="paragraph"><p>This has exactly the same effect as</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -458,7 +458,7 @@ map<span style="color: #990000">.</span>resources <span style="color: #990000">: <h3 id="_singular_resources">3.5. Singular Resources</h3>
<div class="paragraph"><p>You can also apply RESTful routing to singleton resources within your application. In this case, you use <tt>map.resource</tt> instead of <tt>map.resources</tt> and the route generation is slightly different. For example, a routing entry of</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -613,7 +613,7 @@ cellspacing="0" cellpadding="4"> <h4 id="_using_controller">3.6.1. Using :controller</h4>
<div class="paragraph"><p>The <tt>:controller</tt> option lets you use a controller name that is different from the public-facing resource name. For example, this routing entry:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -702,7 +702,7 @@ cellspacing="0" cellpadding="4"> <h3 id="_controller_namespaces_and_routing">3.7. Controller Namespaces and Routing</h3>
<div class="paragraph"><p>Rails allows you to group your controllers into namespaces by saving them in folders underneath <tt>app/controllers</tt>. The <tt>:controller</tt> option provides a convenient way to use these routes. For example, you might have a resource whose controller is purely for admin users in the <tt>admin</tt> folder:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -718,14 +718,14 @@ http://www.gnu.org/software/src-highlite --> </div>
<div class="paragraph"><p>You can also specify a controller namespace with the <tt>:namespace</tt> option instead of a path:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>map<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>adminphotos<span style="color: #990000">,</span> <span style="color: #990000">:</span>namespace <span style="color: #990000">=></span> <span style="color: #FF0000">"admin"</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>controller <span style="color: #990000">=></span> <span style="color: #FF0000">"photos"</span></tt></pre></div></div>
<div class="paragraph"><p>This can be especially useful when combined with <tt>with_options</tt> to map multiple namespaced routes together:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -736,7 +736,7 @@ http://www.gnu.org/software/src-highlite --> <h4 id="_using_singular">3.7.1. Using :singular</h4>
<div class="paragraph"><p>If for some reason Rails isn’t doing what you want in converting the plural resource name to a singular name in member routes, you can override its judgment with the <tt>:singular</tt> option:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -752,7 +752,7 @@ http://www.gnu.org/software/src-highlite --> <h4 id="_using_requirements">3.7.2. Using :requirements</h4>
<div class="paragraph"><p>You an use the <tt>:requirements</tt> option in a RESTful route to impose a format on the implied <tt>:id</tt> parameter in the singular routes. For example:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -763,7 +763,7 @@ http://www.gnu.org/software/src-highlite --> <h4 id="_using_as">3.7.4. Using :as</h4>
<div class="paragraph"><p>The <tt>:as</tt> option lets you override the normal naming for the actual generated paths. For example:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -852,7 +852,7 @@ cellspacing="0" cellpadding="4"> <h4 id="_using_path_names">3.7.5. Using :path_names</h4>
<div class="paragraph"><p>The <tt>:path_names</tt> option lets you override the automatically-generated "new" and "edit" segments in URLs:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -880,7 +880,7 @@ http://www.gnu.org/software/src-highlite --> </tr></table>
</div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -888,7 +888,7 @@ http://www.gnu.org/software/src-highlite --> <h4 id="_using_path_prefix">3.7.6. Using :path_prefix</h4>
<div class="paragraph"><p>The <tt>:path_prefix</tt> option lets you add additional parameters that will be prefixed to the recognized paths. For example, suppose each photo in your application belongs to a particular photographer. In that case, you might declare this route:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -918,7 +918,7 @@ http://www.gnu.org/software/src-highlite --> <h4 id="_using_name_prefix">3.7.7. Using :name_prefix</h4>
<div class="paragraph"><p>You can use the :name_prefix option to avoid collisions between routes. This is most useful when you have two resources with the same name that use <tt>:path_prefix</tt> to map differently. For example:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -936,7 +936,7 @@ map<span style="color: #990000">.</span>resources <span style="color: #990000">: <h4 id="_using_only_and_except">3.7.8. Using :only and :except</h4>
<div class="paragraph"><p>By default, Rails creates routes for all seven of the default actions (index, show, new, create, edit, update, and destroy) for every RESTful route in your application. You can use the <tt>:only</tt> and <tt>:except</tt> options to fine-tune this behavior. The <tt>:only</tt> option specifies that only certain routes should be generated:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -944,7 +944,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>With this declaration, a <tt>GET</tt> request to <tt>/photos</tt> would succeed, but a <tt>POST</tt> request to <tt>/photos</tt> (which would ordinarily be routed to the create action) will fail.</p></div>
<div class="paragraph"><p>The <tt>:except</tt> option specifies a route or list of routes that should <em>not</em> be generated:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -962,7 +962,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_nested_resources">3.8. Nested Resources</h3>
<div class="paragraph"><p>It’s common to have resources that are logically children of other resources. For example, suppose your application includes these models:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -975,7 +975,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>Each ad is logically subservient to one magazine. Nested routes allow you to capture this relationship in your routing. In this case, you might include this route declaration:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1059,7 +1059,7 @@ cellspacing="0" cellpadding="4"> <h4 id="_using_name_prefix_2">3.8.1. Using :name_prefix</h4>
<div class="paragraph"><p>The <tt>:name_prefix</tt> option overrides the automatically-generated prefix in nested route helpers. For example,</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1068,7 +1068,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>This will create routing helpers such as <tt>periodical_ads_url</tt> and <tt>periodical_edit_ad_path</tt>. You can even use <tt>:name_prefix</tt> to suppress the prefix entirely:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1077,7 +1077,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>This will create routing helpers such as <tt>ads_url</tt> and <tt>edit_ad_path</tt>. Note that calling these will still require supplying an article id:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1086,14 +1086,14 @@ edit_ad_path<span style="color: #990000">(</span><span style="color: #009900">@m <h4 id="_using_has_one_and_has_many">3.8.2. Using :has_one and :has_many</h4>
<div class="paragraph"><p>The <tt>:has_one</tt> and <tt>:has_many</tt> options provide a succinct notation for simple nested routes. Use <tt>:has_one</tt> to nest a singleton resource, or <tt>:has_many</tt> to nest a plural resource:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>map<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>photos<span style="color: #990000">,</span> <span style="color: #990000">:</span>has_one <span style="color: #990000">=></span> <span style="color: #990000">:</span>photographer<span style="color: #990000">,</span> <span style="color: #990000">:</span>has_many <span style="color: #990000">=></span> <span style="color: #990000">[:</span>publications<span style="color: #990000">,</span> <span style="color: #990000">:</span>versions<span style="color: #990000">]</span></tt></pre></div></div>
<div class="paragraph"><p>This has the same effect as this set of declarations:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1105,7 +1105,7 @@ http://www.gnu.org/software/src-highlite --> <h4 id="_limits_to_nesting">3.8.3. Limits to Nesting</h4>
<div class="paragraph"><p>You can nest resources within other nested resources if you like. For example:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1124,7 +1124,7 @@ http://www.gnu.org/software/src-highlite --> <h4 id="_shallow_nesting">3.8.4. Shallow Nesting</h4>
<div class="paragraph"><p>The <tt>:shallow</tt> option provides an elegant solution to the difficulties of deeply-nested routes. If you specify this option at any level of routing, then paths for nested resources which reference a specific member (that is, those with an <tt>:id</tt> parameter) will not use the parent path prefix or name prefix. To see what this means, consider this set of routes:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1144,7 +1144,7 @@ http://www.gnu.org/software/src-highlite --> </div></div>
<div class="paragraph"><p>With shallow nesting, you need only supply enough information to uniquely identify the resource that you want to work with. If you like, you can combine shallow nesting with the <tt>:has_one</tt> and <tt>:has_many</tt> options:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1152,7 +1152,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_route_generation_from_arrays">3.9. Route Generation from Arrays</h3>
<div class="paragraph"><p>In addition to using the generated routing helpers, Rails can also generate RESTful routes from an array of parameters. For example, suppose you have a set of routes generated with these entries in routes.rb:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1161,14 +1161,14 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>Rails will generate helpers such as magazine_ad_path that you can use in building links:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #FF0000"><%= link_to "Ad details", magazine_ad_path(@magazine, @ad) %></span></tt></pre></div></div>
<div class="paragraph"><p>Another way to refer to the same route is with an array of objects:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1177,7 +1177,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_namespaced_resources">3.10. Namespaced Resources</h3>
<div class="paragraph"><p>It’s possible to do some quite complex things by combining <tt>:path_prefix</tt> and <tt>:name_prefix</tt>. For example, you can use the combination of these two options to move administrative resources to their own folder in your application:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1186,7 +1186,7 @@ map<span style="color: #990000">.</span>resources <span style="color: #990000">: map<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>ratings<span style="color: #990000">,</span> <span style="color: #990000">:</span>name_prefix <span style="color: #990000">=></span> <span style="color: #FF0000">'admin_photo_'</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>path_prefix <span style="color: #990000">=></span> <span style="color: #FF0000">'admin/photos/:photo_id'</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>controller <span style="color: #990000">=></span> <span style="color: #FF0000">'admin/photo_ratings'</span></tt></pre></div></div>
<div class="paragraph"><p>The good news is that if you find yourself using this level of complexity, you can stop. Rails supports <em>namespaced resources</em> to make placing resources in their own folder a snap. Here’s the namespaced version of those same three routes:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1200,7 +1200,7 @@ http://www.gnu.org/software/src-highlite --> <h4 id="_adding_member_routes">3.11.1. Adding Member Routes</h4>
<div class="paragraph"><p>To add a member route, use the <tt>:member</tt> option:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1208,7 +1208,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>This will enable Rails to recognize URLs such as <tt>/photos/1/preview</tt> using the GET HTTP verb, and route them to the preview action of the Photos controller. It will also create a <tt>preview_photo</tt> route helper.</p></div>
<div class="paragraph"><p>Within the hash of member routes, each route name specifies the HTTP verb that it will recognize. You can use <tt>:get</tt>, <tt>:put</tt>, <tt>:post</tt>, <tt>:delete</tt>, or <tt>:any</tt> here. You can also specify an array of methods, if you need more than one but you don’t want to allow just anything:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1216,7 +1216,7 @@ http://www.gnu.org/software/src-highlite --> <h4 id="_adding_collection_routes">3.11.2. Adding Collection Routes</h4>
<div class="paragraph"><p>To add a collection route, use the <tt>:collection</tt> option:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1224,7 +1224,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>This will enable Rails to recognize URLs such as <tt>/photos/search</tt> using the GET HTTP verb, and route them to the search action of the Photos controller. It will also create a <tt>search_photos</tt> route helper.</p></div>
<div class="paragraph"><p>Just as with member routes, you can specify an array of methods for a collection route:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1232,7 +1232,7 @@ http://www.gnu.org/software/src-highlite --> <h4 id="_adding_new_routes">3.11.3. Adding New Routes</h4>
<div class="paragraph"><p>To add a new route (one that creates a new resource), use the <tt>:new</tt> option:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1247,7 +1247,7 @@ http://www.gnu.org/software/src-highlite --> </tr></table>
</div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1263,7 +1263,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_bound_parameters">4.1. Bound Parameters</h3>
<div class="paragraph"><p>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: <tt>:controller</tt> maps to the name of a controller in your application, and <tt>:action</tt> maps to the name of an action within that controller. For example, consider one of the default Rails routes:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1272,7 +1272,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_wildcard_components">4.2. Wildcard Components</h3>
<div class="paragraph"><p>You can set up as many wildcard symbols within a regular route as you like. Anything other than <tt>:controller</tt> or <tt>:action</tt> will be available to the matching action as part of the params hash. So, if you set up this route:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1281,7 +1281,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_static_text">4.3. Static Text</h3>
<div class="paragraph"><p>You can specify static text when creating a route. In this case, the static text is used only for matching the incoming requests:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1290,7 +1290,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_querystring_parameters">4.4. Querystring Parameters</h3>
<div class="paragraph"><p>Rails routing automatically picks up querystring parameters and makes them available in the <tt>params</tt> hash. For example, with this route:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1299,7 +1299,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_defining_defaults">4.5. Defining Defaults</h3>
<div class="paragraph"><p>You do not need to explicitly use the <tt>:controller</tt> and <tt>:action</tt> symbols within a route. You can supply defaults for these two parameters in a hash:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1307,7 +1307,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>With this route, an incoming URL of <tt>/photos/12</tt> would be dispatched to the <tt>show</tt> action within the <tt>Photos</tt> controller.</p></div>
<div class="paragraph"><p>You an also define other defaults in a route by supplying a hash for the <tt>:defaults</tt> option. This even applies to parameters that are not explicitly defined elsewhere in the route. For example:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1316,7 +1316,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_named_routes_2">4.6. Named Routes</h3>
<div class="paragraph"><p>Regular routes need not use the <tt>connect</tt> method. You can use any other name here to create a <em>named route</em>. For example,</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1325,7 +1325,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_route_requirements">4.7. Route Requirements</h3>
<div class="paragraph"><p>You can use the <tt>:requirements</tt> option to enforce a format for any parameter in a route:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1333,7 +1333,7 @@ http://www.gnu.org/software/src-highlite --> <span style="color: #990000">:</span>requirements <span style="color: #990000">=></span> <span style="color: #FF0000">{</span> <span style="color: #990000">:</span>id <span style="color: #990000">=></span> <span style="color: #FF6600">/[A-Z]\d{5}/</span> <span style="color: #FF0000">}</span></tt></pre></div></div>
<div class="paragraph"><p>This route would respond to URLs such as <tt>/photo/A12345</tt>. You can more succinctly express the same route this way:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1342,7 +1342,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_route_conditions">4.8. Route Conditions</h3>
<div class="paragraph"><p>Route conditions (introduced with the <tt>:conditions</tt> option) are designed to implement restrictions on routes. Currently, the only supported restriction is <tt>:method</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1352,7 +1352,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_route_globbing">4.9. Route Globbing</h3>
<div class="paragraph"><p>Route globbing is a way to specify that a particular parameter should be matched to all the remaining parts of a route. For example</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1361,7 +1361,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_route_options">4.10. Route Options</h3>
<div class="paragraph"><p>You can use <tt>:with_options</tt> to simplify defining groups of similar routes:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1377,14 +1377,14 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>There’s one more way in which routing can do different things depending on differences in the incoming HTTP request: by issuing a response that corresponds to what the request specifies that it will accept. In Rails routing, you can control this with the special <tt>:format</tt> parameter in the route.</p></div>
<div class="paragraph"><p>For instance, consider the second of the default routes in the boilerplate <tt>routes.rb</tt> file:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>map<span style="color: #990000">.</span>connect <span style="color: #FF0000">':controller/:action/:id.:format'</span></tt></pre></div></div>
<div class="paragraph"><p>This route matches requests such as <tt>/photo/edit/1.xml</tt> or <tt>/photo/show/2.rss</tt>. Within the appropriate action code, you can issue different responses depending on the requested format:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1397,7 +1397,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_recognized_mime_types">5.2. Recognized MIME types</h3>
<div class="paragraph"><p>By default, Rails recognizes <tt>html</tt>, <tt>text</tt>, <tt>json</tt>, <tt>csv</tt>, <tt>xml</tt>, <tt>rss</tt>, <tt>atom</tt>, and <tt>yaml</tt> as acceptable response types. If you need types beyond this, you can register them in your environment:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1407,7 +1407,7 @@ http://www.gnu.org/software/src-highlite --> <div class="sectionbody">
<div class="paragraph"><p>When you create a new Rails application, <tt>routes.rb</tt> is initialized with two default routes:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1429,7 +1429,7 @@ map<span style="color: #990000">.</span>connect <span style="color: #FF0000">':c <h3 id="_using_map_root">7.1. Using map.root</h3>
<div class="paragraph"><p>The preferred way to set up the empty route is with the <tt>map.root</tt> command:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1437,7 +1437,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>The use of the <tt>root</tt> method tells Rails that this route applies to requests for the root of the site.</p></div>
<div class="paragraph"><p>For better readability, you can specify an already-created route in your call to <tt>map.root</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1447,7 +1447,7 @@ map<span style="color: #990000">.</span>root <span style="color: #990000">:</spa <h3 id="_connecting_the_empty_string">7.2. Connecting the Empty String</h3>
<div class="paragraph"><p>You can also specify an empty route by explicitly connecting the empty string:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1526,7 +1526,7 @@ formatted_users GET /users.:format {:controller=>"users", :action=>"inde <h4 id="_the_tt_assert_generates_tt_assertion">8.2.1. The <tt>assert_generates</tt> Assertion</h4>
<div class="paragraph"><p>Use <tt>assert_generates</tt> to assert that a particular set of options generate a particular path. You can use this with default routes or custom routes</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1535,21 +1535,21 @@ assert_generates <span style="color: #FF0000">"/about"</span><span style="color: <h4 id="_the_tt_assert_recognizes_tt_assertion">8.2.2. The <tt>assert_recognizes</tt> Assertion</h4>
<div class="paragraph"><p>The <tt>assert_recognizes</tt> assertion is the inverse of <tt>assert_generates</tt>. It asserts that Rails recognizes the given path and routes it to a particular spot in your application.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>assert_recognizes <span style="color: #FF0000">{</span> <span style="color: #990000">:</span>controller <span style="color: #990000">=></span> <span style="color: #FF0000">"photos"</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>action <span style="color: #990000">=></span> <span style="color: #FF0000">"show"</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>id <span style="color: #990000">=></span> <span style="color: #FF0000">"1"</span> <span style="color: #FF0000">}</span><span style="color: #990000">,</span> <span style="color: #FF0000">"/photos/1"</span></tt></pre></div></div>
<div class="paragraph"><p>You can supply a <tt>:method</tt> argument to specify the HTTP verb:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>assert_recognizes <span style="color: #FF0000">{</span> <span style="color: #990000">:</span>controller <span style="color: #990000">=></span> <span style="color: #FF0000">"photos"</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>action <span style="color: #990000">=></span> <span style="color: #FF0000">"create"</span> <span style="color: #FF0000">}</span><span style="color: #990000">,</span> <span style="color: #FF0000">{</span> <span style="color: #990000">:</span>path <span style="color: #990000">=></span> <span style="color: #FF0000">"photos"</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>method <span style="color: #990000">=></span> <span style="color: #990000">:</span>post <span style="color: #FF0000">}</span></tt></pre></div></div>
<div class="paragraph"><p>You can also use the RESTful helpers to test recognition of a RESTful route:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1557,7 +1557,7 @@ http://www.gnu.org/software/src-highlite --> <h4 id="_the_tt_assert_routing_tt_assertion">8.2.3. The <tt>assert_routing</tt> Assertion</h4>
<div class="paragraph"><p>The <tt>assert_routing</tt> 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 <tt>assert_generates</tt> and <tt>assert_recognizes</tt>.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
diff --git a/railties/doc/guides/html/security.html b/railties/doc/guides/html/security.html index 4751e9f92b..8ef01db21a 100644 --- a/railties/doc/guides/html/security.html +++ b/railties/doc/guides/html/security.html @@ -210,7 +210,7 @@ And the most popular injection attack methods Rails will create a new session automatically if a new user accesses the application. It will load an existing session if the user has already used the application.</p></div>
<div class="paragraph"><p>A session usually consists of a hash of values and a session id, usually a 32-character string, to identify the hash. Every cookie sent to the client’s browser includes the session id. And the other way round: the browser will send it to the server on every request from the client. In Rails you can save and retrieve values using the session method:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -326,7 +326,7 @@ The user has his credit back. </div>
</div>
<div class="paragraph"><p>This attack focuses on fixing a user’s session id known to the attacker, and forcing the user’s browser into using this id. It is therefore not necessary for the attacker to steal the session id afterwards. Here is how this attack works:</p></div>
-<div class="olist"><ol>
+<div class="olist arabic"><ol class="arabic">
<li>
<p>
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).
@@ -363,7 +363,7 @@ From now on, the victim and the attacker will co-use the web application with th <div class="paragraph"><p>-- <em>One line of code will protect you from session fixation.</em></p></div>
<div class="paragraph"><p>The most effective countermeasure is to <span style="background-color: #fffcdb;">issue a new session identifier</span> and declare the old one invalid after a successful login. That way, an attacker cannot use the fixed session identifier. This is a good countermeasure against session hijacking, as well. Here is how to create a new session in Rails:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -374,7 +374,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>-- <em>Sessions that never expire extend the time-frame for attacks such as cross-site reference forgery (CSRF), session hijacking and session fixation.</em></p></div>
<div class="paragraph"><p>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 <span style="background-color: #fffcdb;">expire sessions in a database table</span>. Call Session.sweep("20m") to expire sessions that were used longer than 20 minutes ago.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -391,7 +391,7 @@ http://www.gnu.org/software/src-highlite -->
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>The section about session fixation introduced the problem of maintained sessions. An attacker maintaining a session every five minutes can keep the session alive forever, although you are expiring sessions. A simple solution for this would be to add a created_at column to the sessions table. Now you can delete sessions that were created a long time ago. Use this line in the sweep method above:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -478,7 +478,7 @@ The user is <span style="background-color: #fffcdb;">held accountable for the re <div class="paragraph"><p>With this precaution, the attack from above will not work, because the browser sends a GET request for images, which will not be accepted by the web application.</p></div>
<div class="paragraph"><p>But this was only the first step, because <span style="background-color: #fffcdb;">POST requests can be send automatically, too</span>. 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.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -504,7 +504,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>-- <em>Redirection in a web application is an underestimated cracker tool: Not only can the attacker forward the user to a trap web site, he may also create a self-contained attack.</em></p></div>
<div class="paragraph"><p>Whenever the user is allowed to pass (parts of) the URL for redirection, it is possibly vulnerable. The most obvious attack would be to redirect users to a fake web application which looks and feels exactly as the original one. This so-called phishing attack works by sending an unsuspicious link in an email to the users, injecting the link by XSS in the web application or putting the link into an external site. It is unsuspicious, because the link starts with the URL to the web application and the URL to the malicious site is hidden in the redirection parameter: <a href="http://www.example.com/site/redirect?to">http://www.example.com/site/redirect?to</a>= www.attacker.com. Here is an example of a legacy action:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -523,7 +523,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>Many web applications allow users to upload files. <span style="background-color: #fffcdb;">File names, which the user may choose (partly), should always be filtered</span> as an attacker could use a malicious file name to overwrite any file on the server. If you store file uploads at /var/www/uploads, and the user enters a file name like “../../../etc/passwd”, it may overwrite an important file. Of course, the Ruby interpreter would need the appropriate permissions to do so – one more reason to run web servers, database servers and other programs as a less privileged Unix user.</p></div>
<div class="paragraph"><p>When filtering user input file names, <span style="background-color: #fffcdb;">don’t try to remove malicious parts</span>. Think of a situation where the web application removes all “../” in a file name and an attacker uses a string such as “....//” - the result will be “../”. It is best to use a whitelist approach, which <span style="background-color: #fffcdb;">checks for the validity of a file name with a set of accepted characters</span>. This is opposed to a blacklist approach which attempts to remove not allowed characters. In case it isn’t a valid file name, reject it (or replace not accepted characters), but don’t remove them. Here is the file name sanitizer from the <a href="http://github.com/technoweenie/attachment_fu/tree/master">attachment_fu plugin</a>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -547,14 +547,14 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>-- <em>Make sure users cannot download arbitrary files.</em></p></div>
<div class="paragraph"><p>Just as you have to filter file names for uploads, you have to do so for downloads. The send_file() method sends files from the server to the client. If you use a file name, that the user entered, without filtering, any file can be downloaded:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>send_file<span style="color: #990000">(</span><span style="color: #FF0000">'/var/www/uploads/'</span> <span style="color: #990000">+</span> params<span style="color: #990000">[:</span>filename<span style="color: #990000">])</span></tt></pre></div></div>
<div class="paragraph"><p>Simply pass a file name like “../../../etc/passwd” to download the server’s login information. A simple solution against this, is to <span style="background-color: #fffcdb;">check that the requested file is in the expected directory</span>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -602,7 +602,7 @@ Does the admin really have to access the interface from everywhere in the world? <div class="paragraph"><p>-- <em>Without any precautions Model.new(params[:model]) allows attackers to set any database column’s value.</em></p></div>
<div class="paragraph"><p>The mass-assignment feature may become a problem, as it allows an attacker to set any model’s attribute by manipulating the hash passed to a model’s new() method:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -617,7 +617,7 @@ http://www.gnu.org/software/src-highlite --> </div></div>
<div class="paragraph"><p>This will set the following parameters in the controller:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -626,21 +626,21 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_countermeasures">6.1. Countermeasures</h3>
<div class="paragraph"><p>To avoid this, Rails provides two class methods in your ActiveRecord 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:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>attr_protected <span style="color: #990000">:</span>admin</tt></pre></div></div>
<div class="paragraph"><p>A much better way, because it follows the whitelist-principle, is the <span style="background-color: #fffcdb;">attr_accessible method</span>. It is the exact opposite of attr_protected, because <span style="background-color: #fffcdb;">it takes a list of attributes that will be accessible</span>. 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:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>attr_accessible <span style="color: #990000">:</span>name</tt></pre></div></div>
<div class="paragraph"><p>If you want to set a protected attribute, you will to have to assign it individually:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -662,7 +662,7 @@ http://localhost:3006/user/activate?id=</tt></pre> </div></div>
<div class="paragraph"><p>This is possible because on some servers, this way the parameter id, as in params[:id], would be nil. However, here is the finder from the activation action:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -735,7 +735,7 @@ Include more than one honeypot field of all types, including submission buttons <div class="paragraph"><p>-- <em>Tell Rails not to put passwords in the log files.</em></p></div>
<div class="paragraph"><p>By default, Rails logs all requests being made to the web application. But log files can be a huge security issue, as they may contain login credentials, credit card numbers etcetera. When designing a web application security concept, you should also think about what will happen if an attacker got (full) access to the web server. Encrypting secrets and passwords in the database will be quite useless, if the log files list them in clear text. You can <span style="background-color: #fffcdb;">filter certain request parameters from your log files</span> by the filter_parameter_logging method in a controller. These parameters will be marked [FILTERED] in the log.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -750,7 +750,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>-- <em>A common pitfall in Ruby’s regular expressions is to match the string’s beginning and end by ^ and $, instead of \A and \z.</em></p></div>
<div class="paragraph"><p>Ruby uses a slightly different approach than many other languages to match the end and the beginning of a string. That is why even many Ruby and Rails books make this wrong. So how is this a security threat? Imagine you have a File model and you validate the file name by a regular expression like this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -764,7 +764,7 @@ http://www.gnu.org/software/src-highlite --> </div></div>
<div class="paragraph"><p>Whereas %0A is a line feed in URL encoding, so Rails automatically converts it to "file.txt\n<script>alert(<em>hello</em>)</script>". This file name passes the filter because the regular expression matches – up to the line end, the rest does not matter. The correct expression should read:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -774,14 +774,14 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>-- <em>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.</em></p></div>
<div class="paragraph"><p>The most common parameter that a user might tamper with, is the id parameter, as in <tt>http://www.domain.com/project/1</tt>, whereas 1 is the id. It will be available in params[:id] in the controller. There, you will most likely do something like this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #009900">@project</span> <span style="color: #990000">=</span> Project<span style="color: #990000">.</span>find<span style="color: #990000">(</span>params<span style="color: #990000">[:</span>id<span style="color: #990000">])</span></tt></pre></div></div>
<div class="paragraph"><p>This is alright for some web applications, but certainly not if the user is not authorized to view all projects. If the user changes the id to 42, and he is not allowed to see that information, he will have access to it anyway. Instead, <span style="background-color: #fffcdb;">query the user’s access rights, too</span>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -836,7 +836,7 @@ But reject malformed input <h4 id="_introduction_2">8.2.1. Introduction</h4>
<div class="paragraph"><p>SQL injection attacks aim at influencing database queries by manipulating web application parameters. A popular goal of SQL injection attacks is to bypass authorization. Another goal is to carry out data manipulation or reading arbitrary data. Here is an example of how not to use user input data in a query:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -850,7 +850,7 @@ http://www.gnu.org/software/src-highlite --> <h4 id="_bypassing_authorization">8.2.2. Bypassing authorization</h4>
<div class="paragraph"><p>Usually a web application includes access control. The user enters his login credentials, the web applications tries to find the matching record in the users table. The application grants access when it finds a record. However, an attacker may possibly bypass this check with SQL injection. The following shows a typical database query in Rails to find the first record in the users table which matches the login credentials parameters supplied by the user.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -864,7 +864,7 @@ http://www.gnu.org/software/src-highlite --> <h4 id="_unauthorized_reading">8.2.3. Unauthorized reading</h4>
<div class="paragraph"><p>The UNION statement connects two SQL queries and returns the data in one set. An attacker can use it to read arbitrary data from the database. Let’s take the example from above:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -886,14 +886,14 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>Ruby on Rails has a built in filter for special SQL characters, which will escape ' , " , NULL character and line breaks. <span style="background-color: #fffcdb;">Using Model.find(id) or Model.find_by_some thing(something) automatically applies this countermeasure[,#fffcdb]</span>. But in SQL fragments, especially <span style="background-color: #fffcdb;">in conditions fragments (:conditions => "..."), the connection.execute() or Model.find_by_sql() methods, it has to be applied manually</span>.</p></div>
<div class="paragraph"><p>Instead of passing a string to the conditions option, you can pass an array to sanitize tainted strings like this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>Model<span style="color: #990000">.</span>find<span style="color: #990000">(:</span>first<span style="color: #990000">,</span> <span style="color: #990000">:</span>conditions <span style="color: #990000">=></span> <span style="color: #990000">[</span><span style="color: #FF0000">"login = ? AND password = ?"</span><span style="color: #990000">,</span> entered_user_name<span style="color: #990000">,</span> entered_password<span style="color: #990000">])</span></tt></pre></div></div>
<div class="paragraph"><p>As you can see, the first part of the array is an SQL fragment with question marks. The sanitized versions of the variables in the second part of the array replace the question marks. Or you can pass a hash for the same result:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
diff --git a/railties/doc/guides/html/testing_rails_applications.html b/railties/doc/guides/html/testing_rails_applications.html index 16822904fc..7a46b889aa 100644 --- a/railties/doc/guides/html/testing_rails_applications.html +++ b/railties/doc/guides/html/testing_rails_applications.html @@ -196,7 +196,7 @@ test <h3 id="_rails_sets_up_for_testing_from_the_word_go">2.2. Rails Sets up for Testing from the Word Go</h3>
<div class="paragraph"><p>Rails creates a <tt>test</tt> folder for you as soon as you create a Rails project using <tt>rails <em>application_name</em></tt>. If you list the contents of this folder then you shall see:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -213,7 +213,7 @@ fixtures<span style="color: #990000">/</span> functional<span style="color <div class="paragraph"><p>YAML-formatted fixtures are a very human-friendly way to describe your sample data. These types of fixtures have the <strong>.yml</strong> file extension (as in <tt>users.yml</tt>).</p></div>
<div class="paragraph"><p>Here’s a sample YAML fixture file:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -231,7 +231,7 @@ steve<span style="color: #990000">:</span> <h4 id="_erb_8217_in_it_up">2.3.3. ERb’in It Up</h4>
<div class="paragraph"><p>ERb allows you embed ruby code within templates. Both the YAML and CSV fixture formats are pre-processed with ERb when you load fixtures. This allows you to use Ruby to help you generate some sample data.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -249,7 +249,7 @@ mars<span style="color: #990000">:</span> brightest_on<span style="color: #990000">:</span> <span style="color: #FF0000"><%= 13.days.from_now.to_s(:db) %></span></tt></pre></div></div>
<div class="paragraph"><p>Anything encased within the</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -277,7 +277,7 @@ Dump the fixture data into a variable in case you want to access it directly <h4 id="_hashes_with_special_powers">2.3.5. Hashes with Special Powers</h4>
<div class="paragraph"><p>Fixtures are basically Hash objects. As mentioned in point #3 above, you can access the hash object directly because it is automatically setup as a local variable of the test case. For example:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -288,7 +288,7 @@ users<span style="color: #990000">(:</span>david<span style="color: #990000">)</ users<span style="color: #990000">(:</span>david<span style="color: #990000">).</span>id</tt></pre></div></div>
<div class="paragraph"><p>Fixtures can also transform themselves into the form of the original class. Thus, you can get at the methods only available to that class.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -322,7 +322,7 @@ create test/fixtures/posts.yml </div></div>
<div class="paragraph"><p>The default test stub in <tt>test/unit/post_test.rb</tt> looks like this:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -336,28 +336,28 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>A line by line examination of this file will help get you oriented to Rails testing code and terminology.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #000080">require</span></span> <span style="color: #FF0000">'test_helper'</span></tt></pre></div></div>
<div class="paragraph"><p>As you know by now that <tt>test_helper.rb</tt> 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.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> PostTest <span style="color: #990000"><</span> ActiveSupport<span style="color: #990000">::</span>TestCase</tt></pre></div></div>
<div class="paragraph"><p>The <tt>PostTest</tt> class defines a <em>test case</em> because it inherits from <tt>ActiveSupport::TestCase</tt>. <tt>PostTest</tt> thus has all the methods available from <tt>ActiveSupport::TestCase</tt>. You’ll see those methods a little later in this guide.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">def</span></span> test_truth</tt></pre></div></div>
<div class="paragraph"><p>Any method defined within a test case that begins with <tt>test</tt> (case sensitive) is simply called a test. So, <tt>test_password</tt>, <tt>test_valid_password</tt> and <tt>testValidPassword</tt> all are legal test names and are run automatically when the test case is run.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -389,7 +389,7 @@ is the user’s password greater than 5 characters? <h3 id="_preparing_you_application_for_testing">3.1. Preparing you Application for Testing</h3>
<div class="paragraph"><p>Before you can run your tests you need to ensure that the test database structure is current. For this you can use the following rake commands:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -454,7 +454,7 @@ cellspacing="0" cellpadding="4"> <h3 id="_running_tests">3.2. Running Tests</h3>
<div class="paragraph"><p>Running a test is as simple as invoking the file containing the test cases through Ruby:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -483,7 +483,7 @@ Finished in 0.023513 seconds. <div class="paragraph"><p>The <tt>.</tt> (dot) above indicates a passing test. When a test fails you see an <tt>F</tt>; when a test throws an error you see an <tt>E</tt> in its place. The last line of the output is the summary.</p></div>
<div class="paragraph"><p>To see how a test failure is reported, you can add a failing test to the <tt>post_test.rb</tt> test case.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -511,7 +511,7 @@ test_should_not_save_post_without_title(PostTest) </div></div>
<div class="paragraph"><p>In the output, <tt>F</tt> denotes a failure. You can see the corresponding trace shown under <tt>1)</tt> 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:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -540,7 +540,7 @@ Saved the post without a title. </div></div>
<div class="paragraph"><p>Now to get this test to pass we can add a model level validation for the <em>title</em> field.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -569,7 +569,7 @@ Finished in 0.193608 seconds. </div>
<div class="paragraph"><p>To see how an error gets reported, here’s a test containing an error:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -801,7 +801,7 @@ was the appropriate message displayed to the user in the view <div class="paragraph"><p>Now that we have used Rails scaffold generator for our <tt>Post</tt> resource, it has already created the controller code and functional tests. You can take look at the file <tt>posts_controller_test.rb</tt> in the <tt>test/functional</tt> directory.</p></div>
<div class="paragraph"><p>Let me take you through one such test, <tt>test_should_get_index</tt> from the file <tt>posts_controller_test.rb</tt>.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -836,14 +836,14 @@ An optional hash of flash values. </ul></div>
<div class="paragraph"><p>Example: Calling the <tt>:show</tt> action, passing an <tt>id</tt> of 12 as the <tt>params</tt> and setting a <tt>user_id</tt> of 5 in the session:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>get<span style="color: #990000">(:</span>show<span style="color: #990000">,</span> <span style="color: #FF0000">{</span><span style="color: #FF0000">'id'</span> <span style="color: #990000">=></span> <span style="color: #FF0000">"12"</span><span style="color: #FF0000">}</span><span style="color: #990000">,</span> <span style="color: #FF0000">{</span><span style="color: #FF0000">'user_id'</span> <span style="color: #990000">=></span> <span style="color: #993399">5</span><span style="color: #FF0000">}</span><span style="color: #990000">)</span></tt></pre></div></div>
<div class="paragraph"><p>Another example: Calling the <tt>:view</tt> action, passing an <tt>id</tt> of 12 as the <tt>params</tt>, this time with no session, but with a flash message.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -858,7 +858,7 @@ http://www.gnu.org/software/src-highlite --> </div>
<div class="paragraph"><p>Let us modify <tt>test_should_create_post</tt> test in <tt>posts_controller_test.rb</tt> so that all our test pass:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -926,7 +926,7 @@ http://www.gnu.org/software/src-highlite --> </ul></div>
<div class="paragraph"><p>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 <tt>assigns</tt>. For example:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -958,7 +958,7 @@ http://www.gnu.org/software/src-highlite --> <h3 id="_a_fuller_functional_test_example">4.5. A Fuller Functional Test Example</h3>
<div class="paragraph"><p>Here’s another example that uses <tt>flash</tt>, <tt>assert_redirected_to</tt>, and <tt>assert_difference</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -984,14 +984,14 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p><tt>assert_select(element, selector, [equality], [message])</tt> ensures that the equality condition is met on all the selected elements through the selector starting from the <em>element</em> (instance of <tt>HTML::Node</tt>) and its descendants.</p></div>
<div class="paragraph"><p>For example, you could verify the contents on the title element in your response with:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>assert_select <span style="color: #FF0000">'title'</span><span style="color: #990000">,</span> <span style="color: #FF0000">"Welcome to Rails Testing Guide"</span></tt></pre></div></div>
<div class="paragraph"><p>You can also use nested <tt>assert_select</tt> blocks. In this case the inner <tt>assert_select</tt> runs the assertion on the complete collection of elements selected by the outer <tt>assert_select</tt> block:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1000,7 +1000,7 @@ http://www.gnu.org/software/src-highlite --> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
<div class="paragraph"><p>Alternatively the collection of elements selected by the outer <tt>assert_select</tt> may be iterated through so that <tt>assert_select</tt> 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.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1051,7 +1051,7 @@ cellspacing="0" cellpadding="4"> </div>
<div class="paragraph"><p>Here’s an example of using <tt>assert_select_email</tt>:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1064,7 +1064,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>Integration tests are used to test the interaction among any number of controllers. They are generally used to test important work flows within your application.</p></div>
<div class="paragraph"><p>Unlike Unit and Functional tests, integration tests have to be explicitly created under the <em>test/integration</em> folder within your application. Rails provides a generator to create an integration test skeleton for you.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1073,7 +1073,7 @@ http://www.gnu.org/software/src-highlite --> create test/integration/user_flows_test<span style="color: #990000">.</span>rb</tt></pre></div></div>
<div class="paragraph"><p>Here’s what a freshly-generated integration test looks like:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1154,7 +1154,7 @@ cellspacing="0" cellpadding="4"> <h3 id="_integration_testing_examples">5.2. Integration Testing Examples</h3>
<div class="paragraph"><p>A simple integration test that exercises multiple controllers:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1182,7 +1182,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>As you can see the integration test involves multiple controllers and exercises the entire stack from database to dispatcher. In addition you can have multiple session instances open simultaneously in a test and extend those instances with assertion methods to create a very powerful testing DSL (domain-specific language) just for your application.</p></div>
<div class="paragraph"><p>Here’s an example of multiple sessions and custom DSL in an integration test</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1297,7 +1297,7 @@ cellspacing="0" cellpadding="4"> <div class="sectionbody">
<div class="paragraph"><p>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 <tt>Posts</tt> controller:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1357,7 +1357,7 @@ a lambda </ul></div>
<div class="paragraph"><p>Let’s see the earlier example by specifying <tt>setup</tt> callback by specifying a method name as a symbol:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1403,7 +1403,7 @@ http://www.gnu.org/software/src-highlite --> <div class="sectionbody">
<div class="paragraph"><p>Like everything else in you Rails application, it’s recommended to test you routes. An example test for a route in the default <tt>show</tt> action of <tt>Posts</tt> controller above should look like:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1444,7 +1444,7 @@ the right emails are being sent at the right times <h4 id="_the_basic_test_case">10.2.2. The Basic Test case</h4>
<div class="paragraph"><p>Here’s a unit test to test a mailer named <tt>UserMailer</tt> whose action <tt>invite</tt> is used to send an invitation to a friend. It is an adapted version of the base test created by the generator for an <tt>invite</tt> action.</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -1478,7 +1478,7 @@ Cheers!</tt></pre> <h3 id="_functional_testing">10.3. Functional Testing</h3>
<div class="paragraph"><p>Functional testing for mailers involves more than just checking that the email body, recipients and so forth are correct. In functional mail tests you call the mail deliver methods and check that the appropriate emails have been appended to the delivery list. It is fairly safe to assume that the deliver methods themselves do their job You are probably more interested in is whether your own business logic is sending emails when you expect them to got out. For example, you can check that the invite friend operation is sending an email appropriately:</p></div>
<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 2.9
+<div class="content"><!-- Generator: GNU source-highlight 2.11.1
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
diff --git a/railties/doc/guides/source/i18n.txt b/railties/doc/guides/source/i18n.txt index ba3cc42a5b..ebbbbee8a9 100644 --- a/railties/doc/guides/source/i18n.txt +++ b/railties/doc/guides/source/i18n.txt @@ -1,32 +1,38 @@ -The Rails Internationalization API -================================== +The Rails Internationalization (I18n) API +========================================= -The Ruby I18n gem which is shipped with Ruby on Rails (starting from Rails 2.2) provides an easy-to-use and extensible framework for translating your application to a single custom language other than English or providing multi-language support in your application. +The Ruby I18n (shorthand for _internationalization_) gem which is shipped with Ruby on Rails (starting from Rails 2.2) provides an easy-to-use and extensible framework for translating your application to a single custom language other than English or providing multi-language support in your application. + +NOTE: The Ruby I18n framework provides you with all neccessary means for internationalization/localization of your Rails application. You may, however, use any of various plugins and extensions available. See Rails http://rails-i18n.org/wiki[I18n Wiki] for more information. == How I18n in Ruby on Rails works -Internationalization is a complex problem. Natural languages differ in so many ways that it is hard to provide tools for solving all problems at once. For that reason the Rails I18n API focusses on: +Internationalization is a complex problem. Natural languages differ in so many ways (eg. in pluralization rules) that it is hard to provide tools for solving all problems at once. For that reason the Rails I18n API focuses on: * providing support for English and similar languages out of the box * making it easy to customize and extend everything for other languages +As part of this solution, *every static string in the Rails framework* -- eg. ActiveRecord validation messages, time and date formats -- *has been internationalized*, so _localization_ of a Rails application means "over-riding" these defaults. + === The overall architecture of the library Thus, the Ruby I18n gem is split into two parts: -* The public API which is just a Ruby module with a bunch of public methods and definitions how the library works. -* A shipped backend (which is intentionally named the Simple backend) that implements these methods. +* The public API of the i18n framework -- a Ruby module with public methods and definitions how the library works +* A default backend (which is intentionally named _Simple_ backend) that implements these methods + +As a user you should always only access the public methods on the I18n module, but it is useful to know about the capabilities of the backend. -As a user you should always only access the public methods on the I18n module but it is useful to know about the capabilities of the backend you use and maybe exchange the shipped Simple backend with a more powerful one. +NOTE: It is possible (or even desirable) to swap the shipped Simple backend with a more powerful one, which would store translation data in a relational database, GetText dictionary, or similar. See section <<_using_different_backends,Using different backends>> below. === The public I18n API -We will go into more detail about the public methods later but here's a quick overview. The most important methods are: +The most important methods of the I18n API are: [source, ruby] ------------------------------------------------------- -translate # lookup translations -localize # localize Date and Time objects to local formats +translate # Lookup text translations +localize # Localize Date and Time objects to local formats ------------------------------------------------------- These have the aliases #t and #l so you can use them like this: @@ -41,28 +47,42 @@ There are also attribute readers and writers for the following attributes: [source, ruby] ------------------------------------------------------- -load_path # announce your custom translation files -locale # get and set the current locale -default_locale # get and set the default locale -exception_handler # use a different exception_handler -backend # use a different backend +load_path # Announce your custom translation files +locale # Get and set the current locale +default_locale # Get and set the default locale +exception_handler # Use a different exception_handler +backend # Use a different backend ------------------------------------------------------- -== Walkthrough: setup a simple I18n'ed Rails application +So, let's internationalize a simple Rails application from the ground up in the next chapters! -There are just a few, simple steps to get up and running with a I18n support for your application. +== Setup the Rails application for internationalization + +There are just a few, simple steps to get up and running with I18n support for your application. === Configure the I18n module -Rails will wire up all required settings for you with sane defaults. If you need different settings you can overwrite them easily. +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 +config/locales+ directory to your *translations load path*, automatically. + +See the default +en.yml+ locale in this directory, containing a sample pair of translation strings: + +[source, ruby] +------------------------------------------------------- +en: + hello: "Hello world" +------------------------------------------------------- + +This means, that in the +:en+ locale, the key _hello_ will map to _Hello world_ string. Every string inside Rails is internationalized in this way, see for instance ActiveRecord validation messages in the http://github.com/rails/rails/blob/master/activerecord/lib/active_record/locale/en.yml[+activerecord/lib/active_record/locale/en.yml+] file or time and date formats in the http://github.com/rails/rails/blob/master/activesupport/lib/active_support/locale/en.yml[+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 (:en) as a *default locale* by default. I.e if you don't set a different locale, :en will be used for looking up translations. Also, Rails adds all files from config/locales/*.rb,yml to your translations load path. +The I18n library will use *English* as a *default locale*, ie. if you don't set a different locale, +:en+ will be used for looking up translations. -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. -(Hint: 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.) +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 environment.rb says: +The default +environment.rb+ files has instruction how to add locales from another directory and how to set different default locale. Just uncomment and edit the specific lines. [source, ruby] ------------------------------------------------------- @@ -75,22 +95,22 @@ The default environment.rb says: === Optional: custom I18n configuration setup -For the sake of completeness let's mention that if you do not want to use the environment 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 +environment.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: +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*: [source, ruby] ------------------------------------------------------- # in config/initializer/locale.rb # tell the I18n library where to find your translations -I18n.load_path += Dir[ File.join(RAILS_ROOT, 'lib', 'locale', '*.{rb,yml}') ] +I18n.load_path << Dir[ File.join(RAILS_ROOT, 'lib', 'locale', '*.{rb,yml}') ] -# you can omit this if you're happy with English as a default locale +# set default locale to something else then :en I18n.default_locale = :pt ------------------------------------------------------- -=== Set the locale in each request +=== Setting and passing the locale By default the I18n library will use :en (English) as a I18n.default_locale for looking up translations (if you do not specify a locale for a lookup). |