render_async 2.1.5 → 2.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5a8461ed53ed7d4d5518985762d2f76dec99936336c4cbfaffb1ff5e3ae91e10
-  data.tar.gz: e5b013fb3116c1edf08532cff838c54b51042e88c40ef1354b0d2ad211c4793b
+  metadata.gz: 4c2458365f2d0d1c95a9356e4076e483b41e58518a6c0496d0b2d20c8a0c1e44
+  data.tar.gz: 9fce775541e8e12fe742a0ec03dfb52a92f47ac70c953442d74e612f721d0480
 SHA512:
-  metadata.gz: 75f915f3bdb92d38f5b9085377923423fbaa9bd72f39632d819c1114fa283bdd953a1fe3649d3c27f3609b01de951e24e8db008b8c9e5edf1ff2d1a792b809eb
-  data.tar.gz: d78fa9d2c96ee3676542ec6b4c0db93ad606917c225fd6386ed400c6ec9287ec70a9328eb2ae7e880faa04cb96e59e0ff3fc2ef3f469a3ee01bd720f8fe14849
+  metadata.gz: c1a00f85f23df409ba9a505c963359979512c32110096a3b7bf5431942a0a8274711fc2000a909f379d76a921548854bb3bc005e0cc6f6a31b8f46d94692c6f2
+  data.tar.gz: 8aab5df90bf0db84a3c4c82adf6eec772de19b553b9bdcd0d08646fdd20f522eb4cc4d41e7ef335aa856557e8f892cd8f3d7f2507938f042d8f0eaf3988bff75

data/.all-contributorsrc

@@ -196,6 +196,44 @@
       "contributions": [
         "code"
       ]
+    },
+    {
+      "login": "vanboom",
+      "name": "Don",
+      "avatar_url": "https://avatars1.githubusercontent.com/u/251706?v=4",
+      "profile": "https://github.com/vanboom",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "villu164",
+      "name": "villu164",
+      "avatar_url": "https://avatars0.githubusercontent.com/u/998682?v=4",
+      "profile": "https://github.com/villu164",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "Mbuckley0",
+      "name": "Mitchell Buckley",
+      "avatar_url": "https://avatars.githubusercontent.com/u/11203679?v=4",
+      "profile": "https://github.com/Mbuckley0",
+      "contributions": [
+        "code",
+        "doc"
+      ]
+    },
+    {
+      "login": "yhirano55",
+      "name": "yhirano55",
+      "avatar_url": "https://avatars.githubusercontent.com/u/15371677?v=4",
+      "profile": "https://github.com/yhirano55",
+      "contributions": [
+        "code",
+        "doc"
+      ]
     }
   ],
   "repoType": "github"

