railties 3.0.0.rc → 3.0.0.rc2

data/guides/source/ajax_on_rails.textile

@@ -47,7 +47,7 @@ Let's start with the the probably most often used helper: +link_to_remote+, whic
 The signature of +link_to_remote+ function is the same as that of the standard +link_to+ helper:
 
 <ruby>
-def link_to_remote(name, options = {}, html_options = nil)	
+def link_to_remote(name, options = {}, html_options = nil)
 </ruby>
 
 And here is a simple example of link_to_remote in action:
@@ -98,7 +98,7 @@ link_to_remote "Delete the item",
 Note that if we wouldn't override the default behavior (POST), the above snippet would route to the create action rather than destroy.
 
 ** *JavaScript filters* You can customize the remote call further by wrapping it with some JavaScript code. Let's say in the previous example, when deleting a link, you'd like to ask for a confirmation by showing a simple modal text box to the user. This is a typical example what you can accomplish with these options - let's see them one by one:
-*** +:confirm+ =&gt; +msg+ Pops up a JavaScript confirmation dialog, displaying +msg+. If the user chooses 'OK', the request is launched, otherwise canceled. 
+*** +:confirm+ =&gt; +msg+ Pops up a JavaScript confirmation dialog, displaying +msg+. If the user chooses 'OK', the request is launched, otherwise canceled.
 *** +:condition+ =&gt; +code+ Evaluates +code+ (which should evaluate to a boolean) and proceeds if it's true, cancels the request otherwise.
 *** +:before+ =&gt; +code+ Evaluates the +code+ just before launching the request. The output of the code has no influence on the execution. Typically used show a progress indicator (see this in action in the next example).
 *** +:after+ =&gt; +code+ Evaluates the +code+ after launching the request. Note that this is different from the +:success+ or +:complete+ callback (covered in the next section) since those are triggered after the request is completed, while the code snippet passed to +:after+ is evaluated after the remote call is made. A common example is to disable elements on the page or otherwise prevent further action while the request is completed.
@@ -115,8 +115,8 @@ link_to_remote "Update record",
 This generates a remote link which adds 2 parameters to the standard URL generated by Rails, taken from the page (contained in the elements matched by the 'status' and 'completed' DOM id).
 
 ** *Callbacks* Since an AJAX call is typically asynchronous, as it's name suggests (this is not a rule, and you can fire a synchronous request - see the last option, +:type+) your only way of communicating with a request once it is fired is via specifying callbacks. There are six options at your disposal (in fact 508, counting all possible response types, but these six are the most frequent and therefore specified by a constant):
-*** +:loading:+ =&gt; +code+ The request is in the process of receiving the data, but the transfer is not completed yet. 
-*** +:loaded:+ =&gt; +code+ The transfer is completed, but the data is not processed and returned yet 			
+*** +:loading:+ =&gt; +code+ The request is in the process of receiving the data, but the transfer is not completed yet.
+*** +:loaded:+ =&gt; +code+ The transfer is completed, but the data is not processed and returned yet
 *** +:interactive:+ =&gt; +code+ One step after +:loaded+: The data is fully received and being processed
 *** +:success:+ =&gt; +code+ The data is fully received, parsed and the server responded with "200 OK"
 *** +:failure:+ =&gt; +code+ The data is fully received, parsed and the server responded with *anything* but "200 OK" (typically 404 or 500, but in general with any status code ranging from 100 to 509)
@@ -143,15 +143,15 @@ link_to_remote "Add new item",
 ** If you specify the +href+ parameter, the AJAX link will degrade gracefully, i.e. the link will point to the URL even if JavaScript is disabled in the client browser
 ** +link_to_remote+ gains it's AJAX behavior by specifying the remote call in the onclick handler of the link. If you supply +html_options[:onclick]+ you override the default behavior, so use this with care!
 
