Getting started
CSS
Components
JavaScript
SCSS

Pjax

Hubble's Pjax component provides a powerful module to quickly manage Pjax style events, DOM manipulation and web-app style functionality.

Introduction

Before we look at using the Pjax component specifically, we should go over the concept as a whole. Pjax works by fetching HTML from your server via ajax (GET) 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.

An example of this might be a tab navigation that loads the content into the tab panel when the navigation link is clicked. The advantage here is that you:

  1. Only load required HTML content that is necessary for the page over initial GET requests (smaller and faster page loads).
  2. Additional content can be loaded via GET based on events/and/or server conditions, when it is needed.
  3. Pages can show different views depending on a URL query string or URL.

To recap the process works like this:

  1. Page is loaded.
  2. An event (like clicking a button) trigger the Pjax module.
  3. JavaScript makes a GET request to the server for the URL, with the X-PJAX header set to true so the server knows to only return the required data (not the whole page).
  4. Server sends back a valid HTML response.
  5. JavaScript appends the response into the DOM.
  6. User sees the content.

When the module loads content it will check the currently loaded scripts and compare them with any new scripts from the response content. If any new scripts are found they will be loaded once.

Basic usage

You can invoke the Pjax via HTML for a fast and easy setup

Panel 1

Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt.

The data-pjax-href attribute specifies the target URL to send the request to. This can be a relative or absolute link:

The data-pjax-target attribute specifies the id of target node to append the request response into:

The data-pjax-title is an optional parameter to set the new title if when changes. Note that if your response returns a <title> element, that title will always be used. If neither are provided the document's current title will not change.

The data-pjax-state-change is an optional parameter on whether on not the event should trigger a state change. This defaults to FALSE if not provided.

The data-pjax-single-request is an optional parameter on which specifies if the request should only be sent the first time the event is clicked. This defaults to FALSE if not provided.

JavaScript Usage

You can invoke a Pjax request directly via JavaScript:

Server Response

Pjax requests are made via GET. Your server can differentiate these requests from other incoming GET requests by checking if the X-PJAX header is sent with the request.

When sending a response, your server must send valid HTML

Your server does not need to send an entire HTML document, only the content that will be appending into the target node, or the target node itself.

If however, you send an entire HTML document, the module will parse the code and try to find the target node.

If the response contains a <title> element, and stateChange is set to true, that title will be used (regardless of if a full HTML document is sent).