true if value 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
* add() method.
*
* @property SRC_ADD
* @type String
* @static
* @final
*/
HistoryBase.SRC_ADD = SRC_ADD;
/**
* Constant used to identify state changes originating from the
* replace() 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 window.onhashchange
* event natively. Note that even if this is true, you may
* still want to use HistoryHash's synthetic hashchange 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 _config.initialState. If neither the config
* nor a subclass supplies an initial state, this property will be
* null.
*
* @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 Y.Global. 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:
*
* newVal and prevVal properties
* representing the values of the item both before and after the
* change. If the item was newly added, prevVal will be
* undefined.
* null or
* undefined 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:
*
* If true (the default), the new state will be merged
* into the existing state. New values will override existing values,
* and null or undefined values will be
* removed from the state.
*
* If false, the existing state will be discarded as a
* whole and the new state will take its place.
*
null or undefined 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
* add() 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 key,
* 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 add() 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
* add() 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 addValue() 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
* add() 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
* add() 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 add() 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 newVal and
* prevVal properties for the changed item
* @protected
*/
_fireChangeEvent: function (src, key, value) {
/**
*
* 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 fooChange event; for a key named "bar", subscribe
* to barChange, etc.
*
* 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 history:change event.
*
undefined if the item was just added and has no
* previous value.
*
* 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
* fooRemove event; for a key named "bar", subscribe to
* barRemove, etc.
*
* 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 history:change event.
*
add() 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 add() 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 history:change 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;
}, '3.17.2', {"requires": ["event-custom-complex"]});