@canonical/yui 3.18.2-pre

package/build/history-base/history-base-debug.js

@@ -0,0 +1,639 @@
+YUI.add('history-base', function (Y, NAME) {
+
+/**
+ * Provides browser history management functionality using a simple
+ * add/replace/get paradigm. This can be used to ensure that the browser's back
+ * and forward buttons work as the user expects and to provide bookmarkable URLs
+ * that return the user to the current application state, even in an Ajax
+ * application that doesn't perform full-page refreshes.
+ *
+ * @module history
+ * @main history
+ * @since 3.2.0
+ */
+
+/**
+ * Provides global state management backed by an object, but with no browser
+ * history integration. For actual browser history integration and back/forward
+ * support, use the history-html5 or history-hash modules.
+ *
+ * @module history
+ * @submodule history-base
+ * @class HistoryBase
+ * @uses EventTarget
+ * @constructor
+ * @param {Object} config (optional) configuration object, which may contain
+ *   zero or more of the following properties:
+ *
+ * <dl>
+ *   <dt>force (Boolean)</dt>
+ *   <dd>
+ *     If `true`, a `history:change` event will be fired whenever the URL
+ *     changes, even if there is no associated state change. Default is `false`.
+ *   </dd>
+ *
+ *   <dt>initialState (Object)</dt>
+ *   <dd>
+ *     Initial state to set, as an object hash of key/value pairs. This will be
+ *     merged into the current global state.
+ *   </dd>
+ * </dl>
+ */
+
+var Lang      = Y.Lang,
+    Obj       = Y.Object,
+    GlobalEnv = YUI.namespace('Env.History'),
+    YArray    = Y.Array,
+
+    doc       = Y.config.doc,
+    docMode   = doc.documentMode,
+    win       = Y.config.win,
+
+    DEFAULT_OPTIONS = {merge: true},
+    EVT_CHANGE      = 'change',
+    SRC_ADD         = 'add',
+    SRC_REPLACE     = 'replace';
+
+function HistoryBase() {
+    this._init.apply(this, arguments);
+}
+
+Y.augment(HistoryBase, Y.EventTarget, null, null, {
+    emitFacade : true,
+    prefix     : 'history',
+    preventable: false,
+    queueable  : true
+});
+
+if (!GlobalEnv._state) {
+    GlobalEnv._state = {};
+}
+
+// -- Private Methods ----------------------------------------------------------
+
+/**
+ * Returns <code>true</code> if <i>value</i> is a simple object and not a
+ * function or an array.
+ *
+ * @method _isSimpleObject
+ * @param {mixed} value
+ * @return {Boolean}
+ * @private
+ */
+function _isSimpleObject(value) {
+    return Lang.type(value) === 'object';
+}
+
+// -- Public Static Properties -------------------------------------------------
+
+/**
+ * Name of this component.
+ *
+ * @property NAME
+ * @type String
+ * @static
+ */
+HistoryBase.NAME = 'historyBase';
+
+/**
+ * Constant used to identify state changes originating from the
+ * <code>add()</code> method.
+ *
+ * @property SRC_ADD
+ * @type String
+ * @static
+ * @final
+ */
+HistoryBase.SRC_ADD = SRC_ADD;
+
+/**
+ * Constant used to identify state changes originating from the
+ * <code>replace()</code> method.
+ *
+ * @property SRC_REPLACE
+ * @type String
+ * @static
+ * @final
+ */
+HistoryBase.SRC_REPLACE = SRC_REPLACE;
+
+/**
+ * Whether or not this browser supports the HTML5 History API.
+ *
+ * @property html5
+ * @type Boolean
+ * @static
+ */
+
+// All HTML5-capable browsers except Gecko 2+ (Firefox 4+) correctly return
+// true for 'onpopstate' in win. In order to support Gecko 2, we fall back to a
+// UA sniff for now. (current as of Firefox 4.0b2)
+HistoryBase.html5 = !!(win.history && win.history.pushState &&
+        win.history.replaceState && ('onpopstate' in win || Y.UA.gecko >= 2) &&
+        (!Y.UA.android || Y.UA.android >= 2.4));
+
+/**
+ * Whether or not this browser supports the <code>window.onhashchange</code>
+ * event natively. Note that even if this is <code>true</code>, you may
+ * still want to use HistoryHash's synthetic <code>hashchange</code> event
+ * since it normalizes implementation differences and fixes spec violations
+ * across various browsers.
+ *
+ * @property nativeHashChange
+ * @type Boolean
+ * @static
+ */
+
+// Most browsers that support hashchange expose it on the window. Opera 10.6+
+// exposes it on the document (but you can still attach to it on the window).
+//
+// IE8 supports the hashchange event, but only in IE8 Standards
+// Mode. However, IE8 in IE7 compatibility mode still defines the
+// event but never fires it, so we can't just detect the event. We also can't
+// just UA sniff for IE8, since other browsers support this event as well.
+HistoryBase.nativeHashChange = ('onhashchange' in win || 'onhashchange' in doc) &&
+        (!docMode || docMode > 7);
+
+Y.mix(HistoryBase.prototype, {
+    // -- Initialization -------------------------------------------------------
+
+    /**
+     * Initializes this HistoryBase instance. This method is called by the
+     * constructor.
+     *
+     * @method _init
+     * @param {Object} config configuration object
+     * @protected
+     */
+    _init: function (config) {
+        var initialState;
+
+        /**
+         * Configuration object provided by the user on instantiation, or an
+         * empty object if one wasn't provided.
+         *
+         * @property _config
+         * @type Object
+         * @default {}
+         * @protected
+         */
+        config = this._config = config || {};
+
+        /**
+         * If `true`, a `history:change` event will be fired whenever the URL
+         * changes, even if there is no associated state change.
+         *
+         * @property force
+         * @type Boolean
+         * @default false
+         */
+         this.force = !!config.force;
+
+        /**
+         * Resolved initial state: a merge of the user-supplied initial state
+         * (if any) and any initial state provided by a subclass. This may
+         * differ from <code>_config.initialState</code>. If neither the config
+         * nor a subclass supplies an initial state, this property will be
+         * <code>null</code>.
+         *
+         * @property _initialState
+         * @type Object|null
+         * @default {}
+         * @protected
+         */
+        initialState = this._initialState = this._initialState ||
+                config.initialState || null;
+
+        /**
+         * Fired when the state changes. To be notified of all state changes
+         * regardless of the History or YUI instance that generated them,
+         * subscribe to this event on <code>Y.Global</code>. If you would rather
+         * be notified only about changes generated by this specific History
+         * instance, subscribe to this event on the instance.
+         *
+         * @event history:change
+         * @param {EventFacade} e Event facade with the following additional
+         *   properties:
+         *
+         * <dl>
+         *   <dt>changed (Object)</dt>
+         *   <dd>
+         *     Object hash of state items that have been added or changed. The
+         *     key is the item key, and the value is an object containing
+         *     <code>newVal</code> and <code>prevVal</code> properties
+         *     representing the values of the item both before and after the
+         *     change. If the item was newly added, <code>prevVal</code> will be
+         *     <code>undefined</code>.
+         *   </dd>
+         *
+         *   <dt>newVal (Object)</dt>
+         *   <dd>
+         *     Object hash of key/value pairs of all state items after the
+         *     change.
+         *   </dd>
+         *
+         *   <dt>prevVal (Object)</dt>
+         *   <dd>
+         *     Object hash of key/value pairs of all state items before the
+         *     change.
+         *   </dd>
+         *
+         *   <dt>removed (Object)</dt>
+         *   <dd>
+         *     Object hash of key/value pairs of state items that have been
+         *     removed. Values are the old values prior to removal.
+         *   </dd>
+         *
+         *   <dt>src (String)</dt>
+         *   <dd>
+         *     The source of the event. This can be used to selectively ignore
+         *     events generated by certain sources.
+         *   </dd>
+         * </dl>
+         */
+        this.publish(EVT_CHANGE, {
+            broadcast: 2,
+            defaultFn: this._defChangeFn
+        });
+
+        // If initialState was provided, merge it into the current state.
+        if (initialState) {
+            this.replace(initialState);
+        }
+    },
+
+    // -- Public Methods -------------------------------------------------------
+
+    /**
+     * Adds a state entry with new values for the specified keys. By default,
+     * the new state will be merged into the existing state, and new values will
+     * override existing values. Specifying a <code>null</code> or
+     * <code>undefined</code> value will cause that key to be removed from the
+     * new state entry.
+     *
+     * @method add
+     * @param {Object} state Object hash of key/value pairs.
+     * @param {Object} options (optional) Zero or more of the following options:
+     *   <dl>
+     *     <dt>merge (Boolean)</dt>
+     *     <dd>
+     *       <p>
+     *       If <code>true</code> (the default), the new state will be merged
+     *       into the existing state. New values will override existing values,
+     *       and <code>null</code> or <code>undefined</code> values will be
+     *       removed from the state.
+     *       </p>
+     *       <p>
+     *       If <code>false</code>, the existing state will be discarded as a
+     *       whole and the new state will take its place.
+     *       </p>
+     *     </dd>
+     *   </dl>
+     * @chainable
+     */
+    add: function () {
+        var args = YArray(arguments, 0, true);
+        args.unshift(SRC_ADD);
+        return this._change.apply(this, args);
+    },
+
+    /**
+     * Adds a state entry with a new value for a single key. By default, the new
+     * value will be merged into the existing state values, and will override an
+     * existing value with the same key if there is one. Specifying a
+     * <code>null</code> or <code>undefined</code> value will cause the key to
+     * be removed from the new state entry.
+     *
+     * @method addValue
+     * @param {String} key State parameter key.
+     * @param {String} value New value.
+     * @param {Object} options (optional) Zero or more options. See
+     *   <code>add()</code> for a list of supported options.
+     * @chainable
+     */
+    addValue: function (key, value, options) {
+        var state = {};
+        state[key] = value;
+        return this._change(SRC_ADD, state, options);
+    },
+
+    /**
+     * Returns the current value of the state parameter specified by <i>key</i>,
+     * or an object hash of key/value pairs for all current state parameters if
+     * no key is specified.
+     *
+     * @method get
+     * @param {String} key (optional) State parameter key.
+     * @return {Object|String} Value of the specified state parameter, or an
+     *   object hash of key/value pairs for all current state parameters.
+     */
+    get: function (key) {
+        var state    = GlobalEnv._state,
+            isObject = _isSimpleObject(state);
+
+        if (key) {
+            return isObject && Obj.owns(state, key) ? state[key] : undefined;
+        } else {
+            return isObject ? Y.mix({}, state, true) : state; // mix provides a fast shallow clone.
+        }
+    },
+
+    /**
+     * Same as <code>add()</code> except that a new browser history entry will
+     * not be created. Instead, the current history entry will be replaced with
+     * the new state.
+     *
+     * @method replace
+     * @param {Object} state Object hash of key/value pairs.
+     * @param {Object} options (optional) Zero or more options. See
+     *   <code>add()</code> for a list of supported options.
+     * @chainable
+     */
+    replace: function () {
+        var args = YArray(arguments, 0, true);
+        args.unshift(SRC_REPLACE);
+        return this._change.apply(this, args);
+    },
+
+    /**
+     * Same as <code>addValue()</code> except that a new browser history entry
+     * will not be created. Instead, the current history entry will be replaced
+     * with the new state.
+     *
+     * @method replaceValue
+     * @param {String} key State parameter key.
+     * @param {String} value New value.
+     * @param {Object} options (optional) Zero or more options. See
+     *   <code>add()</code> for a list of supported options.
+     * @chainable
+     */
+    replaceValue: function (key, value, options) {
+        var state = {};
+        state[key] = value;
+        return this._change(SRC_REPLACE, state, options);
+    },
+
+    // -- Protected Methods ----------------------------------------------------
+
+    /**
+     * Changes the state. This method provides a common implementation shared by
+     * the public methods for changing state.
+     *
+     * @method _change
+     * @param {String} src Source of the change, for inclusion in event facades
+     *   to facilitate filtering.
+     * @param {Object} state Object hash of key/value pairs.
+     * @param {Object} options (optional) Zero or more options. See
+     *   <code>add()</code> for a list of supported options.
+     * @protected
+     * @chainable
+     */
+    _change: function (src, state, options) {
+        options = options ? Y.merge(DEFAULT_OPTIONS, options) : DEFAULT_OPTIONS;
+
+        if (options.merge && _isSimpleObject(state) &&
+                _isSimpleObject(GlobalEnv._state)) {
+            state = Y.merge(GlobalEnv._state, state);
+        }
+
+        this._resolveChanges(src, state, options);
+        return this;
+    },
+
+    /**
+     * Called by _resolveChanges() when the state has changed. This method takes
+     * care of actually firing the necessary events.
+     *
+     * @method _fireEvents
+     * @param {String} src Source of the changes, for inclusion in event facades
+     *   to facilitate filtering.
+     * @param {Object} changes Resolved changes.
+     * @param {Object} options Zero or more options. See <code>add()</code> for
+     *   a list of supported options.
+     * @protected
+     */
+    _fireEvents: function (src, changes, options) {
+        // Fire the global change event.
+        this.fire(EVT_CHANGE, {
+            _options: options,
+            changed : changes.changed,
+            newVal  : changes.newState,
+            prevVal : changes.prevState,
+            removed : changes.removed,
+            src     : src
+        });
+
+        // Fire change/remove events for individual items.
+        Obj.each(changes.changed, function (value, key) {
+            this._fireChangeEvent(src, key, value);
+        }, this);
+
+        Obj.each(changes.removed, function (value, key) {
+            this._fireRemoveEvent(src, key, value);
+        }, this);
+    },
+
+    /**
+     * Fires a dynamic "[key]Change" event.
+     *
+     * @method _fireChangeEvent
+     * @param {String} src source of the change, for inclusion in event facades
+     *   to facilitate filtering
+     * @param {String} key key of the item that was changed
+     * @param {Object} value object hash containing <i>newVal</i> and
+     *   <i>prevVal</i> properties for the changed item
+     * @protected
+     */
+    _fireChangeEvent: function (src, key, value) {
+        /**
+         * <p>
+         * Dynamic event fired when an individual history item is added or
+         * changed. The name of this event depends on the name of the key that
+         * changed. To listen to change events for a key named "foo", subscribe
+         * to the <code>fooChange</code> event; for a key named "bar", subscribe
+         * to <code>barChange</code>, etc.
+         * </p>
+         *
+         * <p>
+         * Key-specific events are only fired for instance-level changes; that
+         * is, changes that were made via the same History instance on which the
+         * event is subscribed. To be notified of changes made by other History
+         * instances, subscribe to the global <code>history:change</code> event.
+         * </p>
+         *
+         * @event [key]Change
+         * @param {EventFacade} e Event facade with the following additional
+         *   properties:
+         *
+         * <dl>
+         *   <dt>newVal (mixed)</dt>
+         *   <dd>
+         *     The new value of the item after the change.
+         *   </dd>
+         *
+         *   <dt>prevVal (mixed)</dt>
+         *   <dd>
+         *     The previous value of the item before the change, or
+         *     <code>undefined</code> if the item was just added and has no
+         *     previous value.
+         *   </dd>
+         *
+         *   <dt>src (String)</dt>
+         *   <dd>
+         *     The source of the event. This can be used to selectively ignore
+         *     events generated by certain sources.
+         *   </dd>
+         * </dl>
+         */
+        this.fire(key + 'Change', {
+            newVal : value.newVal,
+            prevVal: value.prevVal,
+            src    : src
+        });
+    },
+
+    /**
+     * Fires a dynamic "[key]Remove" event.
+     *
+     * @method _fireRemoveEvent
+     * @param {String} src source of the change, for inclusion in event facades
+     *   to facilitate filtering
+     * @param {String} key key of the item that was removed
+     * @param {mixed} value value of the item prior to its removal
+     * @protected
+     */
+    _fireRemoveEvent: function (src, key, value) {
+        /**
+         * <p>
+         * Dynamic event fired when an individual history item is removed. The
+         * name of this event depends on the name of the key that was removed.
+         * To listen to remove events for a key named "foo", subscribe to the
+         * <code>fooRemove</code> event; for a key named "bar", subscribe to
+         * <code>barRemove</code>, etc.
+         * </p>
+         *
+         * <p>
+         * Key-specific events are only fired for instance-level changes; that
+         * is, changes that were made via the same History instance on which the
+         * event is subscribed. To be notified of changes made by other History
+         * instances, subscribe to the global <code>history:change</code> event.
+         * </p>
+         *
+         * @event [key]Remove
+         * @param {EventFacade} e Event facade with the following additional
+         *   properties:
+         *
+         * <dl>
+         *   <dt>prevVal (mixed)</dt>
+         *   <dd>
+         *     The value of the item before it was removed.
+         *   </dd>
+         *
+         *   <dt>src (String)</dt>
+         *   <dd>
+         *     The source of the event. This can be used to selectively ignore
+         *     events generated by certain sources.
+         *   </dd>
+         * </dl>
+         */
+        this.fire(key + 'Remove', {
+            prevVal: value,
+            src    : src
+        });
+    },
+
+    /**
+     * Resolves the changes (if any) between <i>newState</i> and the current
+     * state and fires appropriate events if things have changed.
+     *
+     * @method _resolveChanges
+     * @param {String} src source of the changes, for inclusion in event facades
+     *   to facilitate filtering
+     * @param {Object} newState object hash of key/value pairs representing the
+     *   new state
+     * @param {Object} options Zero or more options. See <code>add()</code> for
+     *   a list of supported options.
+     * @protected
+     */
+    _resolveChanges: function (src, newState, options) {
+        var changed   = {},
+            isChanged,
+            prevState = GlobalEnv._state,
+            removed   = {};
+
+        newState || (newState = {});
+        options  || (options  = {});
+
+        if (_isSimpleObject(newState) && _isSimpleObject(prevState)) {
+            // Figure out what was added or changed.
+            Obj.each(newState, function (newVal, key) {
+                var prevVal = prevState[key];
+
+                if (newVal !== prevVal) {
+                    changed[key] = {
+                        newVal : newVal,
+                        prevVal: prevVal
+                    };
+
+                    isChanged = true;
+                }
+            }, this);
+
+            // Figure out what was removed.
+            Obj.each(prevState, function (prevVal, key) {
+                if (!Obj.owns(newState, key) || newState[key] === null) {
+                    delete newState[key];
+                    removed[key] = prevVal;
+                    isChanged = true;
+                }
+            }, this);
+        } else {
+            isChanged = newState !== prevState;
+        }
+
+        if (isChanged || this.force) {
+            this._fireEvents(src, {
+                changed  : changed,
+                newState : newState,
+                prevState: prevState,
+                removed  : removed
+            }, options);
+        }
+    },
+
+    /**
+     * Stores the specified state. Don't call this method directly; go through
+     * _resolveChanges() to ensure that changes are resolved and all events are
+     * fired properly.
+     *
+     * @method _storeState
+     * @param {String} src source of the changes
+     * @param {Object} newState new state to store
+     * @param {Object} options Zero or more options. See <code>add()</code> for
+     *   a list of supported options.
+     * @protected
+     */
+    _storeState: function (src, newState) {
+        // Note: the src and options params aren't used here, but they are used
+        // by subclasses.
+        GlobalEnv._state = newState || {};
+    },
+
+    // -- Protected Event Handlers ---------------------------------------------
+
+    /**
+     * Default <code>history:change</code> event handler.
+     *
+     * @method _defChangeFn
+     * @param {EventFacade} e state change event facade
+     * @protected
+     */
+    _defChangeFn: function (e) {
+        this._storeState(e.src, e.newVal, e._options);
+    }
+}, true);
+
+Y.HistoryBase = HistoryBase;
+
+
+}, '@VERSION@', {"requires": ["event-custom-complex"]});

