Skip to content
This repository
Browse code

Merge branch 'master' of git@github.com:lifo/docrails

  • Loading branch information...
commit c78c247c7293781438ba524b15d1ca6c5989ed0e 2 parents 40bc386 + 1dff350
Jeff Dean authored November 13, 2008
24  railties/doc/guides/html/2_2_release_notes.html
@@ -243,6 +243,8 @@ <h2 id="site_title_tagline">Sustainable productivity for web-application develop
243 243
 						
244 244
 							<li><a href="#_method_arrays_for_member_or_collection_routes">Method Arrays for Member or Collection Routes</a></li>
245 245
 						
  246
+							<li><a href="#_resources_with_specific_actions">Resources With Specific Actions</a></li>
  247
+						
246 248
 							<li><a href="#_other_action_controller_changes">Other Action Controller Changes</a></li>
247 249
 						
248 250
 						</ul>
@@ -698,7 +700,7 @@ <h3 id="_other_activerecord_changes">5.6. Other ActiveRecord Changes</h3>
698 700
 </div>
699 701
 <h2 id="_action_controller">6. Action Controller</h2>
700 702
 <div class="sectionbody">
701  
-<div class="para"><p>On the controller side, there are a couple of changes that will help tidy up your routes.</p></div>
  703
+<div class="para"><p>On the controller side, there are several changes that will help tidy up your routes. There are also some internal changes in the routing engine to lower memory usage on complex applications.</p></div>
702 704
 <h3 id="_shallow_route_nesting">6.1. Shallow Route Nesting</h3>
703 705
 <div class="para"><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>
704 706
 <div class="listingblock">
@@ -761,8 +763,24 @@ <h3 id="_method_arrays_for_member_or_collection_routes">6.2. Method Arrays for M
761 763
 </p>
762 764
 </li>
763 765
 </ul></div>
764  
-<div class="para"><p>Action Controller now offers good support for HTTP conditional GET requests, as well as some other additions.</p></div>
765  
-<h3 id="_other_action_controller_changes">6.3. Other Action Controller Changes</h3>
  766
+<h3 id="_resources_with_specific_actions">6.3. Resources With Specific Actions</h3>
  767
+<div class="para"><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>
  768
+<div class="listingblock">
  769
+<div class="content"><!-- Generator: GNU source-highlight 2.9
  770
+by Lorenzo Bettini
  771
+http://www.lorenzobettini.it
  772
+http://www.gnu.org/software/src-highlite -->
  773
+<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>only <span style="color: #990000">=&gt;</span> <span style="color: #990000">[:</span>index<span style="color: #990000">,</span> <span style="color: #990000">:</span>show<span style="color: #990000">]</span>
  774
+map<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>products<span style="color: #990000">,</span> <span style="color: #990000">:</span>except <span style="color: #990000">=&gt;</span> <span style="color: #990000">:</span>destroy
  775
+</tt></pre></div></div>
  776
+<div class="ilist"><ul>
  777
+<li>
  778
+<p>
  779
+Lead Contributor: <a href="http://experthuman.com/">Tom Stuart</a>
  780
+</p>
  781
+</li>
  782
+</ul></div>
  783
+<h3 id="_other_action_controller_changes">6.4. Other Action Controller Changes</h3>
766 784
 <div class="ilist"><ul>
767 785
 <li>
768 786
 <p>
8  railties/doc/guides/html/actioncontroller_basics.html
@@ -925,7 +925,7 @@ <h2 id="_the_tt_request_tt_and_tt_response_tt_objects">9. The <tt>request</tt> a
925 925
 <div class="sectionbody">
926 926
 <div class="para"><p>In every controller there are two accessor methods pointing to the request and the response objects associated with the request cycle that is currently in execution. The <tt>request</tt> method contains an instance of AbstractRequest and the <tt>response</tt> method returns a <tt>response</tt> object representing what is going to be sent back to the client.</p></div>
927 927
 <h3 id="_the_tt_request_tt_object">9.1. The <tt>request</tt> Object</h3>
928  
-<div class="para"><p>The request object contains a lot of useful information about the request coming in from the client. To get a full list of the available methods, refer to the <a href="http://api.rubyonrails.org/classes/ActionController/AbstractRequest.html">API documentation</a>. Among the properties that you can access on this object:</p></div>
  928
+<div class="para"><p>The request object contains a lot of useful information about the request coming in from the client. To get a full list of the available methods, refer to the <a href="http://api.rubyonrails.org/classes/ActionController/AbstractRequest.html">API documentation</a>. Among the properties that you can access on this object are:</p></div>
929 929
 <div class="ilist"><ul>
930 930
 <li>
931 931
 <p>
@@ -1039,7 +1039,7 @@ <h2 id="_http_basic_authentication">10. HTTP Basic Authentication</h2>
1039 1039
 http://www.gnu.org/software/src-highlite -->
1040 1040
 <pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> AdminController <span style="color: #990000">&lt;</span> ApplicationController
1041 1041
 
1042  
-  USERNAME<span style="color: #990000">,</span> PASSWORD <span style="color: #990000">=</span> <span style="color: #FF0000">"humbaba"</span><span style="color: #990000">,</span> <span style="color: #FF0000">"f59a4805511bf4bb61978445a5380c6c"</span>
  1042
+  USERNAME<span style="color: #990000">,</span> PASSWORD <span style="color: #990000">=</span> <span style="color: #FF0000">"humbaba"</span><span style="color: #990000">,</span> <span style="color: #FF0000">"5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8"</span>
1043 1043
 
1044 1044
   before_filter <span style="color: #990000">:</span>authenticate
1045 1045
 
@@ -1047,7 +1047,7 @@ <h2 id="_http_basic_authentication">10. HTTP Basic Authentication</h2>
1047 1047
 
1048 1048
   <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> authenticate
1049 1049
     authenticate_or_request_with_http_basic <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>username<span style="color: #990000">,</span> password<span style="color: #990000">|</span>
1050  
-      username <span style="color: #990000">==</span> USERNAME <span style="color: #990000">&amp;&amp;</span> Digest<span style="color: #990000">::</span>MD5<span style="color: #990000">.</span>hexdigest<span style="color: #990000">(</span>password<span style="color: #990000">)</span> <span style="color: #990000">==</span> PASSWORD
  1050
+      username <span style="color: #990000">==</span> USERNAME <span style="color: #990000">&amp;&amp;</span> Digest<span style="color: #990000">::</span>SHA1<span style="color: #990000">.</span>hexdigest<span style="color: #990000">(</span>password<span style="color: #990000">)</span> <span style="color: #990000">==</span> PASSWORD
1051 1051
     <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
1052 1052
   <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
1053 1053
 
@@ -1104,7 +1104,7 @@ <h3 id="_sending_files">11.1. Sending Files</h3>
1104 1104
 
1105 1105
 <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
1106 1106
 </tt></pre></div></div>
1107  
-<div class="para"><p>This will read and stream the file 4Kb at the time, avoiding loading the entire file into memory at once. You can turn off streaming with the <tt>stream</tt> option or adjust the block size with the <tt>buffer_size</tt> option.</p></div>
  1107
+<div class="para"><p>This will read and stream the file 4Kb at the time, avoiding loading the entire file into memory at once. You can turn off streaming with the <tt>:stream</tt> option or adjust the block size with the <tt>:buffer_size</tt> option.</p></div>
1108 1108
 <div class="admonitionblock">
1109 1109
 <table><tr>
1110 1110
 <td class="icon">
38  railties/doc/guides/html/activerecord_validations_callbacks.html
@@ -264,6 +264,9 @@ <h2 id="site_title_tagline">Sustainable productivity for web-application develop
264 264
 						</ul>
265 265
 					</li>
266 266
 					<li>
  267
+					<a href="#_writing_your_own_validation_methods">Writing your own validation methods</a>
  268
+					</li>
  269
