Add X-PJAX-Selectors header

README.md

@@ -1,6 +1,6 @@
 # Pjax
 
-[![Build Status](http://img.shields.io/travis/MoOx/pjax.svg)](https://travis-ci.org/MoOx/pjax).
+[![Build Status](https://img.shields.io/travis/MoOx/pjax.svg)](https://travis-ci.org/MoOx/pjax).
 
 > Easily enable fast AJAX navigation on any website (using pushState() + XHR)
 
@@ -15,6 +15,8 @@ especially for users with low bandwidth connection._
 
 **No more full page reloads. No more multiple HTTP requests.**
 
+_Pjax does not rely on other libraries, like jQuery or similar. It is written entirely in vanilla JS._
+
 ## Installation
 
 - You can install Pjax from **npm**:
@@ -31,10 +33,6 @@ especially for users with low bandwidth connection._
   <script src="https://cdn.jsdelivr.net/npm/pjax@VERSION/pjax.min.js"></script>
   ```
 
-## No dependencies
-
-_Pjax does not rely on other libraries, like jQuery or similar. It is written entirely in vanilla JS._
-
 ## How Pjax works
 
 Pjax loads pages using AJAX and updates the browser's current URL using `pushState()` without reloading your page's layout or any resources (JS, CSS), giving a fast page load.
@@ -495,6 +493,36 @@ document.addEventListener('pjax:send', topbar.show)
 document.addEventListener('pjax:complete', topbar.hide)
 ```
 
+### HTTP Headers
+
+Pjax uses several custom headers when it makes and receives HTTP requests. 
+If the requests are going to your server, you can use those headers for
+some meta information about the response.
+
+##### Request headers
+
+Pjax sends the following headers with every request:
+
+* `X-Requested-With: "XMLHttpRequest"`
+* `X-PJAX: "true"`
+* `X-PJAX-Selectors`: A serialized JSON array of selectors, taken from 
+`options.selectors`. You can use this to send back only the elements that 
+Pjax will use to switch, instead of sending the whole page. Use `JSON.parse()` 
+server-side to deserialize it back to an array.
+
+##### Response headers
+
+Pjax looks for the following headers on the response:
+
+* `X-PJAX-URL` or `X-XHR-Redirected-To`
+
+  Pjax first checks the `responseURL` property on the XHR object to 
+  check if the request was redirected by the server. Most browsers support 
+  this, but not all. To ensure Pjax will be able to tell when the request 
+  is redirected, you can include one of these headers with the response, 
+  set to the final URL.
+
+
 #### Note about DOM ready state
 
 Most of the time, you will have code related to the current DOM that you only execute when the DOM is ready.

lib/send-request.js

@@ -61,6 +61,7 @@ module.exports = function(location, options, callback) {
   request.timeout = timeout
   request.setRequestHeader("X-Requested-With", "XMLHttpRequest")
   request.setRequestHeader("X-PJAX", "true")
+  request.setRequestHeader("X-PJAX-Selectors", JSON.stringify(options.selectors))
 
   // Send the proper header information for POST forms
   if (requestPayload && requestMethod === "POST") {

tests/lib/send-request.js

@@ -38,3 +38,22 @@ tape("test xhr request", function(t) {
   })
   t.end()
 })
+
+tape("request headers are sent properly", function(t) {
+  var url = "https://httpbin.org/headers"
+  var options = {
+    selectors: ["div.pjax", "div.container"]
+  }
+
+  sendRequest(url, options, function(responseText) {
+    var headers = JSON.parse(responseText).headers
+
+    t.equals(headers["X-Requested-With"], "XMLHttpRequest", "X-Requested-With header is set correctly")
+    // Httpbin.org changes the case to 'X-Pjax'
+    t.equals(headers["X-Pjax"], "true", "X-PJAX header is set correctly")
+    t.equals(headers["X-Pjax-Selectors"], "[\"div.pjax\",\"div.container\"]", "X-PJAX-Selectors header is set correctly")
+
+    t.end()
+  })
+})
+