d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan GroveProvides seamless, gracefully degrading Pjax (pushState + Ajax) functionality,
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grovewhich makes it easy to progressively enhance standard links on the page so that
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grovethey can be loaded normally in old browsers, or via Ajax (with HTML5 history
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grovesupport) in newer browsers.
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan GroveProvides seamless, gracefully degrading Pjax (pushState + Ajax) functionality,
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grovewhich makes it easy to progressively enhance standard links on the page so that
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grovethey can be loaded normally in old browsers, or via Ajax (with HTML5 history
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grovesupport) in newer browsers.
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove@extends Router
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove@uses PjaxBase
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove@param {Object} [config] Config attributes.
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan GroveFired when an error occurs while attempting to load a URL via Ajax.
5616fb39daaf9cc7a10bf50e7c3082e234cc0e7aRyan Grove@param {Object} content Content extracted from the response, if any.
5616fb39daaf9cc7a10bf50e7c3082e234cc0e7aRyan Grove @param {Node} content.node A `Y.Node` instance for a document fragment
5616fb39daaf9cc7a10bf50e7c3082e234cc0e7aRyan Grove containing the extracted HTML content.
5616fb39daaf9cc7a10bf50e7c3082e234cc0e7aRyan Grove @param {String} [content.title] The title of the HTML page, if any,
5616fb39daaf9cc7a10bf50e7c3082e234cc0e7aRyan Grove extracted using the `titleSelector` attribute. If `titleSelector` is not
5616fb39daaf9cc7a10bf50e7c3082e234cc0e7aRyan Grove set or if a title could not be found, this property will be `undefined`.
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove@param {String} responseText Raw Ajax response text.
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove@param {Number} status HTTP status code for the Ajax response.
da8d2cc08af9bbf979ee87a14059ac8e0b74cee8Ryan Grove@param {String} url The absolute URL that failed to load.
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan GroveFired when a URL is successfully loaded via Ajax.
5616fb39daaf9cc7a10bf50e7c3082e234cc0e7aRyan Grove@param {Object} content Content extracted from the response, if any.
5616fb39daaf9cc7a10bf50e7c3082e234cc0e7aRyan Grove @param {Node} content.node A `Y.Node` instance for a document fragment
5616fb39daaf9cc7a10bf50e7c3082e234cc0e7aRyan Grove containing the extracted HTML content.
5616fb39daaf9cc7a10bf50e7c3082e234cc0e7aRyan Grove @param {String} [content.title] The title of the HTML page, if any,
5616fb39daaf9cc7a10bf50e7c3082e234cc0e7aRyan Grove extracted using the `titleSelector` attribute. If `titleSelector` is not
5616fb39daaf9cc7a10bf50e7c3082e234cc0e7aRyan Grove set or if a title could not be found, this property will be `undefined`.
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove@param {String} responseText Raw Ajax response text.
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove@param {Number} status HTTP status code for the Ajax response.
da8d2cc08af9bbf979ee87a14059ac8e0b74cee8Ryan Grove@param {String} url The absolute URL that was loaded.
fe23a9535206b8c78aff2e73f8d0d0106a148a41Ryan GroveY.Pjax = Y.Base.create('pjax', Y.Router, [Y.PjaxBase], {
569c3090f5818228805d517e135aa3799732292aRyan Grove // -- Lifecycle Methods ----------------------------------------------------
569c3090f5818228805d517e135aa3799732292aRyan Grove initializer: function () {
84ae7c9d0c9d7a559d93a52393255678b6ac4e55Ryan Grove this.publish(EVT_ERROR, {defaultFn: this._defCompleteFn});
84ae7c9d0c9d7a559d93a52393255678b6ac4e55Ryan Grove this.publish(EVT_LOAD, {defaultFn: this._defCompleteFn});
60721add39f50a2f904fa5736c6d04bb7aecdb63Eric Ferraiuolo // -- Public Methods -------------------------------------------------------
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove Extracts and returns the relevant HTML content from an Ajax response. The
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove content is extracted using the `contentSelector` attribute as a CSS
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove selector. If `contentSelector` is `null`, the entire response will be
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove The return value is an object containing two properties:
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove - **node**: A `Y.Node` instance for a document fragment containing the
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove extracted HTML content.
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove - **title**: The title of the HTML page, if any, extracted using the
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove `titleSelector` attribute (which defaults to looking for a `<title>`
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove element). If `titleSelector` is not set or if a title could not be
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove found, this property will be `undefined`.
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove @method getContent
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove @param {String} responseText Raw Ajax response text.
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove @return {Object} Content object with the properties described above.
60721add39f50a2f904fa5736c6d04bb7aecdb63Eric Ferraiuolo contentSelector = this.get('contentSelector'),
60721add39f50a2f904fa5736c6d04bb7aecdb63Eric Ferraiuolo content.node = Y.one(frag.all(contentSelector).toFrag());
de68e8889929623e599d718e0e382927589365d5Ryan Grove // -- Protected Methods ----------------------------------------------------
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove Default Pjax route handler. Makes an Ajax request for the requested URL.
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove @method _defaultRoute
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove @param {Object} req Request object.
84ae7c9d0c9d7a559d93a52393255678b6ac4e55Ryan Grove // If there's an outstanding request, abort it.
da8d2cc08af9bbf979ee87a14059ac8e0b74cee8Ryan Grove // Add a 'pjax=1' query parameter if enabled.
fad2b5c47a41574ddfe0ec271ddd139430d3b26dEric Ferraiuolo // Captures the path with query, and hash parts of the URL. Then
fad2b5c47a41574ddfe0ec271ddd139430d3b26dEric Ferraiuolo // properly injects the "pjax=1" query param in the right place,
fad2b5c47a41574ddfe0ec271ddd139430d3b26dEric Ferraiuolo // before any hash fragment, and returns the updated URL.
fad2b5c47a41574ddfe0ec271ddd139430d3b26dEric Ferraiuolo url = url.replace(/([^#]*)(#.*)?$/, function (match, path, hash) {
fad2b5c47a41574ddfe0ec271ddd139430d3b26dEric Ferraiuolo path += (path.indexOf('?') > -1 ? '&' : '?') + 'pjax=1';
84ae7c9d0c9d7a559d93a52393255678b6ac4e55Ryan Grove // Send a request.
84ae7c9d0c9d7a559d93a52393255678b6ac4e55Ryan Grove // -- Event Handlers -------------------------------------------------------
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove Default event handler for both the `error` and `load` events. Attempts to
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove insert the loaded content into the `container` node and update the page's
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove @method _defCompleteFn
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove @param {EventFacade} e
84ae7c9d0c9d7a559d93a52393255678b6ac4e55Ryan Grove _defCompleteFn: function (e) {
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove Handles IO end events.
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove @method _onPjaxIOEnd
84ae7c9d0c9d7a559d93a52393255678b6ac4e55Ryan Grove _onPjaxIOEnd: function () {
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove Handles IO failure events and fires our own `error` event.
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove @method _onPjaxIOFailure
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove Handles IO success events and fires our own 'load' event.
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove @method _onPjaxIOSuccess
da8d2cc08af9bbf979ee87a14059ac8e0b74cee8Ryan Grove If `true`, a "pjax=1" query parameter will be appended to all URLs
da8d2cc08af9bbf979ee87a14059ac8e0b74cee8Ryan Grove requested via Pjax.
da8d2cc08af9bbf979ee87a14059ac8e0b74cee8Ryan Grove Browsers ignore HTTP request headers when caching content, so if the
da8d2cc08af9bbf979ee87a14059ac8e0b74cee8Ryan Grove same URL is used to request a partial Pjax page and a full page, the
da8d2cc08af9bbf979ee87a14059ac8e0b74cee8Ryan Grove browser will cache them under the same key and may later load the
da8d2cc08af9bbf979ee87a14059ac8e0b74cee8Ryan Grove cached partial page when the user actually requests a full page (or vice
da8d2cc08af9bbf979ee87a14059ac8e0b74cee8Ryan Grove To prevent this, we can add a bogus query parameter to the URL so that
da8d2cc08af9bbf979ee87a14059ac8e0b74cee8Ryan Grove Pjax URLs will always be cached separately from non-Pjax URLs.
da8d2cc08af9bbf979ee87a14059ac8e0b74cee8Ryan Grove @attribute addPjaxParam
da8d2cc08af9bbf979ee87a14059ac8e0b74cee8Ryan Grove @type Boolean
da8d2cc08af9bbf979ee87a14059ac8e0b74cee8Ryan Grove @default true
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove Node into which content should be inserted when a page is loaded via
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove Pjax. This node's existing contents will be removed to make way for the
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove new content.
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove If not set, loaded content will not be automatically inserted into the
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove @attribute container
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove @default null
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove CSS selector used to extract a specific portion of the content of a page
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove loaded via Pjax.
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove For example, if you wanted to load the page `example.html` but only use
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove the content within an element with the id "pjax-content", you'd set
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove `contentSelector` to "#pjax-content".
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove If not set, the entire page will be used.
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove @attribute contentSelector
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove @type String
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove @default null
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove // Inherited from Router and already documented there.
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove CSS selector used to extract a page title from the content of a page
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove loaded via Pjax.
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove By default this is set to extract the title from the `<title>` element,
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove but you could customize it to extract the title from an `<h1>`, or from
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove any other element, if that's more appropriate for the content you're
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove @attribute titleSelector
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove @type String
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove @default "title"
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove Time in milliseconds after which an Ajax request should time out. When a
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove timeout occurs, the `error` event will be fired.
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove @attribute timeout
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove @type Number
d5718409d7c1c4cbbd2be4605305c045a68a9136Ryan Grove @default 30000
84ae7c9d0c9d7a559d93a52393255678b6ac4e55Ryan Grove}, '@VERSION@' ,{requires:['pjax-base', 'io-base']});