package/build/history-base/history-base-min.js

@@ -0,0 +1 @@
+YUI.add("history-base",function(e,t){function p(){this._init.apply(this,arguments)}function d(e){return n.type(e)==="object"}var n=e.Lang,r=e.Object,i=YUI.namespace("Env.History"),s=e.Array,o=e.config.doc,u=o.documentMode,a=e.config.win,f={merge:!0},l="change",c="add",h="replace";e.augment(p,e.EventTarget,null,null,{emitFacade:!0,prefix:"history",preventable:!1,queueable:!0}),i._state||(i._state={}),p.NAME="historyBase",p.SRC_ADD=c,p.SRC_REPLACE=h,p.html5=!!(a.history&&a.history.pushState&&a.history.replaceState&&("onpopstate"in a||e.UA.gecko>=2)&&(!e.UA.android||e.UA.android>=2.4)),p.nativeHashChange=("onhashchange"in a||"onhashchange"in o)&&(!u||u>7),e.mix(p.prototype,{_init:function(e){var t;e=this._config=e||{},this.force=!!e.force,t=this._initialState=this._initialState||e.initialState||null,this.publish(l,{broadcast:2,defaultFn:this._defChangeFn}),t&&this.replace(t)},add:function(){var e=s(arguments,0,!0);return e.unshift(c),this._change.apply(this,e)},addValue:function(e,t,n){var r={};return r[e]=t,this._change(c,r,n)},get:function(t){var n=i._state,s=d(n);return t?s&&r.owns(n,t)?n[t]:undefined:s?e.mix({},n,!0):n},replace:function(){var e=s(arguments,0,!0);return e.unshift(h),this._change.apply(this,e)},replaceValue:function(e,t,n){var r={};return r[e]=t,this._change(h,r,n)},_change:function(t,n,r){return r=r?e.merge(f,r):f,r.merge&&d(n)&&d(i._state)&&(n=e.merge(i._state,n)),this._resolveChanges(t,n,r),this},_fireEvents:function(e,t,n){this.fire(l,{_options:n,changed:t.changed,newVal:t.newState,prevVal:t.prevState,removed:t.removed,src:e}),r.each(t.changed,function(t,n){this._fireChangeEvent(e,n,t)},this),r.each(t.removed,function(t,n){this._fireRemoveEvent(e,n,t)},this)},_fireChangeEvent:function(e,t,n){this.fire(t+"Change",{newVal:n.newVal,prevVal:n.prevVal,src:e})},_fireRemoveEvent:function(e,t,n){this.fire(t+"Remove",{prevVal:n,src:e})},_resolveChanges:function(e,t,n){var s={},o,u=i._state,a={};t||(t={}),n||(n={}),d(t)&&d(u)?(r.each(t,function(e,t){var n=u[t];e!==n&&(s[t]={newVal:e,prevVal:n},o=!0)},this),r.each(u,function(e,n){if(!r.owns(t,n)||t[n]===null)delete t[n],a[n]=e,o=!0},this)):o=t!==u,(o||this.force)&&this._fireEvents(e,{changed:s,newState:t,prevState:u,removed:a},n)},_storeState:function(e,t){i._state=t||{}},_defChangeFn:function(e){this._storeState(e.src,e.newVal,e._options)}},!0),e.HistoryBase=p},"@VERSION@",{requires:["event-custom-complex"]});