defunkt / jquery-pjax

pjax = pushState + ajax pjax is a jQuery plugin that uses ajax and pushState to deliver a fast browsing experience with real permalinks, page titles, and a working back button. pjax works by fetching HTML from your server via ajax and replacing the content of a container element on your page with the loaded HTML. It then updates the current URL in the browser using pushState. This results in faster page navigation for two reasons: • No page resources (JS, CSS) get re-executed or re-applied; • If the server is configured for pjax, it can render only partial page contents and thus avoid the potentially costly full layout render. Status of this project jquery-pjax is **largely unmaintained** at this point. It might continue to receive important bug fixes, but _its feature set is frozen_ and it's unlikely that it will get new features or enhancements. Installation pjax depends on jQuery 1.8 or higher. npm standalone script Download and include in your web page: Usage The simplest and most common use of pjax looks like this: This will enable pjax on all links on the page and designate the container as . If you are migrating an existing site, you probably don't want to enable pjax everywhere just yet. Instead of using a global selector like , try annotating pjaxable links with , then use as your selector. Or, try this selector that matches any links inside a container: Server-side configuration Ideally, your server should detect pjax requests by looking at the special HTTP header, and render only the HTML meant to replace the contents of the container element ( in our example) without the rest of the page layout. Here is an example of how this might be done in Ruby on Rails: If you'd like a more automatic solution than pjax for Rails check out [Turbolinks][]. [Check if there is a pjax plugin][plugins] for your favorite server framework. Also check out [RailsCasts #294: Playing with PJAX][railscasts]. Arguments The synopsis for the function is: • is a string to be used for click [event delegation][$.fn.on]. • is a string selector that uniquely identifies the pjax container. • is an object with keys described below. pjax options key | default | description ----|---------|------------ | 650 | ajax timeout in milliseconds after which a full refresh is forced | true | use [pushState][] to add a browser history entry upon navigation | false | replace URL without adding browser history entry | 20 | maximum cache size for previous container contents | | a string or function returning the current pjax version | 0 | vertical position to scroll to after navigation. To avoid changing scroll position, pass . | | see [$.ajax][] | | see [$.ajax][] | | CSS selector for the element where content should be replaced | link.href | a string or function that returns the URL for the ajax request | link | eventually the value for pjax events | | CSS selector for the fragment to extract from ajax response You can change the defaults globally by writing to the object: This is a lower level function used by 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 element as the container: **NOTE** Use the explicit guard. We aren't using so we should avoid binding this event handler unless the browser is actually going to use pjax. Submits a form via pjax. 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. 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 , consider instead. Events All pjax events except & are fired from the pjax container element. event cancel arguments notes event lifecycle upon following a pjaxed link pjax:click ✔︎ options fires from a link that got activated; cancel to prevent pjax pjax:beforeSend ✔︎ xhr, options can set XHR headers pjax:start xhr, options pjax:send xhr, options pjax:clicked options fires after pjax has started from a link that got clicked pjax:beforeReplace contents, options before replacing HTML with content loaded from the server pjax:success data, status, xhr, options after replacing HTML content loaded from the server pjax:timeout ✔︎ xhr, options fires after options.timeout ; will hard refresh unless canceled pjax:error ✔︎ xhr, textStatus, error, options on ajax error; will hard refresh unless canceled pjax:complete xhr, textStatus, options always fires after ajax, regardless of result pjax:end xhr, options event lifecycle on browser Back/Forward navigation pjax:popstate event direction property: "back"/"forward" pjax:start null, options before replacing content pjax:beforeReplace contents, options right before replacing HTML with content from cache pjax:end null, options after replacing content & 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: An example of canceling a event would be to disable the fallback timeout behavior if a spinner is being shown: Advanced configuration Reinitializing plugins/widget on new page content The whole point of pjax is that it fetches and inserts new content _without_ refreshing the page. However, other jQuery plugins or libraries that are set to react on page loaded event (such as ) will not pick up on these changes. Therefore, it's usually a good idea to configure these plugins to reinitialize in the scope of the updated page content. This can be done like so: This will make be called at the document level on normal page load, and on the container level after any pjax navigation (either after clicking on a link or going Back in the browser). Response types that force a r…