API Docs for: 3.5.1
Show:

PjaxBase Class

Defined in: pjax/js/pjax-base.js:45
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 pjax/js/pjax-base.js:392

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:

_getRoot

() String protected

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

Available since 3.5.0

Returns the current path root after popping off the last path segment, making it useful for resolving other URL paths against.

The path root will always begin and end with a '/'.

Returns:

String: The URL's path root.

_navigate

(
  • url
  • [options]
)
Boolean protected

Defined in pjax/js/pjax-base.js:187

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.

_normalizePath

(
  • path
)
String protected

Defined in pjax/js/pjax-base.js:254

Available since 3.5.0

Returns a normalized path, ridding it of any '..' segments and properly handling leading and trailing slashes.

Parameters:

  • path String

    URL path to normalize.

Returns:

String: Normalized path.

_onLinkClick

(
  • e
)
protected

Defined in pjax/js/pjax-base.js:417

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 pjax/js/pjax-base.js:296

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.

_resolvePath

(
  • path
)
String protected

Defined in pjax/js/pjax-base.js:315

Available since 3.5.0

Returns the normalized result of resolving the path against the current path. Falsy values for path will return just the current path.

Parameters:

  • path String

    URL path to resolve.

Returns:

String: Resolved path.

_resolveURL

(
  • url
)
String protected

Defined in pjax/js/pjax-base.js:339

Available since 3.5.0

Resolves the specified URL against the current URL.

This method resolves URLs like a browser does and will always return an absolute URL. When the specified URL is already absolute, it is assumed to be fully resolved and is simply returned as is. Scheme-relative URLs are prefixed with the current protocol. Relative URLs are giving the current URL's origin and are resolved and normalized against the current path root.

Parameters:

Returns:

String: Resolved URL.

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:71

Available since 3.5.0

Holds the delegated pjax-link click handler.

_regexURL

RegExp protected

Defined in pjax/js/pjax-base.js:80

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:452

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.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:472

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:490

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:18

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 ben 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.