Yahoo! UI Library

history  3.3.0pr1

Yahoo! UI Library > history > HistoryBase
Search:
 
Filters

Class HistoryBase - uses EventTarget

Known Subclasses:
HistoryHash HistoryHTML5
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.

Constructor

HistoryBase ( config )
Parameters:
config <Object> (optional) configuration object, which may contain zero or more of the following properties:
initialState (Object)
Initial state to set, as an object hash of key/value pairs. This will be merged into the current global state.

Properties

_config - protected Object

Configuration object provided by the user on instantiation, or an empty object if one wasn't provided.
Default Value: {}

_initialState - protected Object|null

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 Value: {}

html5 - static Boolean

Whether or not this browser supports the HTML5 History API.

NAME - static String

Name of this component.

nativeHashChange - static Boolean

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

SRC_ADD - static final String

Constant used to identify state changes originating from the add() method.

SRC_REPLACE - static final String

Constant used to identify state changes originating from the replace() method.

Methods

_change

protected void _change ( src , state , options )
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.
Chainable: This method is chainable.

_defChangeFn

protected void _defChangeFn ( e )
Default history:change event handler.
Parameters:
e <EventFacade> state change event facade

_fireChangeEvent

protected void _fireChangeEvent ( src , key , value )
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

protected void _fireEvents ( src , changes , options )
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

protected void _fireRemoveEvent ( src , key , value )
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

protected void _init ( config )
Initializes this HistoryBase instance. This method is called by the constructor.
Parameters:
config <Object> configuration object

_isSimpleObject

private Boolean _isSimpleObject ( value )
Returns true if value is a simple object and not a function or an array.
Parameters:
value <mixed>

_resolveChanges

protected void _resolveChanges ( src , newState , options )
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

protected void _storeState ( src , newState , options )
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 add() for a list of supported options.

add

void 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:
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.

If false, the existing state will be discarded as a whole and the new state will take its place.

Chainable: This method is chainable.

addValue

void 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.
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.
Chainable: This method is chainable.

get

Object|String 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:
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.

getIframeHash

static String getIframeHash ( )
Gets the raw (not decoded) current location hash from the IE iframe, minus the preceding '#' character and the hashPrefix (if one is set).
Returns: String
current iframe hash

replace

void 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.
Parameters:
state <Object> Object hash of key/value pairs.
options <Object> (optional) Zero or more options. See add() for a list of supported options.
Chainable: This method is chainable.

replaceValue

void 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.
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.
Chainable: This method is chainable.

Events

[key]Change

[key]Change ( e )

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.

Parameters:
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

[key]Remove ( e )

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.

Parameters:
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

history:change ( e )
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.
Parameters:
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.


Copyright © 2010 Yahoo! Inc. All rights reserved.