Merge pull request #349 from turbolinks/per-page-reload

Add meta tag for opting in to full page reloads
turbolinks · Jan 8, 2018 · 3c1a1fa · 3c1a1fa
2 parents 69d79ad + df3c05c
commit 3c1a1fa
Show file tree

Hide file tree

Showing 6 changed files with 51 additions and 3 deletions.
diff --git a/README.md b/README.md
@@ -67,6 +67,7 @@ Your application can use the [`turbolinks` npm package](https://www.npmjs.com/pa
 [Advanced Usage](#advanced-usage)
 - [Displaying Progress](#displaying-progress)
 - [Reloading When Assets Change](#reloading-when-assets-change)
+- [Ensuring Specific Pages Trigger a Full Reload](#ensuring-specific-pages-trigger-a-full-reload)
 - [Setting a Root Location](#setting-a-root-location)
 - [Following Redirects](#following-redirects)
 - [Redirecting After a Form Submission](#redirecting-after-a-form-submission)
@@ -350,9 +351,16 @@ Annotate asset elements with `data-turbolinks-track="reload"` and include a vers
 </head>
 ```
 
-You can use asset tracking with any HTML element, such as `<link>`, `<script>`, or even `<meta>`. An element annotated with `data-turbolinks-track="reload"` will trigger a full reload if it changes in any way, e.g. if its attributes are not identical, or if the element is present on one page but not on the next.
+## Ensuring Specific Pages Trigger a Full Reload
 
-Note that Turbolinks will only consider tracked assets in `<head>` and not elsewhere on the page.
+If you want certain pages to always fully reload when they're navigated to, set the page's `visit-control` to `reload` using a special `<meta>` tag. This may be useful for pages with 3rd party JavaScript libraries that don't interact well with standard Turbolinks page changes.
+
+```html
+<head>
+  ...
+  <meta name="turbolinks-visit-control" name="reload">
+</head>
+```
 
 ## Setting a Root Location
 

diff --git a/src/turbolinks/snapshot.coffee b/src/turbolinks/snapshot.coffee
@@ -40,6 +40,9 @@ class Turbolinks.Snapshot
   isCacheable: ->
     @getCacheControlValue() isnt "no-cache"
 
+  isVisitable: ->
+    @getSetting("visit-control") isnt "reload"
+
   # Private
 
   getSetting: (name) ->

diff --git a/src/turbolinks/snapshot_renderer.coffee b/src/turbolinks/snapshot_renderer.coffee
@@ -8,7 +8,7 @@ class Turbolinks.SnapshotRenderer extends Turbolinks.Renderer
     @newBody = @newSnapshot.body
 
   render: (callback) ->
-    if @trackedElementsAreIdentical()
+    if @shouldRender()
       @mergeHead()
       @renderView =>
         @replaceBody()
@@ -28,6 +28,9 @@ class Turbolinks.SnapshotRenderer extends Turbolinks.Renderer
     @importBodyPermanentElements()
     @assignNewBody()
 
+  shouldRender: ->
+    @newSnapshot.isVisitable() and @trackedElementsAreIdentical()
+
   trackedElementsAreIdentical: ->
     @currentHeadDetails.getTrackedElementSignature() is @newHeadDetails.getTrackedElementSignature()
 

diff --git a/test/src/fixtures/rendering.html b/test/src/fixtures/rendering.html
@@ -15,6 +15,7 @@ <h1>Rendering</h1>
       <p><a id="body-script-link" href="/fixtures/body_script.html">Body script</a></p>
       <p><a id="eval-false-script-link" href="/fixtures/eval_false_script.html">data-turbolinks-eval=false script</a></p>
       <p><a id="nonexistent-link" href="/nonexistent">Nonexistent link</a></p>
+      <p><a id="visit-control-reload-link" href="/fixtures/visit_control_reload.html">Visit control: reload</a></p>
     </section>
   </body>
 </html>
diff --git a/test/src/fixtures/visit_control_reload.html b/test/src/fixtures/visit_control_reload.html
@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <title>Visit control: reload</title>
+    <script src="/turbolinks.js" data-turbolinks-track="reload"></script>
+    <meta name="turbolinks-visit-control" content="reload">
+  </head>
+  <body>
+    <h1>Visit control: reload</h1>
+  </body>
+</html>
diff --git a/test/src/modules/rendering_tests.coffee b/test/src/modules/rendering_tests.coffee
@@ -41,6 +41,27 @@ renderingTest "reloads when tracked elements change", (assert, session, done) ->
       assert.equal(navigation.action, "load")
       done()
 
+renderingTest "reloads when turbolinks-visit-control setting is reload", (assert, session, done) ->
+  responseReceived = false
+  session.waitForEvent "turbolinks:request-end", (event) ->
+    responseReceived = true
+
+  rendered = false
+  session.waitForEvent "turbolinks:render", (event) ->
+    rendered = true
+
+  session.clickSelector "#visit-control-reload-link", (navigation) ->
+    # Turbolinks calls pushState first, after issuing the request
+    # but before receiving the response. Wait again for the reload.
+    assert.equal(navigation.location.pathname, "/fixtures/visit_control_reload.html")
+    assert.equal(navigation.action, "push")
+    session.waitForNavigation (navigation) ->
+      assert.ok(responseReceived)
+      assert.notOk(rendered)
+      assert.equal(navigation.location.pathname, "/fixtures/visit_control_reload.html")
+      assert.equal(navigation.action, "load")
+      done()
+
 renderingTest "accumulates asset elements in head", (assert, session, done) ->
   originalElements = getAssetElements(session.element.document)
   session.clickSelector "#additional-assets-link", ->