From ef291d997d8751e9289cfc148b24d0b9aea81dc8 Mon Sep 17 00:00:00 2001 From: Robin Dupret Date: Thu, 27 Apr 2017 14:50:27 +0200 Subject: Update the JavaScript guide to use `form_with` `form_with` is the new preferred method to deal with generation of HTML forms and it enables Ajax support by default. [ci skip] --- guides/source/working_with_javascript_in_rails.md | 36 +++++------------------ 1 file changed, 7 insertions(+), 29 deletions(-) (limited to 'guides/source/working_with_javascript_in_rails.md') diff --git a/guides/source/working_with_javascript_in_rails.md b/guides/source/working_with_javascript_in_rails.md index 2a6a87c232..2ef7e8d15d 100644 --- a/guides/source/working_with_javascript_in_rails.md +++ b/guides/source/working_with_javascript_in_rails.md @@ -153,14 +153,15 @@ Unless you have disabled the Asset Pipeline, provides the JavaScript half, and the regular Ruby view helpers add appropriate tags to your DOM. -### form_for +### form_with -[`form_for`](http://api.rubyonrails.org/classes/ActionView/Helpers/FormHelper.html#method-i-form_for) -is a helper that assists with writing forms. `form_for` takes a `:remote` -option. It works like this: +[`form_with`](http://api.rubyonrails.org/classes/ActionView/Helpers/FormHelper.html#method-i-form_with) +is a helper that assists with writing forms. By default, `form_with` considers +that your form will be using Ajax ; you can opt-out by specifying the `:local` +option. ```erb -<%= form_for(@article, remote: true) do |f| %> +<%= form_with(model: @article) do |f| %> ... <% end %> ``` @@ -168,7 +169,7 @@ option. It works like this: This will generate the following HTML: ```html -
+ ...
``` @@ -191,29 +192,6 @@ $(document).ready -> Obviously, you'll want to be a bit more sophisticated than that, but it's a start. You can see more about the events [in the jquery-ujs wiki](https://github.com/rails/jquery-ujs/wiki/ajax). -### form_tag - -[`form_tag`](http://api.rubyonrails.org/classes/ActionView/Helpers/FormTagHelper.html#method-i-form_tag) -is very similar to `form_for`. It has a `:remote` option that you can use like -this: - -```erb -<%= form_tag('/articles', remote: true) do %> - ... -<% end %> -``` - -This will generate the following HTML: - -```html -
- ... -
-``` - -Everything else is the same as `form_for`. See its documentation for full -details. - ### link_to [`link_to`](http://api.rubyonrails.org/classes/ActionView/Helpers/UrlHelper.html#method-i-link_to) -- cgit v1.2.3 From 6ceb7ce162296c1813e95b6a2a68735519028c90 Mon Sep 17 00:00:00 2001 From: Robin Dupret Date: Thu, 27 Apr 2017 15:11:36 +0200 Subject: Add a section with the different Ajax events [ci skip] --- guides/source/working_with_javascript_in_rails.md | 36 +++++++++++++++++++++++ 1 file changed, 36 insertions(+) (limited to 'guides/source/working_with_javascript_in_rails.md') diff --git a/guides/source/working_with_javascript_in_rails.md b/guides/source/working_with_javascript_in_rails.md index 2ef7e8d15d..45dfeee19e 100644 --- a/guides/source/working_with_javascript_in_rails.md +++ b/guides/source/working_with_javascript_in_rails.md @@ -153,6 +153,9 @@ Unless you have disabled the Asset Pipeline, provides the JavaScript half, and the regular Ruby view helpers add appropriate tags to your DOM. +You can read below about the different events that are fired dealing with +remote elements inside your application. + ### form_with [`form_with`](http://api.rubyonrails.org/classes/ActionView/Helpers/FormHelper.html#method-i-form_with) @@ -242,6 +245,39 @@ this generates Since it's just a `
`, all of the information on `form_for` also applies. +Dealing with Ajax events +------------------------ + +Here are the different events that are fired when you deal with elements +that have a `data-remote` attribute: + +NOTE: All handlers bound to these events are always passed the event object as the +first argument. The table below describes the extra parameters passed after the +event argument. For exemple, if the extra parameters are listed as `xhr, settings`, +then to access them, you would define your handler with `function(event, xhr, settings)`. + +| Event name | Extra parameters | Fired | +|---------------------|------------------|-------------------------------------------------------------| +| `ajax:before` | | Before the whole ajax business, aborts if stopped. | +| `ajax:beforeSend` | xhr, options | Before the request is sent, aborts if stopped. | +| `ajax:send` | xhr | When the request is sent. | +| `ajax:success` | xhr, status, err | After completion, if the response was a success. | +| `ajax:error` | xhr, status, err | After completion, if the response was an error. | +| `ajax:complete` | xhr, status | After the request has been completed, no matter the outcome.| +| `ajax:aborted:file` | elements | If there are non-blank file inputs, aborts if stopped. | + +### Stoppable events + +If you stop `ajax:before` or `ajax:beforeSend` by returning false from the +handler method, the Ajax request will never take place. The `ajax:before` event +is also useful for manipulating form data before serialization. The +`ajax:beforeSend` event is also useful for adding custom request headers. + +If you stop the `ajax:aborted:file` event, the default behavior of allowing the +browser to submit the form via normal means (i.e. non-AJAX submission) will be +canceled and the form will not be submitted at all. This is useful for +implementing your own AJAX file upload workaround. + Server-Side Concerns -------------------- -- cgit v1.2.3 From 1cbf4b17198ede59f7e188ca79ad1bb8dad7dfe1 Mon Sep 17 00:00:00 2001 From: Robin Dupret Date: Thu, 27 Apr 2017 15:13:24 +0200 Subject: Nest Action View remote helpers one level deeper [ci skip] --- guides/source/working_with_javascript_in_rails.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'guides/source/working_with_javascript_in_rails.md') diff --git a/guides/source/working_with_javascript_in_rails.md b/guides/source/working_with_javascript_in_rails.md index 45dfeee19e..544c04f768 100644 --- a/guides/source/working_with_javascript_in_rails.md +++ b/guides/source/working_with_javascript_in_rails.md @@ -141,6 +141,8 @@ follow this pattern. Built-in Helpers ---------------------- +### Remote elements + Rails provides a bunch of view helper methods written in Ruby to assist you in generating HTML. Sometimes, you want to add a little Ajax to those elements, and Rails has got your back in those cases. @@ -156,7 +158,7 @@ tags to your DOM. You can read below about the different events that are fired dealing with remote elements inside your application. -### form_with +#### form_with [`form_with`](http://api.rubyonrails.org/classes/ActionView/Helpers/FormHelper.html#method-i-form_with) is a helper that assists with writing forms. By default, `form_with` considers @@ -195,7 +197,7 @@ $(document).ready -> Obviously, you'll want to be a bit more sophisticated than that, but it's a start. You can see more about the events [in the jquery-ujs wiki](https://github.com/rails/jquery-ujs/wiki/ajax). -### link_to +#### link_to [`link_to`](http://api.rubyonrails.org/classes/ActionView/Helpers/UrlHelper.html#method-i-link_to) is a helper that assists with generating links. It has a `:remote` option you @@ -227,7 +229,7 @@ $ -> alert "The article was deleted." ``` -### button_to +#### button_to [`button_to`](http://api.rubyonrails.org/classes/ActionView/Helpers/UrlHelper.html#method-i-button_to) is a helper that helps you create buttons. It has a `:remote` option that you can call like this: -- cgit v1.2.3 From 7bf580c89e1aa9342073a7e498d3c993a078b6a2 Mon Sep 17 00:00:00 2001 From: Robin Dupret Date: Thu, 27 Apr 2017 17:40:15 +0200 Subject: Add documentation of data attributes for UJS [ci skip] --- guides/source/working_with_javascript_in_rails.md | 98 ++++++++++++++++++++++- 1 file changed, 97 insertions(+), 1 deletion(-) (limited to 'guides/source/working_with_javascript_in_rails.md') diff --git a/guides/source/working_with_javascript_in_rails.md b/guides/source/working_with_javascript_in_rails.md index 544c04f768..527b244b0d 100644 --- a/guides/source/working_with_javascript_in_rails.md +++ b/guides/source/working_with_javascript_in_rails.md @@ -195,7 +195,7 @@ $(document).ready -> ``` Obviously, you'll want to be a bit more sophisticated than that, but it's a -start. You can see more about the events [in the jquery-ujs wiki](https://github.com/rails/jquery-ujs/wiki/ajax). +start. #### link_to @@ -247,6 +247,102 @@ this generates Since it's just a ``, all of the information on `form_for` also applies. +### Customize remote elements + +It is possible to customize the behavior of elements with a `data-remote` +attribute without writing a line of JavaScript. Your can specify extra `data-` +attributes to accomplish this. + +#### `data-method` + +Activating hyperlinks always results in an HTTP GET request. However, if your +application is [RESTful](http://en.wikipedia.org/wiki/Representational_State_Transfer), +some links are in fact actions that change data on the server and must be +performed with non-GET requests. This attribute allows marking up such links +with an explicit method such as "post", "put" or "delete". + +The way it works is that, when the link is activated, it constructs a hidden form +in the document with the "action" attribute corresponding to "href" value of the +link and the method corresponding to `data-method` value, and submits that form. + +NOTE: Because submitting forms with HTTP methods other than GET and POST isn't +widely supported across browsers, all other HTTP methods are actually sent over +POST with the intended method indicated in the `_method` parameter. Rails +automatically detects and compensates for this. + +#### `data-url` and `data-params` + +Certain elements of your page aren't actually referring to any URL but you would +like them to trigger Ajax calls. Specifying the `data-url` attribute along with +the `data-remote` one will trigger an Ajax call to the given URL. You can also +specify extra parameters through the `data-params` attribute. + +This can be useful to trigger an action on check-boxes for instance: + +```html + +``` + +#### `data-type` + +It is also possible to defines the Ajax `dataType` explicitly when performing +requests for `data-remote` elements through the `data-type` attribute. + +### Confirmations + +You can ask for an extra confirmation of the user by adding a `data-confirm` +attribute on links and forms. The user will be presented a JavaScript `confirm()` +dialog containing the attribute's text. If the user chooses to cancel, the action +doesn't take place. + +Adding this attribute on links will trigger the dialog on click and adding it +on forms will trigger it on submit. For example: + +```erb +<%= link_to "Dangerous zone", dangerous_zone_path, + data: { confirm: 'Are you sure?'} %> +``` + +This generates: + +```html +Dangerous zone +``` + +The attribute is also allowed on form submit buttons. This allows you to customize +the warning message depending on the button which was activated. In this case, +you should **not** have `data-confirm` on the form itself. + +The default confirmation uses a JavaScript confirm dialog, but you can customize +it by listening to the `confirm` event, that is fired just before the confirmation +window appears to the user. To cancel this default confirmation, make the confirm +handler to return `false`. + +### Automatic disabling + +It is also possible to automatically disable an input while the form is submitting +by using the `data-disable-with` attribute. This is to prevent accidental +double-clicks from the user, which could result in duplicate HTTP requests that +the backend may not detect as such. The value of the attribute is text that will +become the new value of the button in its disabled state. + +This also works for links with `data-method` attribute. + +For example: + +```erb +<%= form_with(model: @article.new) do |f| %> + <%= f.submit data: { "disable-with": "Saving..."} %> +<%= end %> +``` + +This generates a form with: + +```html + +``` + Dealing with Ajax events ------------------------ -- cgit v1.2.3