pjax.js

Automatic Pjax

The Pjax.js is ~~a jQuery plugin~~ script that uses ajax, pushState and automatically detects links and forms, for configure page you need use id="pjax-container" in all pages, example:

<div id="pjax-container">
    ...
</div>

Pjax load all content from pages, but uses only contents from first element using pjax-container, if you don’t need the Pjax in a spefic link or form then use data-pjax-ignore attribute, example:

<p>
    Hello world!
    Example <a data-pjax-ignore href="/page.html">page</a>.
</p>

Setup

Include lib

<link rel="stylesheet" type="text/css" href="pjax.min.css" data-pjax-resource="true">
<script src="pjax.min.js"></script>

Or use CDN:

<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/pjax.js@0.7/pjax.min.css" data-pjax-resource="true">
<script src="https://cdn.jsdelivr.net/npm/pjax.js@0.7/pjax.min.js"></script>

Note: CSS is optional, you can create your own loader or customize the following structure using CSS (the structure is generated by Pjax.js):
<div class="pjax-loader pjax-start pjax-inload pjax-end pjax-hide">
    <div class="pjax-progress"></div>
</div>

Import:

const Pjax = require('pjax.js');

...

ESM/ES6 import:

import Pjax from 'pjax.js';

...

RequireJS:

requirejs(['folder/foo/bar/pjax'], function (Pjax) {
    ...
});

Support

The pjax.js support links, forms with method GET, forms with method POST and support files and multiple files (<input type="file" multiple>).

Requirements:

DOMParser or document.implementation
pushState, replaceState and popstate (DOM History manipulation)
FormData (XMLHttpRequest Level 2) - if need upload files using PJAX (enctype="multipart/form-data")

Tested in:

Internet Explorer 10
Firefox
Google Chrome
iOS 10
Android 2.3+

Usage

For use:

Pjax.start();

Pjax API

Method	Description
`Pjax.supported`	Return `true` if support this lib, otherwise return `false`
`Pjax.remove();`	Remove PJAX requests and events
`Pjax.on(event, function (...) {...});`	Define an event
`Pjax.off(event, function (...) {...});`	Remove an event
`Pjax.request(url[, config])`	Request using script

`Pjax.request()` method

config param is optional, you can define like this:

Pjax.request("/foo/bar", {
    method: "POST",
    replace: true,
    data: "foo=1&bar=2&baz=3"
});

Uploading file:

const formdata = new FormData;
const blob = new Blob(["Hello World!"], {
  type: "text/plain"
});

formdata.append("file", blob, "hello.txt");

Pjax.request("/foo/bar", {
    method: "POST",
    replace: true,
    data: formdata
});

Details for use data::

Property	type	default	description
`replace:`	`bool`	`false`	Sets the history state mode, if you set it to `false` (or omitted) it will use `history.pushState()`, but if you set it to `true` it will use `history.replaceState()`.
`method:`	`string`	`GET`	Define HTTP method
`data:`	`bool`	`false`	To send data in the request, you can use `String` or `FormData`

Pjax Events

Example	Description
`Pjax.on("initiate", function (url, config) {...});`	Trigged when clicked in a link or submit a form or execute `Pjax.request()` method
`Pjax.on("done", function (url, status) {...});`	Trigged when page loaded, `status` return HTTP code
`Pjax.on("fail", function (url, status) {...});`	Trigged when page failed to load, `status` return HTTP code
`Pjax.on("then", function (url) {...});`	Executes every time a request is completed, even if it fails or success
`Pjax.on("history", function (url, stateData) {...});`	Executes every use back or forward
`Pjax.on("handler", function (data, config, callbackDone, callbackFail) {...});`	Create your owner response to Pjax.js request
`Pjax.on("dom", function (url, newdocument) {...});`	Allows you to manipulate an element change manually, for example you can create transitions or change newdocument

Tip: You can use Pjax.on("dom", ...); for remove events in DOM

Pjax configs

Property	type	default	description
`containers:`	`array`	`[ "#pjax-container" ]`	Informs which elements to update on the page
`updatecurrent:`	`bool`	`false`	If `true` request same url in used by current page is executed `history.replaceState`, otherwise nothing will be executed
`updatehead:`	`bool`	`true`	The “pjax.js” has an intelligent update system that helps avoid the “blink” effect, because instead of updating everything it only updates what has been changed, however if you are sure that nothing will change as you page, you can set it to false, the only one that will continue to be updated will be the `<title>` tag
`insertion:`	`string`	`undefined`	Support values `append` and `prepend`, if omitted it will replace the content
`scrollLeft:`	`number`	`0`	After loading a page via PJAX you can define where scrollLeft should scroll. Set `-1` to disable autoscroll in x-cord
`scrollTop:`	`number`	`0`	After loading a page via PJAX you can define where scrollTop should scroll. Set `-1` to disable autoscroll in y-cord
`loader:`	`bool`	`true`	Adds the native Pjax loader, if you want to create a loader of your own, set it to `false`
`nocache:`	`bool`	`false`	Prevent cache
`proxy:`	`string`	`""`	Set Web Proxy
`formSelector:`	`string`	`form:not([data-pjax-ignore]):not([action^='javascript:'])`	Set form selector, set empty for prevent forms uses Pjax
`linkSelector:`	`string`	`a:not([data-pjax-ignore]):not([href^='#']):not([href^='javascript:'])`	Set form selector, set empty for prevent links uses Pjax
`headers:`	`object`	Adds custom headers, eg.: `{ "foo": "bar", "test": "baz" }`

