pushState + ajax = pjax

        .--.
       /    \
      ## a  a
      (   '._)
       |'-- |
     _.\___/_   ___pjax___
   ."\> \Y/|<'.  '._.-'
  /  \ \_\/ /  '-' /
  | --'\_/|/ |   _/
  |___.-' |  |`'`
    |     |  |
    |    / './
   /__./` | |
      \   | |
       \  | |
       ;  | |
       /  | |
 jgs  |___\_.\_
      `-"--'---'

what is it?

pjax loads HTML from your server into the current page without a full reload. It's ajax with real permalinks, page titles, and a working back button that fully degrades.

pjax enhances the browsing experience - nothing more.

You can find a demo on http://pjax.heroku.com/

three ways to pjax on the client side:

One. Functionally obtrusive, loading the href with ajax into data-pjax:

<a href='/explore' data-pjax='#main'>Explore</a>

$('a[data-pjax]').pjax()

Two. Slightly obtrusive, passing a container and binding an error handler:

<a href='/explore' class='js-pjax'>Explore</a>

$('.js-pjax').pjax('#main')

$('#main').on('pjax:error', function(e, xhr, err) {
  $('.error').text('Something went wrong: ' + err)
})

Three. Unobtrusive, showing a 'loading' spinner:

<div id='main'>
  <div class='loader' style='display:none'><img src='spin.gif'></div>
  <div class='tabs'>
    <a href='/explore'>Explore</a>
    <a href='/help'>Help</a>
  </div>
</div>

$('a').pjax('#main').on('click', function(){
  $(this).showLoader()
})

$(link).pjax( container, options )

The $(link).pjax() function accepts a container, an options object, or both. The container MUST be a string selector - this is because we cannot persist jQuery objects using the History API between page loads.

The options are the same as jQuery's $.ajax options with the following additions:

• container - The String selector of the container to load the reponse body. Must be a String.
• target - The Element that was clicked to start the pjax call.
• push - Whether to pushState the URL. Default: true (of course)
• replace - Whether to replaceState the URL. Default: false
• timeout - pjax sets this low, <1s. Set this higher if using a custom error handler. It's ms, so something like timeout: 2000
• fragment - A String selector that specifies a sub-element to be pulled out of the response HTML and inserted into the container. Useful if the server always returns full HTML pages.

$.pjax( options )

You can also just call $.pjax directly. It acts much like $.ajax, even returning the same thing and accepting the same options.

The pjax-specific keys listed in the $(link).pjax() section work here as well.

This pjax call:

$.pjax({
  url: '/authors',
  container: '#main'
})

Roughly translates into this ajax call:

$.ajax({
  url: '/authors',
  dataType: 'html',
  beforeSend: function(xhr){
    xhr.setRequestHeader('X-PJAX', 'true')
  },
  success: function(data){
    $('#main').html(data)
    history.pushState(null, $(data).filter('title').text(), '/authors')
  })
})

pjax on the server side

You'll want to give pjax requests a 'chrome-less' version of your page. That is, the page without any layout.

As you can see in the "ajax call" example above, pjax sets a custom 'X-PJAX' header to 'true' when it makes an ajax request to make detecting it easy.

In Rails, check for request.headers['X-PJAX']:

def my_page
  if request.headers['X-PJAX']
    render :layout => false
  end
end

Or as a before filter in application controller:

layout :set_layout

private
  def set_layout
    if request.headers['X-PJAX']
      false
    else
      "application"
    end
  end

Rails: https://github.com/rails/pjax_rails

Django: https://github.com/jacobian/django-pjax

Asp.Net MVC3: http://biasecurities.com/blog/2011/using-pjax-with-asp-net-mvc3/

page titles

Your HTML should also include a <title> tag if you want page titles to work.

When using a page fragment, pjax will check the fragment DOM element for a title or data-title attribute and use any value it finds.

events

pjax will fire two events on the container you've asked it to load your reponse body into:

• pjax:start - Fired when a pjax ajax request begins.
• pjax:end - Fired when a pjax ajax request ends.

This allows you to, say, display a loading indicator upon pjaxing:

$('a.pjax').pjax('#main')
$('#main')
  .on('pjax:start', function() { $('#loading').show() })
  .on('pjax:end',   function() { $('#loading').hide() })

Because these events bubble, you can also set them on the document:

$('a.pjax').pjax()
$(document)
  .on('pjax:start', function() { $('#loading').show() })
  .on('pjax:end',   function() { $('#loading').hide() })

In addition, custom events are added to complement $.ajax's callbacks.

• pjax:beforeSend - Fired before the pjax request begins. Returning false will abort the request.
• pjax:complete - Fired after the pjax request finishes.
• pjax:success - Fired after the pjax request succeeds.
• pjax:error - Fired after the pjax request fails. Returning false will prevent the the fallback redirect.
• pjax:timeout - Fired if after timeout is reached. Returning false will disable the fallback and will wait indefinitely until the response returns.

CAUTION Callback handlers passed to $.pjax cannot be persisted across full page reloads. Its recommended you use custom events instead.

outside of container

pjax is not limited to replacing the html in the container. Using the payload_items option, you can tell pjax to replace items outside the container.

For example, if you want to change the background color of the page you might:

$.pjax({
  container: "#main",
  payload_items: [{id: "body_bg", eval: '$("body").attr({"background-color": "__pjax_value__"});', default: ""}]
})

And in the HTML that is returned to the pjax:

<div id="body_bg">#ff0000</div>

The payload_items options takes an array of objects, each with the following parameters:

• id - In the HTML that is returned from the pjax call, the id should match the dom id of the element to extract the value.
• eval - A string of javascript that will be evaluated on each pjax.success. The string __pjax_value__ will be replaced by the value that is returned from the pjax call.
• default - The default value, this is the value for any pjax response where there is no value to change.

browser support

pjax only works with browsers that support the history.pushState API.

For a table of supported browsers see: http://caniuse.com/#search=pushstate

To check if pjax is supported, use the $.support.pjax boolean.

When pjax is not supported, $('a').pjax() calls will do nothing (aka links work normally) and $.pjax({url:url}) calls will redirect to the given URL.

install it

$ cd path/to/js
$ wget https://raw.github.com/defunkt/jquery-pjax/master/jquery.pjax.js

Then, in your HTML:

<script src="path/to/js/jquery.pjax.js"></script>

Replace path/to/js with the path to your JavaScript directory, e.g. public/javascripts.

minimize it

curl \
  -d output_info=compiled_code \
  -d compilation_level=SIMPLE_OPTIMIZATIONS \
  -d code_url=https://github.com/defunkt/jquery-pjax/raw/master/jquery.pjax.js \
  http://closure-compiler.appspot.com/compile