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: {}
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.
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.
Constant used to identify state changes originating from the
replace() method.
Methods
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.
protected
void
_defChangeFn
(
e
)
Default history:change event handler.
- Parameters:
-
e
<EventFacade>
state change event facade
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
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.
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
protected
void
_init
(
config
)
Initializes this HistoryBase instance. This method is called by the
constructor.
- Parameters:
-
config
<Object>
configuration object
private
Boolean
_isSimpleObject
(
value
)
Returns true if value is a simple object and not a
function or an array.
- Parameters:
-
value
<mixed>
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.
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.
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.
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.
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.
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.
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.
Methods inherited from EventTarget:
_getType,
_monitor,
_parseType,
addTarget,
after,
before,
bubble,
detach,
detachAll,
fire,
getEvent,
getTargets,
on,
once,
publish,
removeTarget,
subscribe,
unsubscribe,
unsubscribeAll
Events
[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
(
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
(
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.