key | default | description
----|---------|------------
timeout | 650 | ajax timeout in milliseconds after which a full refresh is forced
push | true | use [pushState][] to add a browser history entry upon navigation
replace | false | replace URL without adding browser history entry
maxCacheLength | 20 | maximum cache size for previous container contents
version | | a string or function returning the current pjax version
scrollTo | 0 | vertical position to scroll to after navigation. To avoid changing scroll position, pass false.
type | "GET" | see [$.ajax][]
dataType | "html" | see [$.ajax][]
container | | CSS selector for the element where content should be replaced
url | link.href | a string or function that returns the URL for the ajax request
target | link | eventually the relatedTarget value for pjax events
fragment | | CSS selector for the fragment to extract from ajax response

You can change the defaults globally by writing to the $.pjax.defaults object:

` javascript
$.pjax.defaults.timeout = 1200
`

$3

This is a lower level function used by $.fn.pjax itself. It allows you to get a little more control over the pjax event handling.

This example uses the current click context to set an ancestor as the container:

` javascript
if ($.support.pjax) {
$(document).on('click', 'a[data-pjax]', function(event) {
var container = $(this).closest('[data-pjax-container]')
$.pjax.click(event, {container: container})
})
}
`

NOTE Use the explicit $.support.pjax guard. We aren't using $.fn.pjax so we should avoid binding this event handler unless the browser is actually going to use pjax.

$3

Submits a form via pjax.

` javascript
$(document).on('submit', 'form[data-pjax]', function(event) {
$.pjax.submit(event, '#pjax-container')
})
`

$3

Initiates a request for the current URL to the server using pjax mechanism and replaces the container with the response. Does not add a browser history entry.

` javascript
$.pjax.reload('#pjax-container', options)
`

$3

Manual pjax invocation. Used mainly when you want to start a pjax request in a handler that didn't originate from a click. If you can get access to a click event, consider $.pjax.click(event) instead.

` javascript
function applyFilters() {
var url = urlForFilters()
$.pjax({url: url, container: '#pjax-container'})
}
`

$3

All pjax events except pjax:click & pjax:clicked are fired from the pjax
container, not the link that was clicked.

pjax:send & pjax:complete are a good pair of events to use if you are implementing a
loading indicator. They'll only be triggered if an actual XHR request is made,
not if the content is loaded from cache:

` javascript
$(document).on('pjax:send', function() {
$('#loading').show()
})
$(document).on('pjax:complete', function() {
$('#loading').hide()
})
`

An example of canceling a pjax:timeout event would be to disable the fallback
timeout behavior if a spinner is being shown:

` javascript
$(document).on('pjax:timeout', function(event) {
// Prevent default timeout redirection behavior
event.preventDefault()
})
`

$3

Server configuration will vary between languages and frameworks. The following example shows how you might configure Rails.

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

An X-PJAX request header is set to differentiate a pjax request from normal XHR requests. In this case, if the request is pjax, we skip the layout html and just render the inner contents of the container.

[Check if there is a pjax plugin][plugins] for your favorite server framework.

#### Response types that force a reload

By default, pjax will force a full reload of the page if it receives one of the
following responses from the server:

* Page content that includes when fragment selector wasn't explicitly
configured. Pjax presumes that the server's response hasn't been properly
configured for pjax. If fragment pjax option is given, pjax will simply
extract the content to insert into the DOM based on that selector.

* Page content that is blank. Pjax assumes that the server is unable to deliver
proper pjax contents.

* HTTP response code that is 4xx or 5xx, indicating some server error.

#### Affecting the browser URL

If the server needs to affect the URL which will appear in the browser URL after
pjax navigation (like HTTP redirects work for normal requests), it can set the
X-PJAX-URL header:

` ruby
def index
request.headers['X-PJAX-URL'] = "http://example.com/hello"
end
`

#### Layout Reloading

Layouts can be forced to do a hard reload when assets or html changes.

First set the initial layout version in your header with a custom meta tag.

` html

`

Then from the server side, set the X-PJAX-Version header to the same.

` ruby
if request.headers['X-PJAX']
response.headers['X-PJAX-Version'] = "v123"
end
``

Deploying a deploy, bumping the version constant to force clients to do a full reload the next request getting the new layout and assets.

[compat]: http://caniuse.com/#search=pushstate
[$.fn.on]: http://api.jquery.com/on/
[$.ajax]: http://api.jquery.com/jQuery.ajax/
[pushState]: https://developer.mozilla.org/en-US/docs/Web/Guide/API/DOM/Manipulating_the_browser_history#Adding_and_modifying_history_entries
[plugins]: https://gist.github.com/4283721
[turbolinks]: https://github.com/rails/turbolinks
[railscasts]: http://railscasts.com/episodes/294-playing-with-pjax
[bower]: https://github.com/twitter/bower