3
Copyright 2012 Yahoo! Inc. All rights reserved.
4
Licensed under the BSD License.
5
http://yuilibrary.com/license/
7
YUI.add('history-base', function(Y) {
10
* Provides browser history management functionality using a simple
11
* add/replace/get paradigm. This can be used to ensure that the browser's back
12
* and forward buttons work as the user expects and to provide bookmarkable URLs
13
* that return the user to the current application state, even in an Ajax
14
* application that doesn't perform full-page refreshes.
22
* Provides global state management backed by an object, but with no browser
23
* history integration. For actual browser history integration and back/forward
24
* support, use the history-html5 or history-hash modules.
27
* @submodule history-base
31
* @param {Object} config (optional) configuration object, which may contain
32
* zero or more of the following properties:
35
* <dt>force (Boolean)</dt>
37
* If `true`, a `history:change` event will be fired whenever the URL
38
* changes, even if there is no associated state change. Default is `false`.
41
* <dt>initialState (Object)</dt>
43
* Initial state to set, as an object hash of key/value pairs. This will be
44
* merged into the current global state.
51
GlobalEnv = YUI.namespace('Env.History'),
55
docMode = doc.documentMode,
58
DEFAULT_OPTIONS = {merge: true},
59
EVT_CHANGE = 'change',
61
SRC_REPLACE = 'replace';
63
function HistoryBase() {
64
this._init.apply(this, arguments);
67
Y.augment(HistoryBase, Y.EventTarget, null, null, {
74
if (!GlobalEnv._state) {
75
GlobalEnv._state = {};
78
// -- Private Methods ----------------------------------------------------------
81
* Returns <code>true</code> if <i>value</i> is a simple object and not a
82
* function or an array.
84
* @method _isSimpleObject
85
* @param {mixed} value
89
function _isSimpleObject(value) {
90
return Lang.type(value) === 'object';
93
// -- Public Static Properties -------------------------------------------------
96
* Name of this component.
102
HistoryBase.NAME = 'historyBase';
105
* Constant used to identify state changes originating from the
106
* <code>add()</code> method.
113
HistoryBase.SRC_ADD = SRC_ADD;
116
* Constant used to identify state changes originating from the
117
* <code>replace()</code> method.
119
* @property SRC_REPLACE
124
HistoryBase.SRC_REPLACE = SRC_REPLACE;
127
* Whether or not this browser supports the HTML5 History API.
134
// All HTML5-capable browsers except Gecko 2+ (Firefox 4+) correctly return
135
// true for 'onpopstate' in win. In order to support Gecko 2, we fall back to a
136
// UA sniff for now. (current as of Firefox 4.0b2)
137
HistoryBase.html5 = !!(win.history && win.history.pushState &&
138
win.history.replaceState && ('onpopstate' in win || Y.UA.gecko >= 2) &&
139
(!Y.UA.android || Y.UA.android >= 2.4));
142
* Whether or not this browser supports the <code>window.onhashchange</code>
143
* event natively. Note that even if this is <code>true</code>, you may
144
* still want to use HistoryHash's synthetic <code>hashchange</code> event
145
* since it normalizes implementation differences and fixes spec violations
146
* across various browsers.
148
* @property nativeHashChange
153
// Most browsers that support hashchange expose it on the window. Opera 10.6+
154
// exposes it on the document (but you can still attach to it on the window).
156
// IE8 supports the hashchange event, but only in IE8 Standards
157
// Mode. However, IE8 in IE7 compatibility mode still defines the
158
// event but never fires it, so we can't just detect the event. We also can't
159
// just UA sniff for IE8, since other browsers support this event as well.
160
HistoryBase.nativeHashChange = ('onhashchange' in win || 'onhashchange' in doc) &&
161
(!docMode || docMode > 7);
163
Y.mix(HistoryBase.prototype, {
164
// -- Initialization -------------------------------------------------------
167
* Initializes this HistoryBase instance. This method is called by the
171
* @param {Object} config configuration object
174
_init: function (config) {
178
* Configuration object provided by the user on instantiation, or an
179
* empty object if one wasn't provided.
186
config = this._config = config || {};
189
* If `true`, a `history:change` event will be fired whenever the URL
190
* changes, even if there is no associated state change.
196
this.force = !!config.force;
199
* Resolved initial state: a merge of the user-supplied initial state
200
* (if any) and any initial state provided by a subclass. This may
201
* differ from <code>_config.initialState</code>. If neither the config
202
* nor a subclass supplies an initial state, this property will be
205
* @property _initialState
210
initialState = this._initialState = this._initialState ||
211
config.initialState || null;
214
* Fired when the state changes. To be notified of all state changes
215
* regardless of the History or YUI instance that generated them,
216
* subscribe to this event on <code>Y.Global</code>. If you would rather
217
* be notified only about changes generated by this specific History
218
* instance, subscribe to this event on the instance.
220
* @event history:change
221
* @param {EventFacade} e Event facade with the following additional
225
* <dt>changed (Object)</dt>
227
* Object hash of state items that have been added or changed. The
228
* key is the item key, and the value is an object containing
229
* <code>newVal</code> and <code>prevVal</code> properties
230
* representing the values of the item both before and after the
231
* change. If the item was newly added, <code>prevVal</code> will be
232
* <code>undefined</code>.
235
* <dt>newVal (Object)</dt>
237
* Object hash of key/value pairs of all state items after the
241
* <dt>prevVal (Object)</dt>
243
* Object hash of key/value pairs of all state items before the
247
* <dt>removed (Object)</dt>
249
* Object hash of key/value pairs of state items that have been
250
* removed. Values are the old values prior to removal.
253
* <dt>src (String)</dt>
255
* The source of the event. This can be used to selectively ignore
256
* events generated by certain sources.
260
this.publish(EVT_CHANGE, {
262
defaultFn: this._defChangeFn
265
// If initialState was provided, merge it into the current state.
267
this.replace(initialState);
271
// -- Public Methods -------------------------------------------------------
274
* Adds a state entry with new values for the specified keys. By default,
275
* the new state will be merged into the existing state, and new values will
276
* override existing values. Specifying a <code>null</code> or
277
* <code>undefined</code> value will cause that key to be removed from the
281
* @param {Object} state Object hash of key/value pairs.
282
* @param {Object} options (optional) Zero or more of the following options:
284
* <dt>merge (Boolean)</dt>
287
* If <code>true</code> (the default), the new state will be merged
288
* into the existing state. New values will override existing values,
289
* and <code>null</code> or <code>undefined</code> values will be
290
* removed from the state.
294
* If <code>false</code>, the existing state will be discarded as a
295
* whole and the new state will take its place.
302
var args = YArray(arguments, 0, true);
303
args.unshift(SRC_ADD);
304
return this._change.apply(this, args);
308
* Adds a state entry with a new value for a single key. By default, the new
309
* value will be merged into the existing state values, and will override an
310
* existing value with the same key if there is one. Specifying a
311
* <code>null</code> or <code>undefined</code> value will cause the key to
312
* be removed from the new state entry.
315
* @param {String} key State parameter key.
316
* @param {String} value New value.
317
* @param {Object} options (optional) Zero or more options. See
318
* <code>add()</code> for a list of supported options.
321
addValue: function (key, value, options) {
324
return this._change(SRC_ADD, state, options);
328
* Returns the current value of the state parameter specified by <i>key</i>,
329
* or an object hash of key/value pairs for all current state parameters if
330
* no key is specified.
333
* @param {String} key (optional) State parameter key.
334
* @return {Object|String} Value of the specified state parameter, or an
335
* object hash of key/value pairs for all current state parameters.
337
get: function (key) {
338
var state = GlobalEnv._state,
339
isObject = _isSimpleObject(state);
342
return isObject && Obj.owns(state, key) ? state[key] : undefined;
344
return isObject ? Y.mix({}, state, true) : state; // mix provides a fast shallow clone.
349
* Same as <code>add()</code> except that a new browser history entry will
350
* not be created. Instead, the current history entry will be replaced with
354
* @param {Object} state Object hash of key/value pairs.
355
* @param {Object} options (optional) Zero or more options. See
356
* <code>add()</code> for a list of supported options.
359
replace: function () {
360
var args = YArray(arguments, 0, true);
361
args.unshift(SRC_REPLACE);
362
return this._change.apply(this, args);
366
* Same as <code>addValue()</code> except that a new browser history entry
367
* will not be created. Instead, the current history entry will be replaced
368
* with the new state.
370
* @method replaceValue
371
* @param {String} key State parameter key.
372
* @param {String} value New value.
373
* @param {Object} options (optional) Zero or more options. See
374
* <code>add()</code> for a list of supported options.
377
replaceValue: function (key, value, options) {
380
return this._change(SRC_REPLACE, state, options);
383
// -- Protected Methods ----------------------------------------------------
386
* Changes the state. This method provides a common implementation shared by
387
* the public methods for changing state.
390
* @param {String} src Source of the change, for inclusion in event facades
391
* to facilitate filtering.
392
* @param {Object} state Object hash of key/value pairs.
393
* @param {Object} options (optional) Zero or more options. See
394
* <code>add()</code> for a list of supported options.
398
_change: function (src, state, options) {
399
options = options ? Y.merge(DEFAULT_OPTIONS, options) : DEFAULT_OPTIONS;
401
if (options.merge && _isSimpleObject(state) &&
402
_isSimpleObject(GlobalEnv._state)) {
403
state = Y.merge(GlobalEnv._state, state);
406
this._resolveChanges(src, state, options);
411
* Called by _resolveChanges() when the state has changed. This method takes
412
* care of actually firing the necessary events.
414
* @method _fireEvents
415
* @param {String} src Source of the changes, for inclusion in event facades
416
* to facilitate filtering.
417
* @param {Object} changes Resolved changes.
418
* @param {Object} options Zero or more options. See <code>add()</code> for
419
* a list of supported options.
422
_fireEvents: function (src, changes, options) {
423
// Fire the global change event.
424
this.fire(EVT_CHANGE, {
426
changed : changes.changed,
427
newVal : changes.newState,
428
prevVal : changes.prevState,
429
removed : changes.removed,
433
// Fire change/remove events for individual items.
434
Obj.each(changes.changed, function (value, key) {
435
this._fireChangeEvent(src, key, value);
438
Obj.each(changes.removed, function (value, key) {
439
this._fireRemoveEvent(src, key, value);
444
* Fires a dynamic "[key]Change" event.
446
* @method _fireChangeEvent
447
* @param {String} src source of the change, for inclusion in event facades
448
* to facilitate filtering
449
* @param {String} key key of the item that was changed
450
* @param {Object} value object hash containing <i>newVal</i> and
451
* <i>prevVal</i> properties for the changed item
454
_fireChangeEvent: function (src, key, value) {
457
* Dynamic event fired when an individual history item is added or
458
* changed. The name of this event depends on the name of the key that
459
* changed. To listen to change events for a key named "foo", subscribe
460
* to the <code>fooChange</code> event; for a key named "bar", subscribe
461
* to <code>barChange</code>, etc.
465
* Key-specific events are only fired for instance-level changes; that
466
* is, changes that were made via the same History instance on which the
467
* event is subscribed. To be notified of changes made by other History
468
* instances, subscribe to the global <code>history:change</code> event.
472
* @param {EventFacade} e Event facade with the following additional
476
* <dt>newVal (mixed)</dt>
478
* The new value of the item after the change.
481
* <dt>prevVal (mixed)</dt>
483
* The previous value of the item before the change, or
484
* <code>undefined</code> if the item was just added and has no
488
* <dt>src (String)</dt>
490
* The source of the event. This can be used to selectively ignore
491
* events generated by certain sources.
495
this.fire(key + 'Change', {
496
newVal : value.newVal,
497
prevVal: value.prevVal,
503
* Fires a dynamic "[key]Remove" event.
505
* @method _fireRemoveEvent
506
* @param {String} src source of the change, for inclusion in event facades
507
* to facilitate filtering
508
* @param {String} key key of the item that was removed
509
* @param {mixed} value value of the item prior to its removal
512
_fireRemoveEvent: function (src, key, value) {
515
* Dynamic event fired when an individual history item is removed. The
516
* name of this event depends on the name of the key that was removed.
517
* To listen to remove events for a key named "foo", subscribe to the
518
* <code>fooRemove</code> event; for a key named "bar", subscribe to
519
* <code>barRemove</code>, etc.
523
* Key-specific events are only fired for instance-level changes; that
524
* is, changes that were made via the same History instance on which the
525
* event is subscribed. To be notified of changes made by other History
526
* instances, subscribe to the global <code>history:change</code> event.
530
* @param {EventFacade} e Event facade with the following additional
534
* <dt>prevVal (mixed)</dt>
536
* The value of the item before it was removed.
539
* <dt>src (String)</dt>
541
* The source of the event. This can be used to selectively ignore
542
* events generated by certain sources.
546
this.fire(key + 'Remove', {
553
* Resolves the changes (if any) between <i>newState</i> and the current
554
* state and fires appropriate events if things have changed.
556
* @method _resolveChanges
557
* @param {String} src source of the changes, for inclusion in event facades
558
* to facilitate filtering
559
* @param {Object} newState object hash of key/value pairs representing the
561
* @param {Object} options Zero or more options. See <code>add()</code> for
562
* a list of supported options.
565
_resolveChanges: function (src, newState, options) {
568
prevState = GlobalEnv._state,
571
newState || (newState = {});
572
options || (options = {});
574
if (_isSimpleObject(newState) && _isSimpleObject(prevState)) {
575
// Figure out what was added or changed.
576
Obj.each(newState, function (newVal, key) {
577
var prevVal = prevState[key];
579
if (newVal !== prevVal) {
589
// Figure out what was removed.
590
Obj.each(prevState, function (prevVal, key) {
591
if (!Obj.owns(newState, key) || newState[key] === null) {
592
delete newState[key];
593
removed[key] = prevVal;
598
isChanged = newState !== prevState;
601
if (isChanged || this.force) {
602
this._fireEvents(src, {
605
prevState: prevState,
612
* Stores the specified state. Don't call this method directly; go through
613
* _resolveChanges() to ensure that changes are resolved and all events are
616
* @method _storeState
617
* @param {String} src source of the changes
618
* @param {Object} newState new state to store
619
* @param {Object} options Zero or more options. See <code>add()</code> for
620
* a list of supported options.
623
_storeState: function (src, newState) {
624
// Note: the src and options params aren't used here, but they are used
626
GlobalEnv._state = newState || {};
629
// -- Protected Event Handlers ---------------------------------------------
632
* Default <code>history:change</code> event handler.
634
* @method _defChangeFn
635
* @param {EventFacade} e state change event facade
638
_defChangeFn: function (e) {
639
this._storeState(e.src, e.newVal, e._options);
643
Y.HistoryBase = HistoryBase;
646
}, '3.5.1' ,{requires:['event-custom-complex']});