@canonical/yui 3.18.2-pre

package/build/history-hash/history-hash.js

@@ -0,0 +1,475 @@
+YUI.add('history-hash', function (Y, NAME) {
+
+/**
+ * Provides browser history management backed by
+ * <code>window.location.hash</code>, as well as convenience methods for working
+ * with the location hash and a synthetic <code>hashchange</code> event that
+ * normalizes differences across browsers.
+ *
+ * @module history
+ * @submodule history-hash
+ * @since 3.2.0
+ * @class HistoryHash
+ * @extends HistoryBase
+ * @constructor
+ * @param {Object} config (optional) Configuration object. See the HistoryBase
+ *   documentation for details.
+ */
+
+var HistoryBase = Y.HistoryBase,
+    Lang        = Y.Lang,
+    YArray      = Y.Array,
+    YObject     = Y.Object,
+    GlobalEnv   = YUI.namespace('Env.HistoryHash'),
+
+    SRC_HASH    = 'hash',
+
+    hashNotifiers,
+    oldHash,
+    oldUrl,
+    win             = Y.config.win,
+    useHistoryHTML5 = Y.config.useHistoryHTML5;
+
+function HistoryHash() {
+    HistoryHash.superclass.constructor.apply(this, arguments);
+}
+
+Y.extend(HistoryHash, HistoryBase, {
+    // -- Initialization -------------------------------------------------------
+    _init: function (config) {
+        var bookmarkedState = HistoryHash.parseHash();
+
+        // If an initialState was provided, merge the bookmarked state into it
+        // (the bookmarked state wins).
+        config = config || {};
+
+        this._initialState = config.initialState ?
+                Y.merge(config.initialState, bookmarkedState) : bookmarkedState;
+
+        // Subscribe to the synthetic hashchange event (defined below) to handle
+        // changes.
+        Y.after('hashchange', Y.bind(this._afterHashChange, this), win);
+
+        HistoryHash.superclass._init.apply(this, arguments);
+    },
+
+    // -- Protected Methods ----------------------------------------------------
+    _change: function (src, state, options) {
+        // Stringify all values to ensure that comparisons don't fail after
+        // they're coerced to strings in the location hash.
+        YObject.each(state, function (value, key) {
+            if (Lang.isValue(value)) {
+                state[key] = value.toString();
+            }
+        });
+
+        return HistoryHash.superclass._change.call(this, src, state, options);
+    },
+
+    _storeState: function (src, newState) {
+        var decode  = HistoryHash.decode,
+            newHash = HistoryHash.createHash(newState);
+
+        HistoryHash.superclass._storeState.apply(this, arguments);
+
+        // Update the location hash with the changes, but only if the new hash
+        // actually differs from the current hash (this avoids creating multiple
+        // history entries for a single state).
+        //
+        // We always compare decoded hashes, since it's possible that the hash
+        // could be set incorrectly to a non-encoded value outside of
+        // HistoryHash.
+        if (src !== SRC_HASH && decode(HistoryHash.getHash()) !== decode(newHash)) {
+            HistoryHash[src === HistoryBase.SRC_REPLACE ? 'replaceHash' : 'setHash'](newHash);
+        }
+    },
+
+    // -- Protected Event Handlers ---------------------------------------------
+
+    /**
+     * Handler for hashchange events.
+     *
+     * @method _afterHashChange
+     * @param {Event} e
+     * @protected
+     */
+    _afterHashChange: function (e) {
+        this._resolveChanges(SRC_HASH, HistoryHash.parseHash(e.newHash), {});
+    }
+}, {
+    // -- Public Static Properties ---------------------------------------------
+    NAME: 'historyHash',
+
+    /**
+     * Constant used to identify state changes originating from
+     * <code>hashchange</code> events.
+     *
+     * @property SRC_HASH
+     * @type String
+     * @static
+     * @final
+     */
+    SRC_HASH: SRC_HASH,
+
+    /**
+     * <p>
+     * Prefix to prepend when setting the hash fragment. For example, if the
+     * prefix is <code>!</code> and the hash fragment is set to
+     * <code>#foo=bar&baz=quux</code>, the final hash fragment in the URL will
+     * become <code>#!foo=bar&baz=quux</code>. This can be used to help make an
+     * Ajax application crawlable in accordance with Google's guidelines at
+     * <a href="http://code.google.com/web/ajaxcrawling/">http://code.google.com/web/ajaxcrawling/</a>.
+     * </p>
+     *
+     * <p>
+     * Note that this prefix applies to all HistoryHash instances. It's not
+     * possible for individual instances to use their own prefixes since they
+     * all operate on the same URL.
+     * </p>
+     *
+     * @property hashPrefix
+     * @type String
+     * @default ''
+     * @static
+     */
+    hashPrefix: '',
+
+    // -- Protected Static Properties ------------------------------------------
+
+    /**
+     * Regular expression used to parse location hash/query strings.
+     *
+     * @property _REGEX_HASH
+     * @type RegExp
+     * @protected
+     * @static
+     * @final
+     */
+    _REGEX_HASH: /([^\?#&=]+)=?([^&=]*)/g,
+
+    // -- Public Static Methods ------------------------------------------------
+
+    /**
+     * Creates a location hash string from the specified object of key/value
+     * pairs.
+     *
+     * @method createHash
+     * @param {Object} params object of key/value parameter pairs
+     * @return {String} location hash string
+     * @static
+     */
+    createHash: function (params) {
+        var encode = HistoryHash.encode,
+            hash   = [];
+
+        YObject.each(params, function (value, key) {
+            if (Lang.isValue(value)) {
+                hash.push(encode(key) + '=' + encode(value));
+            }
+        });
+
+        return hash.join('&');
+    },
+
+    /**
+     * Wrapper around <code>decodeURIComponent()</code> that also converts +
+     * chars into spaces.
+     *
+     * @method decode
+     * @param {String} string string to decode
+     * @return {String} decoded string
+     * @static
+     */
+    decode: function (string) {
+        return decodeURIComponent(string.replace(/\+/g, ' '));
+    },
+
+    /**
+     * Wrapper around <code>encodeURIComponent()</code> that converts spaces to
+     * + chars.
+     *
+     * @method encode
+     * @param {String} string string to encode
+     * @return {String} encoded string
+     * @static
+     */
+    encode: function (string) {
+        return encodeURIComponent(string).replace(/%20/g, '+');
+    },
+
+    /**
+     * Gets the raw (not decoded) current location hash, minus the preceding '#'
+     * character and the hashPrefix (if one is set).
+     *
+     * @method getHash
+     * @return {String} current location hash
+     * @static
+     */
+    getHash: (Y.UA.gecko ? function () {
+        // Gecko's window.location.hash returns a decoded string and we want all
+        // encoding untouched, so we need to get the hash value from
+        // window.location.href instead. We have to use UA sniffing rather than
+        // feature detection, since the only way to detect this would be to
+        // actually change the hash.
+        var location = Y.getLocation(),
+            matches  = /#(.*)$/.exec(location.href),
+            hash     = matches && matches[1] || '',
+            prefix   = HistoryHash.hashPrefix;
+
+        return prefix && hash.indexOf(prefix) === 0 ?
+                    hash.replace(prefix, '') : hash;
+    } : function () {
+        var location = Y.getLocation(),
+            hash     = location.hash.substring(1),
+            prefix   = HistoryHash.hashPrefix;
+
+        // Slight code duplication here, but execution speed is of the essence
+        // since getHash() is called every 50ms to poll for changes in browsers
+        // that don't support native onhashchange. An additional function call
+        // would add unnecessary overhead.
+        return prefix && hash.indexOf(prefix) === 0 ?
+                    hash.replace(prefix, '') : hash;
+    }),
+
+    /**
+     * Gets the current bookmarkable URL.
+     *
+     * @method getUrl
+     * @return {String} current bookmarkable URL
+     * @static
+     */
+    getUrl: function () {
+        return location.href;
+    },
+
+    /**
+     * Parses a location hash string into an object of key/value parameter
+     * pairs. If <i>hash</i> is not specified, the current location hash will
+     * be used.
+     *
+     * @method parseHash
+     * @param {String} hash (optional) location hash string
+     * @return {Object} object of parsed key/value parameter pairs
+     * @static
+     */
+    parseHash: function (hash) {
+        var decode = HistoryHash.decode,
+            i,
+            len,
+            match,
+            matches,
+            param,
+            params = {},
+            prefix = HistoryHash.hashPrefix,
+            prefixIndex;
+
+        hash = Lang.isValue(hash) ? hash : HistoryHash.getHash();
+
+        if (prefix) {
+            prefixIndex = hash.indexOf(prefix);
+
+            if (prefixIndex === 0 || (prefixIndex === 1 && hash.charAt(0) === '#')) {
+                hash = hash.replace(prefix, '');
+            }
+        }
+
+        matches = hash.match(HistoryHash._REGEX_HASH) || [];
+
+        for (i = 0, len = matches.length; i < len; ++i) {
+            match = matches[i];
+
+            param = match.split('=');
+
+            if (param.length > 1) {
+                params[decode(param[0])] = decode(param[1]);
+            } else {
+                params[decode(match)] = '';
+            }
+        }
+
+        return params;
+    },
+
+    /**
+     * Replaces the browser's current location hash with the specified hash
+     * and removes all forward navigation states, without creating a new browser
+     * history entry. Automatically prepends the <code>hashPrefix</code> if one
+     * is set.
+     *
+     * @method replaceHash
+     * @param {String} hash new location hash
+     * @static
+     */
+    replaceHash: function (hash) {
+        var location = Y.getLocation(),
+            base     = location.href.replace(/#.*$/, '');
+
+        if (hash.charAt(0) === '#') {
+            hash = hash.substring(1);
+        }
+
+        location.replace(base + '#' + (HistoryHash.hashPrefix || '') + hash);
+    },
+
+    /**
+     * Sets the browser's location hash to the specified string. Automatically
+     * prepends the <code>hashPrefix</code> if one is set.
+     *
+     * @method setHash
+     * @param {String} hash new location hash
+     * @static
+     */
+    setHash: function (hash) {
+        var location = Y.getLocation();
+
+        if (hash.charAt(0) === '#') {
+            hash = hash.substring(1);
+        }
+
+        location.hash = (HistoryHash.hashPrefix || '') + hash;
+    }
+});
+
+// -- Synthetic hashchange Event -----------------------------------------------
+
+// TODO: YUIDoc currently doesn't provide a good way to document synthetic DOM
+// events. For now, we're just documenting the hashchange event on the YUI
+// object, which is about the best we can do until enhancements are made to
+// YUIDoc.
+
+/**
+Synthetic <code>window.onhashchange</code> event that normalizes differences
+across browsers and provides support for browsers that don't natively support
+<code>onhashchange</code>.
+
+This event is provided by the <code>history-hash</code> module.
+
+@example
+
+    YUI().use('history-hash', function (Y) {
+      Y.on('hashchange', function (e) {
+        // Handle hashchange events on the current window.
+      }, Y.config.win);
+    });
+
+@event hashchange
+@param {EventFacade} e Event facade with the following additional
+  properties:
+
+<dl>
+  <dt>oldHash</dt>
+  <dd>
+    Previous hash fragment value before the change.
+  </dd>
+
+  <dt>oldUrl</dt>
+  <dd>
+    Previous URL (including the hash fragment) before the change.
+  </dd>
+
+  <dt>newHash</dt>
+  <dd>
+    New hash fragment value after the change.
+  </dd>
+
+  <dt>newUrl</dt>
+  <dd>
+    New URL (including the hash fragment) after the change.
+  </dd>
+</dl>
+@for YUI
+@since 3.2.0
+**/
+
+hashNotifiers = GlobalEnv._notifiers;
+
+if (!hashNotifiers) {
+    hashNotifiers = GlobalEnv._notifiers = [];
+}
+
+Y.Event.define('hashchange', {
+    on: function (node, subscriber, notifier) {
+        // Ignore this subscription if the node is anything other than the
+        // window or document body, since those are the only elements that
+        // should support the hashchange event. Note that the body could also be
+        // a frameset, but that's okay since framesets support hashchange too.
+        if (node.compareTo(win) || node.compareTo(Y.config.doc.body)) {
+            hashNotifiers.push(notifier);
+        }
+    },
+
+    detach: function (node, subscriber, notifier) {
+        var index = YArray.indexOf(hashNotifiers, notifier);
+
+        if (index !== -1) {
+            hashNotifiers.splice(index, 1);
+        }
+    }
+});
+
+oldHash = HistoryHash.getHash();
+oldUrl  = HistoryHash.getUrl();
+
+if (HistoryBase.nativeHashChange) {
+    // Wrap the browser's native hashchange event if there's not already a
+    // global listener.
+    if (!GlobalEnv._hashHandle) {
+        GlobalEnv._hashHandle = Y.Event.attach('hashchange', function (e) {
+            var newHash = HistoryHash.getHash(),
+                newUrl  = HistoryHash.getUrl();
+
+            // Iterate over a copy of the hashNotifiers array since a subscriber
+            // could detach during iteration and cause the array to be re-indexed.
+            YArray.each(hashNotifiers.concat(), function (notifier) {
+                notifier.fire({
+                    _event : e,
+                    oldHash: oldHash,
+                    oldUrl : oldUrl,
+                    newHash: newHash,
+                    newUrl : newUrl
+                });
+            });
+
+            oldHash = newHash;
+            oldUrl  = newUrl;
+        }, win);
+    }
+} else {
+    // Begin polling for location hash changes if there's not already a global
+    // poll running.
+    if (!GlobalEnv._hashPoll) {
+        GlobalEnv._hashPoll = Y.later(50, null, function () {
+            var newHash = HistoryHash.getHash(),
+                facade, newUrl;
+
+            if (oldHash !== newHash) {
+                newUrl = HistoryHash.getUrl();
+
+                facade = {
+                    oldHash: oldHash,
+                    oldUrl : oldUrl,
+                    newHash: newHash,
+                    newUrl : newUrl
+                };
+
+                oldHash = newHash;
+                oldUrl  = newUrl;
+
+                YArray.each(hashNotifiers.concat(), function (notifier) {
+                    notifier.fire(facade);
+                });
+            }
+        }, null, true);
+    }
+}
+
+Y.HistoryHash = HistoryHash;
+
+// HistoryHash will never win over HistoryHTML5 unless useHistoryHTML5 is false.
+if (useHistoryHTML5 === false || (!Y.History && useHistoryHTML5 !== true &&
+        (!HistoryBase.html5 || !Y.HistoryHTML5))) {
+    Y.History = HistoryHash;
+}
+
+
+}, '@VERSION@', {"requires": ["event-synthetic", "history-base", "yui-later"]});

package/build/history-hash-ie/history-hash-ie-debug.js

@@ -0,0 +1,138 @@
+YUI.add('history-hash-ie', function (Y, NAME) {
+
+/**
+ * Improves IE6/7 support in history-hash by using a hidden iframe to create
+ * entries in IE's browser history. This module is only needed if IE6/7 support
+ * is necessary; it's not needed for any other browser.
+ *
+ * @module history
+ * @submodule history-hash-ie
+ * @since 3.2.0
+ */
+
+// Combination of a UA sniff to ensure this is IE (or a browser that wants us to
+// treat it like IE) and feature detection for native hashchange support (false
+// for IE < 8 or IE8/9 in IE7 mode).
+if (Y.UA.ie && !Y.HistoryBase.nativeHashChange) {
+    var Do          = Y.Do,
+        GlobalEnv   = YUI.namespace('Env.HistoryHash'),
+        HistoryHash = Y.HistoryHash,
+
+        iframe = GlobalEnv._iframe,
+        win    = Y.config.win;
+
+    /**
+     * Gets the raw (not decoded) current location hash from the IE iframe,
+     * minus the preceding '#' character and the hashPrefix (if one is set).
+     *
+     * @method getIframeHash
+     * @return {String} current iframe hash
+     * @static
+     */
+    HistoryHash.getIframeHash = function () {
+        if (!iframe || !iframe.contentWindow) {
+            return '';
+        }
+
+        var prefix = HistoryHash.hashPrefix,
+            hash   = iframe.contentWindow.location.hash.substr(1);
+
+        return prefix && hash.indexOf(prefix) === 0 ?
+                    hash.replace(prefix, '') : hash;
+    };
+
+    /**
+     * Updates the history iframe with the specified hash.
+     *
+     * @method _updateIframe
+     * @param {String} hash location hash
+     * @param {Boolean} replace (optional) if <code>true</code>, the current
+     *   history state will be replaced without adding a new history entry
+     * @protected
+     * @static
+     * @for HistoryHash
+     */
+    HistoryHash._updateIframe = function (hash, replace) {
+        var iframeDoc      = iframe && iframe.contentWindow && iframe.contentWindow.document,
+            iframeLocation = iframeDoc && iframeDoc.location;
+
+        if (!iframeDoc || !iframeLocation) {
+            return;
+        }
+
+        Y.log('updating history iframe: ' + hash + ', replace: ' + !!replace, 'info', 'history');
+
+        if (replace) {
+            iframeLocation.replace(hash.charAt(0) === '#' ? hash : '#' + hash);
+        } else {
+            iframeDoc.open().close();
+            iframeLocation.hash = hash;
+        }
+    };
+
+    Do.before(HistoryHash._updateIframe, HistoryHash, 'replaceHash', HistoryHash, true);
+
+    if (!iframe) {
+        Y.on('domready', function () {
+            var lastUrlHash = HistoryHash.getHash();
+
+            // Create a hidden iframe to store history state, following the
+            // iframe-hiding recommendations from
+            // http://www.paciellogroup.com/blog/?p=604.
+            //
+            // This iframe will allow history navigation within the current page
+            // context. After navigating to another page, all but the most
+            // recent history state will be lost.
+            //
+            // Earlier versions of the YUI History Utility attempted to work
+            // around this limitation by having the iframe load a static
+            // resource. This workaround was extremely fragile and tended to
+            // break frequently (and silently) since it was entirely dependent
+            // on IE's inconsistent handling of iframe history.
+            //
+            // Since this workaround didn't work much of the time anyway and
+            // added significant complexity, it has been removed, and IE6 and 7
+            // now get slightly degraded history support.
+            Y.log('creating dynamic history iframe', 'info', 'history');
+
+            iframe = GlobalEnv._iframe = Y.Node.getDOMNode(Y.Node.create(
+                '<iframe src="javascript:0" style="display:none" height="0" width="0" tabindex="-1" title="empty"/>'
+            ));
+
+            // Append the iframe to the documentElement rather than the body.
+            // Keeping it outside the body prevents scrolling on the initial
+            // page load (hat tip to Ben Alman and jQuery BBQ for this
+            // technique).
+            Y.config.doc.documentElement.appendChild(iframe);
+
+            // Update the iframe with the initial location hash, if any. This
+            // will create an initial history entry that the user can return to
+            // after the state has changed.
+            HistoryHash._updateIframe(lastUrlHash || '#');
+
+            // Listen for hashchange events and keep the iframe's hash in sync
+            // with the parent frame's hash.
+            Y.on('hashchange', function (e) {
+                lastUrlHash = e.newHash;
+
+                if (HistoryHash.getIframeHash() !== lastUrlHash) {
+                    Y.log('updating iframe hash to match URL hash', 'info', 'history');
+                    HistoryHash._updateIframe(lastUrlHash);
+                }
+            }, win);
+
+            // Watch the iframe hash in order to detect back/forward navigation.
+            Y.later(50, null, function () {
+                var iframeHash = HistoryHash.getIframeHash();
+
+                if (iframeHash !== lastUrlHash) {
+                    Y.log('updating URL hash to match iframe hash', 'info', 'history');
+                    HistoryHash.setHash(iframeHash);
+                }
+            }, null, true);
+        });
+    }
+}
+
+
+}, '@VERSION@', {"requires": ["history-hash", "node-base"]});

package/build/history-hash-ie/history-hash-ie-min.js

@@ -0,0 +1 @@
+YUI.add("history-hash-ie",function(e,t){if(e.UA.ie&&!e.HistoryBase.nativeHashChange){var n=e.Do,r=YUI.namespace("Env.HistoryHash"),i=e.HistoryHash,s=r._iframe,o=e.config.win;i.getIframeHash=function(){if(!s||!s.contentWindow)return"";var e=i.hashPrefix,t=s.contentWindow.location.hash.substr(1);return e&&t.indexOf(e)===0?t.replace(e,""):t},i._updateIframe=function(e,t){var n=s&&s.contentWindow&&s.contentWindow.document,r=n&&n.location;if(!n||!r)return;t?r.replace(e.charAt(0)==="#"?e:"#"+e):(n.open().close(),r.hash=e)},n.before(i._updateIframe,i,"replaceHash",i,!0),s||e.on("domready",function(){var t=i.getHash();s=r._iframe=e.Node.getDOMNode(e.Node.create('<iframe src="javascript:0" style="display:none" height="0" width="0" tabindex="-1" title="empty"/>')),e.config.doc.documentElement.appendChild(s),i._updateIframe(t||"#"),e.on("hashchange",function(e){t=e.newHash,i.getIframeHash()!==t&&i._updateIframe(t)},o),e.later(50,null,function(){var e=i.getIframeHash();e!==t&&i.setHash(e)},null,!0)})}},"@VERSION@",{requires:["history-hash","node-base"]});