- Adds fragmentUrl property to allow fetching page fragment from different URL than on a:href
- Accepts plain text responses i.e. fragment can be plain text
.--.
/ \
## a a
( '._)
|'-- |
_.\___/_ ___pjax___
."\> \Y/|<'. '._.-'
/ \ \_\/ / '-' /
| --'\_/|/ | _/
|___.-' | |`'`
| | |
| / './
/__./` | |
\ | |
\ | |
; | |
/ | |
jgs |___\_.\_
`-"--'---'
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/
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').live('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').live('click', function(){
$(this).showLoader()
})
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: falsetimeout
- pjax sets this low, <1s. Set this higher if using a custom error handler. It's ms, so something liketimeout: 2000
fragment
- A String selector that specifies a sub-element to be pulled out of the response HTML and inserted into thecontainer
. Useful if the server always returns full HTML pages.fragmentUrl
- URL for the fragment to be fetched with Ajax. This allows you to get the content from different URL from the one visible to user i.e. the one used for pushState. It can be a String or a function returning the URL as String. The function gets thetarget
as parameter.
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')
})
})
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/
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.
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.
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.
$ 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
.
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