+					<li>
267 270
 					<a href="#_changelog">Changelog</a>
268 271
 					</li>
269 272
 			</ol>
@@ -702,7 +705,40 @@ <h3 id="_using_a_proc_object_with_the_tt_if_tt_and_tt_unless_tt_options">5.3. Us
702 705
 <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
703 706
 </tt></pre></div></div>
704 707
 </div>
705  
-<h2 id="_changelog">6. Changelog</h2>
  708
+<h2 id="_writing_your_own_validation_methods">6. Writing your own validation methods</h2>
  709
+<div class="sectionbody">
  710
+<div class="para"><p>When the built-in validation helpers are not enough for your needs, you can write your own validation methods, by implementing one or more of the <tt>validate</tt>, <tt>validate_on_create</tt> or <tt>validate_on_update</tt> methods. As the names of the methods states, the right method to implement depends on when you want the validations to be ran. The meaning of valid is still the same: to make an object invalid you just need to add a message to it's <tt>errors</tt> collection.</p></div>
  711
+<div class="listingblock">
  712
+<div class="content"><!-- Generator: GNU source-highlight 2.9
  713
+by Lorenzo Bettini
  714
+http://www.lorenzobettini.it
  715
+http://www.gnu.org/software/src-highlite -->
  716
+<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> Invoice <span style="color: #990000">&lt;</span> ActiveRecord<span style="color: #990000">::</span>Base
  717
+  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> validate_on_create
  718
+    errors<span style="color: #990000">.</span>add<span style="color: #990000">(:</span>expiration_date<span style="color: #990000">,</span> <span style="color: #FF0000">"can't be in the past"</span><span style="color: #990000">)</span> <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> <span style="color: #990000">!</span>expiration_date<span style="color: #990000">.</span>blank? <span style="font-weight: bold"><span style="color: #0000FF">and</span></span> expiration_date <span style="color: #990000">&lt;</span> Date<span style="color: #990000">.</span>today
  719
+  <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
  720
+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
  721
+</tt></pre></div></div>
  722
+<div class="para"><p>If your validation rules are too complicated and you want to break it in small methods, you can implement all of them and call one of <tt>validate</tt>, <tt>validate_on_create</tt> or <tt>validate_on_update</tt> methods, passing it the symbols for the methods' names.</p></div>
  723
+<div class="listingblock">
  724
+<div class="content"><!-- Generator: GNU source-highlight 2.9
  725
+by Lorenzo Bettini
  726
+http://www.lorenzobettini.it
  727
+http://www.gnu.org/software/src-highlite -->
  728
+<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> Invoice <span style="color: #990000">&lt;</span> ActiveRecord<span style="color: #990000">::</span>Base
  729
+  validate <span style="color: #990000">:</span>expiration_date_cannot_be_in_the_past<span style="color: #990000">,</span> <span style="color: #990000">:</span>discount_cannot_be_be_more_than_total_value
  730
+
  731
+  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> expiration_date_cannot_be_in_the_past
  732
+    errors<span style="color: #990000">.</span>add<span style="color: #990000">(:</span>expiration_date<span style="color: #990000">,</span> <span style="color: #FF0000">"can't be in the past"</span><span style="color: #990000">)</span> <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> <span style="color: #990000">!</span>expiration_date<span style="color: #990000">.</span>blank? <span style="font-weight: bold"><span style="color: #0000FF">and</span></span> expiration_date <span style="color: #990000">&lt;</span> Date<span style="color: #990000">.</span>today
  733
+  <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
  734
+
  735
+  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> discount_cannot_be_greater_than_total_value
  736
+    errors<span style="color: #990000">.</span>add<span style="color: #990000">(:</span>discount<span style="color: #990000">,</span> <span style="color: #FF0000">"can't be greater than total value"</span><span style="color: #990000">)</span> <span style="font-weight: bold"><span style="color: #0000FF">unless</span></span> discount <span style="color: #990000">&lt;=</span> total_value
  737
+  <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
  738
+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
  739
+</tt></pre></div></div>
  740
+</div>
  741
+<h2 id="_changelog">7. Changelog</h2>
706 742
 <div class="sectionbody">
707 743
 <div class="para"><p><a href="http://rails.lighthouseapp.com/projects/16213/tickets/26-active-record-validations-and-callbacks">http://rails.lighthouseapp.com/projects/16213/tickets/26-active-record-validations-and-callbacks</a></p></div>
708 744
 </div>
72  railties/doc/guides/html/caching_with_rails.html
@@ -235,48 +235,54 @@ <h2 id="_basic_caching">1. Basic Caching</h2>
235 235
 <div class="sectionbody">
236 236
 <div class="para"><p>This is an introduction to the three types of caching techniques that Rails
237 237
 provides by default without the use of any third party plugins.</p></div>
238  
-<div class="para"><p>To get started make sure Base.perform_caching is set to true for your
239  
-environment.</p></div>
  238
+<div class="para"><p>To get started make sure config.action_controller.perform_caching is set
  239
+to true for your environment. This flag is normally set in the
  240
