js/microhistory.js

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