diff options
Diffstat (limited to 'guides/source/ajax_on_rails.md')
| -rw-r--r-- | guides/source/ajax_on_rails.md | 149 |
1 files changed, 76 insertions, 73 deletions
diff --git a/guides/source/ajax_on_rails.md b/guides/source/ajax_on_rails.md index ab94d2b5c9..58fcdf1daf 100644 --- a/guides/source/ajax_on_rails.md +++ b/guides/source/ajax_on_rails.md @@ -182,89 +182,92 @@ link_to_remote "Add to cart", * The very first parameter, a string, is the text of the link which appears on the page. * The second parameter, the `options` hash is the most interesting part as it has the AJAX specific stuff: -** *:url* This is the only parameter that is always required to generate the simplest remote link (technically speaking, it is not required, you can pass an empty `options` hash to `link_to_remote` - but in this case the URL used for the POST request will be equal to your current URL which is probably not your intention). This URL points to your AJAX action handler. The URL is typically specified by Rails REST view helpers, but you can use the `url_for` format too. -** *:update* Specifying a DOM id of the element we would like to update. The above example demonstrates the simplest way of accomplishing this - however, we are in trouble if the server responds with an error message because that will be injected into the page too! However, Rails has a solution for this situation: + * **:url** This is the only parameter that is always required to generate the simplest remote link (technically speaking, it is not required, you can pass an empty `options` hash to `link_to_remote` - but in this case the URL used for the POST request will be equal to your current URL which is probably not your intention). This URL points to your AJAX action handler. The URL is typically specified by Rails REST view helpers, but you can use the `url_for` format too. + * **:update** Specifying a DOM id of the element we would like to update. The above example demonstrates the simplest way of accomplishing this - however, we are in trouble if the server responds with an error message because that will be injected into the page too! However, Rails has a solution for this situation: -```ruby -link_to_remote "Add to cart", - :url => add_to_cart_url(product), - :update => { :success => "cart", :failure => "error" } -``` + ```ruby + link_to_remote "Add to cart", + :url => add_to_cart_url(product), + :update => { :success => "cart", :failure => "error" } + ``` -If the server returns 200, the output of the above example is equivalent to our first, simple one. However, in case of error, the element with the DOM id `error` is updated rather than the `cart` element. + If the server returns 200, the output of the above example is equivalent to our first, simple one. However, in case of error, the element with the DOM id `error` is updated rather than the `cart` element. -** *position* By default (i.e. when not specifying this option, like in the examples before) the response is injected into the element with the specified DOM id, replacing the original content of the element (if there was any). You might want to alter this behavior by keeping the original content - the only question is where to place the new content? This can specified by the `position` parameter, with four possibilities: -*** `:before` Inserts the response text just before the target element. More precisely, it creates a text node from the response and inserts it as the left sibling of the target element. -*** `:after` Similar behavior to `:before`, but in this case the response is inserted after the target element. -*** `:top` Inserts the text into the target element, before its original content. If the target element was empty, this is equivalent with not specifying `:position` at all. -*** `:bottom` The counterpart of `:top`: the response is inserted after the target element's original content. + * **position** By default (i.e. when not specifying this option, like in the examples before) the response is injected into the element with the specified DOM id, replacing the original content of the element (if there was any). You might want to alter this behavior by keeping the original content - the only question is where to place the new content? This can specified by the `position` parameter, with four possibilities: + * `:before` Inserts the response text just before the target element. More precisely, it creates a text node from the response and inserts it as the left sibling of the target element. + * `:after` Similar behavior to `:before`, but in this case the response is inserted after the target element. + * `:top` Inserts the text into the target element, before its original content. If the target element was empty, this is equivalent with not specifying `:position` at all. + * `:bottom` The counterpart of `:top`: the response is inserted after the target element's original content. -A typical example of using `:bottom` is inserting a new <li> element into an existing list: + A typical example of using `:bottom` is inserting a new \<li> element into an existing list: -```ruby -link_to_remote "Add new item", - :url => items_url, - :update => 'item_list', - :position => :bottom -``` + ```ruby + link_to_remote "Add new item", + :url => items_url, + :update => 'item_list', + :position => :bottom + ``` -** *:method* Most typically you want to use a POST request when adding a remote + * **:method** Most typically you want to use a POST request when adding a remote link to your view so this is the default behavior. However, sometimes you'll want to update (PATCH/PUT) or delete/destroy (DELETE) something and you can specify this with the `:method` option. Let's see an example for a typical AJAX link for deleting an item from a list: -```ruby -link_to_remote "Delete the item", - :url => item_url(item), - :method => :delete -``` - -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: -*** `:condition` => `code` Evaluates `code` (which should evaluate to a boolean) and proceeds if it's true, cancels the request otherwise. -*** `:before` => `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` => `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. -*** `:submit` => `dom_id` This option does not make sense for `link_to_remote`, but we'll cover it for the sake of completeness. By default, the parent element of the form elements the user is going to submit is the current form - use this option if you want to change the default behavior. By specifying this option you can change the parent element to the element specified by the DOM id `dom_id`. -*** `:with` > `code` The JavaScript code snippet in `code` is evaluated and added to the request URL as a parameter (or set of parameters). Therefore, `code` should return a valid URL query string (like "item_type=8" or "item_type=8&sort=true"). Usually you want to obtain some value(s) from the page - let's see an example: - -```ruby -link_to_remote "Update record", - :url => record_url(record), - :method => :patch, - :with => "'status=' <plus> 'encodeURIComponent($('status').value) <plus> '&completed=' <plus> $('completed')" -``` - -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 its 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:` => `code` The request is in the process of receiving the data, but the transfer is not completed yet. -*** `:loaded:` => `code` The transfer is completed, but the data is not processed and returned yet -*** `:interactive:` => `code` One step after `:loaded`: The data is fully received and being processed -*** `:success:` => `code` The data is fully received, parsed and the server responded with "200 OK" -*** `:failure:` => `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) -*** `:complete:` => `code` The combination of the previous two: The request has finished receiving and parsing the data, and returned a status code (which can be anything). -*** Any other status code ranging from 100 to 509: Additionally you might want to check for other HTTP status codes, such as 404. In this case simply use the status code as a number: -```ruby -link_to_remote "Add new item", - :url => items_url, - :update => "item_list", - 404 => "alert('Item not found!')" -``` -Let's see a typical example for the most frequent callbacks, `:success`, `:failure` and `:complete` in action: - -```ruby -link_to_remote "Add new item", - :url => items_url, - :update => "item_list", - :before => "$('progress').show()", - :complete => "$('progress').hide()", - :success => "display_item_added(request)", - :failure => "display_error(request)" -``` + ```ruby + link_to_remote "Delete the item", + :url => item_url(item), + :method => :delete + ``` + + 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: + * `:condition` => `code` Evaluates `code` (which should evaluate to a boolean) and proceeds if it's true, cancels the request otherwise. + * `:before` => `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` => `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. + * `:submit` => `dom_id` This option does not make sense for `link_to_remote`, but we'll cover it for the sake of completeness. By default, the parent element of the form elements the user is going to submit is the current form - use this option if you want to change the default behavior. By specifying this option you can change the parent element to the element specified by the DOM id `dom_id`. + * `:with` > `code` The JavaScript code snippet in `code` is evaluated and added to the request URL as a parameter (or set of parameters). Therefore, `code` should return a valid URL query string (like "item_type=8" or "item_type=8&sort=true"). Usually you want to obtain some value(s) from the page - let's see an example: + + ```ruby + link_to_remote "Update record", + :url => record_url(record), + :method => :patch, + :with => "'status=' + 'encodeURIComponent($('status').value) + '&completed=' + $('completed')" + ``` + + 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 its 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:` => `code` The request is in the process of receiving the data, but the transfer is not completed yet. + * `:loaded:` => `code` The transfer is completed, but the data is not processed and returned yet + * `:interactive:` => `code` One step after `:loaded`: The data is fully received and being processed + * `:success:` => `code` The data is fully received, parsed and the server responded with "200 OK" + * `:failure:` => `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) + * `:complete:` => `code` The combination of the previous two: The request has finished receiving and parsing the data, and returned a status code (which can be anything). + * Any other status code ranging from 100 to 509: Additionally you might want to check for other HTTP status codes, such as 404. In this case simply use the status code as a number: + + ```ruby + link_to_remote "Add new item", + :url => items_url, + :update => "item_list", + 404 => "alert('Item not found!')" + ``` + + Let's see a typical example for the most frequent callbacks, `:success`, `:failure` and `:complete` in action: + + ```ruby + link_to_remote "Add new item", + :url => items_url, + :update => "item_list", + :before => "$('progress').show()", + :complete => "$('progress').hide()", + :success => "display_item_added(request)", + :failure => "display_error(request)" + ``` + + * **:type** If you want to fire a synchronous request for some obscure reason (blocking the browser while the request is processed and doesn't return a status code), you can use the `:type` option with the value of `:synchronous`. -** *:type* If you want to fire a synchronous request for some obscure reason (blocking the browser while the request is processed and doesn't return a status code), you can use the `:type` option with the value of `:synchronous`. * Finally, using the `html_options` parameter you can add HTML attributes to the generated tag. It works like the same parameter of the `link_to` helper. There are interesting side effects for the `href` and `onclick` parameters though: -** 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 its 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! + * 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 its 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. |