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

4 files changed, 83 insertions, 17 deletions

diff --git a/railties/guides/source/active_record_validations_callbacks.textile b/railties/guides/source/active_record_validations_callbacks.textile
index 781b9001b6..665e7f9ccc 100644
--- a/railties/guides/source/active_record_validations_callbacks.textile
+++ b/railties/guides/source/active_record_validations_callbacks.textile
@@ -880,7 +880,7 @@ The selectors used to customize the style of error messages are:
 * +#error_explanation p+ - Style for the paragraph holding the message that appears right below the header of the +div+ element.
 * +#error_explanation ul li+ - Style for the list items with individual error messages.
 
-If scaffolding was used, file +app/assets/stylesheets/scaffold.css.scss+ (which later compiles to +app/assets/stylesheets/scaffold.css+), will have been generated automatically. This file defines the red-based styles you saw in the examples above.
+If scaffolding was used, file +app/assets/stylesheets/scaffolds.css.scss+ will have been generated automatically. This file defines the red-based styles you saw in the examples above.
 
 The name of the class and the id can be changed with the +:class+ and +:id+ options, accepted by both helpers.
 
@@ -1162,7 +1162,7 @@ class PictureFile < ActiveRecord::Base
 end
 </ruby>
 
-Note that we needed to instantiate a new +PictureFileCallbacks+ object, since we declared our callback as an instance method. This is particularly useful if the callbacks make use of the state of instantiated object. Often, however, it will make more sense to declare the callbacks as class methods:
+Note that we needed to instantiate a new +PictureFileCallbacks+ object, since we declared our callback as an instance method. This is particularly useful if the callbacks make use of the state of the instantiated object. Often, however, it will make more sense to declare the callbacks as class methods:
 
 <ruby>
 class PictureFileCallbacks
diff --git a/railties/guides/source/ajax_on_rails.textile b/railties/guides/source/ajax_on_rails.textile
index 29d4fae888..3a0ccfe9b2 100644
--- a/railties/guides/source/ajax_on_rails.textile
+++ b/railties/guides/source/ajax_on_rails.textile
@@ -3,7 +3,7 @@ h2. AJAX on Rails
 This guide covers the built-in Ajax/JavaScript functionality of Rails (and more); it will enable you to create rich and dynamic AJAX applications with ease! We will cover the following topics:
 
 * Quick introduction to AJAX and related technologies
-* Handling JavaScript the Rails way: Rails helpers, Prototype and script.aculo.us
+* Unobtrusive JavaScript helpers with drivers for Prototype, jQuery etc
 * Testing JavaScript functionality
 
 endprologue.
@@ -26,14 +26,78 @@ How do 'standard' and AJAX requests differ, why does this matter for understandi
 
 h3. Built-in Rails Helpers
 
-Rails' JavaScript framework of choice is "Prototype":http://www.prototypejs.org. Prototype is a generic-purpose JavaScript framework that aims to ease the development of dynamic web applications by offering DOM manipulation, AJAX and other JavaScript functionality ranging from utility functions to object oriented constructs. It is not specifically written for any language, so Rails provides a set of helpers to enable seamless integration of Prototype with your Rails views.
+Rails 3.1 ships with "jQuery":http://jquery.com as the default JavaScript library. The Gemfile contains <tt>gem 'jquery-rails'</tt> which makes the jQuery files available to the application automatically. This can be accessed as:
 
-To get access to these helpers, all you have to do is to include the prototype framework in your pages - typically in your master layout, application.html.erb - like so:
+<ruby>
+javascript_include_tag :defaults
+</ruby>
+
+h4. Examples
+
+All the remote_method helpers has been removed. To make them working with AJAX, simply pass the <tt>:remote => true</tt> option to the original non-remote method.
+
+<ruby>
+button_to "New", :action => "new", :form_class => "new-thing"
+</ruby>
+
+will produce
+
+<html>
+<form method="post" action="/controller/new" class="new-thing">
+  <div><input value="New" type="submit" /></div>
+</form>
+</html>
 
 <ruby>
-javascript_include_tag 'prototype'
+button_to "Create", :action => "create", :remote => true, :form => { "data-type" => "json" }
 </ruby>
 
