HistoryHTML5 Class
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
Methods
_change
-
src -
state -
options
Changes the state. This method provides a common implementation shared by the public methods for changing state.
_defChangeFn
-
e
Default history:change event handler.
Parameters:
-
eEventFacadestate change event facade
_fireChangeEvent
-
src -
key -
value
Fires a dynamic "[key]Change" event.
_fireEvents
-
src -
changes -
options
Called by _resolveChanges() when the state has changed. This method takes care of actually firing the necessary events.
_fireRemoveEvent
-
src -
key -
value
Fires a dynamic "[key]Remove" event.
_init
-
config
Initializes this HistoryBase instance. This method is called by the constructor.
Parameters:
-
configObjectconfiguration object
_isSimpleObject
-
value
Returns true if value is a simple object and not a
function or an array.
Parameters:
-
valueMixed
Returns:
_resolveChanges
-
src -
newState -
options
Resolves the changes (if any) between newState and the current state and fires appropriate events if things have changed.
_storeState
-
src -
newState -
options
Overrides HistoryBase's _storeState() and pushes or replaces
a history entry using the HTML5 history API when necessary.
add
-
state -
options
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:
-
stateObjectObject hash of key/value pairs.
-
optionsObject(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, andnullorundefinedvalues 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
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.
get
-
key
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:
-
keyString(optional) State parameter key.
replace
-
state -
options
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.
replaceValue
-
key -
value -
options
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.
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:
-
eEventFacadeEvent 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
undefinedif 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:
-
eEventFacadeEvent 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:
-
eEventFacadeEvent 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
newValandprevValproperties representing the values of the item both before and after the change. If the item was newly added,prevValwill beundefined. - 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.