js/microhistory.js

   1 /**
   2  * An implementation of a client-side page cache.
   3  * This object also uses the cache to provide a simple microhistory,
   4  * that is the ability to use the back and forward buttons in the browser
   5  */
   6 var MicroHistory = {
   7     /**
   8      * @var int The maximum number of pages to keep in the cache
   9      */
  10     MAX: 6,
  11     /**
  12      * @var object A hash used to prime the cache with data about the initially
  13      *             loaded page. This is set in the footer, and then loaded
  14      *             by a double-queued event further down this file.
  15      */
  16     primer: {},
  17     /**
  18      * @var array Stores the content of the cached pages
  19      */
  20     pages: [],
  21     /**
  22      * @var int The index of the currently loaded page
  23      *          This is used to know at which point in the history we are
  24      */
  25     current: 0,
  26     /**
  27      * Saves a new page in the cache
  28      *
  29      * @param string hash    The hash part of the url that is being loaded
  30      * @param array  scripts A list of scripts that is required for the page
  31      * @param string menu    A hash that links to a menu stored
  32      *                       in a dedicated menu cache
  33      * @param array  params  A list of parameters used by CommonParams()
  34      * @param string rel     A relationship to the current page:
  35      *                       'samepage': Forces the response to be treated as
  36      *                                   the same page as the current one
  37      *                       'newpage':  Forces the response to be treated as
  38      *                                   a new page
  39      *                       undefined:  Default behaviour, 'samepage' if the
  40      *                                   selflinks of the two pages are the same.
  41      *                                   'newpage' otherwise
  42      *
  43      * @return void
  44      */
  45     add: function (hash, scripts, menu, params, rel) {
  46         if (this.pages.length > MicroHistory.MAX) {
  47             // Trim the cache, to the maximum number of allowed entries
  48             // This way we will have a cached menu for every page
  49             for (var i = 0; i < this.pages.length - this.MAX; i++) {
  50                 delete this.pages[i];
  51             }
  52         }
  53         while (this.current < this.pages.length) {
  54             // trim the cache if we went back in the history
  55             // and are now going forward again
  56             this.pages.pop();
  57         }
  58         if (rel === 'newpage' ||
  59             (
  60                 typeof rel === 'undefined' && (
  61                     typeof this.pages[this.current - 1] === 'undefined' ||
  62                     this.pages[this.current - 1].hash !== hash
  63                 )
  64             )
  65         ) {
  66             this.pages.push({
  67                 hash: hash,
  68                 content: $('#page_content').html(),
  69                 scripts: scripts,
  70                 selflink: $('#selflink').html(),
  71                 menu: menu,
  72                 params: params
  73             });
  74             MicroHistory.setUrlHash(this.current, hash);
  75             this.current++;
  76         }
  77     },
  78     /**
  79      * Restores a page from the cache. This is called when the hash
  80      * part of the url changes and it's structure appears to be valid
  81      *
  82      * @param string index Which page from the history to load
  83      *
  84      * @return void
  85      */
  86     navigate: function (index) {
  87         var localIndex = index;
  88         if (typeof this.pages[localIndex] === 'undefined' ||
  89             typeof this.pages[localIndex].content === 'undefined' ||
  90             typeof this.pages[localIndex].menu === 'undefined' ||
  91             ! MicroHistory.menus.get(this.pages[localIndex].menu)
  92         ) {
  93             Functions.ajaxShowMessage(
  94                 '<div class="alert alert-danger" role="alert">' + Messages.strInvalidPage + '</div>',
  95                 false
  96             );
  97         } else {
  98             AJAX.active = true;
  99             var record = this.pages[localIndex];
 100             AJAX.scriptHandler.reset(function () {
 101                 $('#page_content').html(record.content);
 102                 $('#selflink').html(record.selflink);
 103                 MicroHistory.menus.replace(MicroHistory.menus.get(record.menu));
 104                 CommonParams.setAll(record.params);
 105                 AJAX.scriptHandler.load(record.scripts);
 106                 MicroHistory.current = ++localIndex;
 107             });
 108         }
 109     },
 110     /**
 111      * Resaves the content of the current page in the cache.
 112      * Necessary in order not to show the user some outdated version of the page
 113      *
 114      * @return void
 115      */
 116     update: function () {
 117         var page = this.pages[this.current - 1];
 118         if (page) {
 119             page.content = $('#page_content').html();
 120         }
 121     },
 122     /**
 123      * @var object Dedicated menu cache
 124      */
 125     menus: {
 126         /**
 127          * Returns the number of items in an associative array
 128          *
 129          * @return int
 130          */
 131         size: function (obj) {
 132             var size = 0;
 133             var key;
 134             for (key in obj) {
 135                 if (obj.hasOwnProperty(key)) {
 136                     size++;
 137                 }
 138             }
 139             return size;
 140         },
 141         /**
 142          * @var hash Stores the content of the cached menus
 143          */
 144         data: {},
 145         /**
 146          * Saves a new menu in the cache
 147          *
 148          * @param string hash    The hash (trimmed md5) of the menu to be saved
 149          * @param string content The HTML code of the menu to be saved
 150          *
 151          * @return void
 152          */
 153         add: function (hash, content) {
 154             if (this.size(this.data) > MicroHistory.MAX) {
 155                 // when the cache grows, we remove the oldest entry
 156                 var oldest;
 157                 var key;
 158                 var init = 0;
 159                 for (var i in this.data) {
 160                     if (this.data[i]) {
 161                         if (! init || this.data[i].timestamp.getTime() < oldest.getTime()) {
 162                             oldest = this.data[i].timestamp;
 163                             key = i;
 164                             init = 1;
 165                         }
 166                     }
 167                 }
 168                 delete this.data[key];
 169             }
 170             this.data[hash] = {
 171                 content: content,
 172                 timestamp: new Date()
 173             };
 174         },
 175         /**
 176          * Retrieves a menu given its hash
 177          *
 178          * @param string hash The hash of the menu to be retrieved
 179          *
 180          * @return string
 181          */
 182         get: function (hash) {
 183             if (this.data[hash]) {
 184                 return this.data[hash].content;
 185             } else {
 186                 // This should never happen as long as the number of stored menus
 187                 // is larger or equal to the number of pages in the page cache
 188                 return '';
 189             }
 190         },
 191         /**
 192          * Prepares part of the parameter string used during page requests,
 193          * this is necessary to tell the server which menus we have in the cache
 194          *
 195          * @return string
 196          */
 197         getRequestParam: function () {
 198             var param = '';
 199             var menuHashes = [];
 200             for (var i in this.data) {
 201                 menuHashes.push(i);
 202             }
 203             var menuHashesParam = menuHashes.join('-');
 204             if (menuHashesParam) {
 205                 param = CommonParams.get('arg_separator') + 'menuHashes=' + menuHashesParam;
 206             }
 207             return param;
 208         },
 209         /**
 210          * Replaces the menu with new content
 211          *
 212          * @return void
 213          */
 214         replace: function (content) {
 215             $('#floating_menubar').html(content)
 216                 // Remove duplicate wrapper
 217                 // TODO: don't send it in the response
 218                 .children().first().remove();
 219             $('#topmenu').menuResizer(Functions.mainMenuResizerCallback);
 220         }
 221     }
 222 };
 223
 224 /**
 225  * URL hash management module.
 226  * Allows direct bookmarking and microhistory.
 227  */
 228 MicroHistory.setUrlHash = (function (jQuery, window) {
 229     'use strict';
 230     /**
 231      * Indictaes whether we have already completed
 232      * the initialisation of the hash
 233      *
 234      * @access private
 235      */
 236     var ready = false;
 237     /**
 238      * Stores a hash that needed to be set when we were not ready
 239      *
 240      * @access private
 241      */
 242     var savedHash = '';
 243     /**
 244      * Flag to indicate if the change of hash was triggered
 245      * by a user pressing the back/forward button or if
 246      * the change was triggered internally
 247      *
 248      * @access private
 249      */
 250     var userChange = true;
 251
 252     // Fix favicon disappearing in Firefox when setting location.hash
 253     function resetFavicon () {
 254         if (navigator.userAgent.indexOf('Firefox') > -1) {
 255             // Move the link tags for the favicon to the bottom
 256             // of the head element to force a reload of the favicon
 257             $('head > link[href="favicon\\.ico"]').appendTo('head');
 258         }
 259     }
 260
 261     /**
 262      * Sets the hash part of the URL
 263      *
 264      * @access public
 265      */
 266     function setUrlHash (index, hash) {
 267         /*
 268          * Known problem:
 269          * Setting hash leads to reload in webkit:
 270          * http://www.quirksmode.org/bugreports/archives/2005/05/Safari_13_visual_anomaly_with_windowlocationhref.html
 271          *
 272          * so we expect that users are not running an ancient Safari version
 273          */
 274
 275         userChange = false;
 276         if (ready) {
 277             window.location.hash = 'PMAURL-' + index + ':' + hash;
 278             resetFavicon();
 279         } else {
 280             savedHash = 'PMAURL-' + index + ':' + hash;
 281         }
 282     }
 283     /**
 284      * Start initialisation
 285      */
 286     var urlHash = window.location.hash;
 287     if (urlHash.substring(0, 8) === '#PMAURL-') {
 288         // We have a valid hash, let's redirect the user
 289         // to the page that it's pointing to
 290         var colonPosition = urlHash.indexOf(':');
 291         var questionMarkPosition = urlHash.indexOf('?');
 292         if (colonPosition !== -1 && questionMarkPosition !== -1 && colonPosition < questionMarkPosition) {
 293             var hashUrl = urlHash.substring(colonPosition + 1, questionMarkPosition);
 294             if (hashUrl === 'index.php') {
 295                 window.location = urlHash.substring(
 296                     colonPosition + 1
 297                 );
 298             }
 299         }
 300     } else {
 301         // We don't have a valid hash, so we'll set it up
 302         // when the page finishes loading
 303         jQuery(function () {
 304             /* Check if we should set URL */
 305             if (savedHash !== '') {
 306                 window.location.hash = savedHash;
 307                 savedHash = '';
 308                 resetFavicon();
 309             }
 310             // Indicate that we're done initialising
 311             ready = true;
 312         });
 313     }
 314     /**
 315      * Register an event handler for when the url hash changes
 316      */
 317     jQuery(function () {
 318         jQuery(window).hashchange(function () {
 319             if (userChange === false) {
 320                 // Ignore internally triggered hash changes
 321                 userChange = true;
 322             } else if (/^#PMAURL-\d+:/.test(window.location.hash)) {
 323                 // Change page if the hash changed was triggered by a user action
 324                 var index = window.location.hash.substring(
 325                     8, window.location.hash.indexOf(':')
 326                 );
 327                 MicroHistory.navigate(index);
 328             }
 329         });
 330     });
 331     /**
 332      * Publicly exposes a reference to the otherwise private setUrlHash function
 333      */
 334     return setUrlHash;
 335 }(jQuery, window));