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