-We are finished with +link_to_remote+. I know this is quite a lot to digest for one helper function, but remember, these options are common for all the rest of the Rails view helpers, so we will take a look at the differences / additional parameters in the next sections. 
+We are finished with +link_to_remote+. I know this is quite a lot to digest for one helper function, but remember, these options are common for all the rest of the Rails view helpers, so we will take a look at the differences / additional parameters in the next sections.
 
 h4. AJAX Forms
 
 There are three different ways of adding AJAX forms to your view using Rails Prototype helpers. They are slightly different, but striving for the same goal: instead of submitting the form using the standard HTTP request/response cycle, it is submitted asynchronously, thus not reloading the page. These methods are the following:
 
 * +remote_form_for+ (and it's alias +form_remote_for+) is tied to Rails most tightly of the three since it takes a resource, model or array of resources (in case of a nested resource) as a parameter.
-* +form_remote_tag+ AJAXifies the form by serializing and sending it's data in the background 
-* +submit_to_remote+ and +button_to_remote+ is more rarely used than the previous two. Rather than creating an AJAX form, you add a button/input 
+* +form_remote_tag+ AJAXifies the form by serializing and sending it's data in the background
+* +submit_to_remote+ and +button_to_remote+ is more rarely used than the previous two. Rather than creating an AJAX form, you add a button/input
 
 Let's se them in action one by one!
 
@@ -161,7 +161,7 @@ h5. +form_remote_tag+
 
 h5. +submit_to_remote+
 
-h4. Observing Elements 
+h4. Observing Elements
 
 h5. +observe_field+
 
@@ -186,10 +186,10 @@ In the last section we sent some AJAX requests to the server, and inserted the H
 h4. Javascript without RJS
 
 First we'll check out how to send JavaScript to the server manually. You are practically never going to need this, but it's interesting to understand what's going on under the hood.
-  
+
 <ruby>
 def javascript_test
-  render :text => "alert('Hello, world!')", 
+  render :text => "alert('Hello, world!')",
          :content_type => "text/javascript"
 end
 </ruby>
@@ -207,14 +207,14 @@ def javascript_test
   render :update do |page|
     page.alert "Hello from inline RJS"
   end
-end	
+end
 </ruby>
 
-The above code snippet does exactly the same as the one in the previous section - going about it much more elegantly though. You don't need to worry about headers,write ugly JavaScript code into a string etc. When the first parameter to +render+ is +:update+, Rails expects a block with a single parameter (+page+ in our case, which is the traditional naming convention) which is an instance of the JavaScriptGenerator:"http://api.rubyonrails.org/classes/ActionView/Helpers/PrototypeHelper/JavaScriptGenerator/GeneratorMethods.html" object. As it's name  suggests, JavaScriptGenerator is responsible for generating JavaScript from your Ruby code. You can execute multiple method calls on the +page+ instance - it's all turned into JavaScript code and sent to the server with the appropriate Content Type, "text/javascript". 
+The above code snippet does exactly the same as the one in the previous section - going about it much more elegantly though. You don't need to worry about headers,write ugly JavaScript code into a string etc. When the first parameter to +render+ is +:update+, Rails expects a block with a single parameter (+page+ in our case, which is the traditional naming convention) which is an instance of the JavaScriptGenerator:"http://api.rubyonrails.org/classes/ActionView/Helpers/PrototypeHelper/JavaScriptGenerator/GeneratorMethods.html" object. As it's name  suggests, JavaScriptGenerator is responsible for generating JavaScript from your Ruby code. You can execute multiple method calls on the +page+ instance - it's all turned into JavaScript code and sent to the server with the appropriate Content Type, "text/javascript".
 
 h4. RJS Templates
 
-If you don't want to clutter your controllers with view code (especially when your inline RJS is more than a few lines), you can move your RJS code to a template file. RJS templates should go to the +/app/views/+ directory, just as +.html.erb+ or any other view files of the appropriate controller, conventionally named +js.rjs+. 
+If you don't want to clutter your controllers with view code (especially when your inline RJS is more than a few lines), you can move your RJS code to a template file. RJS templates should go to the +/app/views/+ directory, just as +.html.erb+ or any other view files of the appropriate controller, conventionally named +js.rjs+.
 
 To rewrite the above example, you can leave the body of the action empty, and create a RJS template named +javascript_test.js.rjs+, containing the following line:
 
@@ -265,7 +265,7 @@ The third parameter can either be a string, or a hash of options to be passed to
 page.insert_html :top, :result, :partial => "the_answer"
 </ruby>
 
-You can replace the contents (innerHTML) of an element with the +replace_html+ method. The only difference is that since it's clear where should the new content go, there is no need for a position parameter - so +replace_html+ takes only two arguments, 
+You can replace the contents (innerHTML) of an element with the +replace_html+ method. The only difference is that since it's clear where should the new content go, there is no need for a position parameter - so +replace_html+ takes only two arguments,
 the DOM id of the element you wish to modify and a string or a hash of options to be passed to ActionView::Base#render.
 
 h6. Delay
@@ -273,7 +273,7 @@ h6. Delay
 You can delay the execution of a block of code with +delay+:
 
 <ruby>
-page.delay(10) { page.alert('Hey! Just waited 10 seconds') }	
+page.delay(10) { page.alert('Hey! Just waited 10 seconds') }
 </ruby>
 
 +delay+ takes one parameter (time to wait in seconds) and a block which will be executed after the specified time has passed - whatever else follows a +page.delay+ line is executed immediately, the delay affects only the code in the block.
@@ -283,7 +283,7 @@ h6. Reloading and Redirecting
 You can reload the page with the +reload+ method:
 
 <ruby>
-page.reload	
+page.reload
 </ruby>
 
 When using AJAX, you can't rely on the standard +redirect_to+ controller method - you have to use the +page+'s instance method, also called +redirect_to+:
@@ -292,7 +292,7 @@ When using AJAX, you can't rely on the standard +redirect_to+ controller method
 page.redirect_to some_url
 </ruby>
 
-h6. Generating Arbitrary JavaScript 
+h6. Generating Arbitrary JavaScript
 
 Sometimes even the full power of RJS is not enough to accomplish everything, but you still don't want to drop to pure JavaScript. A nice golden mean is offered by the combination of +<<+, +assign+ and +call+ methods:
 

data/guides/source/api_documentation_guidelines.textile

@@ -25,11 +25,11 @@ end
 
 Communicate to the reader the current way of doing things, both explicitly and implicitly. Use the recommended idioms in edge, reorder sections to emphasize favored approaches if needed, etc. The documentation should be a model for best practices and canonical, modern Rails usage.
 
-Documentation has to be concise but comprehensive. Explore and document edge cases. What happens if a module is anonymous? What if a collection is empty? What if an argument is nil? 
+Documentation has to be concise but comprehensive. Explore and document edge cases. What happens if a module is anonymous? What if a collection is empty? What if an argument is nil?
 
 The proper names of Rails components have a space in between the words, like "Active Support". +ActiveRecord+ is a Ruby module, whereas Active Record is an ORM. Historically there has been lack of consistency regarding this, but we checked with David when docrails started. All Rails documentation consistently refer to Rails components by their proper name, and if in your next blog post or presentation you remember this tidbit and take it into account that'd be fenomenal :).
 
-Spell names correctly: HTML, MySQL, JavaScript, ERb.
+Spell names correctly: HTML, MySQL, JavaScript, ERb. Use the article "an" for "SQL", as in "an SQL statement". Also "an SQLite database".
 
 h3. Example Code
 
@@ -125,7 +125,7 @@ def copy_instance_variables_from(object, exclude = [])
 end
 </ruby>
 
-WARNING: Using a pair of +&#43;...&#43;+ for fixed-width font only works with *words*; that is: anything matching <tt>\A\w&#43;\z</tt>. For anything else  use +&lt;tt&gt;...&lt;/tt&gt;+, notably symbols, setters, inline snippets, etc: 
+WARNING: Using a pair of +&#43;...&#43;+ for fixed-width font only works with *words*; that is: anything matching <tt>\A\w&#43;\z</tt>. For anything else  use +&lt;tt&gt;...&lt;/tt&gt;+, notably symbols, setters, inline snippets, etc:
 
 h4. Regular Font
 

data/guides/source/association_basics.textile

@@ -1401,8 +1401,8 @@ person = Person.create(:name => 'honda')
 post   = Post.create(:name => 'a1')
 person.posts << post
 person.posts << post
-person.posts.inspect # => [#<Post id: 7, name: "a1">] 
-Reading.all.inspect  # => [#<Reading id: 16, person_id: 7, post_id: 7>, #<Reading id: 17, person_id: 7, post_id: 7>] 
+person.posts.inspect # => [#<Post id: 7, name: "a1">]
+Reading.all.inspect  # => [#<Reading id: 16, person_id: 7, post_id: 7>, #<Reading id: 17, person_id: 7, post_id: 7>]
 </ruby>
 
 In the above case there are still two readings. However +person.posts+ shows only one post because the collection loads only unique records.

data/guides/source/caching_with_rails.textile

@@ -98,7 +98,7 @@ You can also use +:if+ (or +:unless+) to pass a Proc that specifies when the act
 
 You can modify the default action cache path by passing a +:cache_path+ option. This will be passed directly to +ActionCachePath.path_for+. This is handy for actions with multiple possible routes that should be cached differently. If a block is given, it is called with the current controller instance.
 
-Finally, if you are using memcached, you can also pass +:expires_in+. In fact, all parameters not used by +caches_action+ are sent to the underlying cache store. 
+Finally, if you are using memcached, you can also pass +:expires_in+. In fact, all parameters not used by +caches_action+ are sent to the underlying cache store.
 
 INFO: Action caching runs in an after filter. Thus, invalid requests won't generate spurious cache entries as long as you halt them. Typically, a redirection in some before filter that checks request preconditions does the job.
 
@@ -242,12 +242,12 @@ Rails 2.1 and above provide +ActiveSupport::Cache::Store+ which can be used to c
 
 The default cache stores provided with Rails include:
 
-1) +ActiveSupport::Cache::MemoryStore+: A cache store implementation which stores everything into memory in the same process. If you're running multiple Ruby on Rails server processes (which is the case if you're using mongrel_cluster or Phusion Passenger), then this means that your Rails server process instances won't be able to share cache data with each other. If your application never performs manual cache item expiry (e.g. when you‘re using generational cache keys), then using +MemoryStore+ is ok. Otherwise, consider carefully whether you should be using this cache store.  
+1) +ActiveSupport::Cache::MemoryStore+: A cache store implementation which stores everything into memory in the same process. If you're running multiple Ruby on Rails server processes (which is the case if you're using mongrel_cluster or Phusion Passenger), then this means that your Rails server process instances won't be able to share cache data with each other. If your application never performs manual cache item expiry (e.g. when you‘re using generational cache keys), then using +MemoryStore+ is ok. Otherwise, consider carefully whether you should be using this cache store.
 
 +MemoryStore+  is not only able to store strings, but also arbitrary Ruby objects.
 
 +MemoryStore+  is not thread-safe. Use +SynchronizedMemoryStore+ instead if you need thread-safety.
