Show:
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], {
                                // ...
                            });

Methods

_defNavigateFn

(
  • e
)
protected

Defined in yui3/src/pjax/js/pjax-base.js:291

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:

_isLinkSameOrigin

(
  • link
)
Boolean protected

Defined in yui3/src/pjax/js/pjax-base.js:152

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

    <p><p>The anchor element to test whether its <code>href</code> is of the same origin as the page's current location.</p></p>

Returns:

Boolean:

<p><p>Whether or not the link's <code>href</code> is of the same origin as the page's current location.</p></p>

_navigate

(
  • url
  • [options]
)
Boolean protected

Defined in yui3/src/pjax/js/pjax-base.js:201

Available since 3.5.0

Underlying implementation for navigate().

Parameters:

  • url String

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

  • [options] Object optional

    <p><p>Additional options to configure the navigation. These are mixed into the <code>navigate</code> event facade.</p></p>

    • [replace] Boolean optional

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

    • [force=false] Boolean optional

      <p><p>Whether the enhanced navigation should occur even in browsers without HTML5 history.</p></p>

Returns:

Boolean:

<p><p><code>true</code> if the URL was navigated to, <code>false</code> otherwise.</p></p>

_onLinkClick

(
  • e
)
protected

Defined in yui3/src/pjax/js/pjax-base.js:316

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:

_pjaxBindUI

() protected

Defined in yui3/src/pjax/js/pjax-base.js:270

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 yui3/src/pjax/js/pjax-base.js:98

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

    <p><p>The URL to navigate to. This must be of the same origin as the current URL.</p></p>

  • [options] Object optional

    <p><p>Additional options to configure the navigation. These are mixed into the <code>navigate</code> event facade.</p></p>

    • [replace] Boolean optional

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

    • [force=false] Boolean optional

      <p><p>Whether the enhanced navigation should occur even in browsers without HTML5 history.</p></p>

Returns:

Boolean:

<p><p><code>true</code> if the URL was navigated to, <code>false</code> otherwise.</p></p>

Properties

_pjaxEvents

EventHandle protected

Defined in yui3/src/pjax/js/pjax-base.js:69

Available since 3.5.0

Holds the delegated pjax-link click handler.

Attributes

allowFallThrough

Boolean

Defined in yui3/src/pjax/js/pjax-base.js:425

Available since 3.18.0

Whether to set window.location when calling navigate() if no routes match the specified URL.

Default: true

linkSelector

String | Function

Defined in yui3/src/pjax/js/pjax-base.js:372

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"

navigateOnHash

Boolean

Defined in yui3/src/pjax/js/pjax-base.js:392

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

scrollToTop

Boolean

Defined in yui3/src/pjax/js/pjax-base.js:410

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

Events

navigate

Defined in yui3/src/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

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

  • [force=false] Boolean optional

    <p><p>Whether the enhanced navigation should occur even in browsers without HTML5 history.</p></p>

  • [hash] String optional

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

  • [originEvent] Event optional

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

  • [replace] Boolean optional

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