+corresponding config/environments/*.rb and caching is disabled by default
  241
+there for development and test, and enabled for production.</p></div>
240 242
 <div class="listingblock">
241 243
 <div class="content"><!-- Generator: GNU source-highlight 2.9
242 244
 by Lorenzo Bettini
243 245
 http://www.lorenzobettini.it
244 246
 http://www.gnu.org/software/src-highlite -->
245  
-<pre><tt>Base<span style="color: #990000">.</span>perform_caching <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #0000FF">true</span></span>
  247
+<pre><tt>config<span style="color: #990000">.</span>action_controller<span style="color: #990000">.</span>perform_caching <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #0000FF">true</span></span>
246 248
 </tt></pre></div></div>
247 249
 <h3 id="_page_caching">1.1. Page Caching</h3>
248 250
 <div class="para"><p>Page caching is a Rails mechanism which allows the request for a generated
249 251
 page to be fulfilled by the webserver, without ever having to go through the
250  
-Rails stack at all. Obviously, this is super fast. Unfortunately, it can't be
  252
+Rails stack at all. Obviously, this is super-fast. Unfortunately, it can't be
251 253
 applied to every situation (such as pages that need authentication) and since
252 254
 the webserver is literally just serving a file from the filesystem, cache
253 255
 expiration is an issue that needs to be dealt with.</p></div>
254 256
 <div class="para"><p>So, how do you enable this super-fast cache behavior?  Simple, let's say you
255  
-have a controller called ProductController and a <em>list</em> action that lists all
  257
+have a controller called ProductsController and a <em>list</em> action that lists all
256 258
 the products</p></div>
257 259
 <div class="listingblock">
258 260
 <div class="content"><!-- Generator: GNU source-highlight 2.9
259 261
 by Lorenzo Bettini
260 262
 http://www.lorenzobettini.it
261 263
 http://www.gnu.org/software/src-highlite -->
262  
-<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> ProductController <span style="color: #990000">&lt;</span> ActionController
  264
+<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> ProductsController <span style="color: #990000">&lt;</span> ActionController
263 265
 
264  
-  cache_page <span style="color: #990000">:</span>list
  266
+  caches_page <span style="color: #990000">:</span>index
265 267
 
266  
-  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> list<span style="color: #990000">;</span> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
  268
+  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> index<span style="color: #990000">;</span> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
267 269
 
268 270
 <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
269 271
 </tt></pre></div></div>
270  
-<div class="para"><p>The first time anyone requestsion products/list, Rails will generate a file
271  
-called list.html and the webserver will then look for that file before it
272  
-passes the next request for products/list to your Rails application.</p></div>
  272
+<div class="para"><p>The first time anyone requests products/index, Rails will generate a file
  273
+called index.html and the webserver will then look for that file before it
  274
+passes the next request for products/index to your Rails application.</p></div>
273 275
 <div class="para"><p>By default, the page cache directory is set to Rails.public_path (which is
274  
-usually set to RAILS_ROOT + "/public") and this can be configured by changing
275  
-the configuration setting Base.cache_public_directory</p></div>
276  
-<div class="para"><p>The page caching mechanism will automatically add a .html exxtension to
  276
+usually set to RAILS_ROOT + "/public") and this can be configured by
  277
+changing the configuration setting ActionController::Base.page_cache_directory. Changing the
  278
+default from /public helps avoid naming conflicts, since you may want to
  279
+put other static html in /public, but changing this will require web
  280
+server reconfiguration to let the web server know where to serve the
  281
+cached files from.</p></div>
  282
+<div class="para"><p>The Page Caching mechanism will automatically add a .html exxtension to
277 283
 requests for pages that do not have an extension to make it easy for the
278 284
 webserver to find those pages and this can be configured by changing the
279  
-configuration setting Base.page_cache_extension</p></div>
  285
+configuration setting ActionController::Base.page_cache_extension.</p></div>
280 286
 <div class="para"><p>In order to expire this page when a new product is added we could extend our
281 287
 example controler like this:</p></div>
282 288
 <div class="listingblock">
@@ -284,9 +290,9 @@ <h3 id="_page_caching">1.1. Page Caching</h3>
284 290
 by Lorenzo Bettini
285 291
 http://www.lorenzobettini.it
286 292
 http://www.gnu.org/software/src-highlite -->
287  
-<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> ProductController <span style="color: #990000">&lt;</span> ActionController
  293
+<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> ProductsController <span style="color: #990000">&lt;</span> ActionController
288 294
 
289  
-  cache_page <span style="color: #990000">:</span>list
  295
+  caches_page <span style="color: #990000">:</span>list
290 296
 
291 297
   <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> list<span style="color: #990000">;</span> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
292 298
 
@@ -299,11 +305,11 @@ <h3 id="_page_caching">1.1. Page Caching</h3>
299 305
 <div class="para"><p>If you want a more complicated expiration scheme, you can use cache sweepers
300 306
 to expire cached objects when things change. This is covered in the section on Sweepers.</p></div>
301 307
 <h3 id="_action_caching">1.2. Action Caching</h3>
302  
-<div class="para"><p>One of the issues with page caching is that you cannot use it for pages that
  308
+<div class="para"><p>One of the issues with Page Caching is that you cannot use it for pages that
303 309
 require to restrict access somehow. This is where Action Caching comes in.
304 310
 Action Caching works like Page Caching except for the fact that the incoming
305 311
 web request does go from the webserver to the Rails stack and Action Pack so
306  
-that before_filters can be run on it before the cache is served, so that
  312
+that before filters can be run on it before the cache is served, so that
307 313
 authentication and other restrictions can be used while still serving the
308 314
 result of the output from a cached copy.</p></div>
309 315
 <div class="para"><p>Clearing the cache works in the exact same way as with Page Caching.</p></div>
@@ -314,10 +320,10 @@ <h3 id="_action_caching">1.2. Action Caching</h3>
314 320
 by Lorenzo Bettini
315 321
 http://www.lorenzobettini.it
316 322
 http://www.gnu.org/software/src-highlite -->
317  
-<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> ProductController <span style="color: #990000">&lt;</span> ActionController
  323
+<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> ProductsController <span style="color: #990000">&lt;</span> ActionController
318 324
 
319 325
   before_filter <span style="color: #990000">:</span>authenticate<span style="color: #990000">,</span> <span style="color: #990000">:</span>only <span style="color: #990000">=&gt;</span> <span style="color: #990000">[</span> <span style="color: #990000">:</span>edit<span style="color: #990000">,</span> <span style="color: #990000">:</span>create <span style="color: #990000">]</span>
320  
-  cache_page <span style="color: #990000">:</span>list
  326
+  caches_page <span style="color: #990000">:</span>list
321 327
   caches_action <span style="color: #990000">:</span>edit
322 328
 
323 329
   <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> list<span style="color: #990000">;</span> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
@@ -336,7 +342,7 @@ <h3 id="_action_caching">1.2. Action Caching</h3>
336 342
 layout so that dynamic information in the layout such as logged in user info
337 343
 or the number of items in the cart can be left uncached. This feature is
338 344
 available as of Rails 2.2.</p></div>
339  
-<div class="para"><p>[More: more examples? Walk-through of action caching from request to response?
  345
+<div class="para"><p>[More: more examples? Walk-through of Action Caching from request to response?
340 346
        Description of Rake tasks to clear cached files? Show example of
341 347
        subdomain caching? Talk about :cache_path, :if and assing blocks/Procs
342 348
        to expire_action?]</p></div>
@@ -346,13 +352,13 @@ <h3 id="_fragment_caching">1.3. Fragment Caching</h3>
346 352
 applications usually build pages with a variety of components not all of which
347 353
 have the same caching characteristics. In order to address such a dynamically
348 354
 created page where different parts of the page need to be cached and expired
349  
-differently Rails provides a mechanism called Fragment caching.</p></div>
350  
-<div class="para"><p>Fragment caching allows a fragment of view logic to be wrapped in a cache
  355
+differently Rails provides a mechanism called Fragment Caching.</p></div>
  356
+<div class="para"><p>Fragment Caching allows a fragment of view logic to be wrapped in a cache
351 357
 block and served out of the cache store when the next request comes in.</p></div>
352  
-<div class="para"><p>As an example, if you wanted to show all the orders placed on your website in
353  
-real time and didn't want to cache that part  of the page, but did want to
354  
-cache the part of the page which lists all products available, you could use
355  
-this piece of code:</p></div>
  358
+<div class="para"><p>As an example, if you wanted to show all the orders placed on your website
  359
+in real time and didn't want to cache that part  of the page, but did want
  360
+to cache the part of the page which lists all products available, you
  361
+could use this piece of code:</p></div>
356 362
 <div class="listingblock">
357 363
 <div class="content"><!-- Generator: GNU source-highlight 2.9
358 364
 by Lorenzo Bettini
@@ -371,7 +377,7 @@ <h3 id="_fragment_caching">1.3. Fragment Caching</h3>
371 377
 </tt></pre></div></div>
372 378
 <div class="para"><p>The cache block in our example will bind to the action that called it and is
373 379
 written out to the same place as the Action Cache, which means that if you
374  
-want to cache multiple fragments per action, you should provide an action_path to the cache call:</p></div>
  380
+want to cache multiple fragments per action, you should provide an action_suffix to the cache call:</p></div>
375 381
 <div class="listingblock">
376 382
 <div class="content"><!-- Generator: GNU source-highlight 2.9
377 383
 by Lorenzo Bettini
@@ -439,10 +445,10 @@ <h3 id="_sweepers">1.4. Sweepers</h3>
439 445
 by Lorenzo Bettini
440 446
 http://www.lorenzobettini.it
441 447
 http://www.gnu.org/software/src-highlite -->
442  
-<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> ProductController <span style="color: #990000">&lt;</span> ActionController
  448
+<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> ProductsController <span style="color: #990000">&lt;</span> ActionController
443 449
 
444 450
   before_filter <span style="color: #990000">:</span>authenticate<span style="color: #990000">,</span> <span style="color: #990000">:</span>only <span style="color: #990000">=&gt;</span> <span style="color: #990000">[</span> <span style="color: #990000">:</span>edit<span style="color: #990000">,</span> <span style="color: #990000">:</span>create <span style="color: #990000">]</span>
445  
-  cache_page <span style="color: #990000">:</span>list
  451
+  caches_page <span style="color: #990000">:</span>list
446 452
   caches_action <span style="color: #990000">:</span>edit
447 453
   cache_sweeper <span style="color: #990000">:</span>store_sweeper<span style="color: #990000">,</span> <span style="color: #990000">:</span>only <span style="color: #990000">=&gt;</span> <span style="color: #990000">[</span> <span style="color: #990000">:</span>create <span style="color: #990000">]</span>
448 454
 
@@ -468,10 +474,10 @@ <h3 id="_sql_caching">1.5. SQL Caching</h3>
468 474
 by Lorenzo Bettini
469 475
 http://www.lorenzobettini.it
470 476
 http://www.gnu.org/software/src-highlite -->
471  
-<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> ProductController <span style="color: #990000">&lt;</span> ActionController
  477
+<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> ProductsController <span style="color: #990000">&lt;</span> ActionController
472 478
 
473 479
   before_filter <span style="color: #990000">:</span>authenticate<span style="color: #990000">,</span> <span style="color: #990000">:</span>only <span style="color: #990000">=&gt;</span> <span style="color: #990000">[</span> <span style="color: #990000">:</span>edit<span style="color: #990000">,</span> <span style="color: #990000">:</span>create <span style="color: #990000">]</span>
474  
-  cache_page <span style="color: #990000">:</span>list
  480
+  caches_page <span style="color: #990000">:</span>list
475 481
   caches_action <span style="color: #990000">:</span>edit
476 482
   cache_sweeper <span style="color: #990000">:</span>store_sweeper<span style="color: #990000">,</span> <span style="color: #990000">:</span>only <span style="color: #990000">=&gt;</span> <span style="color: #990000">[</span> <span style="color: #990000">:</span>create <span style="color: #990000">]</span>
477 483
 
38  railties/doc/guides/html/routing_outside_in.html
@@ -925,6 +925,16 @@ <h3 id="_customizing_resources">3.6. Customizing Resources</h3>
925 925
 <tt>:name_prefix</tt>
926 926
 </p>
927 927
 </li>
  928
+<li>
  929
+<p>
  930
+<tt>:only</tt>
  931
+</p>
  932
+</li>
  933
+<li>
  934
+<p>
  935
+<tt>:except</tt>
  936
+</p>
  937
+</li>
928 938
 </ul></div>
929 939
 <div class="para"><p>You can also add additional routes via the <tt>:member</tt> and <tt>:collection</tt> options, which are discussed later in this guide.</p></div>
930 940
 <h4 id="_using_controller">3.6.1. Using :controller</h4>
@@ -1419,6 +1429,34 @@ <h4 id="_using_name_prefix">3.7.7. Using :name_prefix</h4>
1419 1429
 <td class="content">You can also use <tt>:name_prefix</tt> with non-RESTful routes.</td>
1420 1430
 </tr></table>
1421 1431
 </div>
  1432
+<h4 id="_using_only_and_except">3.7.8. Using :only and :except</h4>
  1433
+<div class="para"><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>
  1434
+<div class="listingblock">
  1435
+<div class="content"><!-- Generator: GNU source-highlight 2.9
  1436
+by Lorenzo Bettini
  1437
+http://www.lorenzobettini.it
  1438
+http://www.gnu.org/software/src-highlite -->
  1439
+<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>only <span style="color: #990000">=&gt;</span> <span style="color: #990000">[:</span>index<span style="color: #990000">,</span> <span style="color: #990000">:</span>show<span style="color: #990000">]</span>
  1440
+</tt></pre></div></div>
  1441
+<div class="para"><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>
  1442
+<div class="para"><p>The <tt>:except</tt> option specifies a route or list of routes that should <em>not</em> be generated:</p></div>
  1443
+<div class="listingblock">
  1444
+<div class="content"><!-- Generator: GNU source-highlight 2.9
  1445
+by Lorenzo Bettini
  1446
+http://www.lorenzobettini.it
  1447
+http://www.gnu.org/software/src-highlite -->
  1448
+<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>except <span style="color: #990000">=&gt;</span> <span style="color: #990000">:</span>destroy
  1449
+</tt></pre></div></div>
  1450
+<div class="para"><p>In this case, all of the normal routes except the route for <tt>destroy</tt> (a <tt>DELETE</tt> request to <tt>/photos/<em>id</em></tt>) will be generated.</p></div>
  1451
+<div class="para"><p>In addition to an action or a list of actions, you can also supply the special symbols <tt>:all</tt> or <tt>:none</tt> to the <tt>:only</tt> and <tt>:accept</tt> options.</p></div>
  1452
+<div class="admonitionblock">
  1453
+<table><tr>
  1454
+<td class="icon">
  1455
+<img src="./images/icons/tip.png" alt="Tip" />
  1456
+</td>
  1457
+<td class="content">If your application has many RESTful routes, using <tt>:only</tt> and <tt>:accept</tt> to generate only the routes that you actually need can cut down on memory use and speed up the routing process.</td>
  1458
+</tr></table>
  1459
+</div>
1422 1460
 <h3 id="_nested_resources">3.8. Nested Resources</h3>
1423 1461
 <div class="para"><p>It's common to have resources that are logically children of other resources. For example, suppose your application includes these models:</p></div>
1424 1462
 <div class="listingblock">
14  railties/doc/guides/source/2_2_release_notes.txt
@@ -209,7 +209,7 @@ Active Record association proxies now respect the scope of methods on the proxie
209 209
 
210 210
 == Action Controller
211 211
 
212  
-On the controller side, there are a couple of changes that will help tidy up your routes. 
  212
+On the controller side, there are several changes that will help tidy up your routes. There are also some internal changes in the routing engine to lower memory usage on complex applications.
213 213
 
214 214
 === Shallow Route Nesting
215 215
 
@@ -250,7 +250,17 @@ map.resources :photos, :collection => { :search => [:get, :post] }
250 250
 
251 251
 * Lead Contributor: link:http://brennandunn.com/[Brennan Dunn]
252 252
 
253  
-Action Controller now offers good support for HTTP conditional GET requests, as well as some other additions.
  253
+=== Resources With Specific Actions
  254
+
  255
+By default, when you use +map.resources+ 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 +:only+ and +:except+ 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 +:all+ or +:none+ options. These options are inherited by nested resources.
  256
+
  257
+[source, ruby]
  258
+-------------------------------------------------------
  259
+map.resources :photos, :only => [:index, :show]
  260
+map.resources :products, :except => :destroy
  261
+-------------------------------------------------------
  262
+
  263
+* Lead Contributor: link:http://experthuman.com/[Tom Stuart]
254 264
 
255 265
 === Other Action Controller Changes
256 266
 
30  railties/doc/guides/source/activerecord_validations_callbacks.txt
@@ -369,6 +369,36 @@ class Account < ActiveRecord::Base
369 369
 end
370 370
 ------------------------------------------------------------------
371 371
 
  372
+== Writing your own validation methods
  373
+
  374
+When the built-in validation helpers are not enough for your needs, you can write your own validation methods, by implementing one or more of the +validate+, +validate_on_create+ or +validate_on_update+ methods. As the names of the methods states, the right method to implement depends on when you want the validations to be ran. The meaning of valid is still the same: to make an object invalid you just need to add a message to it's +errors+ collection.
  375
+
  376
+[source, ruby]
  377
+------------------------------------------------------------------
  378
+class Invoice < ActiveRecord::Base
  379
+  def validate_on_create    
  380
+    errors.add(:expiration_date, "can't be in the past") if !expiration_date.blank? and expiration_date < Date.today
  381
+  end
  382
+end
  383
+------------------------------------------------------------------
  384
+
  385
+If your validation rules are too complicated and you want to break it in small methods, you can implement all of them and call one of +validate+, +validate_on_create+ or +validate_on_update+ methods, passing it the symbols for the methods' names.
  386
+
  387
+[source, ruby]
  388
+------------------------------------------------------------------
  389
+class Invoice < ActiveRecord::Base
  390
+  validate :expiration_date_cannot_be_in_the_past, :discount_cannot_be_more_than_total_value
  391
+
  392
+  def expiration_date_cannot_be_in_the_past
  393
+    errors.add(:expiration_date, "can't be in the past") if !expiration_date.blank? and expiration_date < Date.today
  394
+  end  
  395
+  
  396
+  def discount_cannot_be_greater_than_total_value
  397
+    errors.add(:discount, "can't be greater than total value") unless discount <= total_value
  398
+  end
  399
+end
  400
+------------------------------------------------------------------
  401
+
372 402
 == Changelog
373 403
 
374 404
 http://rails.lighthouseapp.com/projects/16213/tickets/26-active-record-validations-and-callbacks
147  railties/doc/guides/source/command_line.txt
... ...
@@ -0,0 +1,147 @@
  1
+A Guide to The Rails Command Line
  2
+=================================
  3
+
  4
+Rails comes with every command line tool you'll need to
  5
+
  6
+* Create a Rails application
  7
+* Generate models, controllers, database migrations, and unit tests
  8
+* Start a development server
  9
+* Mess with objects through an interactive shell
  10
+* Profile and benchmark your new creation
  11
+ 
  12
+... and much, much more! (Buy now!)
  13
+
  14
+This tutorial assumes you have basic Rails knowledge from reading the Getting Started with Rails Guide.
  15
+
  16
+== Command Line Basics ==
  17
+
  18
+There are a few commands that are absolutely critical to your everyday usage of Rails. In the order of how much you'll probably use them are:
  19
+
  20
+* console
  21
+* server
  22
+* rake
  23
+* generate
  24
+* rails
  25
+ 
  26
+Let's create a simple Rails application to step through each of these commands in context.
  27
+
  28
+=== rails ===
  29
+
  30
+The first thing we'll want to do is create a new Rails application by running the `rails` command after installing Rails.
  31
+
  32
+NOTE: You know you need the rails gem installed by typing `gem install rails` first, right? Okay, okay, just making sure.
  33
+
  34
+[source,shell]
  35
+------------------------------------------------------
  36
+$ rails commandsapp
  37
+
  38
+     create  
  39
+     create  app/controllers
  40
+     create  app/helpers
  41
+     create  app/models
  42
+     ...
  43
+     ...
  44
+     create  log/production.log
  45
+     create  log/development.log
  46
+     create  log/test.log
  47
+------------------------------------------------------
  48
+
  49
+Rails will set you up with what seems like a huge amount of stuff for such a tiny command! You've got the entire Rails directory structure now with all the code you need to run our simple application right out of the box.
  50
+
  51
+NOTE: This output will seem very familiar when we get to the `generate` command. Creepy foreshadowing!
  52
+
  53
+=== server ===
  54
+
  55
+Let's try it! The `server` command launches a small web server written in Ruby named WEBrick which was also installed when you installed Rails. You'll use this any time you want to view your work through a web browser.
  56
+
  57
+NOTE: WEBrick isn't your only option for serving Rails. We'll get to that in a later section. [XXX: which section]
  58
+
  59
+Here we'll flex our `server` command, which without any prodding of any kind will run our new shiny Rails app:
  60
+
  61
+[source,shell]
  62
+------------------------------------------------------
  63
+$ cd commandsapp
  64
+$ ./script/server
  65
+=> Booting WEBrick...
  66
+=> Rails 2.2.0 application started on http://0.0.0.0:3000
  67
+=> Ctrl-C to shutdown server; call with --help for options
  68
+[2008-11-04 10:11:38] INFO  WEBrick 1.3.1
  69
+[2008-11-04 10:11:38] INFO  ruby 1.8.5 (2006-12-04) [i486-linux]
  70
+[2008-11-04 10:11:38] INFO  WEBrick::HTTPServer#start: pid=18994 port=3000
  71
+------------------------------------------------------
  72
+
  73
+WHOA. With just three commands we whipped up a Rails server listening on port 3000. Go! Go right now to your browser and go to http://localhost:3000. I'll wait.
  74
+
  75
+See? Cool! It doesn't do much yet, but we'll change that.
  76
+
  77
+=== generate ===
  78
+
  79
+The `generate` command uses templates to create a whole lot of things. You can always find out what's available by running `generate` by itself. Let's do that:
  80
+
  81
+[source,shell]
  82
+------------------------------------------------------
  83
+$ ./script/generate
  84
+Usage: ./script/generate generator [options] [args]
  85
+
  86
+...
  87
+...
  88
+
  89
+Installed Generators
  90
+  Builtin: controller, integration_test, mailer, migration, model, observer, performance_test, plugin, resource, scaffold, session_migration
  91
+
  92
+...
  93
+...
  94
+------------------------------------------------------
  95
+
  96
+NOTE: You can install more generators through generator gems, portions of plugins you'll undoubtedly install, and you can even create your own!
  97
+
  98
+Using generators will save you a large amount of time by writing *boilerplate code* for you -- necessary for the darn thing to work, but not necessary for you to spend time writing. That's what we have computers for, right?
  99
+
  100
+Let's make our own controller with the controller generator. But what command should we use? Let's ask the generator:
  101
+
  102
+NOTE: All Rails console utilities have help text. For commands that require a lot of input to run correctly, you can just try the command without any parameters (like `rails` or `./script/generate`). For others, you can try adding `--help` or `-h` to the end, as in `./script/server --help`.
  103
+
  104
+[source,shell]
  105
+------------------------------------------------------
  106
+$ ./script/generate controller
  107
+Usage: ./script/generate controller ControllerName [options]
  108
+
  109
+...
  110
+...
  111
+
  112
+Example:
  113
+    `./script/generate controller CreditCard open debit credit close`
  114
+
  115
+    Credit card controller with URLs like /credit_card/debit.
  116
+        Controller: app/controllers/credit_card_controller.rb
  117
+        Views:      app/views/credit_card/debit.html.erb [...]
  118
+        Helper:     app/helpers/credit_card_helper.rb
  119
+        Test:       test/functional/credit_card_controller_test.rb
  120
+
  121
+Modules Example:
  122
+    `./script/generate controller 'admin/credit_card' suspend late_fee`
  123
+
  124
+    Credit card admin controller with URLs /admin/credit_card/suspend.
  125
+        Controller: app/controllers/admin/credit_card_controller.rb
  126
+        Views:      app/views/admin/credit_card/debit.html.erb [...]
  127
+        Helper:     app/helpers/admin/credit_card_helper.rb
  128
+        Test:       test/functional/admin/credit_card_controller_test.rb
  129
+------------------------------------------------------
  130
+
  131
+Ah, the controller generator is expecting parameters in the form of `generate controller ControllerName action1 action2`. Let's make a `Greetings` controller with an action of *hello*, which will say something nice to us.
  132
+
  133
+[source,shell]
  134
+------------------------------------------------------
  135
+$ ./script/generate controller Greeting hello
  136
+     exists  app/controllers/
  137
+     exists  app/helpers/
  138
+     create  app/views/greeting
  139
+     exists  test/functional/
  140
+     create  app/controllers/greetings_controller.rb
  141
+     create  test/functional/greetings_controller_test.rb
  142
+     create  app/helpers/greetings_helper.rb
  143
+     create  app/views/greetings/hello.html.erb
  144
+------------------------------------------------------
  145
+
  146
+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. All from one command!
  147
+
26  railties/doc/guides/source/routing_outside_in.txt
@@ -229,6 +229,8 @@ Although the conventions of RESTful routing are likely to be sufficient for many
229 229
 * +:path_names+
230 230
 * +:path_prefix+
231 231
 * +:name_prefix+
  232
+* +:only+
  233
+* +:except+
232 234
 
233 235
 You can also add additional routes via the +:member+ and +:collection+ options, which are discussed later in this guide.
234 236
 
@@ -400,6 +402,30 @@ This combination will give you route helpers such as +photographer_photos_path+
400 402
 
401 403
 NOTE: You can also use +:name_prefix+ with non-RESTful routes.
402 404
 
  405
+==== Using :only and :except
  406
+
  407
+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 +:only+ and +:except+ options to fine-tune this behavior. The +:only+ option specifies that only certain routes should be generated:
  408
+
  409
+[source, ruby]
  410
+-------------------------------------------------------
  411
+map.resources :photos, :only => [:index, :show]
  412
+-------------------------------------------------------
  413
+
  414
+With this declaration, a +GET+ request to +/photos+ would succeed, but a +POST+ request to +/photos+ (which would ordinarily be routed to the create action) will fail.
  415
+
  416
+The +:except+ option specifies a route or list of routes that should _not_ be generated:
  417
+
  418
+[source, ruby]
  419
+-------------------------------------------------------
  420
+map.resources :photos, :except => :destroy
  421
+-------------------------------------------------------
  422
+
  423
+In this case, all of the normal routes except the route for +destroy+ (a +DELETE+ request to +/photos/_id_+) will be generated.
  424
+
  425
+In addition to an action or a list of actions, you can also supply the special symbols +:all+ or +:none+ to the +:only+ and +:except+ options.
  426
+
  427
+TIP: If your application has many RESTful routes, using +:only+ and +:accept+ to generate only the routes that you actually need can cut down on memory use and speed up the routing process.
  428
+
403 429
 === Nested Resources
404 430
 
405 431
 It's common to have resources that are logically children of other resources. For example, suppose your application includes these models:
390  railties/doc/guides/source/testing_rails_applications.txt
@@ -11,18 +11,17 @@ This guide won't teach you to write a Rails application; it assumes basic famili
11 11
 
12 12
 == Why Write Tests for your Rails Applications? ==
13 13
 
14  
- * Because Ruby code that you write in your Rails application is interpreted, you may only find that it's broken when you actually run your application server and use it through the browser. Writing tests is a clean way of running through your code in advance and catching syntactical and logic errors.
15  
- * Rails tests can also simulate browser requests and thus you can test your application's response without having to test it through your browser.
16  
- * By simply running your Rails tests you can ensure your code adheres to the desired functionality even after some major code refactoring.
17 14
  * Rails makes it super easy to write your tests. It starts by producing skeleton test code in background while you are creating your models and controllers.
  15
+ * By simply running your Rails tests you can ensure your code adheres to the desired functionality even after some major code refactoring.
  16
+ * Rails tests can also simulate browser requests and thus you can test your application's response without having to test it through your browser.
18 17
 
19  
-== Before you Start Writing Tests ==
  18
+== Introduction to Testing ==
20 19
 
21  
-Just about every Rails application interacts heavily with a database - and, as a result, your tests will need a database to interact with as well. To write efficient tests, you'll need to understand how to set up this database and populate it with sample data.
  20
+Testing support was woven into the Rails fabric from the beginning. It wasn't an "oh! let's bolt on support for running tests because they're new and cool" epiphany. Just about every Rails application interacts heavily with a database - and, as a result, your tests will need a database to interact with as well. To write efficient tests, you'll need to understand how to set up this database and populate it with sample data.
22 21
 
23 22
 === The 3 Environments ===
24 23
 
25  
-Testing support was woven into the Rails fabric from the beginning. It wasn't an "oh! let's bolt on support for running tests because they're new and cool" epiphany. One of the consequences of this design decision is that every Rails application you build has 3 sides: a side for production, a side for development, and a side for testing.
  24
+Every Rails application you build has 3 sides: a side for production, a side for development, and a side for testing.
26 25
 
27 26
 One place you'll find this distinction is in the +config/database.yml+ file. This YAML configuration file has 3 different sections defining 3 unique database setups:
28 27
 
@@ -55,11 +54,11 @@ For good tests, you'll need to give some thought to setting up test data. In Rai
55 54
 
56 55
 ==== What Are Fixtures? ====
57 56
 
58  
-_Fixtures_ is a fancy word for sample data. Fixtures allow you to populate your testing database with predefined data before your tests run. Fixtures are database independent and assume one of two formats: *YAML* or *CSV*.
  57
+_Fixtures_ is a fancy word for sample data. Fixtures allow you to populate your testing database with predefined data before your tests run. Fixtures are database independent and assume one of two formats: *YAML* or *CSV*. In this guide we will use *YAML* which is the preferred format.
59 58
 
60 59
 You'll find fixtures under your +test/fixtures+ directory. When you run +script/generate model+ to create a new model, fixture stubs will be automatically created and placed in this directory.
61 60
 
62  
-==== YAML the Camel is a Mammal with Enamel ====
  61
+==== YAML ====
63 62
 
64 63
 YAML-formatted fixtures are a very human-friendly way to describe your sample data. These types of fixtures have the *.yml* file extension (as in +users.yml+).
65 64
 
@@ -69,13 +68,11 @@ Here's a sample YAML fixture file:
69 68
 ---------------------------------------------
70 69
 # low & behold!  I am a YAML comment!
71 70
 david:
72  
- id: 1
73 71
  name: David Heinemeier Hansson
74 72
  birthday: 1979-10-15
75 73
  profession: Systems development
76 74
 
77 75
 steve:
78  
- id: 2
79 76
  name: Steve Ross Kellock
80 77
  birthday: 1974-09-27
81 78
  profession: guy with keyboard
@@ -83,55 +80,24 @@ steve:
83 80
 
84 81
 Each fixture is given a name followed by an indented list of colon-separated key/value pairs. Records are separated by a blank space. You can place comments in a fixture file by using the # character in the first column.
85 82
 
86  
-==== Comma Seperated ====
87  
-
88  
-Fixtures can also be described using the all-too-familiar comma-separated value (CSV) file format. These files, just like YAML fixtures, are placed in the 'test/fixtures' directory, but these end with the +.csv+ file extension (as in +celebrity_holiday_figures.csv+).
89  
-
90  
-A CSV fixture looks like this:
91  
-
92  
---------------------------------------------------------------
93  
-id, username, password, stretchable, comments
94  
-1, sclaus, ihatekids, false, I like to say ""Ho! Ho! Ho!""
95  
-2, ebunny, ihateeggs, true, Hoppity hop y'all
96  
-3, tfairy, ilovecavities, true, "Pull your teeth, I will"
97  
---------------------------------------------------------------
98  
-
99  
-The first line is the header. It is a comma-separated list of fields. The rest of the file is the payload: 1 record per line. A few notes about this format:
100  
-
101  
- * Leading and trailing spaces are trimmed from each value when it is imported
102  
- * If you use a comma as data, the cell must be encased in quotes
103  
- * If you use a quote as data, you must escape it with a 2nd quote
104  
- * Don't use blank lines
105  
- * Nulls can be defined by including no data between a pair of commas
106  
-
107  
-Unlike the YAML format where you give each record in a fixture a name, CSV fixture names are automatically generated. They follow a pattern of "model-name-counter". In the above example, you would have:
108  
-
109  
-* +celebrity-holiday-figures-1+
110  
-* +celebrity-holiday-figures-2+
111  
-* +celebrity-holiday-figures-3+
112  
-
113  
-The CSV format is great to use if you have existing data in a spreadsheet or database and you are able to save it (or export it) as a CSV.
114  
-
115 83
 ==== ERb'in It Up ====
116 84
 
117 85
 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.
118 86
 
119  
-I'll demonstrate with a YAML file:
120  
-
121 87
 [source, ruby]
122 88
 --------------------------------------------------------------
123 89
 <% earth_size = 20 -%>
124 90
 mercury:
125  
-  id: 1
126 91
   size: <%= earth_size / 50 %>
  92
+  brightest_on: <%= 113.days.ago.to_s(:db) %>
127 93
 
128 94
 venus:
129  
-  id: 2
130 95
   size: <%= earth_size / 2 %>
  96
+  brightest_on: <%= 67.days.ago.to_s(:db) %>
131 97
 
132 98
 mars:
133  
-  id: 3
134 99
   size: <%= earth_size - 69 %>
  100
+  brightest_on: <%= 13.days.from_now.to_s(:db) %>
135 101
 --------------------------------------------------------------
136 102
 
137 103
 Anything encased within the
@@ -141,7 +107,7 @@ Anything encased within the
141 107
 <% %>
142 108
 ------------------------
143 109
 
144  
-tag is considered Ruby code. When this fixture is loaded, the +size+ attribute of the three records will be set to 20/50, 20/2, and 20-69 respectively.
  110
+tag is considered Ruby code. When this fixture is loaded, the +size+ attribute of the three records will be set to 20/50, 20/2, and 20-69 respectively. The +brightest_on+ attribute will also be evaluated and formatted by Rails to be compatible with the database.
145 111
 
146 112
 ==== Fixtures in Action ====
147 113
 
@@ -164,9 +130,7 @@ users(:david)
164 130
 users(:david).id
165 131
 --------------------------------------------------------------
166 132
 
167  
-But, by there's another side to fixtures... at night, if the moon is full and the wind completely still, fixtures can also transform themselves into the form of the original class!
168  
-
169  
-Now you can get at the methods only available to that class.
  133
+Fixtures can also transform themselves into the form of the original class. Thus, you can get at the methods only available to that class.
170 134
 
171 135
 [source, ruby]
172 136
 --------------------------------------------------------------
@@ -177,14 +141,18 @@ david = users(:david).find
177 141
 email(david.girlfriend.email, david.location_tonight)
178 142
 --------------------------------------------------------------
179 143
 
180  
-== Unit Testing Your Models ==
  144
+== Unit Testing your Models ==
181 145
 
182 146
 In Rails, unit tests are what you write to test your models.
183 147
 
184  
-When you create a model using +script/generate+, among other things it creates a test stub in the +test/unit+ folder, as well as a fixture for the model:
  148
+For this guide we will be using Rails _scaffolding_. It will create the model, a migration, controller and views for the new resource in a single operation. It will also create a full test suite following Rails best practises. I will be using examples from this generated code and would be supplementing it with additional examples where necessary.
  149
+
  150
+NOTE: For more information on Rails _scaffolding_, refer to link:../getting_started_with_rails.html[Getting Started with Rails]
  151
+
  152
+When you use +script/generate scaffold+, for a resource among other things it creates a test stub in the +test/unit+ folder:
185 153
 
186 154
 -------------------------------------------------------
187  
-$ script/generate model Post
  155
+$ script/generate scaffold post title:string body:text
188 156
 ...
189 157
 create  app/models/post.rb
190 158
 create  test/unit/post_test.rb
@@ -243,6 +211,36 @@ This line of code is called an _assertion_. An assertion is a line of code that
243 211
 
244 212
 Every test contains one or more assertions. Only when all the assertions are successful the test passes.
245 213
 
  214
+=== Preparing you Application for Testing ===
  215
+
  216
+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:
  217
+
  218
+[source, shell]
  219
+-------------------------------------------------------
  220
+$ rake db:migrate
  221
+...
  222
+$ rake db:test:load
  223
+-------------------------------------------------------
  224
+
  225
+Above +rake db:migrate+ runs any pending migrations on the _developemnt_ environment and updates +db/schema.rb+. +rake db:test:load+ recreates the test database from the current db/schema.rb. On subsequent attempts it is a good to first run +db:test:prepare+ as it first checks for pending migrations and warns you appropriately.
  226
+
  227
+NOTE: +db:test:prepare+ will fail with an error if db/schema.rb doesn't exists.
  228
+
  229
+==== Rake Tasks for Preparing you Application for Testing ==
  230
+
  231
+[grid="all"]
  232
+--------------------------------`----------------------------------------------------
  233
+Tasks                           Description
  234
+------------------------------------------------------------------------------------
  235
++rake db:test:clone+            Recreate the test database from the current environment's database schema
  236
++rake db:test:clone_structure+  Recreate the test databases from the development structure
  237
++rake db:test:load+             Recreate the test database from the current +schema.rb+
  238
++rake db:test:prepare+          Check for pending migrations and load the test schema
  239
++rake db:test:purge+            Empty the test database.
  240
+------------------------------------------------------------------------------------
  241
+
  242
+TIP: You can see all these rake tasks and their descriptions by running +rake --tasks --describe+
  243
+
246 244
 === Running Tests ===
247 245
 
248 246
 Running a test is as simple as invoking the file containing the test cases through Ruby:
@@ -277,65 +275,90 @@ Finished in 0.023513 seconds.
277 275
 
278 276
 The +.+ (dot) above indicates a passing test. When a test fails you see an +F+; when a test throws an error you see an +E+ in its place. The last line of the output is the summary. 
279 277
 
280  
-To see how a test failure is reported, you can add a failing test to the +post_test.rb+ test case:
  278
+To see how a test failure is reported, you can add a failing test to the +post_test.rb+ test case.
281 279
 
282 280
 [source,ruby]
283 281
 --------------------------------------------------
284  
-def test_should_have_atleast_one_post
285  
-  post = Post.find(:first)
286  
-  assert_not_nil post
  282
+def test_should_not_save_post_without_title
  283
+  post = Post.new
  284
+  assert !post.save
287 285
 end
288 286
 --------------------------------------------------
289 287
 
290  
-If you haven't added any data to the test fixture for posts, this test will fail. You can see this by running it:
  288
+Let us run this newly added test.
291 289
 
292 290
 -------------------------------------------------------
293  
-$ ruby unit/post_test.rb              
  291
+$ ruby unit/post_test.rb -n test_should_not_save_post_without_title
294 292
 Loaded suite unit/post_test
295 293
 Started
296  
-F.
297  
-Finished in 0.027274 seconds.
  294
+F
  295
+Finished in 0.197094 seconds.
298 296
 
299 297
   1) Failure:
300  
-test_should_have_atleast_one_post(PostTest)
301  
-    [unit/post_test.rb:12:in `test_should_have_atleast_one_post'
  298
+test_should_not_save_post_without_title(PostTest)
  299
+    [unit/post_test.rb:11:in `test_should_not_save_post_without_title'
302 300
      /opt/local/lib/ruby/gems/1.8/gems/activesupport-2.1.1/lib/active_support/testing/setup_and_teardown.rb:33:in `__send__'
303 301
      /opt/local/lib/ruby/gems/1.8/gems/activesupport-2.1.1/lib/active_support/testing/setup_and_teardown.rb:33:in `run']:
304  
-<nil> expected to not be nil.
  302
+<false> is not true.
305 303
 
306  
-2 tests, 2 assertions, 1 failures, 0 errors
  304
+1 tests, 1 assertions, 1 failures, 0 errors
307 305
 -------------------------------------------------------
308 306
 
309 307
 In the output, +F+ denotes a failure. You can see the corresponding trace shown under +1)+ along with the name of the failing test. The next few lines contain the stack trace followed by a message which mentions the actual value and the expected value by the assertion. The default assertion messages provide just enough information to help pinpoint the error. To make the assertion failure message more readable every assertion provides an optional message parameter, as shown here:
310 308
 
311 309
 [source,ruby]
312 310
 --------------------------------------------------
313  
-def test_should_have_atleast_one_post
314  
-  post = Post.find(:first)
315  
-  assert_not_nil post, "Should not be nil as Posts table should have atleast one post"
  311
+def test_should_not_save_post_without_title
  312
+  post = Post.new
  313
+  assert !post.save, "Saved the post without a title"
316 314
 end
317 315
 --------------------------------------------------
318 316
 
319 317
 Running this test shows the friendlier assertion message:
320 318
 
321 319
 -------------------------------------------------------
322  
-$ ruby unit/post_test.rb
  320
+$ ruby unit/post_test.rb -n test_should_not_save_post_without_title
323 321
 Loaded suite unit/post_test
324 322
 Started
325  
-F.
326  
-Finished in 0.024727 seconds.
  323
+F
  324
+Finished in 0.198093 seconds.
327 325
 
328 326
   1) Failure:
329  
-test_should_have_atleast_one_post(PostTest)
330  
-    [unit/post_test.rb:11:in `test_should_have_atleast_one_post'
  327
+test_should_not_save_post_without_title(PostTest)
  328
+    [unit/post_test.rb:11:in `test_should_not_save_post_without_title'
331 329
      /opt/local/lib/ruby/gems/1.8/gems/activesupport-2.1.1/lib/active_support/testing/setup_and_teardown.rb:33:in `__send__'
332 330
      /opt/local/lib/ruby/gems/1.8/gems/activesupport-2.1.1/lib/active_support/testing/setup_and_teardown.rb:33:in `run']:
333  
-Should not be nil as Posts table should have atleast one post.
334  
-<nil> expected to not be nil.
  331
+Saved the post without a title.
  332
+<false> is not true.
  333
+
  334
+1 tests, 1 assertions, 1 failures, 0 errors
  335
+-------------------------------------------------------
  336
+
  337
+Now to get this test to pass we can add a model level validation for the _title_ field.
  338
+
  339
+[source,ruby]
  340
+--------------------------------------------------
  341
+class Post < ActiveRecord::Base
  342
+  validates_presence_of :title
  343
+end
  344
+--------------------------------------------------
  345
+
  346
+Now the test should pass. Let us verify by running the test again:
  347
+
  348
+-------------------------------------------------------
  349
+$ ruby unit/post_test.rb -n test_should_not_save_post_without_title
  350
+Loaded suite unit/post_test
  351
+Started
  352
+.
  353
+Finished in 0.193608 seconds.
335 354
 
336  
-2 tests, 2 assertions, 1 failures, 0 errors
  355
+1 tests, 1 assertions, 0 failures, 0 errors
337 356
 -------------------------------------------------------
338 357
 
  358
+Now if you noticed we first wrote a test which fails for a desired functionality, then we wrote some code which adds the functionality and finally we ensured that our test passes. This approach to software development is referred to as _Test-Driven Development_ (TDD). 
  359
+
  360
+TIP: Many Rails developers practice _Test-Driven Development_ (TDD). This is an excellent way to build up a test suite that exercises every part of your application. TDD is beyond the scope of this guide, but one place to start is with link:http://andrzejonsoftware.blogspot.com/2007/05/15-tdd-steps-to-create-rails.html[15 TDD steps to create a Rails application].
  361
+
339 362
 To see how an error gets reported, here's a test containing an error:
340 363
 
341 364
 [source,ruby]
@@ -350,29 +373,21 @@ end
350 373
 Now you can see even more output in the console from running the tests:
351 374
 
352 375
 -------------------------------------------------------
353  
-$ ruby unit/post_test.rb
  376
+$ ruby unit/post_test.rb -n test_should_report_error
354 377
 Loaded suite unit/post_test
355 378
 Started
356  
-FE.
357  
-Finished in 0.108389 seconds.
358  
-
359  
-  1) Failure:
360  
-test_should_have_atleast_one_post(PostTest)
361  
-    [unit/post_test.rb:11:in `test_should_have_atleast_one_post'
362  
-     /opt/local/lib/ruby/gems/1.8/gems/activesupport-2.1.1/lib/active_support/testing/setup_and_teardown.rb:33:in `__send__'
363  
-     /opt/local/lib/ruby/gems/1.8/gems/activesupport-2.1.1/lib/active_support/testing/setup_and_teardown.rb:33:in `run']:
364  
-Should not be nil as Posts table should have atleast one post.
365  
-<nil> expected to not be nil.
  379
+E
  380
+Finished in 0.195757 seconds.
366 381
 
367  
-  2) Error:
  382
+  1) Error:
368 383
 test_should_report_error(PostTest):
369  
-NameError: undefined local variable or method `some_undefined_variable' for #<PostTest:0x304a7b0>
  384
+NameError: undefined local variable or method `some_undefined_variable' for #<PostTest:0x2cc9de8>
370 385
     /opt/local/lib/ruby/gems/1.8/gems/actionpack-2.1.1/lib/action_controller/test_process.rb:467:in `method_missing'
371  
-    unit/post_test.rb:15:in `test_should_report_error'
  386
+    unit/post_test.rb:16:in `test_should_report_error'
372 387
     /opt/local/lib/ruby/gems/1.8/gems/activesupport-2.1.1/lib/active_support/testing/setup_and_teardown.rb:33:in `__send__'
373 388
     /opt/local/lib/ruby/gems/1.8/gems/activesupport-2.1.1/lib/active_support/testing/setup_and_teardown.rb:33:in `run'
374 389
 
375  
-3 tests, 2 assertions, 1 failures, 1 errors
  390
+1 tests, 0 assertions, 0 failures, 1 errors
376 391
 -------------------------------------------------------
377 392
 
378 393
 Notice the 'E' in the output. It denotes a test with error. 
@@ -383,8 +398,6 @@ NOTE: The execution of each test method stops as soon as any error or a assertio
383 398
 
384 399
 Ideally you would like to include a test for everything which could possibly break. It's a good practice to have at least one test for each of your validations and at least one test for every method in your model.
385 400
 
386  
-TIP: Many Rails developers practice _test-driven development_ (TDD), in which the tests are written _before_ the code that they are testing. This is an excellent way to build up a test suite that exercises every part of your application. TDD is beyond the scope of this guide, but one place to start is with link:http://andrzejonsoftware.blogspot.com/2007/05/15-tdd-steps-to-create-rails.html[15 TDD steps to create a Rails application].
387  
-
388 401
 === Assertions Available ===
389 402
 
390 403
 By now you've caught a glimpse of some of the assertions that are available. Assertions are the worker bees of testing. They are the ones that actually perform the checks to ensure that things are going as planned.
@@ -454,32 +467,9 @@ You should test for things such as:
454 467
  * was the correct object stored in the response template?
455 468
  * was the appropriate message displayed to the user in the view
456 469
 
457  
-When you use +script/generate+ to create a controller, it automatically creates a functional test for that controller in +test/functional+. For example, if you create a post controller:
458  
-
459  
-[source, shell]
460  
--------------------------------------------------------
461  
-$ script/generate controller post
462  
-...
463  
-      create  app/controllers/post_controller.rb
464  
-      create  test/functional/post_controller_test.rb
465  
-...
466  
--------------------------------------------------------
467  
-
468  
-Now if you take a look at the file +posts_controller_test.rb+ in the +test/functional+ directory, you should see:
469  
-
470  
-[source,ruby]
471  
---------------------------------------------------
472  
-require 'test_helper'
473  
-
474  
-class PostsControllerTest < ActionController::TestCase
475  
-  # Replace this with your real tests.
476  
-  def test_truth
477  
-    assert true
478  
-  end
479  
-end
480  
---------------------------------------------------
  470
+Now that we have used Rails scaffold generator for our +Post+ resource, it has already created the controller code and functional tests. You can take look at the file +posts_controller_test.rb+ in the +test/functional+ directory.
481 471
 
482  
-Of course, you need to replace the simple assertion with real testing. Here's a starting example of a functional test:
  472
+Let me take you through one such test, +test_should_get_index+ from the file +posts_controller_test.rb+.
483 473
 
484 474
 [source,ruby]
485 475
 --------------------------------------------------
@@ -513,6 +503,23 @@ Another example: Calling the +:view+ action, passing an +id+ of 12 as the +param
513 503
 get(:view, {'id' => '12'}, nil, {'message' => 'booya!'})
514 504
 --------------------------------------------------
515 505
 
  506
+NOTE: If you try running +test_should_create_post+ test from +posts_controller_test.rb+ it will fail on account of the newly added model level validation and rightly so.
  507
+
  508
+Let us modify +test_should_create_post+ test in +posts_controller_test.rb+ so that all our test pass:
  509
+
  510
+[source,ruby]