lib/yuilib/3.13.0/history-html5/history-html5.js

   1 /*
   2 YUI 3.13.0 (build 508226d)
   3 Copyright 2013 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.13.0', {"optional": ["json"], "requires": ["event-base", "history-base", "node-base"]});