Merge pull request #256 from defunkt/pjax-version-reloading

Layout Reloading

Author: josh

README.md

@@ -243,6 +243,26 @@ An `X-PJAX` request header is set to differentiate a pjax request from normal XH
 
 Check if your favorite server framework supports pjax here: https://gist.github.com/4283721
 
+#### Layout Reloading
+
+Layouts can be forced to do a hard reload assets or html changes.
+
+First set the initial layout version in your header with a custom meta tag.
+
+``` html
+<meta http-equiv="x-pjax-version" content="v123">
+```
+
+Then from the server side, set the `X-PJAX-Version` header to the same.
+
+``` ruby
+if request.headers['X-PJAX']
+  response.headers['X-PJAX-Version'] = "v123"
+end
+```
+
+Deploying a deploy, bumping the version constant to force clients to do a full reload the next request getting the new layout and assets.
+
 ### Legacy API
 
 Pre 1.0 versions used an older style syntax that was analogous to the now deprecated `$.fn.live` api. The current api is based off `$.fn.on`.

jquery.pjax.js

@@ -223,8 +223,23 @@ function pjax(options) {
   }
 
   options.success = function(data, status, xhr) {
+    // If $.pjax.defaults.version is a function, invoke it first.
+    // Otherwise it can be a static string.
+    var currentVersion = (typeof $.pjax.defaults.version === 'function') ?
+      $.pjax.defaults.version() :
+      $.pjax.defaults.version
+
+    var latestVersion = xhr.getResponseHeader('X-PJAX-Version')
+
     var container = extractContainer(data, xhr, options)
 
+    // If there is a layout version mismatch, hard load the new url
+    if (currentVersion && latestVersion && currentVersion !== latestVersion) {
+      locationReplace(container.url)
+      return
+    }
+
+    // If the new response is missing a body, hard load the page
     if (!container.contents) {
       locationReplace(container.url)
       return
@@ -676,6 +691,16 @@ function cachePop(direction, id, value) {
     delete cacheMapping[id]
 }
 
+// Public: Find version identifier for the initial page load.
+//
+// Returns String version or undefined.
+function findVersion() {
+  return $('meta').filter(function() {
+    var name = $(this).attr('http-equiv')
+    return name && name.toUpperCase() === 'X-PJAX-VERSION'
+  }).attr('content')
+}
+
 // Install pjax functions on $.pjax to enable pushState behavior.
 //
 // Does nothing if already enabled.
@@ -700,7 +725,8 @@ function enable() {
     type: 'GET',
     dataType: 'html',
     scrollTo: 0,
-    maxCacheLength: 20
+    maxCacheLength: 20,
+    version: findVersion
   }
   $(window).bind('popstate.pjax', onPjaxPopstate)
 }

test/app.rb

@@ -22,6 +22,7 @@ def title(str)
 after do
   if pjax?
     response.headers['X-PJAX-URL'] = request.url
+    response.headers['X-PJAX-Version'] = 'v1'
   end
 end
 

test/unit/pjax.js

@@ -400,6 +400,23 @@ if ($.support.pjax) {
     }
   })
 
+  asyncTest("header version mismatch does a full load", function() {
+    var frame = this.frame
+
+    frame.$.pjax.defaults.version = 'v2'
+
+    frame.$.pjax({
+      url: "hello.html",
+      container: "#main"
+    })
+
+    this.iframe.onload = function() {
+      equal(frame.$("#main p").html(), "Hello!")
+      equal(frame.location.pathname, "/hello.html")
+      start()
+    }
+  })
+
 
   asyncTest("triggers pjax:start event from container", function() {
     var frame = this.frame