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

1 files changed, 81 insertions, 39 deletions

diff --git a/guides/source/ajax_on_rails.textile b/guides/source/ajax_on_rails.textile
index bfd007490a..e23fdf9a74 100644
--- a/guides/source/ajax_on_rails.textile
+++ b/guides/source/ajax_on_rails.textile
@@ -1,6 +1,8 @@
 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:
+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
 * Unobtrusive JavaScript helpers with drivers for Prototype, jQuery etc
@@ -10,34 +12,99 @@ endprologue.
 
 h3. Hello AJAX - a Quick Intro
 
-You'll need the basics of DOM, HTTP requests and other topics discussed here to really understand Ajax on Rails.
+AJAX is about updating parts of a web page without reloading the page. An AJAX
+call happens as a response to an event, like when the page finished loading or
+when a user clicks on an element. For example, let say you click on a link, which
+would usually take you to a new page, but instead of doing that, an asynchronous
+HTTP request is made and the response is evaluated with JavaScript. That way the
+page is not reloaded and new information can be dynamically included in the page.
+The way that happens is by inserting, removing or changing parts of the DOM. The
+DOM, or Document Object Model, is a convention to represent the HTML document as
+a set of nodes that contain other nodes. For example, a list of names is represented
+as a +ul+ element node containing several +li+ element nodes. An AJAX call can
+be made to obtain a new list item to include, and append it inside a +li+ node to
+the +ul+ node.
 
 h4. Asynchronous JavaScript + XML
 
-Basic terminology, new style of creating web apps
+AJAX means Asynchronous JavaScript + XML. Asynchronous means that the page is not
+reloaded, the request made is separate from the regular page request. Javascript
+is used to evaluate the response and the XML part is a bit misleading as XML is
+not required, you respond to the HTTP request with JSON or regular HTML as well.
 
 h4. The DOM
 
-basics of the DOM, how is it built, properties, features, why is it central to AJAX
+The DOM (Document Object Model) is a convention to represent HTML (or XML)
+documents, as a set of nodes that act as objects and contain other nodes. You can
+have a +div+ element that contains other +div+ elements as well as +p+ elements
+that contain text.
 
 h4. Standard HTML communication vs AJAX
 
-How do 'standard' and AJAX requests differ, why does this matter for understanding AJAX on Rails (tie in for *_remote helpers, the next section)
+In regular HTML comunications, when you click on a link, the browser makes an HTTP
++GET+ request, the server responds with a new HTML document that the browsers renders
+and then replaces the previous one. The same thing happens when you click a button to
+submit a form, except that you make and HTTP +POST+ request, but you also get a new
+HTML document that the browser renders and replaces the current one. In AJAX
+communications, the request is separate, and the response is evaluated in JavaScript
+instead of rendered by the browser. That way you can have more control over the content
+that gets returned, and the page is not reloaded.
 
 h3. Built-in Rails Helpers
 
-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:
+Rails 4.0 ships with "jQuery":http://jquery.com as the default JavaScript library.
+The Gemfile contains +gem 'jquery-rails'+ which provides the +jquery.js+ and
++jquery_ujs.js+ files via the asset pipeline.
+
+You will have to use the +require+ directive to tell Sprockets to load +jquery.js+
+and +jquery.js+. For example, a new Rails application includes a default
++app/assets/javascripts/application.js+ file which contains the following lines:
+
+<plain>
+// ...
+//= require jquery
+//= require jquery_ujs
+// ...
+</plain>
+
+The +application.js+ file acts like a manifest and is used to tell Sprockets the
+files that you wish to require. In this case, you are requiring the files +jquery.js+
+and +jquery_ujs.js+ provided by the +jquery-rails+ gem.
+
+If the application is not using the asset pipeline, this can be accessed as:
 
 <ruby>
 javascript_include_tag :defaults
 </ruby>
 
+By default, +:defaults+ loads jQuery.
+
+You can also choose to use Prototype instead of jQuery and specify the option
+using +-j+ switch while generating the application.
+
+<shell>
+rails new app_name -j prototype
+</shell>
+
+This will add the +prototype-rails+ gem to the Gemfile and modify the
++app/assets/javascripts/application.js+ file:
+
+<plain>
+// ...
+//= require prototype
+//= require prototype_ujs
+// ...
+</plain>
+
+You are ready to add some AJAX love to your Rails app!
+
 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.
+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"
+button_to 'New', action: 'new', form_class: 'new-thing'
 </ruby>
 
 will produce
@@ -49,7 +116,7 @@ will produce
 </html>
 
 <ruby>
-button_to "Create", :action => "create", :remote => true, :form => { "data-type" => "json" }
+button_to 'Create', action: 'create', remote: true, form: { 'data-type' => 'json' }
 </ruby>
 
 will produce
@@ -61,8 +128,8 @@ will produce
 </html>
 
 <ruby>
-button_to "Delete Image", { :action => "delete", :id => @image.id },
-             :confirm => "Are you sure?", :method => :delete
+button_to 'Delete Image', { action: 'delete', id: @image.id },
+             confirm: 'Are you sure?', method: :delete
 </ruby>
 
 will produce
@@ -77,8 +144,8 @@ will produce
 </html>
 
 <ruby>
-button_to('Destroy', 'http://www.example.com', :confirm => 'Are you sure?',
-          :method => "delete", :remote => true, 'data-disable-with' => 'loading...')
+button_to 'Destroy', 'http://www.example.com', confirm: 'Are you sure?',
+             method: 'delete', remote: true, data: { disable_with: 'loading...' }
 </ruby>
 
 will produce
@@ -92,14 +159,6 @@ will produce
 </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
 
 Let's start with what is probably the most often used helper: +link_to_remote+. It has an interesting feature from the documentation point of view: the options supplied to +link_to_remote+ are shared by all other AJAX helpers, so learning the mechanics and options of +link_to_remote+ is a great help when using other helpers.
@@ -223,23 +282,6 @@ h5. +form_remote_tag+
 
 h5. +submit_to_remote+
 
-h4. Observing Elements
-
-h5. +observe_field+
-
-h5. +observe_form+
-
-h4. Calling a Function Periodically
-
-h5. +periodically_call_remote+
-
-
-h4. Miscellaneous Functionality
-
-h5. +remote_function+
-
-h5. +update_page+
-
 h4. Serving JavaScript
 
 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.
@@ -265,4 +307,4 @@ JavaScript testing reminds me the definition of the world 'classic' by Mark Twai
 * Cucumber+Webrat
 * Mention stuff like screw.unit/jsSpec
 
-Note to self: check out the RailsConf JS testing video
+Note to self: check out the RailsConf JS testing video
\ No newline at end of file