diff options
Diffstat (limited to 'guides/source')
| -rw-r--r-- | guides/source/5_1_release_notes.md | 177 | ||||
| -rw-r--r-- | guides/source/working_with_javascript_in_rails.md | 182 |
2 files changed, 295 insertions, 64 deletions
diff --git a/guides/source/5_1_release_notes.md b/guides/source/5_1_release_notes.md index ffa18f1a2b..0f6167f1ee 100644 --- a/guides/source/5_1_release_notes.md +++ b/guides/source/5_1_release_notes.md @@ -40,7 +40,7 @@ Major Features [Pull Request](https://github.com/rails/rails/pull/26836) -Rails 5.1 will allow managing JavaScript dependencies +Rails 5.1 allows managing JavaScript dependencies from NPM via Yarn. This will make it easy to use libraries like React, VueJS or any other library from NPM world. The Yarn support is integrated with the asset pipeline so that all dependencies will work seamlessly with the @@ -70,14 +70,14 @@ offerings. It is no longer required, as the UJS has been rewritten to use plain, vanilla JavaScript. This code now ships inside of Action View as `rails-ujs`. -You can still use the jQuery version if needed, but it is no longer required by default. +You can still use jQuery if needed, but it is no longer required by default. ### System tests [Pull Request](https://github.com/rails/rails/pull/26703) Rails 5.1 has baked-in support for writing Capybara tests, in the form of -System tests. You need no longer worry about configuring Capybara and +System tests. You no longer need to worry about configuring Capybara and database cleaning strategies for such tests. Rails 5.1 provides a wrapper for running tests in Chrome with additional features such as failure screenshots. @@ -86,7 +86,7 @@ screenshots. [Pull Request](https://github.com/rails/rails/pull/28038) -Rails will now allow management of application secrets in a secure way, +Rails now allows management of application secrets in a secure way, building on top of the [sekrets](https://github.com/ahoward/sekrets) gem. Run `bin/rails secrets:setup` to setup a new encrypted secrets file. This will @@ -106,33 +106,24 @@ order to share instance variables, headers and other common setup. ``` ruby class InvitationsMailer < ApplicationMailer - before_action { @inviter, @invitee = params[:inviter], params[:invitee] } before_action { @account = params[:inviter].account } def account_invitation mail subject: "#{@inviter.name} invited you to their Basecamp (#{@account.name})" end - - def project_invitation - @project = params[:project] - @summarizer = ProjectInvitationSummarizer.new(@project.bucket) - - mail subject: "#{@inviter.name.familiar} added you to a project in Basecamp (#{@account.name})" - end end -InvitationsMailer.with(inviter: person_a, invitee: person_b).account_invitation.deliver_later +InvitationsMailer.with(inviter: person_a, invitee: person_b) + .account_invitation.deliver_later ``` ### Direct & resolved routes [Pull Request](https://github.com/rails/rails/pull/23138) -Rails 5.1 has added two new methods, `resolve` and `direct`, to the routing -DSL. - -The `resolve` method allows customizing polymorphic mapping of models. +Rails 5.1 adds two new methods, `resolve` and `direct`, to the routing +DSL. The `resolve` method allows customizing polymorphic mapping of models. ``` ruby resource :basket @@ -181,50 +172,94 @@ Before Rails 5.1, there were two interfaces for handling HTML forms: Rails 5.1 combines both of these interfaces with `form_with`, and can generate form tags based on URLs, scopes or models. -``` erb -# Using just a URL: +Using just a URL: +``` erb <%= form_with url: posts_path do |form| %> <%= form.text_field :title %> <% end %> -# => +<%# Will generate %> + <form action="/posts" method="post" data-remote="true"> <input type="text" name="title"> </form> +``` -# Adding a scope prefixes the input field names: +Adding a scope prefixes the input field names: +``` erb <%= form_with scope: :post, url: posts_path do |form| %> <%= form.text_field :title %> <% end %> -# => + +<%# Will generate %> + <form action="/posts" method="post" data-remote="true"> <input type="text" name="post[title]"> </form> +``` -# Using a model infers both the URL and scope: +Using a model infers both the URL and scope: +``` erb <%= form_with model: Post.new do |form| %> <%= form.text_field :title %> <% end %> -# => + +<%# Will generate %> + <form action="/posts" method="post" data-remote="true"> <input type="text" name="post[title]"> </form> +``` -# An existing model makes an update form and fills out field values: +An existing model makes an update form and fills out field values: +``` erb <%= form_with model: Post.first do |form| %> <%= form.text_field :title %> <% end %> -# => + +<%# Will generate %> + <form action="/posts/1" method="post" data-remote="true"> <input type="hidden" name="_method" value="patch"> <input type="text" name="post[title]" value="<the title of the post>"> </form> ``` +Incompatibilities +----------------- + +The following changes may require immediate action upon upgrade. + +### Transactional tests with multiple connections + +Transactional tests now wrap all Active Record connections in database +transactions. + +When a test spawns additional threads, and those threads obtain database +connections, those connections are now handled specially: + +The threads will share a single connection, which is inside the managed +transaction. This ensures all threads see the database in the same +state, ignoring the outermost transaction. Previously, such additional +connections were unable to see the fixture rows, for example. + +When a thread enters a nested transaction, it will temporarily obtain +exclusive use of the connection, to maintain isolation. + +If your tests currently rely on obtaining a separate, +outside-of-transaction, connection in a spawned thread, you'll need to +switch to more explicit connection management. + +If your tests spawn threads and those threads interact while also using +explicit database transactions, this change may introduce a deadlock. + +The easy way to opt out of this new behavior is to disable transactional +tests on any test cases it affects. + Railties -------- @@ -233,7 +268,7 @@ Please refer to the [Changelog][railties] for detailed changes. ### Removals * Remove deprecated `config.static_cache_control`. - ([commit](https://github.com/rails/rails/commit/c861decd44198f8d7d774ee6a74194d1ac1a5a13) + ([commit](https://github.com/rails/rails/commit/c861decd44198f8d7d774ee6a74194d1ac1a5a13)) * Remove deprecated `config.serve_static_files`. ([commit](https://github.com/rails/rails/commit/0129ca2eeb6d5b2ea8c6e6be38eeb770fe45f1fa)) @@ -267,7 +302,7 @@ Please refer to the [Changelog][railties] for detailed changes. * Add Yarn support in new apps with a yarn binstub and package.json. ([Pull Request](https://github.com/rails/rails/pull/26836)) -* Add Webpack support in new apps via the --webpack option, which will delegate +* Add Webpack support in new apps via the `--webpack` option, which will delegate to the rails/webpacker gem. ([Pull Request](https://github.com/rails/rails/pull/27288)) @@ -278,6 +313,9 @@ Please refer to the [Changelog][railties] for detailed changes. * Add encrypted secrets in `config/secrets.yml.enc`. ([Pull Request](https://github.com/rails/rails/pull/28038)) +* Display railtie class name in `rails initializers`. + ([Pull Request](https://github.com/rails/rails/pull/25257)) + Action Cable ----------- @@ -293,7 +331,7 @@ Please refer to the [Changelog][action-cable] for detailed changes. * Permit same-origin connections by default. ([commit](https://github.com/rails/rails/commit/dae404473409fcab0e07976aec626df670e52282)) -* Add `ActiveSupport::Notifications` hook for broadcasing data. +* Add `ActiveSupport::Notifications` hook for broadcasting data. ([Pull Request](https://github.com/rails/rails/pull/24988)) Action Pack @@ -303,10 +341,37 @@ Please refer to the [Changelog][action-pack] for detailed changes. ### Removals +* Removed support to non-keyword arguments in `#process`, `#get`, `#post`, + `#patch`, `#put`, `#delete`, and `#head` for the `ActionDispatch::IntegrationTest` + and `ActionController::TestCase` classes. + ([Commit](https://github.com/rails/rails/commit/98b8309569a326910a723f521911e54994b112fb), + [Commit](https://github.com/rails/rails/commit/de9542acd56f60d281465a59eac11e15ca8b3323)) + +* Removed deprecated `ActionDispatch::Callbacks.to_prepare` and + `ActionDispatch::Callbacks.to_cleanup`. + ([Commit](https://github.com/rails/rails/commit/3f2b7d60a52ffb2ad2d4fcf889c06b631db1946b)) + +* Removed deprecated methods related to controller filters. + ([Commit](https://github.com/rails/rails/commit/d7be30e8babf5e37a891522869e7b0191b79b757)) + ### Deprecations +* Deprecated `:controller` and `:action` path parameters. + ([Pull Request](https://github.com/rails/rails/pull/23980)) + +* Deprecated `config.action_controller.raise_on_unfiltered_parameters`. + It doesn't have any effect in Rails 5.1. + ([Commit](https://github.com/rails/rails/commit/c6640fb62b10db26004a998d2ece98baede509e5)) + ### Notable changes +* Added the `direct` and `resolve` methods to the routing DSL. + ([Pull Request](https://github.com/rails/rails/pull/23138)) + +* Added a new `ActionDispatch::SystemTestCase` class to write system tests in + your applications. + ([Pull Request](https://github.com/rails/rails/pull/26703)) + Action View ------------- @@ -341,6 +406,9 @@ Please refer to the [Changelog][action-view] for detailed changes. * Add `form_with` to unify `form_tag` and `form_for` usage. ([Pull Request](https://github.com/rails/rails/pull/26976)) +* Add `check_parameters` option to `current_page?`. + ([Pull Request](https://github.com/rails/rails/pull/27549)) + Action Mailer ------------- @@ -378,6 +446,19 @@ Please refer to the [Changelog][active-record] for detailed changes. ### Notable changes +* Change Default Primary Keys to BIGINT. + ([Pull Request](https://github.com/rails/rails/pull/26266)) + +* Virtual/generated column support for MySQL 5.7.5+ and MariaDB 5.2.0+. + ([Commit](https://github.com/rails/rails/commit/65bf1c60053e727835e06392d27a2fb49665484c)) + +* Added support for limits in batch processing. + ([Commit](https://github.com/rails/rails/commit/451437c6f57e66cc7586ec966e530493927098c7)) + +* Transactional tests now wrap all Active Record connections in database + transactions. + ([Pull Request](https://github.com/rails/rails/pull/28726)) + * Skipped comments in the output of `mysqldump` command by default. ([Pull Request](https://github.com/rails/rails/pull/23301)) @@ -389,6 +470,9 @@ Please refer to the [Changelog][active-record] for detailed changes. * Pass `"-v ON_ERROR_STOP=1"` flag with `psql` command to not suppress SQL errors. ([Pull Request](https://github.com/rails/rails/pull/24773)) +* Add `ActiveRecord::Base.connection_pool.stat`. + ([Pull Request](https://github.com/rails/rails/pull/26988)) + Active Model ------------ @@ -440,10 +524,36 @@ Please refer to the [Changelog][active-support] for detailed changes. ### Removals +* Removed the `ActiveSupport::Concurrency::Latch` class. + ([Commit](https://github.com/rails/rails/commit/0d7bd2031b4054fbdeab0a00dd58b1b08fb7fea6)) + +* Removed `halt_callback_chains_on_return_false`. + ([Commit](https://github.com/rails/rails/commit/4e63ce53fc25c3bc15c5ebf54bab54fa847ee02a)) + +* Removed deprecated behavior that halts callbacks when the return is false. + ([Commit](https://github.com/rails/rails/commit/3a25cdca3e0d29ee2040931d0cb6c275d612dffe)) + ### Deprecations +* The top level `HashWithIndifferentAccess` class has been softly deprecated + in favor of the `ActiveSupport::HashWithIndifferentAccess` one. + ([Pull request](https://github.com/rails/rails/pull/28157)) + +* Deprecate passing string to `:if` and `:unless` conditional options on `set_callback` and `skip_callback`. + ([Commit](https://github.com/rails/rails/commit/0952552) + ### Notable changes +* Fixed duration parsing and traveling to make it consistent across DST changes. + ([Commit](https://github.com/rails/rails/commit/8931916f4a1c1d8e70c06063ba63928c5c7eab1e), + [Pull Request](https://github.com/rails/rails/pull/26597)) + +* Updated Unicode to version 9.0.0. + ([Pull Request](https://github.com/rails/rails/pull/27822)) + +* Add Duration#before and #after as aliases for #ago and #since. + ([Pull Request](https://github.com/rails/rails/pull/27721)) + * Added `Module#delegate_missing_to` to delegate method calls not defined for the current object to a proxy object. ([Pull Request](https://github.com/rails/rails/pull/23930)) @@ -452,6 +562,15 @@ Please refer to the [Changelog][active-support] for detailed changes. of the current date & time. ([Pull Request](https://github.com/rails/rails/pull/24930)) +* Introduced the `assert_changes` and `assert_no_changes` methods for tests. + ([Pull Request](https://github.com/rails/rails/pull/25393)) + +* The `travel` and `travel_to` methods now raise on nested calls. + ([Pull Request](https://github.com/rails/rails/pull/24890)) + +* Update `DateTime#change` to support usec and nsec. + ([Pull Request](https://github.com/rails/rails/pull/28242)) + Credits ------- diff --git a/guides/source/working_with_javascript_in_rails.md b/guides/source/working_with_javascript_in_rails.md index 2a6a87c232..9af1c5438c 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. @@ -153,14 +155,18 @@ 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 +You can read below about the different events that are fired dealing with +remote elements inside your application. + +#### 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 +174,7 @@ option. It works like this: This will generate the following HTML: ```html -<form accept-charset="UTF-8" action="/articles" class="new_article" data-remote="true" id="new_article" method="post"> +<form action="/articles" method="post" data-remote="true"> ... </form> ``` @@ -189,32 +195,9 @@ $(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 -<form accept-charset="UTF-8" action="/articles" data-remote="true" method="post"> - ... -</form> -``` - -Everything else is the same as `form_for`. See its documentation for full -details. +start. -### 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 @@ -230,7 +213,7 @@ which generates <a href="/articles/1" data-remote="true">an article</a> ``` -You can bind to the same Ajax events as `form_for`. Here's an example. Let's +You can bind to the same Ajax events as `form_with`. Here's an example. Let's assume that we have a list of articles that can be deleted with just one click. We would generate some HTML like this: @@ -246,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: @@ -262,7 +245,136 @@ this generates </form> ``` -Since it's just a `<form>`, all of the information on `form_for` also applies. +Since it's just a `<form>`, all of the information on `form_with` 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 +<input type="checkbox" data-remote="true" + data-url="/update" data-params="id=10" data-method="put"> +``` + +#### `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 +<a href="..." data-confirm="Are you sure?">Dangerous zone</a> +``` + +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 +<input data-disable-with="Saving..." type="submit"> +``` + +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 -------------------- @@ -297,7 +409,7 @@ The index view (`app/views/users/index.html.erb`) contains: <br> -<%= form_for(@user, remote: true) do |f| %> +<%= form_with(model: @user) do |f| %> <%= f.label :name %><br> <%= f.text_field :name %> <%= f.submit %> |