[Summary view] [Print] [Text view]

   1  /*
   2  YUI 3.17.2 (build 9c3c78e)
   3  Copyright 2014 Yahoo! Inc. All rights reserved.
   4  Licensed under the BSD License.
   5  http://yuilibrary.com/license/
   6  */
   7  
   8  YUI.add('history-html5', function (Y, NAME) {
   9  
  10  /**
  11   * Provides browser history management using the HTML5 history API.
  12   *
  13   * @module history
  14   * @submodule history-html5
  15   * @since 3.2.0
  16   */
  17  
  18  /**
  19   * <p>
  20   * Provides browser history management using the HTML5 history API.
  21   * </p>
  22   *
  23   * <p>
  24   * When calling the <code>add()</code>, <code>addValue()</code>,
  25   * <code>replace()</code>, or <code>replaceValue()</code> methods on
  26   * <code>HistoryHTML5</code>, the following additional options are supported:
  27   * </p>
  28   *
  29   * <dl>
  30   *   <dt><strong>title (String)</strong></dt>
  31   *   <dd>
  32   *     Title to use for the new history entry. Browsers will typically display
  33   *     this title to the user in the detailed history window or in a dropdown
  34   *     menu attached to the back/forward buttons. If not specified, the title
  35   *     of the current document will be used.
  36   *   </dd>
  37   *
  38   *   <dt><strong>url (String)</strong></dt>
  39   *   <dd>
  40   *     URL to display to the user for the new history entry. This URL will be
  41   *     visible in the browser's address bar and will be the bookmarked URL if
  42   *     the user bookmarks the page. It may be a relative path ("foo/bar"), an
  43   *     absolute path ("/foo/bar"), or a full URL ("http://example.com/foo/bar").
  44   *     If you specify a full URL, the origin <i>must</i> be the same as the
  45   *     origin of the current page, or an error will occur. If no URL is
  46   *     specified, the current URL will not be changed.
  47   *   </dd>
  48   * </dl>
  49   *
  50   * @class HistoryHTML5
  51   * @extends HistoryBase
  52   * @constructor
  53   * @param {Object} config (optional) Configuration object.
  54   */
  55  
  56  var HistoryBase     = Y.HistoryBase,
  57      Lang            = Y.Lang,
  58      win             = Y.config.win,
  59      useHistoryHTML5 = Y.config.useHistoryHTML5,
  60  
  61      SRC_POPSTATE    = 'popstate',
  62      SRC_REPLACE     = HistoryBase.SRC_REPLACE;
  63  
  64  function HistoryHTML5() {
  65      HistoryHTML5.superclass.constructor.apply(this, arguments);
  66  }
  67  
  68  Y.extend(HistoryHTML5, HistoryBase, {
  69      // -- Initialization -------------------------------------------------------
  70      _init: function (config) {
  71          var bookmarkedState;
  72  
  73          try {
  74              bookmarkedState = win.history.state;
  75          } catch(e) {
  76              bookmarkedState = null;
  77          }
  78  
  79          // Treat empty state objects as `null` so they're not processed further.
  80          if (Y.Object.isEmpty(bookmarkedState)) {
  81              bookmarkedState = null;
  82          }
  83  
  84          config || (config = {});
  85  
  86          // If both the initial state and the bookmarked state are objects, merge
  87          // them (bookmarked state wins).
  88          if (config.initialState
  89                  && Lang.type(config.initialState) === 'object'
  90                  && Lang.type(bookmarkedState) === 'object') {
  91  
  92              this._initialState = Y.merge(config.initialState, bookmarkedState);
  93          } else {
  94              // Otherwise, the bookmarked state always wins if there is one. If
  95              // there isn't a bookmarked state, history-base will take care of
  96              // falling back to config.initialState or null.
  97              this._initialState = bookmarkedState;
  98          }
  99  
 100          Y.on('popstate', this._onPopState, win, this);
 101  
 102          HistoryHTML5.superclass._init.apply(this, arguments);
 103      },
 104  
 105      // -- Protected Methods ----------------------------------------------------
 106  
 107      /**
 108       * Overrides HistoryBase's <code>_storeState()</code> and pushes or replaces
 109       * a history entry using the HTML5 history API when necessary.
 110       *
 111       * @method _storeState
 112       * @param {String} src Source of the changes.
 113       * @param {Object} newState New state to store.
 114       * @param {Object} options Zero or more options.
 115       * @protected
 116       */
 117      _storeState: function (src, newState, options) {
 118          if (src !== SRC_POPSTATE) {
 119              win.history[src === SRC_REPLACE ? 'replaceState' : 'pushState'](
 120                  newState,
 121                  options.title || Y.config.doc.title || '',
 122                  options.url || Y.config.doc.URL
 123              );
 124          }
 125  
 126          HistoryHTML5.superclass._storeState.apply(this, arguments);
 127      },
 128  
 129      // -- Protected Event Handlers ---------------------------------------------
 130  
 131      /**
 132       * Handler for popstate events.
 133       *
 134       * @method _onPopState
 135       * @param {Event} e
 136       * @protected
 137       */
 138      _onPopState: function (e) {
 139          this._resolveChanges(SRC_POPSTATE, e._event.state || null);
 140      }
 141  }, {
 142      // -- Public Static Properties ---------------------------------------------
 143      NAME: 'historyhtml5',
 144  
 145      /**
 146       * Constant used to identify state changes originating from
 147       * <code>popstate</code> events.
 148       *
 149       * @property SRC_POPSTATE
 150       * @type String
 151       * @static
 152       * @final
 153       */
 154      SRC_POPSTATE: SRC_POPSTATE
 155  });
 156  
 157  if (!Y.Node.DOM_EVENTS.popstate) {
 158      Y.Node.DOM_EVENTS.popstate = 1;
 159  }
 160  
 161  Y.HistoryHTML5 = HistoryHTML5;
 162  
 163  /**
 164   * <p>
 165   * If <code>true</code>, the <code>Y.History</code> alias will always point to
 166   * <code>Y.HistoryHTML5</code> when the history-html5 module is loaded, even if
 167   * the current browser doesn't support HTML5 history.
 168   * </p>
 169   *
 170   * <p>
 171   * If <code>false</code>, the <code>Y.History</code> alias will always point to
 172   * <code>Y.HistoryHash</code> when the history-hash module is loaded, even if
 173   * the current browser supports HTML5 history.
 174   * </p>
 175   *
 176   * <p>
 177   * If neither <code>true</code> nor <code>false</code>, the
 178   * <code>Y.History</code> alias will point to the best available history adapter
 179   * that the browser supports. This is the default behavior.
 180   * </p>
 181   *
 182   * @property useHistoryHTML5
 183   * @type boolean
 184   * @for config
 185   * @since 3.2.0
 186   */
 187  
 188  // HistoryHTML5 will always win over HistoryHash unless useHistoryHTML5 is false
 189  // or HTML5 history is not supported.
 190  if (useHistoryHTML5 === true || (useHistoryHTML5 !== false &&
 191          HistoryBase.html5)) {
 192      Y.History = HistoryHTML5;
 193  }
 194  
 195  
 196  }, '3.17.2', {"optional": ["json"], "requires": ["event-base", "history-base", "node-base"]});