PJAX with HTML5 data attribute

If need overwrite properties for specific link or form you can config using HTML attributes:

Property	equivalent	example	description
`data-pjax-containers`	`containers:`	`<a href="..." data-pjax-containers="[ "#foo", "#bar", "#baz" ]"`	Adjusts the containers when the request comes from a specific form or link
`data-pjax-updatehead`	`updatehead:`	`<a href="..." data-pjax-updatehead="false"`	Allow/Disallow head tag update when the request comes from a specific form or link
`data-pjax-insertion`	`insertion`	`<a href="..." data-pjax-insertion="append"`	Append or prepend data to the containers instead of updating
`data-pjax-scroll-left`	`scrollLeft:`	`<form action="..." data-pjax-scroll-left="10"`	custom scroll-left to specific form or link
`data-pjax-scroll-top`	`scrollTop:`	`<form action="..." data-pjax-scroll-top="-1"`	custom scroll-top to specific form or link
`data-pjax-loader`	`loader:`	`<a href="..." data-pjax-loader="false"`	Allow/Disallow loader animate to specific form or link
`data-pjax-done`	-	`<a href="..." data-pjax-done="console.log('success', this);"`	Custom “done” event to specific form or link
`data-pjax-fail`	-	`<a href="..." data-pjax-fail="console.log('error', this);"`	Custom “error” event to specific form or link
`data-pjax-ignore`	-	`<a href="..." data-pjax-ignore="true">`	Normal navigation to specific form or link
`data-pjax-resource`	-	`<link href="..." data-pjax-resource="true">`	Prevent remove element after update DOM (for now it only works in the `<head>`)

For change configs use like this:

Pjax.start({
    containers: [ "#my-container" ], //Change container element
    scrollLeft: -1, //Disable autoscroll
    scrollTop: -1 //Disable autoscroll
});

Update two elements (or more)

You can change the element you want to update or even add more elements, eg.:

<div id="navbar">
    ...
</div>
<div id="my-container">
    ...
</div>
<script>
Pjax.start({
    containers: [ "#navbar", "#my-container" ] //Change containers element
});
</script>

You can change configs in initiate event, example:

<div id="pjax-container">
    <div id="filter">
        <form>
            ...
        </form>
    </div>
    <div id="search-container">
        ...
    </div>
</div>
<script>
Pjax.start();

Pjax.on("initiate", function (url, configs) {
    if (url.indexOf("/search/") === 0 && window.location.href.indexOf("/search/") === 0) {
        configs.containers = [ "#search-container" ];
    }
});
</script>

If you are on a product search page and are doing a new search instead of updating the entire container will only update the element where the products are, other pages will continue to update the entire container.

Pjax in server-side

It is possible to detect if the request came from the PJAX using the request headers:

Header	Description
`X-PJAX`	Indicates that the page was requested via PJAX
`X-PJAX-Container`	Informs the container selectors used

Example using PHP:

if (isset($_SERVER['HTTP_X_PJAX'])) {
    echo 'You using pjax';
}

Redirect using PJAX

You can use HTTP response header X-PJAX-URL in back-end for force Pjax.js redirects, example:

header('X-PJAX-URL: /new-page.html');

...

Change or add container using PJAX

You can use HTTP response header X-PJAX-URL in back-end for force Pjax.js redirects, example:

if (isset($_SERVER['HTTP_X_PJAX'])) {
    header('X-PJAX-Container: #foo,#bar');

    echo '<div id="foo"> ... </div>';

    echo '<div id="bar"> ... </div>';
}

Custom loader with Pjax

You can custom CSS, example change color and size, put in new CSS file or <style> tag:

.pjax-loader .pjax-progress {
    height: 6px;
    background-color: blue;
}

If you need custom “more”, first remove default loader:

Pjax.start({
    loader: false
});

And after use initiate and then events:

Pjax.on("initiate", function () {
    $(".my-custom-loader").css("display", "block");
});

Pjax.on("then", function () {
    $(".my-custom-loader").css("display", "none");
});

HTML:

<div class="my-custom-loader">
    <img src="loader.gif">
</div>

Pjax handler response

For create a custom responses for Pjax you can use handler event, example:

Pjax.start();

Pjax.on("handler", function (details, done, fail) {
    console.log("handler request:", details.method, details.url);
    console.log("handler target:", details.element);
    console.log("handler mode history:", details.state); // 1 == push, 2 == replace

    setTimeout(function () {
        if (<condition for history state>) {
            done('<div id="pjax-container">Foo: ' + new Date() + '</div>');
        } else {
            fail("Custom Error");
        }
    }, 1000);
});

This site is open source. Improve this page.