#

API Docs for: 3.10.3
Show: Inherited Protected Private Deprecated

# PjaxBase Class

Defined in: `pjax/js/pjax-base.js:43`
Module: pjax-base
Parent Module: pjax

Available since 3.5.0

`Y.Router` extension that provides the core plumbing for enhanced navigation implemented using the pjax technique (HTML5 `pushState` + Ajax).

This makes it easy to enhance the navigation between the URLs of an application in HTML5 history capable browsers by delegating to the router to fulfill the "request" and seamlessly falling-back to using standard full-page reloads in older, less-capable browsers.

The `PjaxBase` class isn't useful on its own, but can be mixed into a `Router`-based class to add Pjax functionality to that Router. For a pre-made standalone Pjax router, see the `Pjax` class.

    var MyRouter = Y.Base.create('myRouter', Y.Router, [Y.PjaxBase], {
        // ...
    });

- Index
- Methods
- Properties
- Attributes
- Events

## Item Index

### Methods

- _defNavigateFn
- _isLinkSameOrigin
- _navigate
- _onLinkClick
- _pjaxBindUI
- navigate

### Properties

- _pjaxEvents
- _regexURL

### Attributes

- linkSelector
- navigateOnHash
- scrollToTop

### Events

- navigate

## Methods

### `_defNavigateFn`

(

- `e`

)
protected

Defined in `pjax/js/pjax-base.js:300`

Available since 3.5.0

Default handler for the `navigate` event.

Adds a new history entry or replaces the current entry for the specified URL and will scroll the page to the top if configured to do so.

#### Parameters:

- `e` EventFacade

### `_isLinkSameOrigin`

(

- `link`

)
Boolean protected

Defined in `pjax/js/pjax-base.js:161`

Available since 3.6.0

Utility method to test whether a specified link/anchor node's `href` is of the same origin as the page's current location.

This normalize browser inconsistencies with how the `port` is reported for anchor elements (IE reports a value for the default port, e.g. "80").

#### Parameters:

- `link` Node

  The anchor element to test whether its `href` is of the same origin as the page's current location.

#### Returns:

Boolean: Whether or not the link's `href` is of the same origin as the page's current location.

### `_navigate`

(

- `url`
- `[options]`

)
Boolean protected

Defined in `pjax/js/pjax-base.js:210`

Available since 3.5.0

Underlying implementation for `navigate()`.

#### Parameters:

- `url` String

  The fully-resolved URL that the router should dispatch to its route handlers to fulfill the enhanced navigation "request", or use to update `window.location` in non-HTML5 history capable browsers.

- `[options]` Object optional

  Additional options to configure the navigation. These are mixed into the `navigate` event facade.

  - `[replace]` Boolean optional

    Whether or not the current history entry will be replaced, or a new entry will be created. Will default to `true` if the specified `url` is the same as the current URL.

  - `[force=false]` Boolean optional

    Whether the enhanced navigation should occur even in browsers without HTML5 history.

#### Returns:

Boolean: `true` if the URL was navigated to, `false` otherwise.

### `_onLinkClick`

(

- `e`

)
protected

Defined in `pjax/js/pjax-base.js:325`

Available since 3.5.0

Handler for delegated link-click events which match the `linkSelector`.

This will attempt to enhance the navigation to the link element's `href` by passing the URL to the `_navigate()` method. When the navigation is being enhanced, the default action is prevented.

If the user clicks a link with the middle/right mouse buttons, or is holding down the Ctrl or Command keys, this method's behavior is not applied and allows the native behavior to occur. Similarly, if the router is not capable or handling the URL because no route-handlers match, the link click will behave natively.

#### Parameters:

- `e` EventFacade

### `_pjaxBindUI`

() protected

Defined in `pjax/js/pjax-base.js:279`

Available since 3.5.0

Binds the delegation of link-click events that match the `linkSelector` to the `_onLinkClick()` handler.

By default this method will only be called if the browser is capable of using HTML5 history.

### `navigate`

(

- `url`
- `[options]`

)
Boolean

Defined in `pjax/js/pjax-base.js:114`

Available since 3.5.0

Navigates to the specified URL if there is a route handler that matches. In browsers capable of using HTML5 history, the navigation will be enhanced by firing the `navigate` event and having the router handle the "request". Non-HTML5 browsers will navigate to the new URL via manipulation of `window.location`.

When there is a route handler for the specified URL and it is being navigated to, this method will return `true`, otherwise it will return `false`.

Note: The specified URL must be of the same origin as the current URL, otherwise an error will be logged and navigation will not occur. This is intended as both a security constraint and a purposely imposed limitation as it does not make sense to tell the router to navigate to a URL on a different scheme, host, or port.

#### Parameters:

- `url` String

  The URL to navigate to. This must be of the same origin as the current URL.