+will produce
+
+<html>
+<form method="post" action="/images/create" class="button_to" data-remote="true" data-type="json">
+  <div><input value="Create" type="submit" /></div>
+</form>
+</html>
+
+<ruby>
+button_to "Delete Image", { :action => "delete", :id => @image.id },
+             :confirm => "Are you sure?", :method => :delete
+</ruby>
+
+will produce
+
+<html>
+<form method="post" action="/images/delete/1" class="button_to">
+  <div>
+    <input type="hidden" name="_method" value="delete" />
+    <input data-confirm='Are you sure?' value="Delete" type="submit" />
+ </div>
+</form>
+</html>
+
+<ruby>
+button_to('Destroy', 'http://www.example.com', :confirm => 'Are you sure?',
+          :method => "delete", :remote => true, :disable_with => 'loading...')
+</ruby>
+
+will produce
+
+<html>
+<form class='button_to' method='post' action='http://www.example.com' data-remote='true'>
+  <div>
+    <input name='_method' value='delete' type='hidden' />
+    <input value='Destroy' type='submit' disable_with='loading...' data-confirm='Are you sure?' />
+  </div>
+</form>
+</html>
+
+You can also choose to use Prototype instead of jQuery and specify the option using +-j+ switch while generating the application.
+
+<shell>
+rails new app_name -j prototype
+</shell>
+
 You are ready to add some AJAX love to your Rails app!
 
 h4. The Quintessential AJAX Rails Helper: link_to_remote
diff --git a/railties/guides/source/asset_pipeline.textile b/railties/guides/source/asset_pipeline.textile
index df41c7a9e8..afaf0f6fe3 100644
--- a/railties/guides/source/asset_pipeline.textile
+++ b/railties/guides/source/asset_pipeline.textile
@@ -234,6 +234,8 @@ The directives that work in the JavaScript files also work in stylesheets, obvio
 
 In this example +require_self+ is used. This puts the CSS contained within the file (if any) at the precise location of the +require_self+ call. If +require_self+ is called more than once, only the last call is respected.
 
+NOTE. If you want to use multiple Sass files, use the "Sass +@import+ rule":http://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html#import instead of the Sprockets directives. Using Sprockets directives all Sass files exist within their own scope, making variables or mixins only available within the document they were defined in.
+
 You can have as many manifest files as you need. For example the +admin.css+ and +admin.js+ manifest could contain the JS and CSS files that are used for the admin section of an application.
 
 The same remarks about ordering made above apply. In particular, you can specify individual files and they are compiled in the order specified:
diff --git a/railties/guides/source/association_basics.textile b/railties/guides/source/association_basics.textile
index f5f0f9340c..8943bfa0a3 100644
--- a/railties/guides/source/association_basics.textile
+++ b/railties/guides/source/association_basics.textile
@@ -211,7 +211,7 @@ end
 
 h4. Choosing Between +belongs_to+ and +has_one+
 
-If you want to set up a 1–1 relationship between two models, you'll need to add +belongs_to+ to one, and +has_one+ to the other. How do you know which is which?
+If you want to set up a one-to-one relationship between two models, you'll need to add +belongs_to+ to one, and +has_one+ to the other. How do you know which is which?
 
 The distinction is in where you place the foreign key (it goes on the table for the class declaring the +belongs_to+ association), but you should give some thought to the actual meaning of the data as well. The +has_one+ relationship says that one of something is yours - that is, that something points back to you. For example, it makes more sense to say that a supplier owns an account than that an account owns a supplier. This suggests that the correct relationships are like this:
 
