Router Class
+ + + + +Provides URL-based routing using HTML5 pushState() or the location hash.
This makes it easy to wire up route handlers for different application states +while providing full back/forward navigation support and bookmarkable, shareable +URLs.
+Constructor
+Router
+
+
+ -
+
+
-
+
+
[config]+ +
+
+
Parameters:
+ +-
+
+
-
+
+
[config]+ Object + optional + + + + +++ + +Config properties.
+-
+
+
-
+
+
[html5]+ Boolean + optional + + +++ + +Overrides the default capability detection + and forces this router to use (
+true) or not use (false) HTML5 + history.
+
+ -
+
+
[root='']+ String + optional + + +++ + +Root path from which all routes should be + evaluated.
+
+
+ -
+
+
[routes=[]+ Array + optional + + +++ + +Array of route definition objects.
+
+
+
+
+ -
+
+
-
+
- Index + + +
- Methods + + +
- Properties + + +
- Attributes + + +
- Events + +
Item Index
+ + +Methods
+ +-
+
+
- + _addAttrs + + + + + +
- + _addLazyAttr + + + + + +
- + _afterHistoryChange + + + + + +
- + _aggregateAttrs + + + + + +
- + _attrCfgHash + + + + + +
- + _baseDestroy + + + + + +
- + _baseInit + + + + + +
- + _cloneDefaultValue + + + + + +
- + _decode + + + + + +
- + _defAttrChangeFn + + + + + +
- + _defDestroyFn + + + + + +
- + _defInitFn + + + + + +
- + _defReadyFn + + + + + +
- + _dequeue + + + + + +
- + _destroyHierarchy + + + + + +
- + _dispatch + + + + + +
- + _filterAdHocAttrs + + + + + +
- + _filterAttrCfgs + + + + + +
- + _fireAttrChange + + + + + +
- + _getAttr + + + + + +
- + _getAttrCfg + + + + + +
- + _getAttrCfgs + + + + + +
- + _getAttrInitVal + + + + + +
- + _getAttrs + + + + + +
- + _getClasses + + + + + +
- + _getFullType + + + + + +
- + _getHashPath + + + + + +
- + _getOrigin + + + + + +
- + _getPath + + + + + +
- + _getPathRoot + + + + + +
- + _getQuery + + + + + +
- + _getRegex + + + + + +
- + _getRequest + + + + + +
- + _getResponse + + + + + +
- + _getRoutes + + + + + +
- + _getStateVal + + + + + +
- + _getType + + + + + +
- + _getURL + + + + + +
- + _hasSameOrigin + + + + + +
- + _initAttrHost + + + + + +
- + _initAttribute + + + + + +
- + _initAttrs + + + + + +
- + _initBase + + + + + +
- + _initHierarchy + + + + + +
- + _initHierarchyData + + + + + +
- + _isLazyAttr + + + + + +
- + _joinURL + + + + + +
- + _monitor + + + + + +
- + _normalizePath + + + + + +
- + _normAttrVals + + + + + +
- + _parseQuery + + + + + +
- + _parseType + + + + + +
- + _preInitEventCfg + + + + + +
- + _protectAttrs + + + + deprecated + + + +
- + _publish + + + + + +
- + _queue + + + + + +
- + _resolvePath + + + + + +
- + _resolveURL + + + + + +
- + _save + + + + + +
- + _set + + + + + +
- + _setAttr + + + + + +
- + _setAttrs + + + + + +
- + _setAttrVal + + + + + +
- + _setRoutes + + + + + +
- + _setStateVal + + + + + +
- + _upgradeURL + + + + + +
- + addAttr + + + + + +
- + addAttrs + + + + + +
- + addTarget + + + + + +
- + after + + + + + +
- + attrAdded + + + + + +
- + before + + + + + +
- + bubble + + + + + +
- + destroy + + + + + +
- + detach + + + + + +
- + detachAll + + + + + +
- + dispatch + + + + + +
- + dispatch + + + static + + + + +
- + fire + + + + + +
- + get + + + + + +
- + getAttrs + + + + + +
- + getEvent + + + + + +
- + getPath + + + + + +
- + getTargets + + + + + +
- + hasRoute + + + + + +
- + init + + + + + +
- + match + + + + + +
- + modifyAttr + + + + + +
- + on + + + + + +
- + once + + + + + +
- + onceAfter + + + + + +
- + parseType + + + + + +
- + publish + + + + + +
- + removeAttr + + + + + +
- + removeQuery + + + + + +
- + removeRoot + + + + + +
- + removeTarget + + + + + +
- + replace + + + + + +
- + reset + + + + + +
- + route + + + + + +
- + save + + + + + +
- + set + + + + + +
- + setAttrs + + + + + +
- + subscribe + + + + deprecated + + + +
- + toString + + + + + +
- + unsubscribe + + + + deprecated + + + +
- + unsubscribeAll + + + + deprecated + + + +
- + upgrade + + + + + +
Properties
+ +-
+
+
- + _allowAdHocAttrs + + + + + +
- + _dispatched + + + + + +
- + _dispatching + + + + + +
- + _historyEvents + + + + + +
- + _html5 + + + + + +
- + _ready + + + + + +
- + _regexPathParam + + + + + +
- + _regexUrlOrigin + + + + + +
- + _regexUrlQuery + + + + + +
- + name + + + + deprecated + + + +
Attributes
+ +-
+
+
- + destroyed + + +
- + html5 + + +
- + initialized + + +
- + root + + +
- + routes + + +
Methods
+ + +_addAttrs
+
+
+ -
+
+
-
+
+
cfgs+ +
+
+ -
+
+
values+ +
+
+ -
+
+
lazy+ +
+
+
Implementation behind the public addAttrs method.
+ +This method is invoked directly by get if it encounters a scenario +in which an attribute's valueFn attempts to obtain the +value an attribute in the same group of attributes, which has not yet +been added (on demand initialization).
+Parameters:
+ +-
+
+
-
+
+
cfgs+ Object + + + + +++ + +An object with attribute name/configuration pairs.
+
+
+ -
+
+
values+ Object + + + + +++ + +An object with attribute name/value pairs, defining the initial values to apply. +Values defined in the cfgs argument will be over-written by values in this argument unless defined as read only.
+
+
+ -
+
+
lazy+ Boolean + + + + +++ + +Whether or not to delay the intialization of these attributes until the first call to get/set. +Individual attributes can over-ride this behavior by defining a lazyAdd configuration property in their configuration. +See addAttr.
+
+
+
_addLazyAttr
+
+
+ -
+
+
-
+
+
name+ +
+
+ -
+
+
[lazyCfg]+ +
+
+
Finishes initializing an attribute which has been lazily added.
+Parameters:
+ + +_afterHistoryChange
+
+
+ -
+
+
-
+
+
e+ +
+
+
Handles history:change and hashchange events.
Parameters:
+ +-
+
+
-
+
+
e+ EventFacade + + + + ++ ++ + +
+
+
_aggregateAttrs
+
+
+ -
+
+
-
+
+
allAttrs+ +
+
+
A helper method, used by _initHierarchyData to aggregate +attribute configuration across the instances class hierarchy.
+ +The method will protect the attribute configuration value to protect the statically defined +default value in ATTRS if required (if the value is an object literal, array or the +attribute configuration has cloneDefaultValue set to shallow or deep).
+Parameters:
+ +-
+
+
-
+
+
allAttrs+ Array + + + + +++ + +An array of ATTRS definitions across classes in the hierarchy +(subclass first, Base last)
+
+
+
Returns:
+ +_attrCfgHash
+
+
+ ()
+
+
+
+
+
+
+
+ private
+
+
+
+
+
+
+
+
+
+
+
+
+ Utility method to define the attribute hash used to filter/whitelist property mixes for +this class for iteration performance reasons.
+_baseDestroy
+
+
+ ()
+
+
+
+
+
+
+
+ private
+
+
+
+
+
+
+
+
+
+
+
+
+ Internal destroy implementation for BaseCore
+_baseInit
+
+
+ ()
+
+
+
+
+
+
+
+ private
+
+
+
+
+
+
+
+
+
+
+
+
+ Internal initialization implementation for BaseCore
+_cloneDefaultValue
+
+
+ -
+
+
-
+
+
cfg+ +
+
+
This method assumes that the value has already been checked to be an object. +Since it's on a critical path, we don't want to re-do the check.
+Parameters:
+ +-
+
+
-
+
+
cfg+ Object + + + + ++ ++ + +
+
+
_decode
+
+
+ -
+
+
-
+
+
string+ +
+
+
Wrapper around decodeURIComponent that also converts + chars into
+spaces.
Parameters:
+ +-
+
+
-
+
+
string+ String + + + + +++ + +String to decode.
+
+
+
Returns:
+ +_defAttrChangeFn
+
+
+ -
+
+
-
+
+
e+ +
+
+
Default function for attribute change events.
+Parameters:
+ +-
+
+
-
+
+
e+ EventFacade + + + + +++ + +The event object for attribute change events.
+
+
+
_defDestroyFn
+
+
+ -
+
+
-
+
+
e+ +
+
+
Default destroy event handler
+Parameters:
+ +-
+
+
-
+
+
e+ EventFacade + + + + +++ + +Event object
+
+
+
_defInitFn
+
+
+ -
+
+
-
+
+
e+ +
+
+
Default init event handler
+Parameters:
+ +-
+
+
-
+
+
e+ EventFacade + + + + +++ + +Event object, with a cfg property which +refers to the configuration object passed to the constructor.
+
+
+
_defReadyFn
+
+
+ -
+
+
-
+
+
e+ +
+
+
Default handler for the ready event.
Parameters:
+ +-
+
+
-
+
+
e+ EventFacade + + + + ++ ++ + +
+
+
_dequeue
+
+
+ ()
+
+
+
+
+
+
+
+ protected
+
+
+
+
+
+
+
+ chainable
+
+
+
+
+
+
+ Shifts the topmost _save() call off the queue and executes it. Does
+nothing if the queue is empty.
_destroyHierarchy
+
+
+ ()
+
+
+
+
+
+
+
+ private
+
+
+
+
+
+
+
+
+
+
+
+
+ Destroys the class hierarchy for this instance by invoking +the destructor method on the prototype of each class in the hierarchy.
+_dispatch
+
+
+ -
+
+
-
+
+
path+ +
+
+ -
+
+
url+ +
+
+ -
+
+
src+ +
+
+
Dispatches to the first route handler that matches the specified path.
+ +If called before the ready event has fired, the dispatch will be aborted.
+This ensures normalized behavior between Chrome (which fires a popstate
+event on every pageview) and other browsers (which do not).
_filterAdHocAttrs
+
+
+ -
+
+
-
+
+
allAttrs+ +
+
+ -
+
+
userVals+ +
+
+
Parameters:
+ +-
+
+
-
+
+
allAttrs+ Object + + + + +++ + +The set of all attribute configurations for this instance. +Attributes will be removed from this set, if they belong to the filtered class, so +that by the time all classes are processed, allCfgs will be empty.
+
+
+ -
+
+
userVals+ Object + + + + +++ + +The config object passed in by the user, from which adhoc attrs are to be filtered.
+
+
+
Returns:
+ +_filterAttrCfgs
+
+
+ -
+
+
-
+
+
clazz+ +
+
+ -
+
+
allCfgs+ +
+
+
A helper method used when processing ATTRS across the class hierarchy during +initialization. Returns a disposable object with the attributes defined for +the provided class, extracted from the set of all attributes passed in.
+Parameters:
+ +-
+
+
-
+
+
clazz+ Function + + + + +++ + +The class for which the desired attributes are required.
+
+
+ -
+
+
allCfgs+ Object + + + + +++ + +The set of all attribute configurations for this instance. +Attributes will be removed from this set, if they belong to the filtered class, so +that by the time all classes are processed, allCfgs will be empty.
+
+
+
Returns:
+ +_fireAttrChange
+
+
+ -
+
+
-
+
+
attrName+ +
+
+ -
+
+
subAttrName+ +
+
+ -
+
+
currVal+ +
+
+ -
+
+
newVal+ +
+
+ -
+
+
opts+ +
+
+ -
+
+
[cfg]+ +
+
+
Utility method to help setup the event payload and fire the attribute change event.
+Parameters:
+ +-
+
+
-
+
+
attrName+ String + + + + +++ + +The name of the attribute
+
+
+ -
+
+
subAttrName+ String + + + + +++ + +The full path of the property being changed, +if this is a sub-attribute value being change. Otherwise null.
+
+
+ -
+
+
currVal+ Any + + + + +++ + +The current value of the attribute
+
+
+ -
+
+
newVal+ Any + + + + +++ + +The new value of the attribute
+
+
+ -
+
+
opts+ Object + + + + +++ + +Any additional event data to mix into the attribute change event's event facade.
+
+
+ -
+
+
[cfg]+ Object + optional + + + + +++ + +The attribute config stored in State, if already available.
+
+
+
_getAttr
+
+
+ -
+
+
-
+
+
name+ +
+
+
Provides the common implementation for the public get method, +allowing Attribute hosts to over-ride either method.
+ +See get for argument details.
+Parameters:
+ +-
+
+
-
+
+
name+ String + + + + +++ + +The name of the attribute.
+
+
+
Returns:
+ +_getAttrCfg
+
+
+ -
+
+
-
+
+
name+ +
+
+
Returns an object with the configuration properties (and value) +for the given attribute. If attrName is not provided, returns the +configuration properties for all attributes.
+Parameters:
+ +-
+
+
-
+
+
name+ String + + + + +++ + +Optional. The attribute name. If not provided, the method will return the configuration for all attributes.
+
+
+
Returns:
+ +_getAttrCfgs
+
+
+ ()
+
+
+
+
+ Object
+
+
+
+
+
+
+ protected
+
+
+
+
+
+
+
+
+
+
+
+
+ Returns an aggregated set of attribute configurations, by traversing +the class hierarchy.
+Returns:
+ +_getAttrInitVal
+
+
+ -
+
+
-
+
+
attr+ +
+
+ -
+
+
cfg+ +
+
+ -
+
+
initValues+ +
+
+
Returns the initial value of the given attribute from +either the default configuration provided, or the +over-ridden value if it exists in the set of initValues +provided and the attribute is not read-only.
+Parameters:
+ + +Returns:
+ +_getAttrs
+
+
+ -
+
+
-
+
+
attrs+ +
+
+
Implementation behind the public getAttrs method, to get multiple attribute values.
+Parameters:
+ +-
+
+
-
+
+
attrs+ Array | boolean + + + + +++ + +Optional. An array of attribute names. If omitted, all attribute values are +returned. If set to true, all attributes modified from their initial values are returned.
+
+
+
Returns:
+ +_getClasses
+
+
+ ()
+
+
+
+
+ Function[]
+
+
+
+
+
+
+ protected
+
+
+
+
+
+
+
+
+
+
+
+
+ Returns the class hierarchy for this object, with BaseCore being the last class in the array.
+Returns:
+ +_getFullType
+
+
+ -
+
+
-
+
+
type+ +
+
+
Returns the fully qualified type, given a short type string. +That is, returns "foo:bar" when given "bar" if "foo" is the configured prefix.
+ +NOTE: This method, unlike _getType, does no checking of the value passed in, and +is designed to be used with the low level _publish() method, for critical path +implementations which need to fast-track publish for performance reasons.
+Parameters:
+ +-
+
+
-
+
+
type+ String + + + + +++ + +The short type to prefix
+
+
+
Returns:
+ +_getHashPath
+
+
+ -
+
+
-
+
+
[hash]+ +
+
+
Returns the resolved path from the hash fragment, or an empty string if the +hash is not path-like.
+Parameters:
+ +-
+
+
-
+
+
[hash]+ String + optional + + + + +++ + +Hash fragment to resolve into a path. By default this + will be the hash from the current URL.
+
+
+
Returns:
+ +_getOrigin
+
+
+ ()
+
+
+
+
+ String
+
+
+
+
+
+
+ protected
+
+
+
+
+
+
+
+
+
+
+
+
+ Gets the location origin (i.e., protocol, host, and port) as a URL.
+Returns:
+ +Example:
+ +http://example.com
+_getPath
+
+
+ ()
+
+
+
+
+ String
+
+
+
+
+
+
+ protected
+
+
+
+
+
+
+
+
+
+
+
+
+ Gets the current route path, relative to the root (if any).
Returns:
+ +_getPathRoot
+
+
+ ()
+
+
+
+
+ String
+
+
+
+
+
+
+ protected
+
+
+
+
+
+
+
+
+
+
+
+
+ Returns the current path root after popping off the last path segment, +making it useful for resolving other URL paths against.
+ +The path root will always begin and end with a '/'.
+Returns:
+ +_getQuery
+
+
+ ()
+
+
+
+
+ String
+
+
+
+
+
+
+ protected
+
+
+
+
+
+
+
+
+
+
+
+
+ Gets the current route query string.
+Returns:
+ +_getRegex
+
+
+ -
+
+
-
+
+
path+ +
+
+ -
+
+
keys+ +
+
+
Creates a regular expression from the given route specification. If path +is already a regex, it will be returned unmodified.
+Parameters:
+ + +Returns:
+ +_getRequest
+
+
+ -
+
+
-
+
+
path+ +
+
+ -
+
+
url+ +
+
+ -
+
+
src+ +
+
+
Gets a request object that can be passed to a route handler.
+Parameters:
+ + +Returns:
+ +_getResponse
+
+
+ -
+
+
-
+
+
req+ +
+
+
Gets a response object that can be passed to a route handler.
+Parameters:
+ +-
+
+
-
+
+
req+ Object + + + + +++ + +Request object.
+
+
+
Returns:
+ +_getRoutes
+
+
+ ()
+
+
+
+
+ Object[]
+
+
+
+
+
+
+ protected
+
+
+
+
+
+
+
+
+
+
+
+
+ Getter for the routes attribute.
Returns:
+ +_getStateVal
+
+
+ -
+
+
-
+
+
name+ +
+
+ -
+
+
[cfg]+ +
+
+
Gets the stored value for the attribute, from either the +internal state object, or the state proxy if it exits
+Parameters:
+ + +Returns:
+ +_getType
+
+
+ ()
+
+
+
+
+
+
+
+ private
+
+
+
+
+
+
+
+
+
+
+
+
+ If the instance has a prefix attribute and the +event type is not prefixed, the instance prefix is +applied to the supplied type.
+_getURL
+
+
+ ()
+
+
+
+
+ String
+
+
+
+
+
+
+ protected
+
+
+
+
+
+
+
+
+
+
+
+
+ Gets the current full URL.
+Returns:
+ +_hasSameOrigin
+
+
+ -
+
+
-
+
+
url+ +
+
+
Returns true when the specified url is from the same origin as the
+current URL; i.e., the protocol, host, and port of the URLs are the same.
All host or path relative URLs are of the same origin. A scheme-relative URL +is first prefixed with the current scheme before being evaluated.
+Parameters:
+ +-
+
+
-
+
+
url+ String + + + + +++ + +URL to compare origin with the current URL.
+
+
+
Returns:
+ +_initAttrHost
+
+
+ -
+
+
-
+
+
attrs+ +
+
+ -
+
+
values+ +
+
+ -
+
+
lazy+ +
+
+
Constructor logic for attributes. Initializes the host state, and sets up the inital attributes passed to the +constructor.
+Parameters:
+ +-
+
+
-
+
+
attrs+ Object + + + + +++ + +The attributes to add during construction (passed through to addAttrs). + These can also be defined on the constructor being augmented with Attribute by defining the ATTRS property on the constructor.
+
+
+ -
+
+
values+ Object + + + + +++ + +The initial attribute values to apply (passed through to addAttrs). + These are not merged/cloned. The caller is responsible for isolating user provided values if required.
+
+
+ -
+
+
lazy+ Boolean + + + + +++ + +Whether or not to add attributes lazily (passed through to addAttrs).
+
+
+
_initAttribute
+
+
+ ()
+
+
+
+
+
+
+
+ private
+
+
+
+
+
+
+
+
+
+
+
+
+ Initializes AttributeCore
+_initAttrs
+
+
+ -
+
+
-
+
+
attrs+ +
+
+ -
+
+
values+ +
+
+ -
+
+
lazy+ +
+
+
Utility method to set up initial attributes defined during construction, +either through the constructor.ATTRS property, or explicitly passed in.
+Parameters:
+ +-
+
+
-
+
+
attrs+ Object + + + + +++ + +The attributes to add during construction (passed through to addAttrs). + These can also be defined on the constructor being augmented with Attribute by defining the ATTRS property on the constructor.
+
+
+ -
+
+
values+ Object + + + + +++ + +The initial attribute values to apply (passed through to addAttrs). + These are not merged/cloned. The caller is responsible for isolating user provided values if required.
+
+
+ -
+
+
lazy+ Boolean + + + + +++ + +Whether or not to add attributes lazily (passed through to addAttrs).
+
+
+
_initBase
+
+
+ -
+
+
-
+
+
config+ +
+
+
Internal construction logic for BaseCore.
+Parameters:
+ +-
+
+
-
+
+
config+ Object + + + + +++ + +The constructor configuration object
+
+
+
_initHierarchy
+
+
+ -
+
+
-
+
+
userVals+ +
+
+
Initializes the class hierarchy for the instance, which includes +initializing attributes for each class defined in the class's +static ATTRS property and +invoking the initializer method on the prototype of each class in the hierarchy.
+Parameters:
+ +-
+
+
-
+
+
userVals+ Object + + + + +++ + +Object with configuration property name/value pairs
+
+
+
_initHierarchyData
+
+
+ ()
+
+
+
+
+
+
+
+ private
+
+
+
+
+
+
+
+
+
+
+
+
+ A helper method used by _getClasses and _getAttrCfgs, which determines both +the array of classes and aggregate set of attribute configurations +across the class hierarchy for the instance.
+_isLazyAttr
+
+
+ -
+
+
-
+
+
name+ +
+
+
Checks whether or not the attribute is one which has been +added lazily and still requires initialization.
+Parameters:
+ +-
+
+
-
+
+
name+ String + + + + +++ + +The name of the attribute
+
+
+
Returns:
+ +_joinURL
+
+
+ -
+
+
-
+
+
url+ +
+
+
Joins the root URL to the specified url, normalizing leading/trailing
+/ characters.
Parameters:
+ +-
+
+
-
+
+
url+ String + + + + +++ + +URL to append to the
+rootURL.
+
+
Returns:
+ +Example:
+ +router.set('root', '/foo');
+router._joinURL('bar'); // => '/foo/bar'
+router._joinURL('/bar'); // => '/foo/bar'
+
+router.set('root', '/foo/');
+router._joinURL('bar'); // => '/foo/bar'
+router._joinURL('/bar'); // => '/foo/bar'
+_monitor
+
+
+ -
+
+
-
+
+
what+ +
+
+ -
+
+
eventType+ +
+
+ -
+
+
o+ +
+
+
This is the entry point for the event monitoring system. +You can monitor 'attach', 'detach', 'fire', and 'publish'. +When configured, these events generate an event. click -> +clickattach, clickdetach, click_publish -- these can +be subscribed to like other events to monitor the event +system. Inividual published events can have monitoring +turned on or off (publish can't be turned off before it +it published) by setting the events 'monitor' config.
+Parameters:
+ +-
+
+
-
+
+
what+ String + + + + +++ + +'attach', 'detach', 'fire', or 'publish'
+
+
+ -
+
+
eventType+ String | CustomEvent + + + + +++ + +The prefixed name of the event being monitored, or the CustomEvent object.
+
+
+ -
+
+
o+ Object + + + + +++ + +Information about the event interaction, such as + fire() args, subscription category, publish config
+
+
+
_normalizePath
+
+
+ -
+
+
-
+
+
path+ +
+
+
Returns a normalized path, ridding it of any '..' segments and properly +handling leading and trailing slashes.
+Parameters:
+ +-
+
+
-
+
+
path+ String + + + + +++ + +URL path to normalize.
+
+
+
Returns:
+ +_normAttrVals
+
+
+ -
+
+
-
+
+
valueHash+ +
+
+
Utility method to normalize attribute values. The base implementation +simply merges the hash to protect the original.
+Parameters:
+ +-
+
+
-
+
+
valueHash+ Object + + + + +++ + +An object with attribute name/value pairs
+
+
+
Returns:
+ +_parseQuery
+
+
+ -
+
+
-
+
+
query+ +
+
+
Parses a URL query string into a key/value hash. If Y.QueryString.parse is
+available, this method will be an alias to that.
Parameters:
+ +-
+
+
-
+
+
query+ String + + + + +++ + +Query string to parse.
+
+
+
Returns:
+ +_parseType
+
+
+ ()
+
+
+
+
+
+
+
+ private
+
+
+
+
+
+
+
+
+
+
+
+
+ Returns an array with the detach key (if provided), +and the prefixed event name from _getType +Y.on('detachcategory| menu:click', fn)
+_preInitEventCfg
+
+
+ -
+
+
-
+
+
config+ +
+
+
Handles the special on, after and target properties which allow the user to +easily configure on and after listeners as well as bubble targets during +construction, prior to init.
+Parameters:
+ +-
+
+
-
+
+
config+ Object + + + + +++ + +The user configuration object
+
+
+
_protectAttrs
+
+
+ -
+
+
-
+
+
attrs+ +
+
+
Utility method to protect an attribute configuration +hash, by merging the entire object and the individual +attr config objects.
+Parameters:
+ +-
+
+
-
+
+
attrs+ Object + + + + +++ + +A hash of attribute to configuration object pairs.
+
+
+
Returns:
+ +_publish
+
+
+ -
+
+
-
+
+
fullType+ +
+
+ -
+
+
etOpts+ +
+
+ -
+
+
ceOpts+ +
+
+
The low level event publish implementation. It expects all the massaging to have been done
+outside of this method. e.g. the type to fullType conversion. It's designed to be a fast
+path publish, which can be used by critical code paths to improve performance.
Parameters:
+ +-
+
+
-
+
+
fullType+ String + + + + +++ + +The prefixed type of the event to publish.
+
+
+ -
+
+
etOpts+ Object + + + + +++ + +The EventTarget specific configuration to mix into the published event.
+
+
+ -
+
+
ceOpts+ Object + + + + +++ + +The publish specific configuration to mix into the published event.
+
+
+
Returns:
+ +etOpts or ceOpts, this will
+be the default CustomEvent instance, and can be configured independently.
+
+ _queue
+
+
+ ()
+
+
+
+
+
+
+
+ protected
+
+
+
+
+
+
+
+ chainable
+
+
+
+
+
+
+ Queues up a _save() call to run after all previously-queued calls have
+finished.
This is necessary because if we make multiple _save() calls before the
+first call gets dispatched, then both calls will dispatch to the last call's
+URL.
All arguments passed to _queue() will be passed on to _save() when the
+queued function is executed.
_resolvePath
+
+
+ -
+
+
-
+
+
path+ +
+
+
Returns the normalized result of resolving the path against the current
+path. Falsy values for path will return just the current path.
Parameters:
+ +-
+
+
-
+
+
path+ String + + + + +++ + +URL path to resolve.
+
+
+
Returns:
+ +_resolveURL
+
+
+ -
+
+
-
+
+
url+ +
+
+
Resolves the specified URL against the current URL.
+ +This method resolves URLs like a browser does and will always return an +absolute URL. When the specified URL is already absolute, it is assumed to +be fully resolved and is simply returned as is. Scheme-relative URLs are +prefixed with the current protocol. Relative URLs are giving the current +URL's origin and are resolved and normalized against the current path root.
+Parameters:
+ +-
+
+
-
+
+
url+ String + + + + +++ + +URL to resolve.
+
+
+
Returns:
+ +_save
+
+
+ -
+
+
-
+
+
[url]+ +
+
+ -
+
+
[replace=false]+ +
+
+
Saves a history entry using either pushState() or the location hash.
This method enforces the same-origin security constraint; attempting to save
+a url that is not from the same origin as the current URL will result in
+an error.
_set
+
+
+ -
+
+
-
+
+
name+ +
+
+ -
+
+
val+ +
+
+ -
+
+
[opts]+ +
+
+
Allows setting of readOnly/writeOnce attributes. See set for argument details.
+Parameters:
+ + +Returns:
+ +_setAttr
+
+
+ -
+
+
-
+
+
name+ +
+
+ -
+
+
value+ +
+
+ -
+
+
[opts]+ +
+
+ -
+
+
force+ +
+
+
Provides the common implementation for the public set and protected _set methods.
+ +See set for argument details.
+Parameters:
+ +-
+
+
-
+
+
name+ String + + + + +++ + +The name of the attribute.
+
+
+ -
+
+
value+ Any + + + + +++ + +The value to set the attribute to.
+
+
+ -
+
+
[opts]+ Object + optional + + + + +++ + +Optional data providing the circumstances for the change.
+
+
+ -
+
+
force+ Boolean + + + + +++ + +If true, allows the caller to set values for +readOnly or writeOnce attributes which have already been set.
+
+
+
Returns:
+ +_setAttrs
+
+
+ -
+
+
-
+
+
attrs+ +
+
+ -
+
+
[opts]+ +
+
+
Implementation behind the public setAttrs method, to set multiple attribute values.
+Parameters:
+ + +Returns:
+ +_setAttrVal
+
+
+ -
+
+
-
+
+
attrName+ +
+
+ -
+
+
subAttrName+ +
+
+ -
+
+
prevVal+ +
+
+ -
+
+
newVal+ +
+
+ -
+
+
[opts]+ +
+
+ -
+
+
[attrCfg]+ +
+
+
Updates the stored value of the attribute in the privately held State object, +if validation and setter passes.
+Parameters:
+ +-
+
+
-
+
+
attrName+ String + + + + +++ + +The attribute name.
+
+
+ -
+
+
subAttrName+ String + + + + +++ + +The sub-attribute name, if setting a sub-attribute property ("x.y.z").
+
+
+ -
+
+
prevVal+ Any + + + + +++ + +The currently stored value of the attribute.
+
+
+ -
+
+
newVal+ Any + + + + +++ + +The value which is going to be stored.
+
+
+ -
+
+
[opts]+ Object + optional + + + + +++ + +Optional data providing the circumstances for the change.
+
+
+ -
+
+
[attrCfg]+ Object + optional + + + + +++ + +Optional config hash for the attribute. This is added for performance along the critical path, +where the calling method has already obtained the config from state.
+
+
+
Returns:
+ +_setRoutes
+
+
+ -
+
+
-
+
+
routes+ +
+
+
Setter for the routes attribute.
Parameters:
+ +-
+
+
-
+
+
routes+ Object[] + + + + +++ + +Array of route objects.
+
+
+
Returns:
+ +_setStateVal
+
+
+ -
+
+
-
+
+
name+ +
+
+ -
+
+
value+ +
+
+
Sets the stored value for the attribute, in either the +internal state object, or the state proxy if it exits
+Parameters:
+ +-
+
+
-
+
+
name+ String + + + + +++ + +The name of the attribute
+
+
+ -
+
+
value+ Any + + + + +++ + +The value of the attribute
+
+
+
_upgradeURL
+
+
+ -
+
+
-
+
+
url+ +
+
+
Upgrades a hash-based URL to a full-path URL, if necessary.
+ +The specified url will be upgraded if its of the same origin as the
+current URL and has a path-like hash. URLs that don't need upgrading will be
+returned as-is.
Parameters:
+ +-
+
+
-
+
+
url+ String + + + + +++ + +The URL to upgrade from hash-based to full-path.
+
+
+
Returns:
+ +Example:
+ +app._upgradeURL('http://example.com/#/foo/'); // => 'http://example.com/foo/';
+addAttr
+
+
+ -
+
+
-
+
+
name+ +
+
+ -
+
+
config+ +
+
+ -
+
+
lazy+ +
+
+
+Adds an attribute with the provided configuration to the host object. +
+ ++The config argument object supports the following properties: +
+ +-
+
- value <Any> +
- The initial value to set on the attribute + +
- valueFn <Function | String> +
-
+
A function, which will return the initial value to set on the attribute. This is useful + for cases where the attribute configuration is defined statically, but needs to + reference the host instance ("this") to obtain an initial value. If both the value and valueFn properties are defined, + the value returned by the valueFn has precedence over the value property, unless it returns undefined, in which + case the value property is used.
+ +valueFn can also be set to a string, representing the name of the instance method to be used to retrieve the value.
+
+
+ - readOnly <boolean> +
- Whether or not the attribute is read only. Attributes having readOnly set to true + cannot be modified by invoking the set method. + +
- writeOnce <boolean> or <string> +
-
+ Whether or not the attribute is "write once". Attributes having writeOnce set to true,
+ can only have their values set once, be it through the default configuration,
+ constructor configuration arguments, or by invoking set.
+
The writeOnce attribute can also be set to the string "initOnly", + in which case the attribute can only be set during initialization + (when used with Base, this means it can only be set during construction)
+
+
+ - setter <Function | String> +
-
+
The setter function used to massage or normalize the value passed to the set method for the attribute. + The value returned by the setter will be the final stored value. Returning + Attribute.INVALID_VALUE, from the setter will prevent + the value from being stored. +
+ +setter can also be set to a string, representing the name of the instance method to be used as the setter function.
+
+
+ - getter <Function | String> +
-
+
+ The getter function used to massage or normalize the value returned by the get method for the attribute. + The value returned by the getter function is the value which will be returned to the user when they + invoke get. +
+ +getter can also be set to a string, representing the name of the instance method to be used as the getter function.
+
+
+ - validator <Function | String> +
-
+
+ The validator function invoked prior to setting the stored value. Returning + false from the validator function will prevent the value from being stored. +
+ +validator can also be set to a string, representing the name of the instance method to be used as the validator function.
+
+
+ - lazyAdd <boolean> +
- Whether or not to delay initialization of the attribute until the first call to get/set it. + This flag can be used to over-ride lazy initialization on a per attribute basis, when adding multiple attributes through + the addAttrs method. + +
The setter, getter and validator are invoked with the value and name passed in as the first and second arguments, and with +the context ("this") set to the host object.
+ +Configuration properties outside of the list mentioned above are considered private properties used internally by attribute, +and are not intended for public use.
+Parameters:
+ +-
+
+
-
+
+
name+ String + + + + +++ + +The name of the attribute.
+
+
+ -
+
+
config+ Object + + + + +++ + +An object with attribute configuration property/value pairs, specifying the configuration for the attribute.
+ ++NOTE: The configuration object is modified when adding an attribute, so if you need +to protect the original values, you will need to merge the object. +
+
+
+ -
+
+
lazy+ Boolean + + + + +++ + +(optional) Whether or not to add this attribute lazily (on the first call to get/set).
+
+
+
Returns:
+ +addAttrs
+
+
+ -
+
+
-
+
+
cfgs+ +
+
+ -
+
+
values+ +
+
+ -
+
+
lazy+ +
+
+
Configures a group of attributes, and sets initial values.
+ ++NOTE: This method does not isolate the configuration object by merging/cloning. +The caller is responsible for merging/cloning the configuration object if required. +
+Parameters:
+ +-
+
+
-
+
+
cfgs+ Object + + + + +++ + +An object with attribute name/configuration pairs.
+
+
+ -
+
+
values+ Object + + + + +++ + +An object with attribute name/value pairs, defining the initial values to apply. +Values defined in the cfgs argument will be over-written by values in this argument unless defined as read only.
+
+
+ -
+
+
lazy+ Boolean + + + + +++ + +Whether or not to delay the intialization of these attributes until the first call to get/set. +Individual attributes can over-ride this behavior by defining a lazyAdd configuration property in their configuration. +See addAttr.
+
+
+
Returns:
+ +addTarget
+
+
+ -
+
+
-
+
+
o+ +
+
+
Registers another EventTarget as a bubble target. Bubble order +is determined by the order registered. Multiple targets can +be specified.
+ +Events can only bubble if emitFacade is true.
+ +Included in the event-custom-complex submodule.
+Parameters:
+ +-
+
+
-
+
+
o+ EventTarget + + + + +++ + +the target to add
+
+
+
after
+
+
+ -
+
+
-
+
+
type+ +
+
+ -
+
+
fn+ +
+
+ -
+
+
[context]+ +
+
+ -
+
+
[arg*]+ +
+
+
Subscribe to a custom event hosted by this object. The +supplied callback will execute after any listeners add +via the subscribe method, and after the default function, +if configured for the event, has executed.
+Parameters:
+ +-
+
+
-
+
+
type+ String + + + + +++ + +The name of the event
+
+
+ -
+
+
fn+ Function + + + + +++ + +The callback to execute in response to the event
+
+
+ -
+
+
[context]+ Object + optional + + + + +++ + +Override
+thisobject in callback
+
+ -
+
+
[arg*]+ Any + optional + + + + +++ + +0..n additional arguments to supply to the subscriber
+
+
+
Returns:
+ +attrAdded
+
+
+ -
+
+
-
+
+
name+ +
+
+
Checks if the given attribute has been added to the host
+Parameters:
+ +-
+
+
-
+
+
name+ String + + + + +++ + +The name of the attribute to check.
+
+
+
Returns:
+ +before
+
+
+ ()
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Executes the callback before a DOM event, custom event +or method. If the first argument is a function, it +is assumed the target is a method. For DOM and custom +events, this is an alias for Y.on.
+ +For DOM and custom events: +type, callback, context, 0-n arguments
+ +For methods: +callback, object (method host), methodName, context, 0-n arguments
+Returns:
+ +bubble
+
+
+ -
+
+
-
+
+
evt+ +
+
+
Propagate an event. Requires the event-custom-complex module.
+Parameters:
+ +-
+
+
-
+
+
evt+ CustomEvent + + + + +++ + +the custom event to propagate
+
+
+
Returns:
+ +destroy
+
+
+ ()
+
+
+
+
+ BaseCore
+
+
+
+
+
+
+
+
+
+
+
+
+ chainable
+
+
+
+
+
+
+ Destroy lifecycle method. Invokes destructors for the class hierarchy.
+Returns:
+ +detach
+
+
+ -
+
+
-
+
+
type+ +
+
+ -
+
+
fn+ +
+
+ -
+
+
context+ +
+
+
Detach one or more listeners the from the specified event
+Parameters:
+ +-
+
+
-
+
+
type+ String | Object + + + + +++ + +Either the handle to the subscriber or the + type of event. If the type + is not specified, it will attempt to remove + the listener from all hosted events.
+
+
+ -
+
+
fn+ Function + + + + +++ + +The subscribed function to unsubscribe, if not + supplied, all subscribers will be removed.
+
+
+ -
+
+
context+ Object + + + + +++ + +The custom object passed to subscribe. This is + optional, but if supplied will be used to + disambiguate multiple listeners that are the same + (e.g., you subscribe many object using a function + that lives on the prototype)
+
+
+
Returns:
+ +detachAll
+
+
+ -
+
+
-
+
+
type+ +
+
+
Removes all listeners from the specified event. If the event type +is not specified, all listeners from all hosted custom events will +be removed.
+Parameters:
+ +-
+
+
-
+
+
type+ String + + + + +++ + +The type, or name of the event
+
+
+
dispatch
+
+
+ ()
+
+
+
+
+
+
+
+
+
+
+
+
+
+ chainable
+
+
+
+
+
+
+ Dispatches to the first route handler that matches the current URL, if any.
+ +If dispatch() is called before the ready event has fired, it will
+automatically wait for the ready event before dispatching. Otherwise it
+will dispatch immediately.
dispatch
+
+
+ ()
+
+
+
+
+
+
+
+
+
+
+
+ static
+
+
+
+
+
+
+
+
+ Dispatches to the first route handler that matches the specified path for
+all active router instances.
This provides a mechanism to cause all active router instances to dispatch
+to their route handlers without needing to change the URL or fire the
+history:change or hashchange event.
fire
+
+
+ -
+
+
-
+
+
type+ +
+
+ -
+
+
arguments+ +
+
+
Fire a custom event by name. The callback functions will be executed +from the context specified when the event was created, and with the +following parameters.
+ +If the custom event object hasn't been created, then the event hasn't +been published and it has no subscribers. For performance sake, we +immediate exit in this case. This means the event won't bubble, so +if the intention is that a bubble target be notified, the event must +be published on this object first.
+ +The first argument is the event type, and any additional arguments are +passed to the listeners as parameters. If the first of these is an +object literal, and the event is configured to emit an event facade, +that object is mixed into the event facade and the facade is provided +in place of the original object.
+Parameters:
+ +-
+
+
-
+
+
type+ String | Object + + + + +++ + +The type of the event, or an object that contains +a 'type' property.
+
+
+ -
+
+
arguments+ Object* + + + + +++ + +an arbitrary set of parameters to pass to +the handler. If the first of these is an object literal and the event is +configured to emit an event facade, the event facade will replace that +parameter after the properties the object literal contains are copied to +the event facade.
+
+
+
Returns:
+ +get
+
+
+ -
+
+
-
+
+
name+ +
+
+
Returns the current value of the attribute. If the attribute +has been configured with a 'getter' function, this method will delegate +to the 'getter' to obtain the value of the attribute.
+Parameters:
+ +-
+
+
-
+
+
name+ String + + + + +++ + +The name of the attribute. If the value of the attribute is an Object, +dot notation can be used to obtain the value of a property of the object (e.g.
+get("x.y.z"))
+
+
Returns:
+ +getAttrs
+
+
+ -
+
+
-
+
+
attrs+ +
+
+
Gets multiple attribute values.
+Parameters:
+ +-
+
+
-
+
+
attrs+ Array | boolean + + + + +++ + +Optional. An array of attribute names. If omitted, all attribute values are +returned. If set to true, all attributes modified from their initial values are returned.
+
+
+
Returns:
+ +getEvent
+
+
+ -
+
+
-
+
+
type+ +
+
+ -
+
+
prefixed+ +
+
+
Returns the custom event of the provided type has been created, a +falsy value otherwise
+Parameters:
+ + +Returns:
+ +getPath
+
+
+ ()
+
+
+
+
+ String
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Gets the current route path, relative to the root (if any).
Returns:
+ +getTargets
+
+
+ ()
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Returns an array of bubble targets for this object.
+Returns:
+ +hasRoute
+
+
+ -
+
+
-
+
+
url+ +
+
+
Returns true if this router has at least one route that matches the
+specified URL, false otherwise.
This method enforces the same-origin security constraint on the specified
+url; any URL which is not from the same origin as the current URL will
+always return false.
Parameters:
+ +-
+
+
-
+
+
url+ String + + + + +++ + +URL to match.
+
+
+
Returns:
+ + +init
+
+
+ -
+
+
-
+
+
cfg+ +
+
+
Init lifecycle method, invoked during construction. Sets up attributes +and invokes initializers for the class hierarchy.
+Parameters:
+ +-
+
+
-
+
+
cfg+ Object + + + + +++ + +Object with configuration property name/value pairs
+
+
+
Returns:
+ +match
+
+
+ -
+
+
-
+
+
path+ +
+
+
Returns an array of route objects that match the specified URL path.
+ +This method is called internally to determine which routes match the current +path whenever the URL changes. You may override it if you want to customize +the route matching logic, although this usually shouldn't be necessary.
+ +Each returned route object has the following properties:
+ +-
+
callback: A function or a string representing the name of a function +this router that should be executed when the route is triggered.
+keys: An array of strings representing the named parameters defined in +the route's path specification, if any.
+path: The route's path specification, which may be either a string or +a regex.
+regex: A regular expression version of the route's path specification. +This regex is used to determine whether the route matches a given path.
+
Parameters:
+ +-
+
+
-
+
+
path+ String + + + + +++ + +URL path to match.
+
+
+
Returns:
+ +Example:
+ +router.route('/foo', function () {});
+router.match('/foo');
+// => [{callback: ..., keys: [], path: '/foo', regex: ...}]
+modifyAttr
+
+
+ -
+
+
-
+
+
name+ +
+
+ -
+
+
config+ +
+
+
Updates the configuration of an attribute which has already been added.
+ ++The properties which can be modified through this interface are limited +to the following subset of attributes, which can be safely modified +after a value has already been set on the attribute: readOnly, writeOnce, +broadcast and getter. +
+on
+
+
+ -
+
+
-
+
+
type+ +
+
+ -
+
+
fn+ +
+
+ -
+
+
[context]+ +
+
+ -
+
+
[arg*]+ +
+
+
Subscribe a callback function to a custom event fired by this object or +from an object that bubbles its events to this object.
+ +Callback functions for events published with emitFacade = true will
+receive an EventFacade as the first argument (typically named "e").
+These callbacks can then call e.preventDefault() to disable the
+behavior published to that event's defaultFn. See the EventFacade
+API for all available properties and methods. Subscribers to
+non-emitFacade events will receive the arguments passed to fire()
+after the event name.
To subscribe to multiple events at once, pass an object as the first +argument, where the key:value pairs correspond to the eventName:callback, +or pass an array of event names as the first argument to subscribe to +all listed events with the same callback.
+ +Returning false from a callback is supported as an alternative to
+calling e.preventDefault(); e.stopPropagation();. However, it is
+recommended to use the event methods whenever possible.
Parameters:
+ +-
+
+
-
+
+
type+ String + + + + +++ + +The name of the event
+
+
+ -
+
+
fn+ Function + + + + +++ + +The callback to execute in response to the event
+
+
+ -
+
+
[context]+ Object + optional + + + + +++ + +Override
+thisobject in callback
+
+ -
+
+
[arg*]+ Any + optional + + + + +++ + +0..n additional arguments to supply to the subscriber
+
+
+
Returns:
+ +once
+
+
+ -
+
+
-
+
+
type+ +
+
+ -
+
+
fn+ +
+
+ -
+
+
[context]+ +
+
+ -
+
+
[arg*]+ +
+
+
Listen to a custom event hosted by this object one time.
+This is the equivalent to on except the
+listener is immediatelly detached when it is executed.
Parameters:
+ +-
+
+
-
+
+
type+ String + + + + +++ + +The name of the event
+
+
+ -
+
+
fn+ Function + + + + +++ + +The callback to execute in response to the event
+
+
+ -
+
+
[context]+ Object + optional + + + + +++ + +Override
+thisobject in callback
+
+ -
+
+
[arg*]+ Any + optional + + + + +++ + +0..n additional arguments to supply to the subscriber
+
+
+
Returns:
+ +onceAfter
+
+
+ -
+
+
-
+
+
type+ +
+
+ -
+
+
fn+ +
+
+ -
+
+
[context]+ +
+
+ -
+
+
[arg*]+ +
+
+
Listen to a custom event hosted by this object one time.
+This is the equivalent to after except the
+listener is immediatelly detached when it is executed.
Parameters:
+ +-
+
+
-
+
+
type+ String + + + + +++ + +The name of the event
+
+
+ -
+
+
fn+ Function + + + + +++ + +The callback to execute in response to the event
+
+
+ -
+
+
[context]+ Object + optional + + + + +++ + +Override
+thisobject in callback
+
+ -
+
+
[arg*]+ Any + optional + + + + +++ + +0..n additional arguments to supply to the subscriber
+
+
+
Returns:
+ +parseType
+
+
+ -
+
+
-
+
+
type+ +
+
+ -
+
+
[pre=this._yuievt.config.prefix]+ +
+
+
Takes the type parameter passed to 'on' and parses out the +various pieces that could be included in the type. If the +event type is passed without a prefix, it will be expanded +to include the prefix one is supplied or the event target +is configured with a default prefix.
+Parameters:
+ + +Returns:
+ +publish
+
+
+ -
+
+
-
+
+
type+ +
+
+ -
+
+
opts+ +
+
+
Creates a new custom event of the specified type. If a custom event +by that name already exists, it will not be re-created. In either +case the custom event is returned.
+Parameters:
+ +-
+
+
-
+
+
type+ String + + + + +++ + +the type, or name of the event
+
+
+ -
+
+
opts+ Object + + + + +++ + +optional config params. Valid properties are:
+ +-
+
- + 'broadcast': whether or not the YUI instance and YUI global are notified when the event is fired (false) + +
- + 'bubbles': whether or not this event bubbles (true) + Events can only bubble if emitFacade is true. + +
- + 'context': the default execution context for the listeners (this) + +
- + 'defaultFn': the default function to execute when this event fires if preventDefault was not called + +
- + 'emitFacade': whether or not this event emits a facade (false) + +
- + 'prefix': the prefix for this targets events, e.g., 'menu' in 'menu:click' + +
- + 'fireOnce': if an event is configured to fire once, new subscribers after + the fire will be notified immediately. + +
- + 'async': fireOnce event listeners will fire synchronously if the event has already + fired unless async is true. + +
- + 'preventable': whether or not preventDefault() has an effect (true) + +
- + 'preventedFn': a function that is executed when preventDefault is called + +
- + 'queuable': whether or not this event can be queued during bubbling (false) + +
- + 'silent': if silent is true, debug messages are not provided for this event. + +
- + 'stoppedFn': a function that is executed when stopPropagation is called + + +
- + 'monitored': specifies whether or not this event should send notifications about + when the event has been attached, detached, or published. + +
- + 'type': the event type (valid option if not provided as the first parameter to publish) + +
+
+
Returns:
+ +removeAttr
+
+
+ -
+
+
-
+
+
name+ +
+
+
Removes an attribute from the host object
+Parameters:
+ +-
+
+
-
+
+
name+ String + + + + +++ + +The name of the attribute to be removed.
+
+
+
removeQuery
+
+
+ -
+
+
-
+
+
url+ +
+
+
Removes a query string from the end of the url (if one exists) and returns +the result.
+Parameters:
+ +-
+
+
-
+
+
url+ String + + + + +++ + +URL.
+
+
+
Returns:
+ +removeRoot
+
+
+ -
+
+
-
+
+
url+ +
+
+
Removes the root URL from the front of url (if it's there) and returns
+the result. The returned path will always have a leading /.
Parameters:
+ +-
+
+
-
+
+
url+ String + + + + +++ + +URL.
+
+
+
Returns:
+ +removeTarget
+
+
+ -
+
+
-
+
+
o+ +
+
+
Removes a bubble target
+Parameters:
+ +-
+
+
-
+
+
o+ EventTarget + + + + +++ + +the target to remove
+
+
+
replace
+
+
+ -
+
+
-
+
+
[url]+ +
+
+
Replaces the current browser history entry with a new one, and dispatches to +the first matching route handler, if any.
+ +Behind the scenes, this method uses HTML5 pushState() in browsers that
+support it (or the location hash in older browsers and IE) to change the
+URL.
The specified URL must share the same origin (i.e., protocol, host, and +port) as the current page, or an error will occur.
+Parameters:
+ +-
+
+
-
+
+
[url]+ String + optional + + + + +++ + +URL to set. This URL needs to be of the same origin as + the current URL. This can be a URL relative to the router's
+root+ attribute. If no URL is specified, the page's current URL will be used.
+
+
Example:
+ +// Starting URL: http://example.com/
+
+router.replace('/path/');
+// New URL: http://example.com/path/
+
+router.replace('/path?foo=bar');
+// New URL: http://example.com/path?foo=bar
+
+router.replace('/');
+// New URL: http://example.com/
+reset
+
+
+ -
+
+
-
+
+
name+ +
+
+
Resets the attribute (or all attributes) to its initial value, as long as +the attribute is not readOnly, or writeOnce.
+Parameters:
+ +-
+
+
-
+
+
name+ String + + + + +++ + +Optional. The name of the attribute to reset. If omitted, all attributes are reset.
+
+
+
Returns:
+ +route
+
+
+ -
+
+
-
+
+
path+ +
+
+ -
+
+
callbacks+ +
+
+
Adds a route handler for the specified URL path.
+ +The path parameter may be either a string or a regular expression. If it's
+a string, it may contain named parameters: :param will match any single
+part of a URL path (not including / characters), and *param will match
+any number of parts of a URL path (including / characters). These named
+parameters will be made available as keys on the req.params object that's
+passed to route handlers.
If the path parameter is a regex, all pattern matches will be made
+available as numbered keys on req.params, starting with 0 for the full
+match, then 1 for the first subpattern match, and so on.
Here's a set of sample routes along with URL paths that they match:
+ +-
+
Route:
+ +/photos/:tag/:page- URL:
/photos/kittens/1, params:{tag: 'kittens', page: '1'}
+ - URL:
/photos/puppies/2, params:{tag: 'puppies', page: '2'}
+- URL:
Route:
+ +/file/*path- URL:
/file/foo/bar/baz.txt, params:{path: 'foo/bar/baz.txt'}
+ - URL:
/file/foo, params:{path: 'foo'}
+- URL:
Middleware: Routes also support an arbitrary number of callback
+functions. This allows you to easily reuse parts of your route-handling code
+with different route. This method is liberal in how it processes the
+specified callbacks, you can specify them as separate arguments, or as
+arrays, or both.
If multiple route match a given URL, they will be executed in the order they +were added. The first route that was added will be the first to be executed.
+ +Passing Control: Invoking the next() function within a route callback
+will pass control to the next callback function (if any) or route handler
+(if any). If a value is passed to next(), it's assumed to be an error,
+therefore stopping the dispatch chain, unless that value is: "route",
+which is special case and dispatching will skip to the next route handler.
+This allows middleware to skip any remaining middleware for a particular
+route.
Parameters:
+ +-
+
+
-
+
+
path+ String | RegExp + + + + +++ + +Path to match. May be a string or a regular + expression.
+
+
+ -
+
+
callbacks+ Array | Function | String + + + + multiple + + +++ + +Callback functions to call + whenever this route is triggered. These can be specified as separate + arguments, or in arrays, or both. If a callback is specified as a + string, the named function will be called on this router instance.
+-
+
+
-
+
+
req+ Object + + +++ + +Request object containing information about + the request. It contains the following properties.
+-
+
+
-
+
+
params+ Array | Object + + ++ Captured parameters matched by + the route path specification. If a string path was used and contained + named parameters, then this will be a key/value hash mapping parameter + names to their matched values. If a regex path was used, this will be + an array of subpattern matches starting at index 0 for the full match, + then 1 for the first subpattern match, and so on. ++
+
+ -
+
+
path+ String + + ++ The current URL path. ++
+
+ -
+
+
pendingCallbacks+ Number + + ++ Number of remaining + callbacks the route handler has after this one in the dispatch chain. ++
+
+ -
+
+
pendingRoutes+ Number + + ++ Number of matching routes + after this one in the dispatch chain. ++
+
+ -
+
+
query+ Object + + ++ Query hash representing the URL + query string, if any. Parameter names are keys, and are mapped to + parameter values. ++
+
+ -
+
+
url+ String + + ++ The full URL. ++
+
+ -
+
+
src+ String + + ++ What initiated the dispatch. In an + HTML5 browser, when the back/forward buttons are used, this property + will have a value of "popstate". ++
+
+
+
+ -
+
+
-
+
+
res+ Object + + +++ + +Response object containing methods and + information that relate to responding to a request. It contains the + following properties.
+-
+
+
-
+
+
req+ Object + + ++ Reference to the request object. ++
+
+
+
+ -
+
+
-
+
+
next+ Function + + +++ + +Function to pass control to the next + callback or the next matching route if no more callbacks (middleware) + exist for the current route handler. If you don't call this function, + then no further callbacks or route handlers will be executed, even if + there are more that match. If you do call this function, then the next + callback (if any) or matching route handler (if any) will be called. + All of these functions will receive the same
+reqandresobjects + that were passed to this route (so you can use these objects to pass + data along to subsequent callbacks and routes).-
+
+
-
+
+
[err]+ String + optional + + ++ Optional error which will stop the + dispatch chaining for this+req, unless the value is"route", which + is special cased to jump skip past any callbacks for the current route + and pass control the next route handler. +
+
+
+
+ -
+
+
+
+ -
+
+
Example:
+ +router.route('/photos/:tag/:page', function (req, res, next) {
+ Y.log('Current tag: ' + req.params.tag);
+ Y.log('Current page number: ' + req.params.page);
+});
+
+// Using middleware.
+
+router.findUser = function (req, res, next) {
+ req.user = this.get('users').findById(req.params.user);
+ next();
+};
+
+router.route('/users/:user', 'findUser', function (req, res, next) {
+ // The findUser middleware puts the user object on the req.
+ Y.log('Current user:' req.user.get('name'));
+});
+save
+
+
+ -
+
+
-
+
+
[url]+ +
+
+
Saves a new browser history entry and dispatches to the first matching route +handler, if any.
+ +Behind the scenes, this method uses HTML5 pushState() in browsers that
+support it (or the location hash in older browsers and IE) to change the
+URL and create a history entry.
The specified URL must share the same origin (i.e., protocol, host, and +port) as the current page, or an error will occur.
+Parameters:
+ +-
+
+
-
+
+
[url]+ String + optional + + + + +++ + +URL to set. This URL needs to be of the same origin as + the current URL. This can be a URL relative to the router's
+root+ attribute. If no URL is specified, the page's current URL will be used.
+
+
Example:
+ +// Starting URL: http://example.com/
+
+router.save('/path/');
+// New URL: http://example.com/path/
+
+router.save('/path?foo=bar');
+// New URL: http://example.com/path?foo=bar
+
+router.save('/');
+// New URL: http://example.com/
+set
+
+
+ -
+
+
-
+
+
name+ +
+
+ -
+
+
value+ +
+
+ -
+
+
[opts]+ +
+
+
Sets the value of an attribute.
+Parameters:
+ +-
+
+
-
+
+
name+ String + + + + +++ + +The name of the attribute. If the +current value of the attribute is an Object, dot notation can be used +to set the value of a property within the object (e.g.
+set("x.y.z", 5)).
+
+ -
+
+
value+ Any + + + + +++ + +The value to set the attribute to.
+
+
+ -
+
+
[opts]+ Object + optional + + + + +++ + +Optional data providing the circumstances for the change.
+
+
+
Returns:
+ +setAttrs
+
+
+ -
+
+
-
+
+
attrs+ +
+
+ -
+
+
[opts]+ +
+
+
Sets multiple attribute values.
+Parameters:
+ + +Returns:
+ +subscribe
+
+
+ ()
+
+
+
+
+
+ deprecated
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ subscribe to an event
+toString
+
+
+ ()
+
+
+
+
+ String
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Default toString implementation. Provides the constructor NAME +and the instance guid, if set.
+Returns:
+ +unsubscribe
+
+
+ ()
+
+
+
+
+
+ deprecated
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ detach a listener
+unsubscribeAll
+
+
+ -
+
+
-
+
+
type+ +
+
+
Removes all listeners from the specified event. If the event type +is not specified, all listeners from all hosted custom events will +be removed.
+Parameters:
+ +-
+
+
-
+
+
type+ String + + + + +++ + +The type, or name of the event
+
+
+
Properties
+ + +_allowAdHocAttrs
+ Boolean
+
+
+
+
+ protected
+
+
+
+
+
+
+
+
+ This property controls whether or not instances of this class should +allow users to add ad-hoc attributes through the constructor configuration +hash.
+ +AdHoc attributes are attributes which are not defined by the class, and are +not handled by the MyClass.NONATTRS_CFG
+Default: undefined (false)
+ + + + + +_dispatched
+ Boolean
+
+
+
+
+ protected
+
+
+
+
+
+
+
+
+ Whether or not _dispatch() has been called since this router was
+instantiated.
Default: undefined
+ + + + + +_dispatching
+ Boolean
+
+
+
+
+ protected
+
+
+
+
+
+
+
+
+ Whether or not we're currently in the process of dispatching to routes.
+Default: undefined
+ + + + + +_historyEvents
+ EventHandle
+
+
+
+
+ protected
+
+
+
+
+
+
+
+
+ History event handle for the history:change or hashchange event
+subscription.
_html5
+ Boolean
+
+
+
+
+ protected
+
+
+
+
+
+
+
+
+ Cached copy of the html5 attribute for internal use.
_ready
+ Boolean
+
+
+
+
+ protected
+
+
+
+
+
+
+
+
+ Whether or not the ready event has fired yet.
Default: undefined
+ + + + + +_regexPathParam
+ RegExp
+
+
+
+
+ protected
+
+
+
+
+
+
+
+
+ Regex used to match parameter placeholders in route paths.
+ +Subpattern captures:
+ +-
+
Parameter prefix character. Either a
:for subpath parameters that + should only match a single level of a path, or*for splat parameters + that should match any number of path levels.
+Parameter name, if specified, otherwise it is a wildcard match.
+
_regexUrlOrigin
+ RegExp
+
+
+
+
+ protected
+
+
+
+
+
+
+
+
+ Regex that matches everything before the path portion of a URL (the origin). +This will be used to strip this part of the URL from a string when we +only want the path.
+_regexUrlQuery
+ RegExp
+
+
+
+
+ protected
+
+
+
+
+
+
+
+
+ Regex that matches and captures the query portion of a URL, minus the
+preceding ? character, and discarding the hash portion of the URL if any.
name
+ String
+
+
+ deprecated
+
+
+
+
+
+
+
+
+
+
+ The string used to identify the class of this object.
+Attributes
+ + +destroyed
+ Boolean
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ readonly
+
+
+
+
+ Flag indicating whether or not this object +has been through the destroy lifecycle phase.
+Default: false
+ + + +Fires event destroyedChange
+
+
+ Fires when the value for the configuration attribute destroyed is
+ changed. You can listen for the event using the on method if you
+ wish to be notified before the attribute's value has changed, or
+ using the after method if you wish to be notified after the
+ attribute's value has changed.
+
Parameters:
+ +-
+
-
+
e+ EventFacade + ++ An Event Facade object with the following + attribute-specific properties added: ++ +-
+
-
+
prevVal+ Any +The value of the attribute, prior to it being set.+
+ -
+
newVal+ Any +The value the attribute is to be set to.+
+ -
+
attrName+ String +The name of the attribute being set.+
+ -
+
subAttrName+ String +If setting a property within the attribute's value, the name of the sub-attribute property being set.+
+
+ -
+
html5
+ Boolean
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Whether or not this browser is capable of using HTML5 history.
+ +Setting this to false will force the use of hash-based history even on
+HTML5 browsers, but please don't do this unless you understand the
+consequences.
Fires event html5Change
+
+
+ Fires when the value for the configuration attribute html5 is
+ changed. You can listen for the event using the on method if you
+ wish to be notified before the attribute's value has changed, or
+ using the after method if you wish to be notified after the
+ attribute's value has changed.
+
Parameters:
+ +-
+
-
+
e+ EventFacade + ++ An Event Facade object with the following + attribute-specific properties added: ++ +-
+
-
+
prevVal+ Any +The value of the attribute, prior to it being set.+
+ -
+
newVal+ Any +The value the attribute is to be set to.+
+ -
+
attrName+ String +The name of the attribute being set.+
+ -
+
subAttrName+ String +If setting a property within the attribute's value, the name of the sub-attribute property being set.+
+
+ -
+
initialized
+ Boolean
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ readonly
+
+
+
+
+ Flag indicating whether or not this object +has been through the init lifecycle phase.
+Default: false
+ + + +Fires event initializedChange
+
+
+ Fires when the value for the configuration attribute initialized is
+ changed. You can listen for the event using the on method if you
+ wish to be notified before the attribute's value has changed, or
+ using the after method if you wish to be notified after the
+ attribute's value has changed.
+
Parameters:
+ +-
+
-
+
e+ EventFacade + ++ An Event Facade object with the following + attribute-specific properties added: ++ +-
+
-
+
prevVal+ Any +The value of the attribute, prior to it being set.+
+ -
+
newVal+ Any +The value the attribute is to be set to.+
+ -
+
attrName+ String +The name of the attribute being set.+
+ -
+
subAttrName+ String +If setting a property within the attribute's value, the name of the sub-attribute property being set.+
+
+ -
+
root
+ String
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Absolute root path from which all routes should be evaluated.
+ +For example, if your router is running on a page at
+http://example.com/myapp/ and you add a route with the path /, your
+route will never execute, because the path will always be preceded by
+/myapp. Setting root to /myapp would cause all routes to be
+evaluated relative to that root URL, so the / route would then execute
+when the user browses to http://example.com/myapp/.
Default: `''`
+ + + +Fires event rootChange
+
+
+ Fires when the value for the configuration attribute root is
+ changed. You can listen for the event using the on method if you
+ wish to be notified before the attribute's value has changed, or
+ using the after method if you wish to be notified after the
+ attribute's value has changed.
+
Parameters:
+ +-
+
-
+
e+ EventFacade + ++ An Event Facade object with the following + attribute-specific properties added: ++ +-
+
-
+
prevVal+ Any +The value of the attribute, prior to it being set.+
+ -
+
newVal+ Any +The value the attribute is to be set to.+
+ -
+
attrName+ String +The name of the attribute being set.+
+ -
+
subAttrName+ String +If setting a property within the attribute's value, the name of the sub-attribute property being set.+
+
+ -
+
routes
+ Object[]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Array of route objects.
+ +Each item in the array must be an object with the following properties:
+ +-
+
path: String or regex representing the path to match. See the docs +for theroute()method for more details.
+callbacks: Function or a string representing the name of a +function on this router instance that should be called when the +route is triggered. An array of functions and/or strings may also be +provided. See the docs for theroute()method for more details.
+
This attribute is intended to be used to set routes at init time, or to
+completely reset all routes after init. To add routes after init without
+resetting all existing routes, use the route() method.
Default: `[]`
+ + + +Fires event routesChange
+
+
+ Fires when the value for the configuration attribute routes is
+ changed. You can listen for the event using the on method if you
+ wish to be notified before the attribute's value has changed, or
+ using the after method if you wish to be notified after the
+ attribute's value has changed.
+
Parameters:
+ +-
+
-
+
e+ EventFacade + ++ An Event Facade object with the following + attribute-specific properties added: ++ +-
+
-
+
prevVal+ Any +The value of the attribute, prior to it being set.+
+ -
+
newVal+ Any +The value the attribute is to be set to.+
+ -
+
attrName+ String +The name of the attribute being set.+
+ -
+
subAttrName+ String +If setting a property within the attribute's value, the name of the sub-attribute property being set.+
+
+ -
+
Events
+ + +destroy
+
+
+
+
+
+
+
+
+
+
+
+
+ +Lifecycle event for the destroy phase, +fired prior to destruction. Invoking the preventDefault +method on the event object provided to subscribers will +prevent destruction from proceeding. +
+ ++Subscribers to the "after" moment of this event, will be notified +after destruction is complete (and as a result cannot prevent +destruction). +
+Event Payload:
+ +-
+
+
-
+
+
e+ EventFacade + + + + +++ + +Event object
+
+
+
init
+
+
+
+
+
+
+
+
+
+
+
+
+ +Lifecycle event for the init phase, fired prior to initialization. +Invoking the preventDefault() method on the event object provided +to subscribers will prevent initialization from occuring. +
+ ++Subscribers to the "after" momemt of this event, will be notified +after initialization of the object is complete (and therefore +cannot prevent initialization). +
+Event Payload:
+ +-
+
+
-
+
+
e+ EventFacade + + + + +++ + +Event object, with a cfg property which +refers to the configuration object passed to the constructor.
+
+
+
ready
+
+
+
+
+
+
+
+
+
+
+
+
+ Fired when the router is ready to begin dispatching to route handlers.
+ +You shouldn't need to wait for this event unless you plan to implement some +kind of custom dispatching logic. It's used internally in order to avoid +dispatching to an initial route if a browser history change occurs first.
+Event Payload:
+ +-
+
+
-
+
+
dispatched+ Boolean + + + + +++ + +
+trueif routes have already been dispatched + (most likely due to a history change).
+
+