- `[options]` Object optional

  Additional options to configure the navigation. These are mixed into the `navigate` event facade.

  - `[replace]` Boolean optional

    Whether or not the current history entry will be replaced, or a new entry will be created. Will default to `true` if the specified `url` is the same as the current URL.

  - `[force=false]` Boolean optional

    Whether the enhanced navigation should occur even in browsers without HTML5 history.

#### Returns:

Boolean: `true` if the URL was navigated to, `false` otherwise.

## Properties

### `_pjaxEvents`

EventHandle protected

Defined in `pjax/js/pjax-base.js:69`

Available since 3.5.0

Holds the delegated pjax-link click handler.

### `_regexURL`

RegExp protected

Defined in `pjax/js/pjax-base.js:78`

Available since 3.5.0

Regex used to break up a URL string around the URL's path.

Subpattern captures:

1. Origin, everything before the URL's path-part.
2. The URL's path-part.
3. Suffix, everything after the URL's path-part.

## Attributes

### `linkSelector`

String | Function

Defined in `pjax/js/pjax-base.js:381`

Available since 3.5.0

CSS selector string used to filter link click events so that only the links which match it will have the enhanced navigation behavior of Pjax applied.

When a link is clicked and that link matches this selector, Pjax will attempt to dispatch to any route handlers matching the link's `href` URL. If HTML5 history is not supported or if no route handlers match, the link click will be handled by the browser just like any old link.

Default: "a.yui3-pjax"

#### Fires event `linkSelectorChange`

Fires when the value for the configuration attribute `linkSelector` is changed. You can listen for the event using the `on` method if you wish to be notified before the attribute's value has changed, or using the `after` method if you wish to be notified after the attribute's value has changed.

#### Parameters:

- `e` EventFacade
  An Event Facade object with the following attribute-specific properties added:
  - `prevVal` Any
    The value of the attribute, prior to it being set.
  - `newVal` Any
    The value the attribute is to be set to.
  - `attrName` String
    The name of the attribute being set.
  - `subAttrName` String
    If setting a property within the attribute's value, the name of the sub-attribute property being set.

### `navigateOnHash`

Boolean

Defined in `pjax/js/pjax-base.js:401`

Available since 3.5.0

Whether navigating to a hash-fragment identifier on the current page should be enhanced and cause the `navigate` event to fire.

By default Pjax allows the browser to perform its default action when a user is navigating within a page by clicking in-page links (e.g. `<a href="#top">Top of page</a>`) and does not attempt to interfere or enhance in-page navigation.

Default: false

#### Fires event `navigateOnHashChange`

Fires when the value for the configuration attribute `navigateOnHash` is changed. You can listen for the event using the `on` method if you wish to be notified before the attribute's value has changed, or using the `after` method if you wish to be notified after the attribute's value has changed.

#### Parameters:

- `e` EventFacade
  An Event Facade object with the following attribute-specific properties added:
  - `prevVal` Any
    The value of the attribute, prior to it being set.
  - `newVal` Any
    The value the attribute is to be set to.
  - `attrName` String
    The name of the attribute being set.
  - `subAttrName` String
    If setting a property within the attribute's value, the name of the sub-attribute property being set.

### `scrollToTop`

Boolean

Defined in `pjax/js/pjax-base.js:419`

Available since 3.5.0

Whether the page should be scrolled to the top after navigating to a URL.

When the user clicks the browser's back button, the previous scroll position will be maintained.

Default: true

#### Fires event `scrollToTopChange`

Fires when the value for the configuration attribute `scrollToTop` is changed. You can listen for the event using the `on` method if you wish to be notified before the attribute's value has changed, or using the `after` method if you wish to be notified after the attribute's value has changed.

#### Parameters:

- `e` EventFacade
  An Event Facade object with the following attribute-specific properties added:
  - `prevVal` Any
    The value of the attribute, prior to it being set.
  - `newVal` Any
    The value the attribute is to be set to.
  - `attrName` String
    The name of the attribute being set.
  - `subAttrName` String
    If setting a property within the attribute's value, the name of the sub-attribute property being set.

## Events

### `navigate`

Defined in `pjax/js/pjax-base.js:16`

Available since 3.5.0

Fired when navigating to a URL via Pjax.

When the `navigate()` method is called or a pjax link is clicked, this event will be fired if the browser supports HTML5 history and the router has a route handler for the specified URL.

This is a useful event to listen to for adding a visual loading indicator while the route handlers are busy handling the URL change.

#### Event Payload:

- `url` String

  The URL that the router will dispatch to its route handlers in order to fulfill the enhanced navigation "request".

- `[force=false]` Boolean optional

  Whether the enhanced navigation should occur even in browsers without HTML5 history.

- `[hash]` String optional

  The hash-fragment (including "#") of the `url`. This will be present when the `url` differs from the current URL only by its hash and `navigateOnHash` has been set to `true`.

- `[originEvent]` Event optional

  The event that caused the navigation. Usually this would be a click event from a "pjax" anchor element.

- `[replace]` Boolean optional

  Whether or not the current history entry will be replaced, or a new entry will be created. Will default to `true` if the specified `url` is the same as the current URL.