@@ -566,7 +566,7 @@ The <tt>build_<em>association</em></tt> method returns a new object of the assoc
 
 h6(#belongs_to-create_association). <tt>create_<em>association</em>(attributes = {})</tt>
 
-The <tt>create_<em>association</em></tt> method returns a new object of the associated type. This object will be instantiated from the passed attributes, and the link through this object's foreign key will be set. In addition, the associated object _will_ be saved (assuming that it passes any validations).
+The <tt>create_<em>association</em></tt> method returns a new object of the associated type. This object will be instantiated from the passed attributes, the link through this object's foreign key will be set, and, once it passes all of the validations specified on the associated model, the associated object _will_ be saved.
 
 <ruby>
 @customer = @order.create_customer(:customer_number => 123,
@@ -576,7 +576,7 @@ The <tt>create_<em>association</em></tt> method returns a new object of the asso
 
 h5. Options for +belongs_to+
 
-In many situations, you can use the default behavior of +belongs_to+ without any customization. But despite Rails' emphasis of convention over customization, you can alter that behavior in a number of ways. This section covers the options that you can pass when you create a +belongs_to+ association. For example, an association with several options might look like this:
+In many situations, you can use the default behavior of +belongs_to+ without any customization. But despite Rails' emphasis of convention over configuration, you can alter that behavior in a number of ways. This section covers the options that you can pass when you create a +belongs_to+ association. For example, an association with several options might look like this:
 
 <ruby>
 class Order < ActiveRecord::Base
@@ -760,9 +760,9 @@ h6(#belongs_to-validate). +:validate+
 
 If you set the +:validate+ option to +true+, then associated objects will be validated whenever you save this object. By default, this is +false+: associated objects will not be validated when this object is saved.
 
-h5(#belongs_to-how_to_know_whether_theres_an_associated_object). How To Know Whether There's an Associated Object?
+h5(#belongs_to-do_any_associated_objects_exist). Do Any Associated Objects Exist?
 
-To know whether there's and associated object just check <tt><em>association</em>.nil?</tt>:
+You can see if any associated objects exist by using the <tt><em>association</em>.nil?</tt> method:
 
 <ruby>
 if @order.customer.nil?
@@ -834,7 +834,7 @@ The <tt>build_<em>association</em></tt> method returns a new object of the assoc
 
 h6(#has_one-create_association). <tt>create_<em>association</em>(attributes = {})</tt>
 
-The <tt>create_<em>association</em></tt> method returns a new object of the associated type. This object will be instantiated from the passed attributes, and the link through its foreign key will be set. In addition, the associated object _will_ be saved (assuming that it passes any validations).
+The <tt>create_<em>association</em></tt> method returns a new object of the associated type. This object will be instantiated from the passed attributes, the link through its foreign key will be set, and, once it passes all of the validations specified on the associated model, the associated object _will_ be saved.
 
 <ruby>
 @account = @supplier.create_account(:terms => "Net 30")
@@ -842,7 +842,7 @@ The <tt>create_<em>association</em></tt> method returns a new object of the asso
 
 h5. Options for +has_one+
 
-In many situations, you can use the default behavior of +has_one+ without any customization. But despite Rails' emphasis of convention over customization, you can alter that behavior in a number of ways. This section covers the options that you can pass when you create a +has_one+ association. For example, an association with several options might look like this:
+In many situations, you can use the default behavior of +has_one+ without any customization. But despite Rails' emphasis of convention over configuration, you can alter that behavior in a number of ways. This section covers the options that you can pass when you create a +has_one+ association. For example, an association with several options might look like this:
 
 <ruby>
 class Supplier < ActiveRecord::Base
@@ -980,9 +980,9 @@ h6(#has_one-validate). +:validate+
 
 If you set the +:validate+ option to +true+, then associated objects will be validated whenever you save this object. By default, this is +false+: associated objects will not be validated when this object is saved.
 
-h5(#has_one-how_to_know_whether_theres_an_associated_object). How To Know Whether There's an Associated Object?
+h5(#has_one-do_any_associated_objects_exist). Do Any Associated Objects Exist?
 
-To know whether there's and associated object just check <tt><em>association</em>.nil?</tt>:
+You can see if any associated objects exist by using the <tt><em>association</em>.nil?</tt> method:
 
 <ruby>
 if @supplier.account.nil?
@@ -1147,7 +1147,7 @@ The <tt><em>collection</em>.build</tt> method returns one or more new objects of
 
 h6(#has_many-collection-create). <tt><em>collection</em>.create(attributes = {})</tt>
 
-The <tt><em>collection</em>.create</tt> method returns a new object of the associated type. This object will be instantiated from the passed attributes, the link through its foreign key will be created, and the associated object _will_ be saved (assuming that it passes any validations).
+The <tt><em>collection</em>.create</tt> method returns a new object of the associated type. This object will be instantiated from the passed attributes, the link through its foreign key will be created, and, once it passes all of the validations specified on the associated model, the associated object _will_ be saved.
 
 <ruby>
 @order = @customer.orders.create(:order_date => Time.now,
@@ -1576,7 +1576,7 @@ The <tt><em>collection</em>.build</tt> method returns a new object of the associ
 
 h6(#has_and_belongs_to_many-create-attributes). <tt><em>collection</em>.create(attributes = {})</tt>
 
-The <tt><em>collection</em>.create</tt> method returns a new object of the associated type. This object will be instantiated from the passed attributes, the link through the join table will be created, and the associated object _will_ be saved (assuming that it passes any validations).
+The <tt><em>collection</em>.create</tt> method returns a new object of the associated type. This object will be instantiated from the passed attributes, the link through the join table will be created, and, once it passes all of the validations specified on the associated model, the associated object _will_ be saved.
 
 <ruby>
 @assembly = @part.assemblies.create(