eadz/jquery-pjax

pushState + ajax = pjax

## 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 at http://pjax.heroku.com/


## three ways to pjax on the client side:

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

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

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


2. Slightly obtrusive, passing a container and jQuery ajax options:

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

   $('a.js-pjax').pjax('#main', { timeout: null, error: function(xhr, err){
     $('.error').text('Something went wrong: ' + err)
   })


3. 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').live('click', function(){
     $(this).showLoader()
   })


## $(link).pjax( container, options )

The $(link).pjax() function accepts a container, an options object,
or both. The options are the same as jQuery's $.ajax options with the
following additions:

container - The selector of the container to load the reponse body into, or
            the container itself.
     push - Whether to pushState the URL. Defaults to true (of course).
  replace - Whether to replaceState the URL. Defaults to false.
  timeout - pjax sets this low, <1s. Set this higher if using a custom
            error handler. It's in ms, so something like `timeout: 2000`
    error - By default this callback reloads the target page once `timeout`
            ms elapses.


## $.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


## page titles

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


## install it

  $ cd path/to/js
  $ curl -O https://github.com/defunkt/jquery-pjax/raw/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'.