| /** |
| * |
| * jsGET |
| * |
| * jsGET is a http GET-Variables clone for javascript, using the hash part of the URL (index.html#...). |
| * You can set and get variables, and run a listener to hash changes, e.g. when the the history back button gets pressed. |
| * This allows you to create a usable history navigation in your ajax application. It should work with all A-grade browsers. |
| * |
| * @author Fabian Vogelsteller <fabian@feindura.org> |
| * @copyright Fabian Vogelsteller |
| * @license http://www.gnu.org/licenses GNU General Public License version 3 |
| * |
| * @version 0.2 |
| * |
| * ### Properties |
| * - vars: (object) the hash variables object loaded by get(), set(), remove(), or clear() or load() plus various indicators and trackers: |
| * - vars.current: (object) the current variables. |
| * - vars.old: (object) the old variables, before they where changed with set(), remove(), clear() or the browser history back button. *WARNING*: this is one is only valid while the listener is invoked. |
| * - vars.changed: (object) the variables which have changed since the last call of get(), set(), remove(), clear(), load() or the browser history back button. *WARNING*: this is one is updated by setChangedVars() depending on 'vars.old' and usually is only valid while the listener is invoked. |
| * - vars.change_count: (integer) a number of variables changed/added/removed since the last time the listener was invoked. *WARNING*: this is one is updated by setChangedVars() depending on 'vars.old' and usually is only valid while the listener is invoked. |
| * - vars.last_hash_loaded: (string, internal use only) the raw hash string which was just processed; in the listener, this equals the current hash. |
| * - vars.last_hash_saved: (string, internal use only) the hash section string which was the last one generated by set(), clear() or remove(). |
| * - vars.foreign_hash_change: (boolean) TRUE when the hash was changed from outside our control, e.g. when the user hit the 'back/history' button in the browser, after the previous invocation of the listener. |
| * - vars.hash_changed: (boolean) TRUE when the hash has changed after the previous invocation of the listener. |
| * |
| * ### Methods |
| * - load(): loads the current hash variables into the vars.current property as JSON object. Return the updated set of key/value pairs. |
| * - clear(): clears the hash part of the URL. (because it's not completely possible, it sets it to "#_") |
| * - get(get): (string) try to get a hash variable with the given name. |
| * - set(set): (string,object) sets the given parameters to the hash variables. If it's a string it should have the following format: "key=value". Return the updated set of key/value pairs. |
| * - remove(remove): (string,array) the variable name(s) which should be removed from the hash variables. Return the old set of key/value pairs. |
| * - addListener(listener,callAlways,bind): (listener: function, callAlways: boolean, bind: object instance) creates a listener which calls the given function when a hash change occurs. The called function will get the vars property (vars.current,vars.old,vars.changed) and use the "bind" parameter as "this", when specified. |
| * The return of the addListener() method is a setInterval ID and must be passed to the removeListener() method to stop the listening. |
| * When callAlways is FALSE, it only calls when the browser history buttons are pressed and not when get(), set(), remove() or clear() is called. |
| * - removeListener(listenerID): (the setInterval Id received from a addListener() method) removes a listener set with the addListener() method. |
| * - setChangedVars(): (internal use) updates the vars.changed collection and vars.change_count value. |
| * |
| * ### ATTENTION! |
| * Everytime you call set(), remove() or clear() a new hash string will be set, |
| * that means you also create a new history step in the browser history! |
| * |
| * These are 'special' characters to jsGET and will therefor be encoded when they are part of a key or value: |
| * # & = |
| */ |
| |
| var jsGET = { |
| vars: { |
| old: {}, |
| current: {}, |
| changed: {}, |
| change_count: 0, |
| last_hash_loaded: '', |
| last_hash_saved: window.location.hash, |
| foreign_hash_change: false, |
| hash_changed: false |
| }, |
| load: function() { |
| // only load hash variables when anything changed in the hash since last time we loaded them: |
| var i; |
| var new_hash = window.location.hash; |
| |
| if (this.vars.last_hash_loaded !== new_hash) { |
| // detect whether the hash was changed outside our control, e.g. when user pushed BACK/HISTORY button in browser: |
| if (new_hash !== this.vars.last_hash_saved) { |
| this.vars.foreign_hash_change = true; |
| } |
| this.vars.hash_changed = true; |
| |
| var hashVars = new_hash.split('#'); |
| this.vars.current = {}; |
| if (typeof hashVars[1] !== 'undefined' && hashVars[1] && hashVars[1] !== '_') { |
| hashVars = hashVars[1].split('&'); |
| for(i = 0; i < hashVars.length; i++) { |
| var hashVar = hashVars[i].split('='); |
| this.vars.current[this.decode(hashVar[0])] = (typeof hashVar[1] !== 'undefined' ? this.decode(hashVar[1]) : ''); |
| } |
| } |
| this.vars.last_hash_loaded = new_hash; |
| } |
| return this.vars.current; |
| }, |
| // encode special characters in the input string; use encodeURIComponent() to encode as that one is fast and ensures proper Unicode handling as well: bonus! |
| encode: function(s) { |
| s = encodeURIComponent(s); |
| // BUT! browsers take things like '%26' in the URL anywhere and translate it to '&' before we get our hands on the fragment part, so we need to prevent the browsers from doing this: |
| s = s.replace(/%/g, '$'); // we can do this safely as encodeURIComponent() will have encoded any '$' in the original string! |
| return s; |
| }, |
| decode: function(s) { |
| s = s.replace(/\$/g, '%'); |
| s = decodeURIComponent(s); |
| return s; |
| }, |
| clear: function() { |
| this.vars.last_hash_saved = window.location.hash = "#_"; |
| //window.location.href = window.location.href.replace( /#.*$/, ""); |
| return false; |
| }, |
| get: function(key) { |
| this.load(); |
| return (this.vars.current.hasOwnProperty(key) ? this.vars.current[key] : null); |
| }, |
| set: function(set) { |
| var key; |
| |
| //if (typeof console !== 'undefined' && console.log) console.log('savedHistory'); |
| this.load(); |
| |
| if (typeof set !== 'object') { |
| var setSplit = set.split('='); |
| set = {}; |
| // be aware that the _value_ of the key, value pair can have an embedded '=' (or more) itself: |
| key = setSplit.shift(); |
| var value = setSplit.join('='); |
| set[key] = value; |
| } |
| else { |
| // do not damage the set passed in as a parameter |
| set = this.helpers.cloneObject(set); |
| } |
| |
| // var |
| var hashString = ''; |
| var sep = '#'; |
| |
| // check for change in existing vars |
| for(key in this.vars.current) { |
| if (this.vars.current.hasOwnProperty(key)) { |
| if (set.hasOwnProperty(key)) { |
| hashString += sep+this.encode(key)+'='+this.encode(set[key]); |
| delete set[key]; |
| } |
| else { |
| hashString += sep+this.encode(key)+'='+this.encode(this.vars.current[key]); |
| } |
| sep = '&'; |
| } |
| } |
| |
| // add new vars |
| for(key in set) { |
| if (set.hasOwnProperty(key)) { |
| hashString += sep+this.encode(key)+'='+this.encode(set[key]); |
| sep = '&'; |
| } |
| } |
| this.vars.last_hash_saved = window.location.hash = hashString; |
| return this.load(); |
| }, |
| remove: function(remove) { |
| var removes; |
| var i; |
| var key; |
| |
| this.load(); |
| |
| if (typeof remove !== 'object') { |
| removes = [remove]; |
| } else { |
| removes = remove; |
| } |
| |
| // var |
| var hashString = ''; |
| var sep = '#'; |
| |
| for (i = 0; i < removes.length; i++) { |
| if (this.vars.current.hasOwnProperty(removes[i])) { |
| delete this.vars.current[removes[i]]; |
| } |
| } |
| |
| // create new hash string |
| for(key in this.vars.current) { |
| if (this.vars.current.hasOwnProperty(key)) { |
| hashString += sep+this.encode(key)+'='+this.encode(this.vars.current[key]); |
| sep = '&'; |
| } |
| } |
| this.vars.last_hash_saved = window.location.hash = hashString; |
| |
| this.load(); |
| // a bit odd: this one returns the OLD set, while set() returns the UPDATED set... |
| return this.vars.current; |
| }, |
| setChangedVars: function() { |
| var change_count; |
| var key; |
| var oldVars = this.helpers.cloneObject(this.vars.old); |
| this.vars.changed = this.helpers.cloneObject(this.vars.current); |
| |
| // check for changed vars |
| change_count = 0; |
| for (key in this.vars.changed) { |
| if (this.vars.changed.hasOwnProperty(key)) { |
| if (oldVars.hasOwnProperty(key)) { |
| if (oldVars[key] === this.vars.changed[key]) { |
| change_count--; // faster?/simpler than multiple 'else' branches just to track change_count |
| delete this.vars.changed[key]; |
| } |
| delete oldVars[key]; |
| } |
| change_count++; |
| } |
| } |
| // merge the rest of this.vars.old with the changedVars |
| for (key in oldVars) { |
| if (oldVars.hasOwnProperty(key) /* && !this.vars.changed.hasOwnProperty(key) */ ) { |
| this.vars.changed[key] = oldVars[key]; |
| change_count++; |
| } |
| } |
| this.vars.change_count = change_count; |
| }, |
| addListener: function(listener, callAlways, bind, freq) { // use the returned interval ID for removeListener |
| |
| this.load(); |
| this.vars.hash_changed = false; |
| this.vars.foreign_hash_change = false; |
| this.vars.old = this.helpers.cloneObject(this.vars.current); |
| |
| this.pollHash = function() { |
| var key; |
| |
| this.load(); // side effect: an immediate check (one more) to see whether the hash has changed by us or others |
| |
| // and make sure listener always fires whn callAlways==FALSE and user is going back&forth in the browser history (one or more history entries may match this.vars.last_hash_saved !) |
| this.vars.last_hash_saved = window.location.hash; |
| |
| if (this.vars.hash_changed) { |
| this.setChangedVars(); |
| if (callAlways || this.vars.foreign_hash_change) { |
| // var |
| /* |
| if (typeof console !== 'undefined' && console.log) console.log('-----'); |
| if (typeof console !== 'undefined' && console.log) console.log(this.vars.old); |
| if (typeof console !== 'undefined' && console.log) console.log(this.vars.changed); |
| */ |
| // call the given listener function |
| if (typeof listener === 'function') { |
| listener.apply(bind, [this.vars]); |
| } |
| |
| // only reset the 'old' array, i.e. effect the '.changed' set, when the listener was actually (to be) invoked. |
| // |
| // also reset the 'changed' markers so changes applied inside the listener don't 'recursively' trigger the listener: |
| this.load(); |
| this.vars.hash_changed = false; |
| this.vars.foreign_hash_change = false; |
| |
| /* |
| if (typeof console !== 'undefined' && console.log) console.log('-----'); |
| if (typeof console !== 'undefined' && console.log) console.log(this.vars.current); |
| if (typeof console !== 'undefined' && console.log) console.log(this.vars.old); |
| if (typeof console !== 'undefined' && console.log) console.log(this.vars.changed); |
| */ |
| this.vars.old = new this.vars.current.constructor(); |
| for (key in this.vars.current) { |
| if (this.vars.current.hasOwnProperty(key)) { |
| this.vars.old[key] = this.vars.current[key]; |
| } |
| } |
| } |
| } |
| }; |
| |
| var self = this; |
| return setInterval(function() { |
| self.pollHash(); |
| }, (freq || 500)); |
| }, |
| removeListener: function(listenerID) { // use the interval ID returned by addListener |
| delete this.pollHash; |
| return clearInterval(listenerID); |
| }, |
| helpers: |
| { |
| // eqv. of mootools Object.clone(): |
| cloneObject: function(obj) { |
| var key; |
| var rv = new obj.constructor(); |
| for (key in obj) { |
| if (obj.hasOwnProperty(key)) { |
| rv[key] = obj[key]; |
| } |
| } |
| return rv; |
| } |
| } |
| }; |
| |
| |
| /* settings for jsLint: undef: true, browser: true, indent: 4 */ |
| |
