Version 3.17.2
Show:

HistoryHTML5 Class

Extends HistoryBase
Module: history-html5
Parent Module: history

Provides browser history management using the HTML5 history API.

When calling the add(), addValue(), replace(), or replaceValue() methods on HistoryHTML5, the following additional options are supported:

title (String)
Title to use for the new history entry. Browsers will typically display this title to the user in the detailed history window or in a dropdown menu attached to the back/forward buttons. If not specified, the title of the current document will be used.
url (String)
URL to display to the user for the new history entry. This URL will be visible in the browser's address bar and will be the bookmarked URL if the user bookmarks the page. It may be a relative path ("foo/bar"), an absolute path ("/foo/bar"), or a full URL ("http://example.com/foo/bar"). If you specify a full URL, the origin must be the same as the origin of the current page, or an error will occur. If no URL is specified, the current URL will not be changed.

Constructor

HistoryHTML5

(
  • config
)

Parameters:

  • config Object

    (optional) Configuration object.

Methods

_change

(
  • src
  • state
  • options
)
protected chainable

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 add() for a list of supported options.

_defChangeFn

(
  • e
)
protected

Default history:change event handler.

Parameters:

_fireChangeEvent

(
  • src
  • key
  • value
)
protected

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 newVal and prevVal properties for the changed item

_fireEvents

(
  • src
  • changes
  • options
)
protected

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 add() for a list of supported options.

_fireRemoveEvent

(
  • src
  • key
  • value
)
protected

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

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

Parameters:

  • config Object

    configuration object

_isSimpleObject

(
  • value
)
Boolean private

Returns true if value is a simple object and not a function or an array.

Parameters:

  • value Mixed

Returns:

_onPopState

(
  • e
)
protected

Handler for popstate events.

Parameters:

_resolveChanges

(
  • src
  • newState
  • options
)
protected

Resolves the changes (if any) between newState 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 add() for a list of supported options.

_storeState

(
  • src
  • newState
  • options
)
protected

Inherited from HistoryBase but overwritten in history/js/history-html5.js:98

Overrides HistoryBase's _storeState() and pushes or replaces a history entry using the HTML5 history API when necessary.

Parameters:

  • src String

    Source of the changes.

  • newState Object

    New state to store.

  • options Object

    Zero or more options.

add

(
  • state
  • options
)
chainable

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 null or undefined 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:

    merge (Boolean)

    If true (the default), the new state will be merged into the existing state. New values will override existing values, and null or undefined values will be removed from the state.

      <p>
      If <code>false</code>, the existing state will be discarded as a
      whole and the new state will take its place.
      </p>
    </dd>

addValue

(
  • key
  • value
  • options
)
chainable

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 null or undefined 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 add() for a list of supported options.

get

(
  • key
)
Object | String

Returns the current value of the state parameter specified by key, 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

Same as add() 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 add() for a list of supported options.

replaceValue

(
  • key
  • value
  • options
)
chainable

Same as addValue() 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 add() for a list of supported options.

Properties

_config

Object protected

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

Default: {}

_initialState

Object | Null protected

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 _config.initialState. If neither the config nor a subclass supplies an initial state, this property will be null.

Default: {}

force

Boolean

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

Default: false

SRC_POPSTATE

String final static

Constant used to identify state changes originating from popstate events.

Events

[key]Change

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 fooChange event; for a key named "bar", subscribe to barChange, etc.

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 history:change event.

Event Payload:

  • e EventFacade

    Event facade with the following additional properties:

    newVal (mixed)
    The new value of the item after the change.
    prevVal (mixed)
    The previous value of the item before the change, or undefined if the item was just added and has no previous value.
    src (String)
    The source of the event. This can be used to selectively ignore events generated by certain sources.

[key]Remove

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 fooRemove event; for a key named "bar", subscribe to barRemove, etc.

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 history:change event.

Event Payload:

  • e EventFacade

    Event facade with the following additional properties:

    prevVal (mixed)
    The value of the item before it was removed.
    src (String)
    The source of the event. This can be used to selectively ignore events generated by certain sources.

history:change

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 Y.Global. 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:

    changed (Object)
    Object hash of state items that have been added or changed. The key is the item key, and the value is an object containing newVal and prevVal properties representing the values of the item both before and after the change. If the item was newly added, prevVal will be undefined.
    newVal (Object)
    Object hash of key/value pairs of all state items after the change.
    prevVal (Object)
    Object hash of key/value pairs of all state items before the change.
    removed (Object)
    Object hash of key/value pairs of state items that have been removed. Values are the old values prior to removal.
    src (String)
    The source of the event. This can be used to selectively ignore events generated by certain sources.