2
Copyright (c) 2010, Yahoo! Inc. All rights reserved.
3
Code licensed under the BSD License:
4
http://developer.yahoo.com/yui/license.html
8
YUI.add('history-deprecated', function(Y) {
13
* <strong>Deprecated since 3.2.0.</strong> The Browser History Utility provides
14
* the ability to use the back/forward navigation buttons in a DHTML
15
* application. It also allows a DHTML application to be bookmarked in a
18
* This utility requires the following static markup:
20
* <iframe id="yui-history-iframe" src="path-to-real-asset-in-same-domain"></iframe>
21
* <input id="yui-history-field" type="hidden">
23
* @module history-deprecated
24
* @deprecated Please use the new "history" module instead.
28
* This class represents an instance of the browser history utility.
31
* @deprecated Please use the new "history" module instead.
35
var win = Y.config.win,
38
encode = encodeURIComponent,
39
decode = decodeURIComponent,
43
// YUI Compressor helper...
44
E_MISSING_OR_INVALID_ARG = 'Missing or invalid argument',
46
// Regular expression used to parse query strings and such.
47
REGEXP = /([^=&]+)=([^&]*)/g,
49
// A few private variables...
54
* @event history:ready
55
* @description Fires when the browser history utility is ready
58
EV_HISTORY_READY = 'history:ready',
61
* @event history:globalStateChange
62
* @description Fires when the global state of the page has changed (that is,
63
* when the state of at least one browser history module has changed)
66
EV_HISTORY_GLOBAL_STATE_CHANGE = 'history:globalStateChange',
69
* @event history:moduleStateChange
70
* @description Fires when the state of a history module object has changed
73
EV_HISTORY_MODULE_STATE_CHANGE = 'history:moduleStateChange';
76
G = YUI.Env.history || {
78
// Flag used to tell whether the history utility is ready to be used.
81
// List of registered modules.
84
// INPUT field (with type="hidden" or type="text") or TEXTAREA.
85
// This field keeps the value of the initial state, current state
86
// the list of all states across pages within a single browser session.
89
// Hidden IFrame used to store the browsing history on IE6/7.
96
* Returns the portion of the hash after the '#' symbol.
98
* @return {string} The hash portion of the document's location
102
// We branch at runtime for Gecko since window.location.hash in Gecko
103
// returns a decoded string, and we want all encoding untouched.
104
_getHash = function () {
105
var m = /#(.*)$/.exec(win.location.href);
106
return m && m[1] ? m[1] : '';
109
_getHash = function () {
110
return win.location.hash.substr(1);
115
* Stores the initial state and current state for all registered modules
116
* in the (hidden) form field specified during initialization.
117
* @method _storeStates
120
function _storeStates() {
121
var initialStates = [], currentStates = [];
123
Y.Object.each(G._modules, function (module, moduleId) {
124
initialStates.push(moduleId + '=' + module.initialState);
125
currentStates.push(moduleId + '=' + module.currentState);
128
G._stateField.set('value', initialStates.join('&') + '|' + currentStates.join('&'));
132
* Sets the new currentState attribute of all modules depending on the new fully
133
* qualified state. Also notifies the modules which current state has changed.
134
* @method _handleFQStateChange
135
* @param {string} fqstate fully qualified state
138
function _handleFQStateChange(fqstate) {
139
var m, states = [], globalStateChanged = false;
143
REGEXP.lastIndex = 0;
144
while ((m = REGEXP.exec(fqstate))) {
148
Y.Object.each(G._modules, function (module, moduleId) {
149
var currentState = states[moduleId];
151
if (!currentState || module.currentState !== currentState) {
152
module.currentState = currentState || module.initialState;
153
module.fire(EV_HISTORY_MODULE_STATE_CHANGE, decode(module.currentState));
154
globalStateChanged = true;
160
Y.Object.each(G._modules, function (module, moduleId) {
161
if (module.currentState !== module.initialState) {
162
module.currentState = module.initialState;
163
module.fire(EV_HISTORY_MODULE_STATE_CHANGE, decode(module.currentState));
164
globalStateChanged = true;
169
if (globalStateChanged) {
170
H.fire(EV_HISTORY_GLOBAL_STATE_CHANGE);
175
* Update the IFrame with our new state.
176
* @method _updateIFrame
178
* @return {boolean} true if successful. false otherwise.
180
function _updateIFrame(fqstate) {
183
html = '<html><body>' +
184
fqstate.replace(/&/g,'&').
185
replace(/</g,'<').
186
replace(/>/g,'>').
187
replace(/"/g,'"') +
191
doc = G._historyIFrame.get('contentWindow.document');
192
// TODO: The Node API should expose these methods in the very near future...
194
doc.invoke('write', html, '', '', '', ''); // see bug #2447937
203
* Periodically checks whether our internal IFrame is ready to be used
204
* @method _checkIframeLoaded
207
function _checkIframeLoaded() {
208
var elem, fqstate, hash;
210
if (!G._historyIFrame.get('contentWindow.document')) {
211
// Check again in 10 msec...
212
setTimeout(_checkIframeLoaded, 10);
216
// Periodically check whether a navigate operation has been
217
// requested on the main window. This will happen when
218
// History.navigate has been called or after the user
219
// has hit the back/forward button.
220
elem = G._historyIFrame.get('contentWindow.document.body');
221
// We must use innerText, and not innerHTML because our string contains
222
// the "&" character (which would end up being escaped as "&") and
223
// the string comparison would fail...
224
fqstate = elem ? elem.get('innerText') : null;
228
setInterval(function () {
229
var newfqstate, states, newHash;
231
elem = G._historyIFrame.get('contentWindow.document.body');
232
// See my comment above about using innerText instead of innerHTML...
233
newfqstate = elem ? elem.get('innerText') : null;
235
newHash = _getHash();
237
if (newfqstate !== fqstate) {
239
fqstate = newfqstate;
240
_handleFQStateChange(fqstate);
244
Y.Object.each(G._modules, function (module, moduleId) {
245
states.push(moduleId + '=' + module.initialState);
247
newHash = states.join('&');
252
// Allow the state to be bookmarked by setting the top window's
253
// URL fragment identifier. Note that here, we are on IE < 8
254
// which does not touch the browser history when changing the
255
// hash (unlike all the other browsers).
256
win.location.hash = hash = newHash;
260
} else if (newHash !== hash) {
262
// The hash has changed. The user might have clicked on a link,
263
// or modified the URL directly, or opened the same application
264
// bookmarked in a specific state using a bookmark. However, we
265
// know the hash change was not caused by a hit on the back or
266
// forward buttons, or by a call to navigate() (because it would
267
// have been handled above) We must handle these cases, which is
268
// why we also need to keep track of hash changes on IE!
270
// Note that IE6 has some major issues with this kind of user
271
// interaction (the history stack gets completely messed up)
272
// but it seems to work fine on IE7.
276
// Now, store a new history entry. The following will cause the
277
// code above to execute, doing all the dirty work for us...
278
_updateIFrame(newHash);
284
H.fire(EV_HISTORY_READY);
288
* Finish up the initialization of the browser utility library.
289
* @method _initialize
292
function _initialize() {
293
var m, parts, moduleId, module, initialState, currentState, hash;
295
// Decode the content of our storage field...
296
parts = G._stateField.get('value').split('|');
298
if (parts.length > 1) {
300
REGEXP.lastIndex = 0;
301
while ((m = REGEXP.exec(parts[0]))) {
304
module = G._modules[moduleId];
306
module.initialState = initialState;
310
REGEXP.lastIndex = 0;
311
while ((m = REGEXP.exec(parts[1]))) {
314
module = G._modules[moduleId];
316
module.currentState = currentState;
321
// IE8 in IE7 mode defines window.onhashchange, but never fires it...
322
if (!Y.Lang.isUndefined(win.onhashchange) &&
323
(Y.Lang.isUndefined(doc.documentMode) || doc.documentMode > 7)) {
325
// The HTML5 way of handling DHTML history...
326
// @TODO This is case-insensitive, at least in IE (WHY? spec, please actually specify things)
328
win.onhashchange = function () {
329
var hash = _getHash();
330
_handleFQStateChange(hash);
335
H.fire(EV_HISTORY_READY);
337
} else if (_useIFrame) {
339
// IE < 8 or IE8 in quirks mode or IE7 standards mode
340
_checkIframeLoaded();
344
// Periodically check whether a navigate operation has been
345
// requested on the main window. This will happen when
346
// History.navigate has been called, or after the user
347
// has hit the back/forward button.
349
// On Gecko and Opera, we just need to watch the hash...
352
setInterval(function () {
353
var newHash = _getHash();
354
if (newHash !== hash) {
356
_handleFQStateChange(hash);
362
H.fire(EV_HISTORY_READY);
367
H = Y.mix(new Y.EventTarget(), {
370
* Registers a new module.
372
* @param {string} moduleId Non-empty string uniquely identifying the
373
* module you wish to register.
374
* @param {string} initialState The initial state of the specified
375
* module corresponding to its earliest history entry.
376
* @return {History.Module} The newly registered module
378
register: function (moduleId, initialState) {
381
if (!Y.Lang.isString(moduleId) || Y.Lang.trim(moduleId) === '' || !Y.Lang.isString(initialState)) {
382
throw new Error(E_MISSING_OR_INVALID_ARG);
385
moduleId = encode(moduleId);
386
initialState = encode(initialState);
388
if (G._modules[moduleId]) {
389
// The module seems to have already been registered.
393
// Note: A module CANNOT be registered once the browser history
394
// utility has been initialized. This is related to reading and
395
// writing state values from/to the input field. Relaxing this
396
// rule would potentially create situations rather complicated
402
module = new H.Module(moduleId, initialState);
403
G._modules[moduleId] = module;
408
* Initializes the Browser History Manager. Call this method
409
* from a script block located right after the opening body tag.
411
* @param {string|HTML Element} stateField <input type="hidden"> used
412
* to store application states. Must be in the static markup.
413
* @param {string|HTML Element} historyIFrame IFrame used to store
414
* the history (only required for IE6/7)
417
initialize: function (stateField, historyIFrame) {
421
// The browser history utility has already been initialized.
425
stateField = Y.one(stateField);
427
throw new Error(E_MISSING_OR_INVALID_ARG);
430
tagName = stateField.get('tagName').toUpperCase();
431
type = stateField.get('type');
433
if (tagName !== 'TEXTAREA' && (tagName !== 'INPUT' || type !== 'hidden' && type !== 'text')) {
434
throw new Error(E_MISSING_OR_INVALID_ARG);
437
// IE < 8 or IE8 in quirks mode or IE7 standards mode
438
if (Y.UA.ie && (Y.Lang.isUndefined(doc.documentMode) || doc.documentMode < 8)) {
440
historyIFrame = Y.one(historyIFrame);
441
if (!historyIFrame || historyIFrame.get('tagName').toUpperCase() !== 'IFRAME') {
442
throw new Error(E_MISSING_OR_INVALID_ARG);
446
if (Y.UA.opera && !Y.Lang.isUndefined(win.history.navigationMode)) {
447
// Disable Opera's fast back/forward navigation mode and put
448
// it in compatible mode. This makes anchor-based history
449
// navigation work after the page has been navigated away
450
// from and re-activated, at the cost of slowing down
451
// back/forward navigation to and from that page.
452
win.history.navigationMode = 'compatible';
455
G._stateField = stateField;
456
G._historyIFrame = historyIFrame;
458
Y.on('domready', _initialize);
463
* Stores a new entry in the browser history by changing the state of a registered module.
465
* @param {string} module Non-empty string representing your module.
466
* @param {string} state String representing the new state of the specified module.
467
* @return {boolean} Indicates whether the new state was successfully added to the history.
470
navigate: function (moduleId, state) {
473
if (!Y.Lang.isString(moduleId) || !Y.Lang.isString(state)) {
474
throw new Error(E_MISSING_OR_INVALID_ARG);
477
// The ncoding of module id and state takes place in mutiNavigate.
479
states[moduleId] = state;
481
return H.multiNavigate(states);
485
* Stores a new entry in the browser history by changing the state
486
* of several registered modules in one atomic operation.
487
* @method multiNavigate
488
* @param {object} states Associative array of module-state pairs to set simultaneously.
489
* @return {boolean} Indicates whether the new state was successfully added to the history.
492
multiNavigate: function (states) {
493
var newStates = [], fqstate, globalStateChanged = false;
499
Y.Object.each(G._modules, function (module, moduleId) {
500
var state, decodedModuleId = decode(moduleId);
502
if (!states.hasOwnProperty(decodedModuleId)) {
503
// The caller did not wish to modify the state of this
504
// module. We must however include it in fqstate!
505
state = module.currentState;
507
state = encode(states[decodedModuleId]);
508
if (state !== module.upcomingState) {
509
module.upcomingState = state;
510
globalStateChanged = true;
514
newStates.push(moduleId + '=' + state);
517
if (!globalStateChanged) {
518
// Nothing changed, so don't do anything.
522
fqstate = newStates.join('&');
525
return _updateIFrame(fqstate);
527
win.location.hash = fqstate;
533
* Returns the current state of the specified module.
534
* @method getCurrentState
535
* @param {string} moduleId Non-empty string representing your module.
536
* @return {string} The current state of the specified module.
539
getCurrentState: function (moduleId) {
542
if (!Y.Lang.isString(moduleId)) {
543
throw new Error(E_MISSING_OR_INVALID_ARG);
550
moduleId = encode(moduleId);
551
module = G._modules[moduleId];
556
return decode(module.currentState);
560
* Returns the state of a module according to the URL fragment
561
* identifier. This method is useful to initialize your modules
562
* if your application was bookmarked from a particular state.
563
* @method getBookmarkedState
564
* @param {string} moduleId Non-empty string representing your module.
565
* @return {string} The bookmarked state of the specified module.
568
getBookmarkedState: function (moduleId) {
571
if (!Y.Lang.isString(moduleId)) {
572
throw new Error(E_MISSING_OR_INVALID_ARG);
575
moduleId = encode(moduleId);
577
// Use location.href instead of location.hash which is already
578
// URL-decoded, which creates problems if the state value
579
// contained special characters...
580
h = win.location.href;
585
REGEXP.lastIndex = 0;
586
while ((m = REGEXP.exec(h))) {
587
if (m[1] === moduleId) {
597
* Returns the value of the specified query string parameter.
598
* This method is not used internally by the Browser History Manager.
599
* However, it is provided here as a helper since many applications
600
* using the Browser History Manager will want to read the value of
601
* url parameters to initialize themselves.
602
* @method getQueryStringParameter
603
* @param {string} paramName Name of the parameter we want to look up.
604
* @param {string} queryString Optional URL to look at. If not specified,
605
* this method uses the URL in the address bar.
606
* @return {string} The value of the specified parameter, or null.
608
* @deprecated Use Y.QueryString.parse() in the querystring module.
609
* This will be removed in 3.2.0.
611
getQueryStringParameter: function (paramName, url) {
614
url = url || win.location.href;
616
i = url.indexOf('?');
617
q = i >= 0 ? url.substr(i + 1) : url;
619
// Remove the hash if any
620
i = q.lastIndexOf('#');
621
q = i >= 0 ? q.substr(0, i) : q;
623
REGEXP.lastIndex = 0;
624
while ((m = REGEXP.exec(q))) {
625
if (m[1] === paramName) {
635
* This class represents a browser history module.
636
* @class History.Module
638
* @param id {String} the module identifier
639
* @param initialState {String} the module's initial state
640
* @deprecated Please use the new "history" module instead.
642
H.Module = function (id, initialState) {
645
* The module identifier
652
* The module's initial state
656
this.initialState = initialState;
659
* The module's current state
663
this.currentState = initialState;
666
* The module's upcoming state. There can be a slight delay between the
667
* time a state is changed, and the time a state change is detected.
668
* This property allows us to not fire the module state changed event
669
* multiple times, making client code simpler.
674
this.upcomingState = initialState;
677
Y.augment(H.Module, Y.EventTarget);
682
}, '3.2.0' ,{skinnable:false, requires:['node-base']});