AlloyUI - API Docs

  • API Docs for Version: 3.1.0-deprecated.60

    • Show:

    HistoryBase Class

    Defined in: yui3/src/history/js/history-base.js:13
    Module: history-base
    Parent Module: history

    Provides global state management backed by an object, but with no browser history integration. For actual browser history integration and back/forward support, use the history-html5 or history-hash modules.

    Methods

    _change

    (
    • src
    • state
    • options
    )
    protected chainable

    Defined in yui3/src/history/js/history-base.js:376

    Changes the state. This method provides a common implementation shared by the public methods for changing state.

    Parameters:

    • src String

      Source of the change, for inclusion in event facades to facilitate filtering.

    • state Object

      Object hash of key/value pairs.

    • options Object

      (optional) Zero or more options. See <code>add()</code> for a list of supported options.

    _defChangeFn

    (
    • e
    )
    protected

    Defined in yui3/src/history/js/history-base.js:622

    Default <code>history:change</code> event handler.

    Parameters:

    _fireChangeEvent

    (
    • src
    • key
    • value
    )
    protected

    Defined in yui3/src/history/js/history-base.js:434

    Fires a dynamic "[key]Change" event.

    Parameters:

    • src String

      source of the change, for inclusion in event facades to facilitate filtering

    • key String

      key of the item that was changed

    • value Object

      object hash containing <i>newVal</i> and <i>prevVal</i> properties for the changed item

    _fireEvents

    (
    • src
    • changes
    • options
    )
    protected

    Defined in yui3/src/history/js/history-base.js:401

    Called by _resolveChanges() when the state has changed. This method takes care of actually firing the necessary events.

    Parameters:

    • src String

      Source of the changes, for inclusion in event facades to facilitate filtering.

    • changes Object

      Resolved changes.

    • options Object

      Zero or more options. See <code>add()</code> for a list of supported options.

    _fireRemoveEvent

    (
    • src
    • key
    • value
    )
    protected

    Defined in yui3/src/history/js/history-base.js:493

    Fires a dynamic "[key]Remove" event.

    Parameters:

    • src String

      source of the change, for inclusion in event facades to facilitate filtering

    • key String

      key of the item that was removed

    • value Mixed

      value of the item prior to its removal

    _init

    (
    • config
    )
    protected

    Defined in yui3/src/history/js/history-base.js:158

    Initializes this HistoryBase instance. This method is called by the constructor.

    Parameters:

    • config Object

      configuration object

    _isSimpleObject

    (
    • value
    )
    Boolean private

    Defined in yui3/src/history/js/history-base.js:72

    Returns <code>true</code> if <i>value</i> is a simple object and not a function or an array.

    Parameters:

    • value Mixed

    Returns:

    Boolean:

    _resolveChanges

    (
    • src
    • newState
    • options
    )
    protected

    Defined in yui3/src/history/js/history-base.js:543

    Resolves the changes (if any) between <i>newState</i> and the current state and fires appropriate events if things have changed.

    Parameters:

    • src String

      source of the changes, for inclusion in event facades to facilitate filtering

    • newState Object

      object hash of key/value pairs representing the new state

    • options Object

      Zero or more options. See <code>add()</code> for a list of supported options.

    _storeState

    (
    • src
    • newState
    • options
    )
    protected

    Defined in yui3/src/history/js/history-base.js:602

    Stores the specified state. Don't call this method directly; go through _resolveChanges() to ensure that changes are resolved and all events are fired properly.

    Parameters:

    • src String

      source of the changes

    • newState Object

      new state to store

    • options Object

      Zero or more options. See <code>add()</code> for a list of supported options.

    add

    (
    • state
    • options
    )
    chainable

    Defined in yui3/src/history/js/history-base.js:265

    Adds a state entry with new values for the specified keys. By default, the new state will be merged into the existing state, and new values will override existing values. Specifying a <code>null</code> or <code>undefined</code> value will cause that key to be removed from the new state entry.

    Parameters:

    • state Object

      Object hash of key/value pairs.

    • options Object

      (optional) Zero or more of the following options: <dl> <dt>merge (Boolean)</dt> <dd> <p> If <code>true</code> (the default), the new state will be merged into the existing state. New values will override existing values, and <code>null</code> or <code>undefined</code> values will be removed from the state. </p> <p> If <code>false</code>, the existing state will be discarded as a whole and the new state will take its place. </p> </dd> </dl>

    addValue

    (
    • key
    • value
    • options
    )
    chainable

    Defined in yui3/src/history/js/history-base.js:298

    Adds a state entry with a new value for a single key. By default, the new value will be merged into the existing state values, and will override an existing value with the same key if there is one. Specifying a <code>null</code> or <code>undefined</code> value will cause the key to be removed from the new state entry.

    Parameters:

    • key String

      State parameter key.

    • value String

      New value.

    • options Object

      (optional) Zero or more options. See <code>add()</code> for a list of supported options.

    get

    (
    • key
    )
    Object | String

    Defined in yui3/src/history/js/history-base.js:318

    Returns the current value of the state parameter specified by <i>key</i>, or an object hash of key/value pairs for all current state parameters if no key is specified.

    Parameters:

    • key String

      (optional) State parameter key.

    Returns:

    Object | String:

    Value of the specified state parameter, or an object hash of key/value pairs for all current state parameters.

    replace

    (
    • state
    • options
    )
    chainable

    Defined in yui3/src/history/js/history-base.js:339

    Same as <code>add()</code> except that a new browser history entry will not be created. Instead, the current history entry will be replaced with the new state.

    Parameters:

    • state Object

      Object hash of key/value pairs.

    • options Object

      (optional) Zero or more options. See <code>add()</code> for a list of supported options.

    replaceValue

    (
    • key
    • value
    • options
    )
    chainable

    Defined in yui3/src/history/js/history-base.js:356

    Same as <code>addValue()</code> except that a new browser history entry will not be created. Instead, the current history entry will be replaced with the new state.

    Parameters:

    • key String

      State parameter key.

    • value String

      New value.

    • options Object

      (optional) Zero or more options. See <code>add()</code> for a list of supported options.

    Properties

    _config

    Object protected

    Defined in yui3/src/history/js/history-base.js:169

    Configuration object provided by the user on instantiation, or an empty object if one wasn't provided.

    Default: {}

    _initialState

    Object | Null protected

    Defined in yui3/src/history/js/history-base.js:190

    Resolved initial state: a merge of the user-supplied initial state (if any) and any initial state provided by a subclass. This may differ from <code>_config.initialState</code>. If neither the config nor a subclass supplies an initial state, this property will be <code>null</code>.

    Default: {}

    force

    Boolean

    Defined in yui3/src/history/js/history-base.js:180

    If true, a history:change event will be fired whenever the URL changes, even if there is no associated state change.

    Default: false

    html5

    Boolean static

    Defined in yui3/src/history/js/history-base.js:118

    Whether or not this browser supports the HTML5 History API.

    NAME

    String static

    Defined in yui3/src/history/js/history-base.js:87

    Name of this component.

    nativeHashChange

    Boolean static

    Defined in yui3/src/history/js/history-base.js:133

    Whether or not this browser supports the <code>window.onhashchange</code> event natively. Note that even if this is <code>true</code>, you may still want to use HistoryHash's synthetic <code>hashchange</code> event since it normalizes implementation differences and fixes spec violations across various browsers.

    SRC_ADD

    String final static

    Defined in yui3/src/history/js/history-base.js:96

    Constant used to identify state changes originating from the <code>add()</code> method.

    SRC_REPLACE

    String final static

    Defined in yui3/src/history/js/history-base.js:107

    Constant used to identify state changes originating from the <code>replace()</code> method.

    Events

    [key]Change

    Defined in yui3/src/history/js/history-base.js:446

    <p> Dynamic event fired when an individual history item is added or changed. The name of this event depends on the name of the key that changed. To listen to change events for a key named "foo", subscribe to the <code>fooChange</code> event; for a key named "bar", subscribe to <code>barChange</code>, etc. </p>

    <p> Key-specific events are only fired for instance-level changes; that is, changes that were made via the same History instance on which the event is subscribed. To be notified of changes made by other History instances, subscribe to the global <code>history:change</code> event. </p>

    Event Payload:

    • e EventFacade

      Event facade with the following additional properties:

      <dl> <dt>newVal (mixed)</dt> <dd> The new value of the item after the change. </dd>

      <dt>prevVal (mixed)</dt> <dd> The previous value of the item before the change, or <code>undefined</code> if the item was just added and has no previous value. </dd>

      <dt>src (String)</dt> <dd> The source of the event. This can be used to selectively ignore events generated by certain sources. </dd> </dl>

    [key]Remove

    Defined in yui3/src/history/js/history-base.js:504

    <p> Dynamic event fired when an individual history item is removed. The name of this event depends on the name of the key that was removed. To listen to remove events for a key named "foo", subscribe to the <code>fooRemove</code> event; for a key named "bar", subscribe to <code>barRemove</code>, etc. </p>

    <p> Key-specific events are only fired for instance-level changes; that is, changes that were made via the same History instance on which the event is subscribed. To be notified of changes made by other History instances, subscribe to the global <code>history:change</code> event. </p>

    Event Payload:

    • e EventFacade

      Event facade with the following additional properties:

      <dl> <dt>prevVal (mixed)</dt> <dd> The value of the item before it was removed. </dd>

      <dt>src (String)</dt> <dd> The source of the event. This can be used to selectively ignore events generated by certain sources. </dd> </dl>

    history:change

    Defined in yui3/src/history/js/history-base.js:205

    Fired when the state changes. To be notified of all state changes regardless of the History or YUI instance that generated them, subscribe to this event on <code>Y.Global</code>. If you would rather be notified only about changes generated by this specific History instance, subscribe to this event on the instance.

    Event Payload:

    • e EventFacade

      Event facade with the following additional properties:

      <dl> <dt>changed (Object)</dt> <dd> Object hash of state items that have been added or changed. The key is the item key, and the value is an object containing <code>newVal</code> and <code>prevVal</code> properties representing the values of the item both before and after the change. If the item was newly added, <code>prevVal</code> will be <code>undefined</code>. </dd>

      <dt>newVal (Object)</dt> <dd> Object hash of key/value pairs of all state items after the change. </dd>

      <dt>prevVal (Object)</dt> <dd> Object hash of key/value pairs of all state items before the change. </dd>

      <dt>removed (Object)</dt> <dd> Object hash of key/value pairs of state items that have been removed. Values are the old values prior to removal. </dd>

      <dt>src (String)</dt> <dd> The source of the event. This can be used to selectively ignore events generated by certain sources. </dd> </dl>