jQuery 3 compatibility for history navigation

jQuery 3 doesn't support the `selector` property on jQuery objects
anymore. Instead, this refactors pjax options handling to always expect
that `container` is explicitly specified as a string selector.

Author: mislav

jquery.pjax.js

@@ -19,9 +19,7 @@
 // pjax specific options:
 //
 //
-// container - Where to stick the response body. Usually a String selector.
-//             $(container).html(xhr.responseBody)
-//             (default: current jquery context)
+// container - String selector for the element where to place the response body.
 //      push - Whether to pushState the URL. Defaults to true (of course).
 //   replace - Want to use replaceState instead? That's cool.
 //
@@ -30,11 +28,13 @@
 //
 // Returns the jQuery object
 function fnPjax(selector, container, options) {
-  var context = this
+  options = optionsFor(container, options)
   return this.on('click.pjax', selector, function(event) {
-    var opts = $.extend({}, optionsFor(container, options))
-    if (!opts.container)
-      opts.container = $(this).attr('data-pjax') || context
+    var opts = options
+    if (!opts.container) {
+      opts = $.extend({}, options)
+      opts.container = $(this).attr('data-pjax')
+    }
     handleClick(event, opts)
   })
 }
@@ -52,11 +52,6 @@ function fnPjax(selector, container, options) {
 //   // is the same as
 //   $(document).pjax('a')
 //
-//  $(document).on('click', 'a', function(event) {
-//    var container = $(this).closest('[data-pjax-container]')
-//    $.pjax.click(event, container)
-//  })
-//
 // Returns nothing.
 function handleClick(event, container, options) {
   options = optionsFor(container, options)
@@ -110,8 +105,7 @@ function handleClick(event, container, options) {
 // Examples
 //
 //  $(document).on('submit', 'form', function(event) {
-//    var container = $(this).closest('[data-pjax-container]')
-//    $.pjax.submit(event, container)
+//    $.pjax.submit(event, '[data-pjax-container]')
 //  })
 //
 // Returns nothing.
@@ -158,8 +152,7 @@ function handleSubmit(event, container, options) {
 //
 // Accepts these extra keys:
 //
-// container - Where to stick the response body.
-//             $(container).html(xhr.responseBody)
+// container - String selector for where to stick the response body.
 //      push - Whether to pushState the URL. Defaults to true (of course).
 //   replace - Want to use replaceState instead? That's cool.
 //
@@ -176,26 +169,31 @@ function pjax(options) {
     options.url = options.url()
   }
 
-  var target = options.target
-
   var hash = parseURL(options.url).hash
 
-  var context = options.context = findContainerFor(options.container)
+  var containerType = $.type(options.container)
+  if (containerType !== 'string') {
+    throw "expected string value for 'container' option; got " + containerType
+  }
+  var context = options.context = $(options.container)
+  if (!context.length) {
+    throw "the container selector '" + options.container + "' did not match anything"
+  }
 
   // We want the browser to maintain two separate internal caches: one
   // for pjax'd partial page loads and one for normal page loads.
   // Without adding this secret parameter, some browsers will often
   // confuse the two.
   if (!options.data) options.data = {}
   if ($.isArray(options.data)) {
-    options.data.push({name: '_pjax', value: context.selector})
+    options.data.push({name: '_pjax', value: options.container})
   } else {
-    options.data._pjax = context.selector
+    options.data._pjax = options.container
   }
 
   function fire(type, args, props) {
     if (!props) props = {}
-    props.relatedTarget = target
+    props.relatedTarget = options.target
     var event = $.Event(type, props)
     context.trigger(event, args)
     return !event.isDefaultPrevented()
@@ -211,7 +209,7 @@ function pjax(options) {
     }
 
     xhr.setRequestHeader('X-PJAX', 'true')
-    xhr.setRequestHeader('X-PJAX-Container', context.selector)
+    xhr.setRequestHeader('X-PJAX-Container', options.container)
 
     if (!fire('pjax:beforeSend', [xhr, settings]))
       return false
@@ -284,7 +282,7 @@ function pjax(options) {
       id: options.id || uniqueId(),
       url: container.url,
       title: container.title,
-      container: context.selector,
+      container: options.container,
       fragment: options.fragment,
       timeout: options.timeout
     }
@@ -347,7 +345,7 @@ function pjax(options) {
       id: uniqueId(),
       url: window.location.href,
       title: document.title,
-      container: context.selector,
+      container: options.container,
       fragment: options.fragment,
       timeout: options.timeout
     }
@@ -363,7 +361,7 @@ function pjax(options) {
   if (xhr.readyState > 0) {
     if (options.push && !options.replace) {
       // Cache current container element before replacing it
-      cachePush(pjax.state.id, cloneContents(context))
+      cachePush(pjax.state.id, [options.container, cloneContents(context)])
 
       window.history.pushState(null, "", options.requestUrl)
     }
@@ -448,13 +446,14 @@ function onPjaxPopstate(event) {
     }
 
     var cache = cacheMapping[state.id] || []
-    var container = $(cache[0] || state.container), contents = cache[1]
+    var containerSelector = cache[0] || state.container
+    var container = $(containerSelector), contents = cache[1]
 
     if (container.length) {
       if (previousState) {
         // Cache current container before replacement and inform the
         // cache which direction the history shifted.
-        cachePop(direction, previousState.id, cloneContents(container))
+        cachePop(direction, previousState.id, [containerSelector, cloneContents(container)])
       }
 
       var popstateEvent = $.Event('pjax:popstate', {
@@ -466,7 +465,7 @@ function onPjaxPopstate(event) {
       var options = {
         id: state.id,
         url: state.url,
-        container: container,
+        container: containerSelector,
         push: false,
         fragment: state.fragment,
         timeout: state.timeout,
@@ -568,7 +567,7 @@ function cloneContents(container) {
   cloned.find('script').each(function(){
     if (!this.src) jQuery._data(this, 'globalEval', false)
   })
-  return [container.selector, cloned.contents()]
+  return cloned.contents()
 }
 
 // Internal: Strip internal query params from parsed URL.
@@ -618,49 +617,14 @@ function stripHash(location) {
 //
 // Returns options Object.
 function optionsFor(container, options) {
-  // Both container and options
-  if ( container && options )
+  if (container && options) {
+    options = $.extend({}, options)
     options.container = container
-
-  // First argument is options Object
-  else if ( $.isPlainObject(container) )
-    options = container
-
-  // Only container
-  else
-    options = {container: container}
-
-  // Find and validate container
-  if (options.container)
-    options.container = findContainerFor(options.container)
-
-  return options
-}
-
-// Internal: Find container element for a variety of inputs.
-//
-// Because we can't persist elements using the history API, we must be
-// able to find a String selector that will consistently find the Element.
-//
-// container - A selector String or jQuery object.
-//
-// Returns a jQuery object whose context is `document` and has a selector.
-function findContainerFor(container) {
-  var formatedContainer
-
-  if (jQuery.type(container) === 'string') {
-    formatedContainer = $(container)
-    formatedContainer.selector = container
-  } else {
-    formatedContainer = container
-  }
-
-  if (!formatedContainer.length) {
-    throw "no pjax container for " + container
-  } else if (!formatedContainer.selector) {
-    throw "cant get selector for pjax container"
+    return options
+  } else if ($.isPlainObject(container)) {
+    return container
   } else {
-    return formatedContainer
+    return {container: container}
   }
 }
 

test/unit/fn_pjax.js

@@ -19,7 +19,7 @@ if ($.support.pjax) {
   asyncTest("pushes new url", function() {
     var frame = this.frame
 
-    frame.$("#main").pjax("a").on("pjax:end", function() {
+    frame.$("#main").pjax("a", "#main").on("pjax:end", function() {
       equal(frame.location.pathname, "/dinosaurs.html")
       start()
     })
@@ -30,7 +30,7 @@ if ($.support.pjax) {
   asyncTest("replaces container html from response data", function() {
     var frame = this.frame
 
-    frame.$("#main").pjax("a").on("pjax:end", function() {
+    frame.$("#main").pjax("a", "#main").on("pjax:end", function() {
       equal(frame.$("iframe").attr('title'), "YouTube video player")
       start()
     })
@@ -41,30 +41,18 @@ if ($.support.pjax) {
   asyncTest("sets title to response title tag", function() {
     var frame = this.frame
 
-    frame.$("#main").pjax("a").on("pjax:end", function() {
+    frame.$("#main").pjax("a", "#main").on("pjax:end", function() {
       equal(frame.document.title, "dinosaurs")
       start()
     })
 
     frame.$("a[href='/dinosaurs.html']").trigger('click')
   })
 
-
-  asyncTest("uses second argument as container", function() {
-    var frame = this.frame
-
-    frame.$("body").pjax("a", "#main").on("pjax:end", "#main", function() {
-      equal(frame.location.pathname, "/dinosaurs.html")
-      start()
-    })
-
-    frame.$("a[href='/dinosaurs.html']").click()
-  })
-
   asyncTest("uses second argument as options", function() {
     var frame = this.frame
 
-    frame.$("#main").pjax("a", {push: true}).on("pjax:end", function() {
+    frame.$("#main").pjax("a", {container: "#main", push: true}).on("pjax:end", function() {
       equal(frame.location.pathname, "/dinosaurs.html")
       start()
     })
@@ -102,7 +90,7 @@ if ($.support.pjax) {
   asyncTest("sets relatedTarget to clicked element", function() {
     var frame = this.frame
 
-    frame.$("#main").pjax("a")
+    frame.$("#main").pjax("a", "#main")
 
     var link = frame.$("a[href='/dinosaurs.html']")[0]
 
@@ -118,7 +106,7 @@ if ($.support.pjax) {
   asyncTest("doesn't ignore left click", function() {
     var frame = this.frame
 
-    frame.$("#main").pjax("a")
+    frame.$("#main").pjax("a", "#main")
 
     var event = frame.$.Event('click')
     event.which = 0
@@ -131,7 +119,7 @@ if ($.support.pjax) {
   asyncTest("ignores middle clicks", function() {
     var frame = this.frame
 
-    frame.$("#main").pjax("a")
+    frame.$("#main").pjax("a", "#main")
 
     var event = frame.$.Event('click')
     event.which = 3
@@ -233,9 +221,9 @@ if ($.support.pjax) {
   asyncTest("triggers pjax:click event from link", function() {
     var frame = this.frame
 
-    frame.$("#main").pjax("a").on("pjax:click", function(event, options) {
+    frame.$("#main").pjax("a", "#main").on("pjax:click", function(event, options) {
       ok(event)
-      ok(options.container.is('#main'))
+      equal(options.container, "#main")
       ok(options.url.match("/dinosaurs.html"))
       start()
     })
@@ -246,9 +234,9 @@ if ($.support.pjax) {
   asyncTest("triggers pjax:clicked event from link", function() {
     var frame = this.frame
 
-    frame.$("#main").pjax("a").on("pjax:clicked", function(event, options) {
+    frame.$("#main").pjax("a", "#main").on("pjax:clicked", function(event, options) {
       ok(event)
-      ok(options.container.is('#main'))
+      equal(options.container, "#main")
       ok(options.url.match("/dinosaurs.html"))
       start()
     })

test/unit/pjax.js

@@ -108,24 +108,6 @@ if ($.support.pjax) {
     })
   })
 
-  asyncTest("container option accepts jQuery object", 1, function() {
-    var container = this.frame.$("#main")
-
-    navigate(this.frame)
-    .pjax({ url: "hello.html", container: container }, function(frame) {
-      equal(frame.$("#main > p").html().trim(), "Hello!")
-    })
-  })
-
-  asyncTest("container option accepts DOM element with ID", 1, function() {
-    var container = this.frame.document.getElementById("main")
-
-    navigate(this.frame)
-    .pjax({ url: "hello.html", container: container }, function(frame) {
-      equal(frame.$("#main > p").html().trim(), "Hello!")
-    })
-  })
-
   asyncTest("url option accepts function", 2, function() {
     var numCalls = 0
     var url = function() {