data/.github/CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# :pray: Contributing
+
+Thank you for considering or deciding to contribute, this is much appreciated!
+Any kind of bug reports and pull requests are encouraged and welcome on GitHub at
+https://github.com/renderedtext/render_async.
+
+## :inbox_tray: Installing dependencies
+
+You can install all needed dependencies by running `bin/setup`.
+
+## :runner: Running RSpec tests
+
+You can run either `rake spec` or `bundle exec rspec` to run all the RSpec tests
+in the project.
+
+## :running_woman: Running integration tests
+
+There is a simple command `bin/integration-tests` which sets up 2 submodules,
+and runs Cucumber features in them.
+
+There are 2 submodules for render_async. The submodules are Rails 5 and Rails 6
+projects which are located in:
+
+  - `spec/fixtures/rails-5-base-app`, and
+  - `spec/fixtures/rails-6-base-app`.
+
+You can find [Rails 5 base app here](https://github.com/nikolalsvk/rails-5-base-app/tree/render-async),
+and the [Rails 6 base app here](https://github.com/nikolalsvk/rails-6-base-app/tree/render-async).
+
+Each of them have different use cases of render_async defined in `app/views/render_asyncs/_use_cases.html.erb` in their repos.
+All the feature tests are inside `features/render_async.feature` and `features/render_async_jquery.feature` files.
+
+If you are adding one or more feature tests or use cases, make sure to make a
+PR on those repos as well and include them in the PR on the render_async repo.
+
+## :sos: Need help?
+
+Got any issues or difficulties?
+Join [render_async's Discord channel](https://discord.gg/SPfbeRm)
+and ask questions there. We will try to respond to you as quickly as possible.

data/.gitignore

@@ -15,3 +15,4 @@ spec/reports
 test/tmp
 test/version_tmp
 tmp
+.DS_Store

data/.gitmodules

@@ -2,3 +2,7 @@
 	path = spec/fixtures/rails-5-base-app
 	url = git@github.com:nikolalsvk/rails-5-base-app.git
 	branch = render-async
+[submodule "spec/fixtures/rails-6-base-app"]
+	path = spec/fixtures/rails-6-base-app
+	url = git@github.com:nikolalsvk/rails-6-base-app.git
+	branch = render-async

data/CHANGELOG.md

@@ -1,8 +1,64 @@
-### 2.1.1 (2019/8/17)
+### 2.1.10 (2021/03/21)
+
+* [#146](https://github.com/renderedtext/render_async/pull/146): Add comment when we check if container is present - [@nikolalsvk](https://github.com/nikolalsvk).
+* [#145](https://github.com/renderedtext/render_async/pull/145): Wrap html_options for turbolinks - [@yhirano55](https://github.com/yhirano55).
+* [#144](https://github.com/renderedtext/render_async/pull/144): Avoid TypeError if container has already disappear - [@yhirano55](https://github.com/yhirano55).
+
+### 2.1.9 (2021/02/23)
+
+* [#142](https://github.com/renderedtext/render_async/pull/142): Update Turbolinks docs - [@nikolalsvk](https://github.com/nikolalsvk).
+* [#141](https://github.com/renderedtext/render_async/pull/141): Add Support for Turbo - [@MBuckley0](https://github.com/Mbuckley0).
+* [#139](https://github.com/renderedtext/render_async/pull/139): Fix readme configuration-options anchor - [@richardvenneman](https://github.com/richardvenneman).
+* [#138](https://github.com/renderedtext/render_async/pull/138): Add Rails 6 base app as a fixture - [@nikolalsvk](https://github.com/nikolalsvk).
+* [#137](https://github.com/renderedtext/render_async/pull/137): Rename config - [@nikolalsvk](https://github.com/nikolalsvk).
+
+### 2.1.8 (2020/10/24)
+
+* [#134](https://github.com/renderedtext/render_async/pull/134): Add config option for setting nonce - [@nikolalsvk](https://github.com/nikolalsvk).
+* [#132](https://github.com/renderedtext/render_async/pull/132): Refresh render_async with an event - [@nikolalsvk](https://github.com/nikolalsvk).
+* [#131](https://github.com/renderedtext/render_async/pull/131): Start to poll on page load with toggle - [@nikolalsvk](https://github.com/nikolalsvk).
+* [#130](https://github.com/renderedtext/render_async/pull/130): Set up control events after document loaded - [@nikolalsvk](https://github.com/nikolalsvk).
+* [#127](https://github.com/renderedtext/render_async/pull/127): Update README.md, to reflect correct turbolinks configuration value - [@villu164](https://github.com/villu164).
+
+### 2.1.7 (2020/8/1)
+
+* [#125](https://github.com/renderedtext/render_async/pull/125): Implement retry after some time feature - [@nikolalsvk](https://github.com/nikolalsvk).
+* [#124](https://github.com/renderedtext/render_async/pull/124): Add more info on how to control polling - [@nikolalsvk](https://github.com/nikolalsvk).
+* [#123](https://github.com/renderedtext/render_async/pull/123): Simplify calling of start and stop event when interval is defined - [@nikolalsvk](https://github.com/nikolalsvk).
+* [#119](https://github.com/renderedtext/render_async/pull/119): Add polling control start/stop events - [@vanboom](https://github.com/vanboom).
+* [#120](https://github.com/renderedtext/render_async/pull/120): Fine tune custom content_for feature - [@nikolalsvk](https://github.com/nikolalsvk).
+* [#117](https://github.com/renderedtext/render_async/pull/117): Allow a custom content_for name - [@vanboom](https://github.com/vanboom).
+
+### 2.1.6 (2020/5/9)
+
+* [#114](https://github.com/renderedtext/render_async/pull/114): Call render_async logic if document state is ready or interactive - [@nikolalsvk](https://github.com/nikolalsvk).
+* [#113](https://github.com/renderedtext/render_async/pull/113): Remove interval after Turbolinks visit event - [@nikolalsvk](https://github.com/nikolalsvk).
+* [#112](https://github.com/renderedtext/render_async/pull/112): Add X-Requested-With header in Vanilla JS - [@nikolalsvk](https://github.com/nikolalsvk).
+* [#110](https://github.com/renderedtext/render_async/pull/110): Remove preventDefault, and load toggle in stream - [@vanboom](https://github.com/vanboom).
+
+### 2.1.5 (2020/3/22)
+
+* [#105](https://github.com/renderedtext/render_async/pull/105): Load toggle listeners after page loads - [@nikolalsvk](https://github.com/nikolalsvk).
+* [#104](https://github.com/renderedtext/render_async/pull/104): Attach container to dispatched events - [@nikolalsvk](https://github.com/nikolalsvk).
+* [#103](https://github.com/renderedtext/render_async/pull/103): Add generic "load" and "error" events - [@lipsumar](https://github.com/lipsumar).
+* [#98](https://github.com/renderedtext/render_async/pull/98): Bump nonce pattern in the README to follow Rails CSP standard - [@colinxfleming](https://github.com/colinxfleming).
+
+### 2.1.4 (2019/11/11)
+
+* [#96](https://github.com/renderedtext/render_async/pull/96): Add once option to remove event once it's triggered #94 - [@fffx](https://github.com/fffx).
+
+### 2.1.3 (2019/9/24)
+
+* [#95](https://github.com/renderedtext/render_async/pull/95): Use double quotes for displaying error message - [@nikolalsvk](https://github.com/nikolalsvk).
+* [#93](https://github.com/renderedtext/render_async/pull/93): Fix: "Uncaught ReferenceError: \_interval" #92 - [@fffx](https://github.com/fffx).
+
+### 2.1.2 (2019/8/17)
+
 * [#89](https://github.com/renderedtext/render_async/pull/89): Bump version to 2.1.2 - [@nikolalsvk](https://github.com/nikolalsvk).
 * [#82](https://github.com/renderedtext/render_async/pull/88): When toggle true, do not fire `_renderAsyncFunc` on `turbolinks:load` - [@ThanhKhoaIT](https://github.com/ThanhKhoaIT).
 
 ### 2.1.1 (2019/8/17)
+
 * [#85](https://github.com/renderedtext/render_async/pull/85): Rename main JS function and support toggle feature with other features - [@nikolalsvk](https://github.com/nikolalsvk).
 * [#82](https://github.com/renderedtext/render_async/pull/82): Add toggle selector and event to render - [@ThanhKhoaIT](https://github.com/ThanhKhoaIT).
 * DEPRECATION WARNING - html_options is now a hash that you pass to render_async instead of an argument. If you passed for example a nonce: '21312aas...', you will need to pass

data/README.md

@@ -1,32 +1,70 @@
-[![Build Status](https://semaphoreci.com/api/v1/renderedtext/render_async/branches/master/shields_badge.svg)](https://semaphoreci.com/renderedtext/render_async)
-[![All Contributors](https://img.shields.io/badge/all_contributors-20-orange.svg?style=flat-square)](#contributors)
-[![Gem Version](https://badge.fury.io/rb/render_async.svg)](https://badge.fury.io/rb/render_async)
-[![Donate](https://img.shields.io/badge/$-support-green.svg)](https://www.paypal.me/nikolalsvk/10)
-[![Code Climate](https://codeclimate.com/github/renderedtext/render_async/badges/gpa.svg)](https://codeclimate.com/github/renderedtext/render_async)
-[![Test Coverage](https://codeclimate.com/github/renderedtext/render_async/badges/coverage.svg)](https://codeclimate.com/github/renderedtext/render_async/coverage)
-[![Help Contribute to Open Source](https://www.codetriage.com/renderedtext/render_async/badges/users.svg)](https://www.codetriage.com/renderedtext/render_async)
-
-![render_async](http://s2blog.wpengine.com/wp-content/uploads/assets/images/2017-06-08/speed-up-rendering-rails-pages-with-render-async.png)
-
-# render_async
-
-Speed up rendering Rails pages with this gem.
-
-`render_async` renders partials to your views **asynchronously**. This is done
-through adding JavaScript code that does AJAX request to your controller which
-then renders your partial into a Rails view.
-
-Workflow:
-
-1. user visits a Rails page
-2. AJAX request on the controller action
+<p align="center">
+  <img src='http://s2blog.wpengine.com/wp-content/uploads/assets/images/2017-06-08/speed-up-rendering-rails-pages-with-render-async.png' alt='render_async' />
+
+  <h1 align="center">👋 Welcome to render_async</h1>
+
+  <h3 align="center">Let's make your Rails pages fast again :racehorse:</h3>
+
+  <br />
+
+  <p align="center">
+    <a href="https://www.paypal.me/nikolalsvk/10" target="_blank">
+     <img src="https://img.shields.io/badge/$-support-green.svg" alt="Donate" />
+    </a>
+    <a href="https://rubygems.org/gems/render_async" target="_blank">
+      <img src="https://img.shields.io/gem/dt/render_async" alt="Downloads" />
+    </a>
+    <a href="#contributors" target="_blank">
+     <img src="https://img.shields.io/github/all-contributors/renderedtext/render_async" alt="All contributors" />
+    </a>
+    <a href="https://badge.fury.io/rb/render_async" target="_blank">
+     <img src="https://badge.fury.io/rb/render_async.svg" alt="Gem Version" />
+    </a>
+    <br />
+    <a href="https://discord.gg/SPfbeRm" target="_blank">
+      <img src="https://img.shields.io/discord/738783603214909521" alt="Discord Server" />
+    </a>
+    <a href="https://semaphoreci.com/renderedtext/render_async" target="_blank">
+     <img src="https://semaphoreci.com/api/v1/renderedtext/render_async/branches/master/shields_badge.svg" alt="Build Status" />
+    </a>
+    <a href="https://codeclimate.com/github/renderedtext/render_async" target="_blank">
+     <img src="https://img.shields.io/codeclimate/maintainability/renderedtext/render_async" alt="Code Climate Maintainablity" />
+    </a>
+    <a href="https://codeclimate.com/github/renderedtext/render_async/coverage" target="_blank">
+     <img src="https://img.shields.io/codeclimate/coverage/renderedtext/render_async" alt="Test Coverage" />
+    </a>
+    <a href="https://github.com/renderedtext/render_async/blob/master/LICENSE" target="_blank">
+      <img src="https://img.shields.io/github/license/renderedtext/render_async" alt="License" />
+    </a>
+    <a href="https://www.codetriage.com/renderedtext/render_async" target="_blank">
+     <img src="https://www.codetriage.com/renderedtext/render_async/badges/users.svg" alt="Help Contribute to Open Source" />
+    </a>
+  </p>
+</p>
+
+### `render_async` is here to make your pages show faster to users.
+
+Pages become faster seamlessly by rendering partials to your views.
+
+Partials render **asynchronously** and let users see your page **faster**
+than using regular rendering.
+
+It works with Rails and its tools out of the box.
+
+:sparkles:  A quick overview of how `render_async` does its magic:
+
+1. user visits a page
+2. `render_async` makes an AJAX request on the controller action
 3. controller renders a partial
-4. partials renders in the place where you put `render_async` helper
+4. partial renders in the place where you put `render_async` view helper
 
-JavaScript is injected into `<%= content_for :render_async %>` so you choose
+JavaScript is injected straight into `<%= content_for :render_async %>` so you choose
 where to put it.
 
-## Installation
+:mega:  P.S. Join our [Discord channel](https://discord.gg/SPfbeRm) for help and discussion, and let's make `render_async` even better!
+
+## :package: Installation
+
 Add this line to your application's Gemfile:
 
 ```ruby
@@ -37,14 +75,14 @@ And then execute:
 
     $ bundle install
 
-## Usage
+## :hammer: Usage
 
 1. Include `render_async` view helper somewhere in your views (e.g. `app/views/comments/show.html.erb`):
     ```erb
     <%= render_async comment_stats_path %>
     ```
 
-2. Then create a route that will `config/routes.rb`:
+2. Then create a route for it `config/routes.rb`:
     ```ruby
     get :comment_stats, controller: :comments
     ```
@@ -70,7 +108,7 @@ And then execute:
     <%= content_for :render_async %>
     ```
 
-## Advanced usage
+## :hammer_and_wrench: Advanced usage
 
 Advanced usage includes information on different options, such as:
 
@@ -81,16 +119,22 @@ Advanced usage includes information on different options, such as:
   - [Passing in a placeholder](#passing-in-a-placeholder)
   - [Passing in an event name](#passing-in-an-event-name)
   - [Using default events](#using-default-events)
+  - [Refreshing the partial](#refreshing-the-partial)
   - [Retry on failure](#retry-on-failure)
+    - [Retry after some time](#retry-after-some-time)
   - [Toggle event](#toggle-event)
+    - [Control polling with a toggle](#control-polling-with-a-toggle)
   - [Polling](#polling)
+  - [Controlled polling](#controlled-polling)
   - [Handling errors](#handling-errors)
   - [Caching](#caching)
   - [Doing non-GET requests](#doing-non-get-requests)
   - [Using with Turbolinks](#using-with-turbolinks)
+  - [Using with Turbo](#using-with-turbo)
   - [Using with respond_to and JS format](#using-with-respond_to-and-js-format)
-  - [Nested Async Renders](#nested-async-renders)
-  - [Configuration](#configuration)
+  - [Nested async renders](#nested-async-renders)
+  - [Customizing the content_for name](#customizing-the-content_for-name)
+  - [Configuration options](#configuration-options)
 
 ### Passing in a container ID
 
@@ -136,6 +180,7 @@ Rendered code in the view:
 `javascript_tag`, to drop HTML tags into the `script` element.
 
 Example of utilizing `html_options` with a [nonce](https://edgeguides.rubyonrails.org/security.html#content-security-policy):
+
 ```erb
 <%= render_async users_path, html_options: { nonce: true } %>
 ```
@@ -154,6 +199,8 @@ Rendered code in the view:
 </div>
 ```
 
+> :bulb:  You can enable `nonce` to be set everywhere by using [configuration option](#configuration-options) render_async provides.
+
 ### Passing in an HTML element name
 
 `render_async` can take in an HTML element name, allowing you to control
@@ -240,13 +287,12 @@ document.addEventListener("users-loaded", function(event) {
 });
 ```
 
-NOTE: Dispatching events is also supported for older browsers that don't
-support Event constructor.
+> :bulb: Dispatching events is also supported for older browsers that don't support Event constructor.
 
 ### Using default events
 
 `render_async` will fire the event `render_async_load` when an async partial
-has loaded and rendered on page.
+has loaded and rendered on the page.
 
 In case there is an error, the event `render_async_error` will fire instead.
 
@@ -268,14 +314,44 @@ document.addEventListener('render_async_error', function(event) {
 });
 
 // with jQuery
-$(document).on('render_async_load', function(event, container) {
-  console.log('Async partial loaded in this container:', container);
+$(document).on('render_async_load', function(event) {
+  console.log('Async partial loaded in this container:', event.container);
 });
-$(document).on('render_async_error', function(event, container) {
-  console.log('Async partial could not load in this container:', container);
+$(document).on('render_async_error', function(event) {
+  console.log('Async partial could not load in this container:', event.container);
 });
 ```
 
+### Refreshing the partial
+
+`render_async` lets you refresh (reload) the partial by letting you dispatch
+the 'refresh' event on the `render_async`'s container. An example:
+
+```erb
+<%= render_async comments_path,
+                 container_id: 'refresh-me',
+                 replace_container: false %>
+
+<button id="refresh-button">Refresh comments</button>
+
+<script>
+  var button = document.getElementById('refresh-button')
+  var container = document.getElementById('refresh-me');
+
+  button.addEventListener('click', function() {
+    var event = new Event('refresh');
+
+    // Dispatch 'refresh' on the render_async container
+    container.dispatchEvent(event)
+  })
+</script>
+```
+
+If you follow the example above, when you click "Refresh comments" button,
+`render_async` will trigger again and reload the `comments_path`.
+
+> :bulb:  Note that you need to pass `replace_container: false` so you can later dispatch an event on that container.
+
 ### Retry on failure
 
 `render_async` can retry your requests if they fail for some reason.
@@ -293,6 +369,39 @@ it will show an [error message](#handling-errors) which you need to specify.
 This can show useful when you know your requests often fail, and you don't want
 to refresh the whole page just to retry them.
 
+#### Retry after some time
+
+If you want to retry requests but with some delay in between the calls, you can
+pass a `retry_delay` option together with `retry_count` like so:
+
+```erb
+<%= render_async users_path,
+                 retry_count: 5,
+                 retry_delay: 2000 %>
+```
+
+This will make `render_async` wait for 2 seconds before retrying after each
+failure. In the end, if the request is still failing after 5th time, it will
+dispatch a [default error event](#using-default-events).
+
+> :candy:  If you are catching an event after an error, you can get `retryCount` from
+the event. `retryCount` will have the number of retries it took before the event was dispatched.
+
+Here is an example on how to get `retryCount`:
+
+```erb
+<%= render_async users_path,
+                 retry_count: 5,
+                 retry_delay: 2000,
+                 error_event_name: 'it-failed-badly' %>
+
+<script>
+  document.addEventListener('it-failed-badly', function(event) {
+    console.log("Request failed after " + event.retryCount + " tries!")
+  });
+</script>
+```
+
 ### Toggle event
 
 You can trigger `render_async` loading by clicking or doing another event to a
@@ -302,37 +411,57 @@ default event that will trigger `render_async` will be 'click' event. You can
 do this by doing the following:
 
 ```erb
-<a href='#' id='detail-button'>Detail</a>
-<%= render_async comments_path, toggle: { selector: '#detail-button', event: :click } %>
+<a href='#' id='comments-button'>Load comments</a>
+<%= render_async comments_path, toggle: { selector: '#comments-button', event: :click } %>
 ```
 
-This will trigger `render_async` to load the `comments_path` when you click the `#details-button` element.
-If you want to remove event once it's triggered, you can pass `once: true` in the toggle options.
-The `once` option is false by default.
+This will trigger `render_async` to load the `comments_path` when you click the `#comments-button` element.
+If you want to remove an event once it's triggered, you can pass `once: true` in the toggle options.
+The `once` option is false (`nil`) by default.
 
 You can also pass in a placeholder before the `render_async` is triggered. That
 way, the element that started `render_async` logic will be removed after the
 request has been completed. You can achieve this behaviour with something like this:
 
 ```erb
-<%= render_async comments_path, toggle: { selector: '#detail-button', event: :click } do %>
-  <a href='#' id='detail-button'>Detail</a>
+<%= render_async comments_path, toggle: { selector: '#comments-button', event: :click } do %>
+  <a href='#' id='comments-button'>Load comments</a>
 <% end %>
 ```
 
+#### Control polling with a toggle
+
 Also, you can mix interval and toggle features. This way, you can turn polling
-on, and off by clicking the "Detail" button. In order to do this, you need to
+on, and off by clicking the "Load comments" button. In order to do this, you need to
 pass `toggle` and `interval` arguments to `render_async` call like this:
 
 ```erb
-<a href='#' id='detail-button'>Detail</a>
-<%= render_async comments_path, toggle: { selector: '#detail-button', event: :click }, interval: 2000 %>
+<a href='#' id='comments-button'>Load comments</a>
+<%= render_async comments_path, toggle: { selector: '#comments-button', event: :click }, interval: 2000 %>
 ```
 
+If you want `render_async` to render the request on load, you can pass `start:
+true`. Passing the `start` option inside the `toggle` hash will trigger
+`render_async` on page load. You can then toggle off polling by interacting
+with the element you specified. An example:
+
+```erb
+<a href='#' id='comments-button'>Toggle comments loading</a>
+<%= render_async comments_path,
+                 toggle: { selector: '#comments-button',
+                           event: :click,
+                           start: true },
+                 interval: 2000 %>
+```
+
+In the example above, the comments will load as soon as the page is rendered.
+Then, you can stop polling for comments by clicking the "Toggle comments
+loading" button.
+
 ### Polling
 
 You can call `render_async` with interval argument. This will make render_async
-call specified path at specified interval.
+call specified path at the specified interval.
 
 By doing this:
 ```erb
@@ -342,15 +471,65 @@ You are telling `render_async` to fetch comments_path every 5 seconds.
 
 This can be handy if you want to enable polling for a specific URL.
 
-NOTE: By passing interval to `render_async`, initial container element
-will remain in HTML tree, it will not be replaced with request response.
-You can handle how that container element is rendered and its style by
-[passing in an HTML element name](#passing-in-an-html-element-name) and
-[HTML element class](#passing-in-a-container-class-name).
+> :warning:  By passing interval to `render_async`, the initial container element
+> will remain in the HTML tree and it will not be replaced with request response.
+> You can handle how that container element is rendered and its style by
+> [passing in an HTML element name](#passing-in-an-html-element-name) and
+> [HTML element class](#passing-in-a-container-class-name).
+
+### Controlled polling
+
+You can controller `render_async` [polling](#polling) in 2 manners.
+First one is pretty simple, and it involves using the [toggle](#toggle-event)
+feature. To do this, you can follow instructions in the
+[control polling with a toggle section](#control-polling-with-a-toggle).
+
+The second option is more advanced and it involves emitting events to the `render_async`'s
+container element. From your code, you can emit the following events:
+  - 'async-stop' - this will stop polling
+  - 'async-start' - this will start polling.
+
+> :bulb:  Please note that events need to be dispatched to a render_async container.
+
+An example of how you can do this looks like this:
+
+```erb
+<%= render_async wave_render_async_path,
+                 container_id: 'controllable-interval', # set container_id so we can get it later easily
+                 interval: 3000 %>
+
+<button id='stop-polling'>Stop polling</button>
+<button id='start-polling'>Start polling</button>
+
+<script>
+  var container = document.getElementById('controllable-interval')
+  var stopPolling = document.getElementById('stop-polling')
+  var startPolling = document.getElementById('start-polling')
+
+  var triggerEventOnContainer = function(eventName) {
+    var event = new Event(eventName);
+
+    container.dispatchEvent(event)
+  }
+
+  stopPolling.addEventListener('click', function() {
+    container.innerHTML = '<p>Polling stopped</p>'
+    triggerEventOnContainer('async-stop')
+  })
+  startPolling.addEventListener('click', function() {
+    triggerEventOnContainer('async-start')
+  })
+</script>
+```
+
+We are rendering two buttons - "Stop polling" and "Start polling". Then, we
+attach an event listener to catch any clicking on the buttons. When the buttons
+are clicked, we either stop the polling or start the polling, depending on which
+button a user clicks.
 
 ### Handling errors
 
-`render_async` let's you handle errors by allowing you to pass in `error_message`
+`render_async` lets you handle errors by allowing you to pass in `error_message`
 and `error_event_name`.
 
 - `error_message`
@@ -396,10 +575,10 @@ Then, in the partial (e.g. `app/views/comments/_comment_stats.html.erb`):
 <% end %>
 ```
 
-* The first time the page renders, it will make the AJAX call.
-* Any other times (until the cache expires), it will render from cache
+- The first time the page renders, it will make the AJAX call.
+- Any other times (until the cache expires), it will render from cache
   instantly, without making the AJAX call.
-* You can expire cache simply by passing `:expires_in` in your view where
+- You can expire cache simply by passing `:expires_in` in your view where
   you cache the partial
 
 ### Doing non-GET requests
@@ -437,19 +616,49 @@ end
 ```
 
 This way, you're not breaking Turbolinks flow of loading or reloading a page.
-It makes it more efficient that the next option that is suggested below.
+It is more efficient than the next option below.
 
 Another option:
 If you want, you can tell Turbolinks to reload your `render_async` call as follows:
 
 ```erb
-<%= render_async events_path, 'data-turbolinks-track': 'reload' %>
+<%= render_async events_path, html_options: { 'data-turbolinks-track': 'reload' } %>
 ```
 
 This will reload the whole page with Turbolinks.
 
-Make sure to put `<%= content_for :render_async %>` in your base view file in
-the `<head>` and not the `<body>`.
+> :bulb:  If Turbolinks is misbehaving in some way, make sure to put `<%= content_for :render_async %>` in your base view file in
+the `<body>` and not the `<head>`.
+
+### Using with Turbo
+
+On Turbo applications, you may experience caching issues when navigating
+away from, and then back to, a page with a `render_async` call on it. This will
+likely show up as an empty div.
+
+If you're using Turbo, you can resolve this by setting Turbo
+configuration of `render_async` to true:
+
+```rb
+RenderAsync.configure do |config|
+  config.turbo = true # Enable this option if you are using Turbo
+end
+```
+
+This way, you're not breaking Turbos flow of loading or reloading a page.
+It is more efficient than the next option below.
+
+Another option:
+If you want, you can tell Turbo to reload your `render_async` call as follows:
+
+```erb
+<%= render_async events_path, html_options: { 'data-turbo-track': 'reload' } %>
+```
+
+This will reload the whole page with Turbo.
+
+> :bulb:  If Turbo is misbehaving in some way, make sure to put `<%= content_for :render_async %>` in your base view file in
+the `<body>` and not the `<head>`.
 
 ### Using with respond_to and JS format
 
@@ -468,7 +677,7 @@ def comment_stats
 end
 ```
 
-When you do this, Rails will sometime set the response's `Content-Type` header
+When you do this, Rails will sometimes set the response's `Content-Type` header
 to `text/javascript`. This causes the partial not to be rendered in the HTML.
 This usually happens when there's browser caching.
 
@@ -479,7 +688,7 @@ render call:
 render partial: "comment_stats", content_type: 'text/html'
 ```
 
-### Nested Async Renders
+### Nested async renders
 
 It is possible to nest async templates within other async templates. When doing
 so, another `content_for` is required to ensure the JavaScript needed to load
@@ -506,7 +715,20 @@ For example:
 <%= content_for :render_async %>
 ```
 
-### Configuration
+### Customizing the content_for name
+
+The `content_for` name may be customized by passing the `content_for_name`
+option to `render_async`. This option is especially useful when doing [nested async
+renders](#nested-async-renders) to better control the location of the injected JavaScript.
+
+For example:
+```erb
+<%= render_async comment_stats_path, content_for_name: :render_async_comment_stats %>
+
+<%= content_for :render_async_comment_stats %>
+```
+
+### Configuration options
 
 `render_async` renders Vanilla JS (regular JavaScript, non-jQuery code)
 **by default** in order to fetch the request from the server.
@@ -516,10 +738,14 @@ so.
 
 You can configure it by doing the following anywhere before you call
 `render_async`:
+
 ```rb
 RenderAsync.configure do |config|
-  config.jquery = true # This will render jQuery code, and skip Vanilla JS code
-  config.turbolinks = false # Enable this option if you are using Turbolinks 5+
+  config.jquery = true # This will render jQuery code, and skip Vanilla JS code. The default value is false.
+  config.turbolinks = true # Enable this option if you are using Turbolinks 5+. The default value is false.
+  config.turbo = true # Enable this option if you are using Turbo. The default value is false.
+  config.replace_container = false # Set to false if you want to keep the placeholder div element from render_async. The default value is true.
+  config.nonces = true # Set to true if you want render_async's javascript_tag always to receive nonce: true. The default value is false.
 end
 ```
 
@@ -529,17 +755,34 @@ Also, you can do it like this:
 RenderAsync.configuration.jquery = true
 ```
 
-## Development
+Aside from configuring whether the gem relies on jQuery or VanillaJS, you can
+configure other options:
+
+- `turbolinks` option - If you are using Turbolinks 5+, you should enable this option since it supports Turbolinks way of loading data. The default value for this option is false.
+- `turbo` option - If you are using Turbo, you should enable this option since it supports Turbo way of loading data. The default value for this option is false.
+- `replace_container` option - If you want render_async to replace its container with the request response, turn this on. You can turn this on globally for all render_async calls, but if you use this option in a specific render_async call, it will override the global configuration. The default value is true.
+- `nonces` - If you need to pass in `nonce: true` to the `javascript_tag` in your application, it might make sense for you to turn this on globally for all render_async calls. To read more about nonces, check out [Rails' official guide on security](https://edgeguides.rubyonrails.org/security.html). The default value is false.
+
+## :hammer_and_pick: Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run
 `rake spec` to run the tests. You can also run `bin/console` for an interactive
-prompt that will allow you to experiment.
+prompt that will allow you to experiment. To run integration tests, use
+`bin/integration-tests`. For more information, check out [CONTRIBUTING](.github/CONTRIBUTING.md) file, please.
+
+Got any questions or comments about development (or anything else)?
+Join [render_async's Discord channel](https://discord.gg/SPfbeRm)
+and let's make `render_async` even better!
+
+## :pray: Contributing
 
-## Contributing
+Check out [CONTRIBUTING](.github/CONTRIBUTING.md) file, please.
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/renderedtext/render_async.
+Got any issues or difficulties?
+Join [render_async's Discord channel](https://discord.gg/SPfbeRm)
+and let's make `render_async` even better!
 
-## License
+## :memo: License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
 
@@ -552,7 +795,8 @@ Thanks goes to these wonderful people ([emoji key](https://github.com/kentcdodds
 | [<img src="https://avatars2.githubusercontent.com/u/3028124?v=4" width="100px;"/><br /><sub><b>Nikola Đuza</b></sub>](https://nikolalsvk.github.io)<br />[💬](#question-nikolalsvk "Answering Questions") [💻](https://github.com/renderedtext/render_async/commits?author=nikolalsvk "Code") [📖](https://github.com/renderedtext/render_async/commits?author=nikolalsvk "Documentation") [👀](#review-nikolalsvk "Reviewed Pull Requests") | [<img src="https://avatars0.githubusercontent.com/u/3866868?v=4" width="100px;"/><br /><sub><b>Colin</b></sub>](http://www.colinxfleming.com)<br />[💻](https://github.com/renderedtext/render_async/commits?author=colinxfleming "Code") [📖](https://github.com/renderedtext/render_async/commits?author=colinxfleming "Documentation") [💡](#example-colinxfleming "Examples") | [<img src="https://avatars2.githubusercontent.com/u/334273?v=4" width="100px;"/><br /><sub><b>Kasper Grubbe</b></sub>](http://kaspergrubbe.com)<br />[💻](https://github.com/renderedtext/render_async/commits?author=kaspergrubbe "Code") | [<img src="https://avatars2.githubusercontent.com/u/163584?v=4" width="100px;"/><br /><sub><b>Sai Ram Kunala</b></sub>](https://sairam.xyz/)<br />[📖](https://github.com/renderedtext/render_async/commits?author=sairam "Documentation") | [<img src="https://avatars2.githubusercontent.com/u/3065882?v=4" width="100px;"/><br /><sub><b>Josh Arnold</b></sub>](https://github.com/nightsurge)<br />[💻](https://github.com/renderedtext/render_async/commits?author=nightsurge "Code") [📖](https://github.com/renderedtext/render_async/commits?author=nightsurge "Documentation") | [<img src="https://avatars3.githubusercontent.com/u/107798?v=4" width="100px;"/><br /><sub><b>Elad Shahar</b></sub>](https://eladshahar.com)<br />[💻](https://github.com/renderedtext/render_async/commits?author=SaladFork "Code") [💡](#example-SaladFork "Examples") | [<img src="https://avatars3.githubusercontent.com/u/232392?v=4" width="100px;"/><br /><sub><b>Sasha</b></sub>](http://www.revzin.co.il)<br />[💻](https://github.com/renderedtext/render_async/commits?author=sasharevzin "Code") [📖](https://github.com/renderedtext/render_async/commits?author=sasharevzin "Documentation") |
 | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
 | [<img src="https://avatars3.githubusercontent.com/u/50223?v=4" width="100px;"/><br /><sub><b>Ernest Surudo</b></sub>](http://elsurudo.com)<br />[💻](https://github.com/renderedtext/render_async/commits?author=elsurudo "Code") | [<img src="https://avatars1.githubusercontent.com/u/334809?v=4" width="100px;"/><br /><sub><b>Kurtis Rainbolt-Greene</b></sub>](https://kurtis.rainbolt-greene.online)<br />[💻](https://github.com/renderedtext/render_async/commits?author=krainboltgreene "Code") | [<img src="https://avatars2.githubusercontent.com/u/59744?v=4" width="100px;"/><br /><sub><b>Richard Schneeman</b></sub>](https://www.schneems.com)<br />[📖](https://github.com/renderedtext/render_async/commits?author=schneems "Documentation") | [<img src="https://avatars1.githubusercontent.com/u/75705?v=4" width="100px;"/><br /><sub><b>Richard Venneman</b></sub>](https://www.cityspotters.com)<br />[📖](https://github.com/renderedtext/render_async/commits?author=richardvenneman "Documentation") | [<img src="https://avatars3.githubusercontent.com/u/381395?v=4" width="100px;"/><br /><sub><b>Filipe W. Lima</b></sub>](https://github.com/filipewl)<br />[📖](https://github.com/renderedtext/render_async/commits?author=filipewl "Documentation") | [<img src="https://avatars0.githubusercontent.com/u/3135638?v=4" width="100px;"/><br /><sub><b>Jesús Eduardo Clemens Chong</b></sub>](https://github.com/eclemens)<br />[💻](https://github.com/renderedtext/render_async/commits?author=eclemens "Code") | [<img src="https://avatars3.githubusercontent.com/u/1935686?v=4" width="100px;"/><br /><sub><b>René Klačan</b></sub>](https://github.com/reneklacan)<br />[💻](https://github.com/renderedtext/render_async/commits?author=reneklacan "Code") |
-| [<img src="https://avatars1.githubusercontent.com/u/1313442?v=4" width="100px;"/><br /><sub><b>Gil Gomes</b></sub>](http://gilgomes.com.br)<br />[📖](https://github.com/renderedtext/render_async/commits?author=gil27 "Documentation") | [<img src="https://avatars0.githubusercontent.com/u/6081795?v=4" width="100px;"/><br /><sub><b>Khoa Nguyen</b></sub>](https://github.com/ThanhKhoaIT)<br />[💻](https://github.com/renderedtext/render_async/commits?author=ThanhKhoaIT "Code") [📖](https://github.com/renderedtext/render_async/commits?author=ThanhKhoaIT "Documentation") | [<img src="https://avatars2.githubusercontent.com/u/8645918?v=4" width="100px;"/><br /><sub><b>Preet Sethi</b></sub>](https://www.linkedin.com/in/preetsethila/)<br />[💻](https://github.com/renderedtext/render_async/commits?author=preetsethi "Code") | [<img src="https://avatars3.githubusercontent.com/u/11586335?v=4" width="100px;"/><br /><sub><b>fangxing</b></sub>](https://github.com/fffx)<br />[💻](https://github.com/renderedtext/render_async/commits?author=fffx "Code") | [<img src="https://avatars3.githubusercontent.com/u/1191418?v=4" width="100px;"/><br /><sub><b>Emmanuel Pire</b></sub>](http://blog.lipsumarium.com)<br />[💻](https://github.com/renderedtext/render_async/commits?author=lipsumar "Code") [📖](https://github.com/renderedtext/render_async/commits?author=lipsumar "Documentation") | [<img src="https://avatars1.githubusercontent.com/u/615509?v=4" width="100px;"/><br /><sub><b>Maxim Geerinck</b></sub>](https://github.com/maximgeerinck)<br />[💻](https://github.com/renderedtext/render_async/commits?author=maximgeerinck "Code") |
+| [<img src="https://avatars1.githubusercontent.com/u/1313442?v=4" width="100px;"/><br /><sub><b>Gil Gomes</b></sub>](http://gilgomes.com.br)<br />[📖](https://github.com/renderedtext/render_async/commits?author=gil27 "Documentation") | [<img src="https://avatars0.githubusercontent.com/u/6081795?v=4" width="100px;"/><br /><sub><b>Khoa Nguyen</b></sub>](https://github.com/ThanhKhoaIT)<br />[💻](https://github.com/renderedtext/render_async/commits?author=ThanhKhoaIT "Code") [📖](https://github.com/renderedtext/render_async/commits?author=ThanhKhoaIT "Documentation") | [<img src="https://avatars2.githubusercontent.com/u/8645918?v=4" width="100px;"/><br /><sub><b>Preet Sethi</b></sub>](https://www.linkedin.com/in/preetsethila/)<br />[💻](https://github.com/renderedtext/render_async/commits?author=preetsethi "Code") | [<img src="https://avatars3.githubusercontent.com/u/11586335?v=4" width="100px;"/><br /><sub><b>fangxing</b></sub>](https://github.com/fffx)<br />[💻](https://github.com/renderedtext/render_async/commits?author=fffx "Code") | [<img src="https://avatars3.githubusercontent.com/u/1191418?v=4" width="100px;"/><br /><sub><b>Emmanuel Pire</b></sub>](http://blog.lipsumarium.com)<br />[💻](https://github.com/renderedtext/render_async/commits?author=lipsumar "Code") [📖](https://github.com/renderedtext/render_async/commits?author=lipsumar "Documentation") | [<img src="https://avatars1.githubusercontent.com/u/615509?v=4" width="100px;"/><br /><sub><b>Maxim Geerinck</b></sub>](https://github.com/maximgeerinck)<br />[💻](https://github.com/renderedtext/render_async/commits?author=maximgeerinck "Code") | [<img src="https://avatars1.githubusercontent.com/u/251706?v=4" width="100px;"/><br /><sub><b>Don</b></sub>](https://github.com/vanboom)<br />[💻](https://github.com/renderedtext/render_async/commits?author=vanboom "Code") |
+| [<img src="https://avatars0.githubusercontent.com/u/998682?v=4" width="100px;"/><br /><sub><b>villu164</b></sub>](https://github.com/villu164)<br />[📖](https://github.com/renderedtext/render_async/commits?author=villu164 "Documentation") | [<img src="https://avatars.githubusercontent.com/u/11203679?v=4" width="100px;"/><br /><sub><b>Mitchell Buckley</b></sub>](https://github.com/Mbuckley0)<br />[💻](https://github.com/renderedtext/render_async/commits?author=Mbuckley0 "Code") [📖](https://github.com/renderedtext/render_async/commits?author=Mbuckley0 "Documentation") | [<img src="https://avatars.githubusercontent.com/u/15371677?v=4" width="100px;"/><br /><sub><b>yhirano55</b></sub>](https://github.com/yhirano55)<br />[💻](https://github.com/renderedtext/render_async/commits?author=yhirano55 "Code") [📖](https://github.com/renderedtext/render_async/commits?author=yhirano55 "Documentation") |
 <!-- ALL-CONTRIBUTORS-LIST:END -->
 
 This project follows the [all-contributors](https://github.com/kentcdodds/all-contributors) specification. Contributions of any kind welcome!