-                                      
+
 <ruby>
 ActionController::Base.cache_store = :memory_store
 </ruby>
@@ -280,7 +280,7 @@ It also accepts a hash of additional options:
 
 The read and write methods of the +MemCacheStore+ accept an options hash too. When reading you can specify +:raw => true+ to prevent the object being marshaled (by default this is false which means the raw value in the cache is passed to +Marshal.load+ before being returned to you.)
 
-When writing to the cache it is also possible to specify +:raw => true+ means the value is not passed to +Marshal.dump+ before being stored in the cache (by default this is false). 
+When writing to the cache it is also possible to specify +:raw => true+ means the value is not passed to +Marshal.dump+ before being stored in the cache (by default this is false).
 
 The write method also accepts an +:unless_exist+ flag which determines whether the memcached add (when true) or set (when false) method is used to store the item in the cache and an +:expires_in+ option that specifies the time-to-live for the cached item in seconds.
 
@@ -367,7 +367,7 @@ h3. Advanced Caching
 Along with the built-in mechanisms outlined above, a number of excellent plugins exist to help with finer grained control over caching. These include Chris Wanstrath's excellent cache_fu plugin (more info "here": http://errtheblog.com/posts/57-kickin-ass-w-cachefu) and Evan Weaver's interlock plugin (more info "here": http://blog.evanweaver.com/articles/2007/12/13/better-rails-caching/). Both of these plugins play nice with memcached and are a must-see for anyone
 seriously considering optimizing their caching needs.
 
-Also the new "Cache money":http://github.com/nkallen/cache-money/tree/master plugin is supposed to be mad cool. 
+Also the new "Cache money":http://github.com/nkallen/cache-money/tree/master plugin is supposed to be mad cool.
 
 h3. References
 

data/guides/source/command_line.textile

@@ -23,19 +23,19 @@ There are a few commands that are absolutely critical to your everyday usage of
 * <tt>rake</tt>
 * <tt>rails generate</tt>
 * <tt>rails dbconsole</tt>
-* <tt>rails app_name</tt>
+* <tt>rails new app_name</tt>
 
 Let's create a simple Rails application to step through each of these commands in context.
 
-h4. +rails+
+h4. +rails new+
 
-The first thing we'll want to do is create a new Rails application by running the +rails+ command after installing Rails.
+The first thing we'll want to do is create a new Rails application by running the +rails new+ command after installing Rails.
 
 WARNING: You know you need the rails gem installed by typing +gem install rails+ first, if you don't have this installed, follow the instructions in the "Rails 3 Release Notes":/3_0_release_notes.html
 
 <shell>
-$ rails commandsapp
-     create  
+$ rails new commandsapp
+     create
      create  README
      create  .gitignore
      create  Rakefile
@@ -352,7 +352,7 @@ $ mkdir gitapp
 $ cd gitapp
 $ git init
 Initialized empty Git repository in .git/
-$ rails . --git --database=postgresql
+$ rails new . --git --database=postgresql
       exists
       create  app/controllers
       create  app/helpers
@@ -397,7 +397,7 @@ development:
 ...
 </shell>
 
-It also generated some lines in our database.yml configuration corresponding to our choice of PostgreSQL for database. The only catch with using the SCM options is that you have to make your application's directory first, then initialize your SCM, then you can run the +rails+ command to generate the basis of your app.
+It also generated some lines in our database.yml configuration corresponding to our choice of PostgreSQL for database. The only catch with using the SCM options is that you have to make your application's directory first, then initialize your SCM, then you can run the +rails new+ command to generate the basis of your app.
 
 h4. +server+ with Different Backends
 
@@ -570,7 +570,7 @@ h5. +test:+ Rails tests
 
 INFO: A good description of unit testing in Rails is given in "A Guide to Testing Rails Applications":testing.html
 
-Rails comes with a test suite called Test::Unit. It is through the use of tests that Rails itself is so stable, and the slew of people working on Rails can prove that everything works as it should. 
+Rails comes with a test suite called Test::Unit. It is through the use of tests that Rails itself is so stable, and the slew of people working on Rails can prove that everything works as it should.
 
 The +test:+ namespace helps in running the different tests you will (hopefully!) write.
 

data/guides/source/configuring.textile

@@ -51,15 +51,15 @@ h4. Rails General Configuration
 
 * +config.dependency_loading+ enables or disables dependency loading during the request cycle. Setting dependency_loading to _true_ will allow new classes to be loaded during a request and setting it to _false_ will disable this behavior.
 
-* +config.eager_load_paths+ accepts an array of paths from which Rails will eager load on boot if cache classes is enabled. All elements of this array must also be in +load_paths+. 
+* +config.eager_load_paths+ accepts an array of paths from which Rails will eager load on boot if cache classes is enabled. All elements of this array must also be in +load_paths+.
 
 * +config.load_once_paths+ accepts an array of paths from which Rails will automatically load from only once. All elements of this array must also be in +load_paths+.
 
-* +config.load_paths+ accepts an array of additional paths to prepend to the load path. By default, all app, lib, vendor and mock paths are included in this list. 
+* +config.load_paths+ accepts an array of additional paths to prepend to the load path. By default, all app, lib, vendor and mock paths are included in this list.
 
-* +config.log_level+ defines the verbosity of the Rails logger. In production mode, this defaults to +:info+. In development mode, it defaults to +:debug+. 
+* +config.log_level+ defines the verbosity of the Rails logger. In production mode, this defaults to +:info+. In development mode, it defaults to +:debug+.
 
-* +config.log_path+ overrides the path to the log file to use. Defaults to +log/#{environment}.log+ (e.g. log/development.log or log/production.log). 
+* +config.log_path+ overrides the path to the log file to use. Defaults to +log/#{environment}.log+ (e.g. log/development.log or log/production.log).
 
 * +config.logger+ accepts a logger conforming to the interface of Log4r or the default Ruby 1.8+ Logger class, which is then used to log information from Action Controller. Set to nil to disable logging.
 
@@ -73,7 +73,7 @@ h4. Rails General Configuration
 
 * +config.preload_frameworks+ enables or disables preloading all frameworks at startup.
 
-* +config.reload_plugins+ enables or disables plugin reloading. 
+* +config.reload_plugins+ enables or disables plugin reloading.
 
 * +config.root_path+ configures the root path of the application.
 
@@ -181,7 +181,7 @@ There are only a few configuration options for Action View, starting with four o
 
 * +config.action_view.warn_cache_misses+ tells Rails to display a warning whenever an action results in a cache miss on your view paths. The default is +false+.
 
-* +config.action_view.field_error_proc+ provides an HTML generator for displaying errors that come from Active Record. The default is <tt>Proc.new{ |html_tag, instance| "&lt;div class=\"field_with_errors\"&gt;#{html_tag}&lt;/div&gt;" }</tt>
+* +config.action_view.field_error_proc+ provides an HTML generator for displaying errors that come from Active Record. The default is <tt>Proc.new{ |html_tag, instance| %Q(%&lt;div class=&quot;field_with_errors&quot;&gt;#{html_tag}&lt;/div&gt;).html_safe }</tt>
 
 * +config.action_view.default_form_builder+ tells Rails which form builder to use by default. The default is +ActionView::Helpers::FormBuilder+.
 

data/guides/source/contributing_to_rails.textile

@@ -48,7 +48,7 @@ h4. Install git
 
 Rails uses git for source code control. You won’t be able to do anything without the Rails source code, and this is a prerequisite. The "git homepage":http://git-scm.com/ has installation instructions. If you’re on OS X, use the "Git for OS X":http://code.google.com/p/git-osx-installer/ installer. If you're unfamiliar with git, there are a variety of resources on the net that will help you learn more:
 
-* "Everyday Git":http://www.kernel.org/pub/software/scm/git/docs/everyday.html will teach you just enough about git to get by. 
+* "Everyday Git":http://www.kernel.org/pub/software/scm/git/docs/everyday.html will teach you just enough about git to get by.
 * The "PeepCode screencast":https://peepcode.com/products/git on git ($9) is easier to follow.
 * "GitHub":http://github.com/guides/home offers links to a variety of git resources.
 * "Pro Git":http://progit.org/book/ is an entire book about git with a Creative Commons license.
@@ -58,7 +58,7 @@ h4. Get the Rails Source Code
 Don’t fork the main Rails repository. Instead, you want to clone it to your own computer. Navigate to the folder where you want the source code (it will create its own /rails subdirectory) and run:
 
 <shell>
-git clone git://github.com/rails/rails.git  
+git clone git://github.com/rails/rails.git
 cd rails
 </shell>
 
@@ -66,8 +66,10 @@ h4. Set up and Run the Tests
 
 All of the Rails tests must pass with any code you submit, otherwise you have no chance of getting code accepted. This means you need to be able to run the tests. First, you need to install all Rails dependencies with bundler:
 
+NOTE: Ensure you install bundler v1.0
+
 <shell>
-gem install bundler
+gem install -v=1.0.0.rc.6 bundler
 bundle install --without db
 </shell>
 
@@ -90,7 +92,7 @@ By default, when you run Active Record tests, it will execute the test suite thr
 
 <shell>
 cd activerecord
-rake test_sqlite3 
+rake test_sqlite3
 rake test_sqlite3 TEST=test/cases/validations_test.rb
 </shell>
 
@@ -258,15 +260,15 @@ h4. Update Rails
 Update your copy of Rails. It’s pretty likely that other changes to core Rails have happened while you were working. Go get them:
 
 <shell>
-git checkout master  
-git pull  
+git checkout master
+git pull
 </shell>
 
 Now reapply your patch on top of the latest changes:
 
 <shell>
-git checkout my_new_branch  
-git rebase master  
+git checkout my_new_branch
+git rebase master
 </shell>
 
 No conflicts? Tests still pass? Change still seems reasonable to you? Then move on.
@@ -276,8 +278,8 @@ h4. Create a Patch
 Now you can create a patch file to share with other developers (and with the Rails core team). Still in your branch, run
 
 <shell>
-git commit -a  
-git format-patch master --stdout > my_new_patch.diff  
+git commit -a
+git format-patch master --stdout > my_new_patch.diff
 </shell>
 
 Sanity check the results of this operation: open the diff file in your text editor of choice and make sure that no unintended changes crept in.
@@ -302,4 +304,5 @@ h3. Changelog
 
 * April 6, 2010: Fixed document to validate XHTML 1.0 Strict. "Jaime Iniesta":http://jaimeiniesta.com
 * August 1, 2009: Updates/amplifications by "Mike Gunderloy":credits.html#mgunderloy
-* March 2, 2009: Initial draft by "Mike Gunderloy":credits.html#mgunderloy
+* March 2, 2009: Initial draft by "Mike Gunderloy":credits.html#mgunderloy
+

data/guides/source/debugging_rails_applications.textile

@@ -96,23 +96,25 @@ Will be rendered as follows:
 Title: Rails debugging guide
 </pre>
 
-h4. Debugging JavaScript
+h4. Debugging RJS
 
-Rails has built-in support to debug RJS, to active it, set +ActionView::Base.debug_rjs+ to _true_, 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).
+Rails has optional built-in support to debug RJS. When enabled, responses are wrapped in a try/catch block that displays the caught exception using +alert()+, and then re-raises it.
 
-To enable it, add the following in the +Rails::Initializer do |config|+ block inside +environment.rb+:
+The flag to enable RJS debugging in your configuration files is +config.action_view.debug_rjs+:
 
 <ruby>
-config.action_view[:debug_rjs] = true
+config.action_view.debug_rjs = true
 </ruby>
 
-Or, at any time, setting +ActionView::Base.debug_rjs+ to _true_:
+or at any time setting +ActionView::Base.debug_rjs+:
 
 <ruby>
 ActionView::Base.debug_rjs = true
 </ruby>
 
-TIP: For more information on debugging javascript refer to "Firebug":http://getfirebug.com/, the popular debugger for Firefox.
+It is enabled by default in development mode, and disabled in the rest.
+
+TIP: For more information on debugging JavaScript, refer to "Firebug":http://getfirebug.com/, the popular debugger for Firefox.
 
 h3. The Logger
 

data/guides/source/form_helpers.textile

@@ -647,7 +647,7 @@ the +params+ hash will contain
 {'person' => {'name' => 'Henry'}}
 </erb>
 
-and +params["name"]+ will retrieve the submitted value in the controller.
+and +params[:person][:name]+ will retrieve the submitted value in the controller.
 
 Hashes can be nested as many levels as required, for example
 

data/guides/source/generators.textile

@@ -1,6 +1,6 @@
 h2. Creating and Customizing Rails Generators
 
-Rails generators are an essential tool if you plan to improve your workflow and in this guide you will learn how to create and customize already existing generators.
+Rails generators are an essential tool if you plan to improve your workflow. With this guide you will learn how to create generators and customize existing ones.
 
 In this guide you will:
 
@@ -13,7 +13,7 @@ In this guide you will:
 
 endprologue.
 
-NOTE: This guide is about Rails generators for versions >= 3.0. Rails generators from previous versions are not supported.
+NOTE: This guide is about generators in Rails 3, previous versions are not covered.
 
 h3. First Contact
 
@@ -35,7 +35,7 @@ h3. Creating Your First Generator
 
 Since Rails 3.0, generators are built on top of "Thor":http://github.com/wycats/thor. Thor provides powerful options parsing and a great API for manipulating files. For instance, let's build a generator that creates an initializer file named +initializer.rb+ inside +config/initializers+.
 
-The first step is to create a file at +RAILS_APP/lib/generators/initializer_generator.rb+ with the following content:
+The first step is to create a file at +lib/generators/initializer_generator.rb+ with the following content:
 
 <ruby>
 class InitializerGenerator < Rails::Generators::Base
@@ -74,7 +74,7 @@ Now we can see the new description by invoking +--help+ on the new generator. Th
 
 h3. Creating Generators with Generators
 
-A faster way to create a generator is using the generator's generator:
+Generators themselves have a generator:
 
 <shell>
 $ rails generate generator initializer
@@ -84,7 +84,7 @@ $ rails generate generator initializer
       create  lib/generators/initializer/templates
 </shell>
 
-And it will create a new generator as follows:
+This is the generator just created:
 
 <ruby>
 class InitializerGenerator < Rails::Generators::NamedBase
@@ -92,7 +92,7 @@ class InitializerGenerator < Rails::Generators::NamedBase
 end
 </ruby>
 
-First, notice that we are inheriting from +Rails::Generators::NamedBase+ instead of +Rails::Generators::Base+. This means that our generator expects as least one argument, which will be the name of the initializer.
+First, notice that we are inheriting from +Rails::Generators::NamedBase+ instead of +Rails::Generators::Base+. This means that our generator expects at least one argument, which will be the name of the initializer.
 
 We can see that by invoking the description of this new generator (don't forget to delete the old generator file):
 
@@ -102,7 +102,9 @@ Usage:
   rails generate initializer NAME [options]
 </shell>
 
-We can also see in our new generator that it has a class method called +source_root+. This method points to where our generator templates will be placed and by default it points to the created directory under +RAILS_APP/lib/generators/initializer/templates+. In order to understand what a generator template means, let's create a file at +RAILS_APP/lib/generators/initializer/templates/initializer.rb+ with the following content:
+We can also see that our new generator has a class method called +source_root+. This method points to where our generator templates will be placed, if any, and by default it points to the created directory +lib/generators/initializer/templates+.
+
+In order to understand what a generator template means, let's create the file +lib/generators/initializer/templates/initializer.rb+ with the following content:
 
 <ruby>
 # Add initialization content here
@@ -124,16 +126,14 @@ end
 And let's execute our generator:
 
 <shell>
-$ rails generate initializer foo
+$ rails generate initializer core_extensions
 </shell>
 
-We can see that now a initializer named foo was created at +config/initializers/foo.rb+ with the contents of our template. That means that +copy_file+ copied a file in our source root to the destination path we gave. The method +file_name+ is automatically created when we inherit from +Rails::Generators::NamedBase+.
+We can see that now a initializer named core_extensions was created at +config/initializers/core_extensions.rb+ with the contents of our template. That means that +copy_file+ copied a file in our source root to the destination path we gave. The method +file_name+ is automatically created when we inherit from +Rails::Generators::NamedBase+.
 
 h3. Generators Lookup
 
-Now that we've created our first generator, we need to briefly discuss generator lookup. The way Rails finds generators is exactly the same way Ruby find files, i.e. using +$LOAD_PATHS+.
-
-For instance, when you say +rails generate initializer foo+, Rails knows you want to invoke the initializer generator and then search for the following generators in the $LOAD_PATHS:
+When you run +rails generate initializer core_extensions+ Rails requires these files in turn until one is found:
 
 <shell>
 rails/generators/initializer/initializer_generator.rb
@@ -142,11 +142,13 @@ rails/generators/initializer_generator.rb
 generators/initializer_generator.rb
 </shell>
 
-If none of them is found, it raises an error message.
+If none is found you get an error message.
+
+INFO: The examples above put files under the application's +lib+ because said directoty belongs to +$LOAD_PATH+.
 
 h3. Customizing Your Workflow
 
-Rails generators are flexible enough to let you customize your scaffold the way you want. In your +config/application.rb+ there is a section just for generators:
+Rails own generators are flexible enough to let you customize scaffolding. They can be configured in +config/application.rb+, these are some defaults:
 
 <ruby>
 config.generators do |g|
@@ -166,7 +168,7 @@ $ rails generate scaffold User name:string
       invoke    test_unit
       create      test/unit/user_test.rb
       create      test/fixtures/users.yml
-       route  map.resources :users
+       route  resources :users
       invoke  scaffold_controller
       create    app/controllers/users_controller.rb
       invoke    erb
@@ -186,9 +188,9 @@ $ rails generate scaffold User name:string
       create    public/stylesheets/scaffold.css
 </shell>
 
-Looking at this output, it's easy to understand how generators work on Rails 3.0 and above. The scaffold generator doesn't actually generate anything, it just invokes others to do the work. This allows us to add/replace/remove any of those invocations. For instance, the scaffold generator invokes the scaffold_controller generator, which invokes erb, test_unit and helper generators. Since each generator has a single responsibility, they are easy to reuse, avoiding code duplication.
+Looking at this output, it's easy to understand how generators work in Rails 3.0 and above. The scaffold generator doesn't actually generate anything, it just invokes others to do the work. This allows us to add/replace/remove any of those invocations. For instance, the scaffold generator invokes the scaffold_controller generator, which invokes erb, test_unit and helper generators. Since each generator has a single responsibility, they are easy to reuse, avoiding code duplication.
 
-Our first customization on the workflow will be to stop generating stylesheets and test fixtures on scaffold. We can achieve that by changing our application to the following:
+Our first customization on the workflow will be to stop generating stylesheets and test fixtures for scaffolds. We can achieve that by changing our configuration to the following:
 
 <ruby>
 config.generators do |g|
@@ -199,7 +201,7 @@ config.generators do |g|
 end
 </ruby>
 
-If we generate another resource on scaffold, we can notice that neither stylesheets nor fixtures are created anymore. If you want to customize it further, for example to use +Datamapper+ and +RSpec+ instead of +ActiveRecord+ and +TestUnit+, it's just a matter of adding their gems to your application and configuring your generators.
+If we generate another resource with the scaffold generator, we can notice that neither stylesheets nor fixtures are created anymore. If you want to customize it further, for example to use DataMapper and RSpec instead of Active Record and TestUnit, it's just a matter of adding their gems to your application and configuring your generators.
 
 To demonstrate this, we are going to create a new helper generator that simply adds some instance variable readers. First, we create a generator:
 
@@ -224,18 +226,18 @@ end
 We can try out our new generator by creating a helper for users:
 
 <shell>
-$ rails generate my_helper users
+$ rails generate my_helper products
 </shell>
 
 And it will generate the following helper file in +app/helpers+:
 
 <ruby>
-module UsersHelper
-  attr_reader :users, :user
+module ProductsHelper
+  attr_reader :products, :product
 end
 </ruby>
 
-Which is what we expected. We can now tell scaffold to use our new helper generator by configuring +config/application.rb+ once again:
+Which is what we expected. We can now tell scaffold to use our new helper generator by editing +config/application.rb+ once again:
 
 <ruby>
 config.generators do |g|
@@ -247,7 +249,7 @@ config.generators do |g|
 end
 </ruby>
 
-And see it in action when invoking generator once again:
+and see it in action when invoking the generator:
 
 <shell>
 $ rails generate scaffold Post body:text
@@ -260,7 +262,7 @@ We can notice on the output that our new helper was invoked instead of the Rails
 
 Since Rails 3.0, this is easy to do due to the hooks concept. Our new helper does not need to be focused in one specific test framework, it can simply provide a hook and a test framework just needs to implement this hook in order to be compatible.
 
-To do that, we can change your generator to the following:
+To do that, we can change the generator this way:
 
 <ruby>
 class MyHelperGenerator < Rails::Generators::NamedBase
@@ -287,9 +289,9 @@ And now you can re-run scaffold for another resource and see it generating tests
 
 h3. Customizing Your Workflow by Changing Generators Templates
 
-In the step above, we simply wanted to add a line to the generated helper, without adding any extra functionality. There is a simpler way to do that, and it's by replacing the templates of already existing generators.
+In the step above we simply wanted to add a line to the generated helper, without adding any extra functionality. There is a simpler way to do that, and it's by replacing the templates of already existing generators, in that case +Rails::Generators::HelperGenerator+.
 
-In Rails 3.0 and above, generators don't just look in the source root for templates, they also search for templates in other paths. And one of them is inside +RAILS_APP/lib/templates+. Since we want to customize +Rails::Generators::HelperGenerator+, we can do that by simply making a template copy inside +RAILS_APP/lib/templates/rails/helper+ with the name +helper.rb+. So let's create that file with the following content:
+In Rails 3.0 and above, generators don't just look in the source root for templates, they also search for templates in other paths. And one of them is +lib/templates+. Since we want to customize +Rails::Generators::HelperGenerator+, we can do that by simply making a template copy inside +lib/templates/rails/helper+ with the name +helper.rb+. So let's create that file with the following content:
 
 <erb>
 module <%= class_name %>Helper
@@ -297,7 +299,7 @@ module <%= class_name %>Helper
 end
 </erb>
 
-So now we can revert the changes in +config/application.rb+:
+and revert the last change in +config/application.rb+:
 
 <ruby>
 config.generators do |g|
@@ -308,11 +310,11 @@ config.generators do |g|
 end
 </ruby>
 
-If you generate another resource, you can see that we got exactly the same result! This is useful if you want to customize your scaffold templates and/or layout by just creating +edit.html.erb+, +index.html.erb+ and so on inside +RAILS_APP/lib/templates/erb/scaffold+.
+If you generate another resource, you can see that we get exactly the same result! This is useful if you want to customize your scaffold templates and/or layout by just creating +edit.html.erb+, +index.html.erb+ and so on inside +lib/templates/erb/scaffold+.
 
 h3. Adding Generators Fallbacks
 
-One last feature about generators which is quite useful for plugin generators is fallbacks. For example, imagine that you want to add a feature on top of TestUnit test framework, like "shoulda":http://github.com/thoughtbot/shoulda does. Since TestUnit already implements all generators required by Rails and shoulda just wants to overwrite part of it, there is no need for shoulda to reimplement some generators again, it can simply tell Rails to use a +TestUnit+ generator if none was found under the +Shoulda+ namespace.
+One last feature about generators which is quite useful for plugin generators is fallbacks. For example, imagine that you want to add a feature on top of TestUnit like "shoulda":http://github.com/thoughtbot/shoulda does. Since TestUnit already implements all generators required by Rails and shoulda just wants to overwrite part of it, there is no need for shoulda to reimplement some generators again, it can simply tell Rails to use a +TestUnit+ generator if none was found under the +Shoulda+ namespace.
 
 We can easily simulate this behavior by changing our +config/application.rb+ once again:
 
@@ -328,7 +330,7 @@ config.generators do |g|
 end
 </ruby>
 
-Now, if you create a Comment scaffold, you will see that the shoulda generators are being invoked, and at the end, they are just falling back to test unit generators:
+Now, if you create a Comment scaffold, you will see that the shoulda generators are being invoked, and at the end, they are just falling back to TestUnit generators:
 
 <shell>
 $ rails generate scaffold Comment body:text
@@ -363,6 +365,8 @@ h3. Changelog
 
 "Lighthouse Ticket":http://rails.lighthouseapp.com/projects/16213-rails-guides/tickets/102
 
+* August 23, 2010: Edit pass by "Xavier Noria":credits.html#fxn
+
 * April 30, 2010: Reviewed by José Valim
 
 * November 20, 2009: First version by José Valim