eZ.PlatformUIApp Class
PlatformUI Application
Constructor
eZ.PlatformUIApp
()
Item Index
Methods
- _addAttrs
- _addLazyAttr
- _addOutOfOrder
- _afterActiveViewChange
- _afterContainerChange
- _afterHistoryChange
- _aggregateAttrs
- _attachView
- _attrCfgHash
- _baseDestroy
- _baseInit
- _cloneDefaultValue
- _contentRoute
- _decode
- _defAttrChangeFn
- _defDestroyFn
- _defInitFn
- _defNavigateFn
- _defReadyFn
- _dequeue
- _destroyContainer
- _destroyHierarchy
- _detachView
- _dispatch
- _dispatchConfig
- _filterAdHocAttrs
- _fireAppReadyEvent
- _fireAttrChange
- _getAttr
- _getAttrCfg
- _getAttrCfgs
- _getAttrInitVal
- _getAttrs
- _getClasses
- _getContainer
- _getFullType
- _getHashPath
- _getInstanceAttrCfgs
- _getOrigin
- _getParams
- _getParamValues
- _getPath
- _getPathRoot
- _getQuery
- _getRegex
- _getRequest
- _getResponse
- _getRoutes
- _getStateVal
- _getType
- _getURL
- _getViewContainer
- _hasPotentialSubscribers
- _hasSameOrigin
- _initAttrHost
- _initAttribute
- _initAttrs
- _initBase
- _initHierarchy
- _initHierarchyData
- _initHtml5
- _isChildView
- _isLazyAttr
- _isLinkSameOrigin
- _isParentView
- _joinURL
- _monitor
- _navigate
- _normalizePath
- _normAttrVals
- _onLinkClick
- _onPjaxIOComplete
- _onPjaxIOEnd
- _parseQuery
- _parseType
- _pathHasRoot
- _pjaxBindUI
- _preInitEventCfg
- _protectAttrs deprecated
- _publish
- _queue
- _resolvePath
- _resolveURL
- _save
- _set
- _setAttr
- _setAttrs
- _setAttrVal
- _setGlobals
- _setParams
- _setRoutes
- _setStateVal
- _setTransitions
- _uiSetActiveView
- _upgradeURL
- addAttr
- addAttrs
- addTarget
- after
- attachEvents
- attrAdded
- before
- bubble
- create
- createView
- destroy
- detach
- detachAll
- detachEvents
- dispatch
- fire
- get
- getAttrs
- getContent
- getEvent
- getLanguageName
- getPath
- getTargets
- getViewInfo
- hasRoute
- init
- initializer
- loadContent
- match
- modifyAttr
- navigate
- on
- once
- onceAfter
- param
- parseType
- publish
- remove
- removeAttr
- removeQuery
- removeRoot
- removeTarget
- render
- renderSideView
- renderView
- replace
- reset
- route
- save
- set
- setAttrs
- showContent
- showView
- subscribe deprecated
- toString
- unsubscribe deprecated
- unsubscribeAll deprecated
- upgrade
Properties
Attributes
- activeView
- addPjaxParam
- allowFallThrough
- anonymousUserId
- apiRoot
- assetRoot
- capi
- config
- container
- contentCreationDefaultLanguageCode
- contentSelector
- destroyed
- html5
- initialized
- interfaceLanguages
- linkSelector
- localesMap
- navigateOnHash
- params
- root
- routes
- scrollToTop
- serverRouting
- systemLanguageList
- timeout
- titleSelector
- transitions
- viewContainer
Methods
_addAttrs
-
cfgs
-
values
-
lazy
Parameters:
-
cfgs
ObjectAn object with attribute name/configuration pairs. -
values
ObjectAn 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
BooleanWhether 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]
Parameters:
-
name
ObjectThe name of the attribute -
[lazyCfg]
Object optionalOptional config hash for the attribute. This is added for performance along the critical path, where the calling method has already obtained lazy config from state.
_addOutOfOrder
-
name
-
cfg
Parameters:
-
name
Stringattribute name -
cfg
Objectattribute configuration
_afterActiveViewChange
-
e
activeViewChange
event (which is fired when the
activeView
attribute changes) by detaching the old view, attaching the new
view.
The activeView
attribute is read-only, so the public API to change its
value is through the showView()
method.
Parameters:
_afterContainerChange
()
protected
containerChange
events. Detaches event handlers from the old
container (if any) and attaches them to the new container.
Right now the container
attr is initOnly so this event should only ever
fire the first time the container is created, but in the future (once Y.App
can handle it) we may allow runtime container changes.
_afterHistoryChange
-
e
history:change
and hashchange
events.
Parameters:
_aggregateAttrs
-
allAttrs
Parameters:
-
allAttrs
ArrayAn array of ATTRS definitions across classes in the hierarchy (subclass first, Base last)
Returns:
_attachView
-
view
-
prepend=false
viewContainer
, and
assign it to the instance
property of the associated view info metadata.
Parameters:
-
view
ViewView to attach. -
prepend=false
BooleanWhether the view should be prepended instead of appended to theviewContainer
.
_attrCfgHash
()
private
_baseDestroy
()
private
_baseInit
()
private
_cloneDefaultValue
-
cfg
Parameters:
-
cfg
Object
_contentRoute
-
req
-
res
-
next
loadContent()
middleware.
Parameters:
-
req
ObjectRequest object. -
res
ObjectResponse Object. -
next
FunctionFunction to pass control to the next route callback.
_decode
-
string
decodeURIComponent
that also converts +
chars into
spaces.
Parameters:
-
string
StringString to decode.
Returns:
_defAttrChangeFn
-
e
-
eventFastPath
Parameters:
-
e
EventFacadeThe event object for attribute change events. -
eventFastPath
BooleanWhether or not we're using this as a fast path in the case of no listeners or not
_defInitFn
-
e
Parameters:
-
e
EventFacadeEvent object, with a cfg property which refers to the configuration object passed to the constructor.
_dequeue
()
protected
chainable
_save()
call off the queue and executes it. Does
nothing if the queue is empty.
_destroyContainer
()
protected
viewContainer
and
checks to make sure not to remove and purge the <body>
.
_destroyHierarchy
()
private
_detachView
-
view
Parameters:
-
view
ViewView to detach.
_dispatch
-
req
-
res
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).
Parameters:
-
req
ObjectRequest object. -
res
StringResponse object.
_dispatchConfig
()
protected
Dispatches the config
attribute value so that the app is configured
accordingly. The values consumed by the app are removed from the
configuration.
_filterAdHocAttrs
-
allAttrs
-
userVals
Parameters:
-
allAttrs
ObjectThe 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
ObjectThe config object passed in by the user, from which adhoc attrs are to be filtered.
Returns:
_fireAppReadyEvent
()
private
Fires the custom ez:yui-app:ready
DOM event. It is dispatched
from the document
object.
_fireAttrChange
-
attrName
-
subAttrName
-
currVal
-
newVal
-
opts
-
[cfg]
Parameters:
-
attrName
StringThe name of the attribute -
subAttrName
StringThe full path of the property being changed, if this is a sub-attribute value being change. Otherwise null. -
currVal
AnyThe current value of the attribute -
newVal
AnyThe new value of the attribute -
opts
ObjectAny additional event data to mix into the attribute change event's event facade. -
[cfg]
Object optionalThe attribute config stored in State, if already available.
_getAttr
-
name
Parameters:
-
name
StringThe name of the attribute.
Returns:
_getAttrCfg
-
name
Parameters:
-
name
StringOptional. The attribute name. If not provided, the method will return the configuration for all attributes.
Returns:
_getAttrCfgs
()
Object
protected
Returns:
_getAttrInitVal
-
attr
-
cfg
-
initValues
Parameters:
-
attr
StringThe name of the attribute -
cfg
ObjectThe attribute configuration object -
initValues
ObjectThe object with simple and complex attribute name/value pairs returned from _normAttrVals
Returns:
_getAttrs
-
attrs
Parameters:
-
attrs
String | BooleanOptional. 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:
_getContainer
-
value
container
attribute.
Parameters:
-
value
Node | NullCurrent attribute value.
Returns:
_getFullType
-
type
Parameters:
-
type
StringThe short type to prefix
Returns:
_getHashPath
-
[hash]
Parameters:
-
[hash]
String optionalHash fragment to resolve into a path. By default this will be the hash from the current URL.
Returns:
_getInstanceAttrCfgs
-
allCfgs
addAttrs
,
from the static cached ATTRS for the class.
Parameters:
-
allCfgs
ObjectThe 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:
addAttrs
.
_getOrigin
()
String
protected
Returns:
Example:
http://example.com
_getParams
()
Object
protected
params
attribute.
Returns:
name
-> RegExp | Function.
_getParamValues
-
route
-
path
route
and path
, suitable to use
form req.params
.
**Note:** This method will return false
if a named param handler rejects a
param value.
Parameters:
-
route
ObjectThe route to get param values for. -
path
StringThe route path (root removed) that provides the param values.
Returns:
name
-> value
for named params processed by this
router's param handlers, or an array of matches for a route with unnamed
params. If a named param handler rejects a value, then false
will be
returned.
_getPath
()
String
protected
Returns:
_getPathRoot
()
String
protected
Returns:
_getQuery
()
String
protected
Returns:
_getRegex
-
path
-
keys
Parameters:
-
path
String | RegExpRoute path specification. -
keys
ArrayArray reference to which route parameter names will be added.
Returns:
_getRequest
-
src
Y.Router
's _getRequest()
method and adds a reference
to this app instance at req.app
.
Parameters:
-
src
StringWhat initiated the URL change and need for the request.
Returns:
_getResponse
-
req
Parameters:
-
req
ObjectRequest object.
Returns:
_getRoutes
()
Object
protected
routes
attribute.
Returns:
_getStateVal
-
name
-
[cfg]
Parameters:
-
name
StringThe name of the attribute -
[cfg]
Object optionalOptional 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:
_getType
()
private
_getURL
()
String
protected
Returns:
_getViewContainer
-
value
viewContainer
attribute.
Parameters:
-
value
Node | NullCurrent attribute value.
Returns:
_hasPotentialSubscribers
-
fullType
Parameters:
-
fullType
StringThe fully prefixed type name
Returns:
_hasSameOrigin
-
url
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
StringURL to compare origin with the current URL.
Returns:
_initAttrHost
-
attrs
-
values
-
lazy
Parameters:
-
attrs
ObjectThe 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
ObjectThe 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
BooleanWhether or not to add attributes lazily (passed through to addAttrs).
_initAttribute
()
private
_initAttrs
-
attrs
-
values
-
lazy
Parameters:
-
attrs
ObjectThe 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
ObjectThe 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
BooleanWhether or not to add attributes lazily (passed through to addAttrs).
_initBase
-
config
Parameters:
-
config
ObjectThe constructor configuration object
_initHierarchy
-
userVals
Parameters:
-
userVals
ObjectObject with configuration property name/value pairs
_initHierarchyData
()
private
_initHtml5
()
Boolean
protected
html5
attribute.
The value returned is dependent on the value of the serverRouting
attribute. When serverRouting
is explicit set to false
(not just falsy),
the default value for html5
will be set to false
for *all* browsers.
When serverRouting
is true
or undefined
the returned value will be
dependent on the browser's capability of using HTML5 history.
Returns:
_isChildView
-
view
-
parent
view
is configured as a child of the specified
parent
view. This requires both views to be either named-views, or view
instances created using configuration data that exists in the views
object, e.g. created by the createView()
or showView()
method.
Parameters:
Returns:
_isLazyAttr
-
name
Parameters:
-
name
StringThe name of the attribute
Returns:
_isLinkSameOrigin
-
link
href
is of
the same origin as the page's current location.
This normalize browser inconsistencies with how the port
is reported for
anchor elements (IE reports a value for the default port, e.g. "80").
Parameters:
-
link
NodeThe anchor element to test whether itshref
is of the same origin as the page's current location.
Returns:
href
is of the same origin as
the page's current location.
_isParentView
-
view
-
parent
view
is configured as the parent of the
specified child
view. This requires both views to be either named-views,
or view instances created using configuration data that exists in the
views
object, e.g. created by the createView()
or showView()
method.
Parameters:
Returns:
_joinURL
-
url
root
URL to the specified _url_, normalizing leading/trailing
/
characters.
Parameters:
-
url
StringURL to append to theroot
URL.
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
Parameters:
-
what
String'attach', 'detach', 'fire', or 'publish' -
eventType
String | CustomEventThe prefixed name of the event being monitored, or the CustomEvent object. -
o
ObjectInformation about the event interaction, such as fire() args, subscription category, publish config
_normalizePath
-
path
Parameters:
-
path
StringURL path to normalize.
Returns:
_normAttrVals
-
valueHash
Parameters:
-
valueHash
ObjectAn object with attribute name/value pairs
Returns:
_onLinkClick
-
e
linkSelector
.
This will attempt to enhance the navigation to the link element's href
by
passing the URL to the _navigate()
method. When the navigation is being
enhanced, the default action is prevented.
If the user clicks a link with the middle/right mouse buttons, or is holding
down the Ctrl or Command keys, this method's behavior is not applied and
allows the native behavior to occur. Similarly, if the router is not capable
or handling the URL because no route-handlers match, the link click will
behave natively.
Parameters:
_onPjaxIOComplete
-
id
-
ioResponse
-
details
Y.io()
response and puts it on the
route's response object.
Parameters:
-
id
StringTheY.io
transaction id. -
ioResponse
ObjectTheY.io
response object. -
details
ObjectExtra details carried through fromloadContent()
.
_onPjaxIOEnd
-
id
-
details
Parameters:
-
id
StringTheY.io
transaction id. -
details
ObjectExtra details carried through fromloadContent()
.
_parseQuery
-
query
Y.QueryString.parse
is
available, this method will be an alias to that.
Parameters:
-
query
StringQuery string to parse.
Returns:
_parseType
()
private
_pathHasRoot
-
root
-
path
true
when the specified path
is semantically within the
specified root
path.
If the root
does not end with a trailing slash ("/"), one will be added
before the path
is evaluated against the root path.
Parameters:
-
root
StringRoot path used to evaluate whether the specificedpath
is semantically within. A trailing slash ("/") will be added if it does not already end with one. -
path
StringPath to evaluate for containing the specifiedroot
.
Returns:
path
is semantically within the
root
path.
Example:
this._pathHasRoot('/app', '/app/foo'); // => true
this._pathHasRoot('/app/', '/app/foo'); // => true
this._pathHasRoot('/app/', '/app/'); // => true
this._pathHasRoot('/app', '/foo/bar'); // => false
this._pathHasRoot('/app/', '/foo/bar'); // => false
this._pathHasRoot('/app/', '/app'); // => false
this._pathHasRoot('/app', '/app'); // => false
_pjaxBindUI
()
protected
linkSelector
to
the _onLinkClick()
handler.
By default this method will only be called if the browser is capable of
using HTML5 history.
_preInitEventCfg
-
config
Parameters:
-
config
ObjectThe user configuration object
_protectAttrs
-
attrs
Parameters:
-
attrs
ObjectA hash of attribute to configuration object pairs.
Returns:
_publish
-
fullType
-
etOpts
-
ceOpts
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
StringThe prefixed type of the event to publish. -
etOpts
ObjectThe EventTarget specific configuration to mix into the published event. -
ceOpts
ObjectThe 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
_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
path
against the current
path. Falsy values for path
will return just the current path.
Parameters:
-
path
StringURL path to resolve.
Returns:
_resolveURL
-
url
Parameters:
-
url
StringURL to resolve.
Returns:
_save
-
[url]
-
[replace=false]
pushState()
or the location hash,
or gracefully-degrade to sending a request to the server causing a full-page
reload.
Overrides Router's _save()
method to preform graceful-degradation when the
app's serverRouting
is true
and html5
is false
by updating the full
URL via standard assignment to window.location
or by calling
window.location.replace()
; both of which will cause a request to the
server resulting in a full-page reload.
Otherwise this will just delegate off to Router's _save()
method allowing
the client-side enhanced routing to occur.
Parameters:
-
[url]
String optionalURL for the history entry. -
[replace=false]
Boolean optionalIftrue
, the current history entry will be replaced instead of a new one being added.
_set
-
name
-
val
-
[opts]
Parameters:
-
name
StringThe name of the attribute. -
val
AnyThe value to set the attribute to. -
[opts]
Object optionalOptional data providing the circumstances for the change.
Returns:
_setAttr
-
name
-
value
-
[opts]
-
force
Parameters:
-
name
StringThe name of the attribute. -
value
AnyThe value to set the attribute to. -
[opts]
Object optionalOptional data providing the circumstances for the change. -
force
BooleanIf true, allows the caller to set values for readOnly or writeOnce attributes which have already been set.
Returns:
_setAttrs
-
attrs
-
[opts]
Parameters:
-
attrs
ObjectAn object with attributes name/value pairs. -
[opts]
Object optionalOptional data providing the circumstances for the change
Returns:
_setAttrVal
-
attrName
-
subAttrName
-
prevVal
-
newVal
-
[opts]
-
[attrCfg]
Parameters:
-
attrName
StringThe attribute name. -
subAttrName
StringThe sub-attribute name, if setting a sub-attribute property ("x.y.z"). -
prevVal
AnyThe currently stored value of the attribute. -
newVal
AnyThe value which is going to be stored. -
[opts]
Object optionalOptional data providing the circumstances for the change. -
[attrCfg]
Object optionalOptional 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:
_setGlobals
()
private
Registers the Y
sandbox object and the app instance in the global
eZ.YUI
namespace.
_setParams
-
params
params
attribute.
Parameters:
-
params
ObjectMap in the form:name
-> RegExp | Function.
Returns:
name
-> RegExp | Function.
_setRoutes
-
routes
routes
attribute.
Parameters:
-
routes
ObjectArray of route objects.
Returns:
_setStateVal
-
name
-
value
Parameters:
-
name
StringThe name of the attribute -
value
AnyThe value of the attribute
_setTransitions
-
transitions
transitions
attribute.
When specified as true
, the defaults will be use as specified by the
transitions
prototype property.
Parameters:
-
transitions
Boolean | ObjectThe newtransitions
attribute value.
Returns:
_uiSetActiveView
-
newView
-
[oldView]
-
[options]
activeView
by attaching the
newView
to this app, and detaching the oldView
from this app using any
specified options
.
The newView
is attached to the app by rendering it to the viewContainer
,
and making this app a bubble target of its events.
The oldView
is detached from the app by removing it from the
viewContainer
, and removing this app as a bubble target for its events.
The oldView
will either be preserved or properly destroyed.
**Note:** The activeView
attribute is read-only and can be changed by
calling the showView()
method.
Parameters:
-
newView
ViewThe View which is now this app'sactiveView
. -
[oldView]
View optionalThe View which was this app'sactiveView
. -
[options]
Object optionalOptional object containing any of the following properties:-
[callback]
Function optionalOptional callback function to call after new
activeView
is ready to use, the function will be passed:-
view
ViewA reference to the newactiveView
.
-
-
[prepend=false]
Boolean optionalWhether the
view
should be prepended instead of appended to theviewContainer
. -
[render]
Boolean optionalWhether the
view
should be rendered. Note: If no value is specified, a view instance will only be rendered if it's newly created by this method. -
[update=false]
Boolean optionalWhether an existing view should have its attributes updated by passing the
config
object to itssetAttrs()
method. Note: This option does not have an effect if theview
instance is created as a result of calling this method.
-
_upgradeURL
-
url
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
StringThe 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
StringThe name of the attribute. -
config
ObjectAn 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
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
ObjectAn object with attribute name/configuration pairs. -
values
ObjectAn 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
BooleanWhether 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
Parameters:
-
o
EventTargetthe target to add
after
-
type
-
fn
-
[context]
-
[arg*]
Parameters:
-
type
StringThe name of the event -
fn
FunctionThe callback to execute in response to the event -
[context]
Object optionalOverridethis
object in callback -
[arg*]
Any optional0..n additional arguments to supply to the subscriber
Returns:
attachEvents
-
[events]
events
attribute when the view is initialized.
You may override this method to customize the event attaching logic.
Parameters:
-
[events]
Object optionalHash of events to attach. See the docs for theevents
attribute for details on the format. If not specified, this view'sevents
property will be used.
attrAdded
-
name
Parameters:
-
name
StringThe name of the attribute to check.
Returns:
before
()
Returns:
bubble
-
evt
Parameters:
-
evt
CustomEventthe custom event to propagate
Returns:
create
-
[container]
containerTemplate
property, and is _not_ added to the DOM automatically.
You may override this method to customize how the container node is created
(such as by rendering it from a custom template format). Your method must
return a Y.Node
instance.
Parameters:
-
[container]
HTMLElement | Node | String optionalSelector string,Y.Node
instance, or DOM element to use at the container node.
Returns:
createView
-
name
-
[config]
name
to look up
the view info metadata defined in the views
object. The passed-in config
object is passed to the view constructor function.
This function also maps a view instance back to its view info metadata.
Parameters:
-
name
StringThe name of a view defined on theviews
object. -
[config]
Object optionalThe configuration object passed to the view constructor function when creating the new view instance.
Returns:
destroy
-
[options]
remove
property to destroy the container as well.
Parameters:
-
[options]
Object optionalOptions.-
[remove=false]
Boolean optionalIf
true
, this View's container will be removed from the DOM and destroyed as well.
-
detach
-
type
-
fn
-
context
Parameters:
-
type
String | ObjectEither 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
FunctionThe subscribed function to unsubscribe, if not supplied, all subscribers will be removed. -
context
ObjectThe 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
Parameters:
-
type
StringThe type, or name of the event
detachEvents
()
chainable
attachEvents()
.
dispatch
()
chainable
dispatch()
is called before the ready
event has fired, it will
automatically wait for the ready
event before dispatching. Otherwise it
will dispatch immediately.
fire
-
type
-
arguments
Parameters:
-
type
String | ObjectThe type of the event, or an object that contains a 'type' property. -
arguments
Objectan 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
Parameters:
-
name
StringThe 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
Parameters:
-
attrs
String | BooleanOptional. 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:
getContent
-
responseText
contentSelector
attribute as a CSS
selector. If contentSelector
is null
, the entire response will be
returned.
The return value is an object containing two properties:
* node
: A Y.Node
instance for a document fragment containing the
extracted HTML content.
* title
: The title of the HTML page, if any, extracted using the
titleSelector
attribute (which defaults to looking for a <title>
element). If titleSelector
is not set or if a title could not be
found, this property will be undefined
.
Parameters:
-
responseText
StringRaw Ajax response text.
Returns:
getEvent
-
type
-
prefixed
Parameters:
-
type
Stringthe type, or name of the event -
prefixed
Stringif true, the type is prefixed already
Returns:
getLanguageName
-
languageCode
Returns the language name of the language with the given
languageCode
. If no language is found with this code, the language
code is returned.
Parameters:
-
languageCode
String
Returns:
getPath
()
String
Returns:
getTargets
()
Returns:
getViewInfo
-
view
views
object.
Parameters:
-
view
View | StringView instance, or name of a view defined on theviews
object.
Returns:
undefined
if the view is
not registered.
hasRoute
-
url
true
if this router has at least one route that matches the
specified URL, false
otherwise. This also checks that any named param
handlers also accept app param values in the url
.
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
StringURL to match.
Returns:
true
if there's at least one matching route, false
otherwise.
init
-
cfg
Parameters:
-
cfg
ObjectObject with configuration property name/value pairs
Returns:
initializer
()
Initializes the application.
loadContent
-
req
-
res
-
next
req.ioURL
: The full URL that was used to make the Y.io()
XHR. This
may contain "pjax=1"
if the addPjaxParam
option is set.
- res.content
: An object containing node
and title
properties for
the content extracted from the server's response. See getContent()
for
more details.
- res.ioResponse
: The full Y.io()
response object. This is useful if
you need access to the XHR's response status
or HTTP headers.
Parameters:
-
req
ObjectRequest object. -
res
ObjectResponse Object. -
next
FunctionFunction to pass control to the next route callback.
Example:
router.route('/foo/', 'loadContent', function (req, res, next) {
Y.one('container').setHTML(res.content.node);
Y.config.doc.title = res.content.title;
});
match
-
path
root
, then the specified path
_must_ be
semantically within the root
path to match any routes.
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
StringURL path to match. This should be an absolute path that starts with a slash: "/".
Returns:
Example:
router.route('/foo', function () {});
router.match('/foo');
// => [{callback: ..., keys: [], path: '/foo', regex: ...}]
modifyAttr
-
name
-
config
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.
Note: New attributes cannot be added using this interface. New attributes must be added using {{#crossLink "AttributeCore/addAttr:method"}}addAttr{{/crossLink}}, or an appropriate manner for a class which utilises Attributes (e.g. the {{#crossLink "Base/ATTRS:property"}}ATTRS{{/crossLink}} property in {{#crossLink "Base"}}Base{{/crossLink}}).
Parameters:
-
name
StringThe name of the attribute whose configuration is to be updated. -
config
ObjectAn object with configuration property/value pairs, specifying the configuration properties to modify.
on
-
type
-
fn
-
[context]
-
[arg*]
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.
this.on({
"attrChange" : this._onAttrChange,
"change" : this._onChange
});
You can also pass an array of event names as the first argument to
subscribe to all listed events with the same callback.
this.on([ "change", "attrChange" ], this._onChange);
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
StringThe name of the event -
fn
FunctionThe callback to execute in response to the event -
[context]
Object optionalOverridethis
object in callback -
[arg*]
Any optional0..n additional arguments to supply to the subscriber
Returns:
once
-
type
-
fn
-
[context]
-
[arg*]
on
except the
listener is immediatelly detached when it is executed.
Parameters:
-
type
StringThe name of the event -
fn
FunctionThe callback to execute in response to the event -
[context]
Object optionalOverridethis
object in callback -
[arg*]
Any optional0..n additional arguments to supply to the subscriber
Returns:
onceAfter
-
type
-
fn
-
[context]
-
[arg*]
after
except the
listener is immediatelly detached when it is executed.
Parameters:
-
type
StringThe name of the event -
fn
FunctionThe callback to execute in response to the event -
[context]
Object optionalOverridethis
object in callback -
[arg*]
Any optional0..n additional arguments to supply to the subscriber
Returns:
param
-
name
-
handler
req.params
to use named params, but
still applying extra validation or formatting to the param values parsed
from the URL.
If a param handler regex or function returns a value of false
, null
,
undefined
, or NaN
, the current route will not match and be skipped. All
other return values will be used in place of the original param value parsed
from the URL.
Parameters:
-
name
StringName of the param used in route paths. -
handler
Function | RegExpFunction to invoke or regular expression toexec()
during route dispatching whose return value is used as the new param value. Values offalse
,null
,undefined
, orNaN
will cause the current route to not match and be skipped. When a function is specified, it will be invoked in the context of this instance with the following parameters:-
value
StringThe current param value parsed from the URL.
-
name
StringThe name of the param.
-
Example:
router.param('postId', function (value) {
return parseInt(value, 10);
});
router.param('username', /^\w+$/);
router.route('/posts/:postId', function (req) {
Y.log('Post: ' + req.params.id);
});
router.route('/users/:username', function (req) {
// req.params.username
is an array because the result of calling
// exec()
on the regex is assigned as the param's value.
Y.log('User: ' + req.params.username[0]);
});
router.route('*', function () {
Y.log('Catch-all no routes matched!');
});
// URLs which match routes:
router.save('/posts/1'); // => "Post: 1"
router.save('/users/ericf'); // => "User: ericf"
// URLs which do not match routes because params fail validation:
router.save('/posts/a'); // => "Catch-all no routes matched!"
router.save('/users/ericf,rgrove'); // => "Catch-all no routes matched!"
parseType
-
type
-
[pre]
Parameters:
-
type
Stringthe type -
[pre]
String optionalThe prefix. Defaults to this._yuievt.config.prefix
Returns:
publish
-
type
-
opts
Parameters:
-
type
Stringthe type, or name of the event -
opts
Objectoptional config params. Valid properties are:-
[broadcast=false]
Boolean optionalwhether or not the YUI instance and YUI global are notified when the event is fired.
-
[bubbles=true]
Boolean optionalWhether or not this event bubbles. Events can only bubble if
emitFacade
is true. -
[context=this]
Object optionalthe default execution context for the listeners.
-
[defaultFn]
Function optionalthe default function to execute when this event fires if preventDefault was not called.
-
[emitFacade=false]
Boolean optionalwhether or not this event emits a facade.
-
[prefix]
String optionalthe prefix for this targets events, e.g., 'menu' in 'menu:click'.
-
[fireOnce=false]
Boolean optionalif an event is configured to fire once, new subscribers after the fire will be notified immediately.
-
[async=false]
Boolean optionalfireOnce event listeners will fire synchronously if the event has already fired unless
async
istrue
. -
[preventable=true]
Boolean optionalwhether or not
preventDefault()
has an effect. -
[preventedFn]
Function optionala function that is executed when
preventDefault()
is called. -
[queuable=false]
Boolean optionalwhether or not this event can be queued during bubbling.
-
[silent]
Boolean optionalif silent is true, debug messages are not provided for this event.
-
[stoppedFn]
Function optionala function that is executed when stopPropagation is called.
-
[monitored]
Boolean optionalspecifies whether or not this event should send notifications about when the event has been attached, detached, or published.
-
[type]
String optionalthe event type (valid option if not provided as the first parameter to publish).
-
Returns:
remove
()
chainable
removeAttr
-
name
Parameters:
-
name
StringThe name of the attribute to be removed.
removeQuery
-
url
Parameters:
-
url
StringURL.
Returns:
removeRoot
-
url
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
StringURL.
Returns:
render
()
chainable
viewContainer
node to the
container
node if it isn't already a child of the container, and the
activeView
will be appended the view container, if it isn't already.
You should call this method at least once, usually after the initialization
of your app instance so the proper DOM structure is setup and optionally
append the container to the DOM if it's not there already.
You may override this method to customize the app's rendering, but you
should expect that the viewContainer
's contents will be modified by the
app for the purpose of rendering the activeView
when it changes.
renderSideView
-
ViewConstructor
-
ServiceConstructor
-
params
-
done
Instantiates and renders a side view with the given ViewConstructor
and
ServiceConstructor
. It does pretty much the same thing as what
happened when the app is creating a side view.
Parameters:
-
ViewConstructor
Function -
ServiceConstructor
Function -
params
Objectthe parameters expected by the side view service
-
done
Function-
error
False | Error -
viewService
eZ.ViewService -
view
eZ.View
-
renderView
-
ViewConstructor
-
ServiceConstructor
-
requestParams
-
done
Instantiates and renders a view with the given ViewConstructor
and
ServiceConstructor
. It does pretty much the same thing as what
happened when navigating in the app but it skips the routing phase.
When done, the done
callback is called with the view and view
service instances as parameters.
Parameters:
-
ViewConstructor
Function -
ServiceConstructor
Function -
requestParams
Objectthe request parameters expected by the view service.
-
done
Function-
error
False | Error -
viewService
eZ.ViewService -
view
eZ.View
-
replace
-
[url]
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 optionalURL to set. This URL needs to be of the same origin as the current URL. This can be a URL relative to the router'sroot
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
Parameters:
-
name
StringOptional. The name of the attribute to reset. If omitted, all attributes are reset.
Returns:
route
-
route
-
callbacks
route
.
The route
parameter may be a string or regular expression to represent a
URL path, or a route object. If it's a string (which is most common), 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 route
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.
Alternatively, an object can be provided to represent the route and it may
contain a path
property which is a string or regular expression which
causes the route to be process as described above. If the route object
already contains a regex
or regexp
property, the route will be
considered fully-processed and will be associated with any callacks
specified on the object and those specified as parameters to this method.
**Note:** Any additional data contained on the route object will be
preserved.
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'}
* Route: /file/*path
* URL: /file/foo/bar/baz.txt
, params: {path: 'foo/bar/baz.txt'}
* URL: /file/foo
, params: {path: 'foo'}
**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:
-
route
String | RegExp | ObjectRoute to match. May be a string or a regular expression, or a route object. -
callbacks
Array | Function | String multipleCallback 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
ObjectRequest object containing information about the request. It contains the following properties.
-
params
Array | ObjectCaptured 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
StringThe current URL path. -
pendingCallbacks
NumberNumber of remaining callbacks the route handler has after this one in the dispatch chain. -
pendingRoutes
NumberNumber of matching routes after this one in the dispatch chain. -
query
ObjectQuery hash representing the URL query string, if any. Parameter names are keys, and are mapped to parameter values. -
route
ObjectReference to the current route object whose callbacks are being dispatched. -
router
ObjectReference to this router instance. -
src
StringWhat initiated the dispatch. In an HTML5 browser, when the back/forward buttons are used, this property will have a value of "popstate". When thedispath()
method is called, thesrc
will be"dispatch"
. -
url
StringThe full URL.
-
-
res
ObjectResponse object containing methods and information that relate to responding to a request. It contains the following properties.
-
req
ObjectReference to the request object.
-
-
next
FunctionFunction 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
req
andres
objects that were passed to this route (so you can use these objects to pass data along to subsequent callbacks and routes).-
[err]
String optionalOptional error which will stop the dispatch chaining for thisreq
, 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]
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 optionalURL to set. This URL needs to be of the same origin as the current URL. This can be a URL relative to the router'sroot
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]
Parameters:
-
name
StringThe 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
AnyThe value to set the attribute to. -
[opts]
Object optionalOptional data providing the circumstances for the change.
Returns:
setAttrs
-
attrs
-
[opts]
Parameters:
-
attrs
ObjectAn object with attributes name/value pairs. -
[opts]
Object optionalOptional data providing the circumstances for the change.
Returns:
showContent
-
content
-
[options]
-
[callback]
activeView
attribute using the specified content
.
This provides an easy way to view-ify HTML content which should be shown as
this app's active/visible view. This method will determine the appropriate
view container
node based on the specified content
. By default, a new
Y.View
instance will be created unless options.view
is specified.
Under the hood, this method calls the showView()
method, so refer to its
docs for more information.
Parameters:
-
content
HTMLElement | Node | StringThe content to show, it may be provided as a selector string, a DOM element, or aY.Node
instance. -
[options]
Object optionalOptional objects containing any of the following properties in addition to anyshowView()
options:-
[view]
Object | String optionalThe name of a view defined in this app's
views
, or an object with the following properties:-
name
StringThe name of a view defined in this app'sviews
. -
[config]
Object optionalOptional configuration to use when creating the new view instance. This config object can also be used to update an existing or preserved view's attributes whenoptions.update
istrue
. **Note:** If acontainer
is specified, it will be overridden by thecontent
specified in the first argument.
-
-
-
[callback]
Function optionalOptional callback function to call after the newactiveView
is ready to use. **Note:** this will overrideoptions.callback
and it can be specified as either the second or third argument. The function will be passed the following:-
view
ViewA reference to the new
activeView
.
-
showView
-
view
-
[config]
-
[options]
-
[callback]
activeView
attribute to the specified view
.
The view
will be "attached" to this app, meaning it will be both rendered
into this app's viewContainer
node and all of its events will bubble to
the app. The previous activeView
will be "detached" from this app.
When a string-name is provided for a view which has been registered on this
app's views
object, the referenced metadata will be used and the
activeView
will be set to either a preserved view instance, or a new
instance of the registered view will be created using the specified config
object passed-into this method.
A callback function can be specified as either the third or fourth argument,
and this function will be called after the new view
becomes the
activeView
, is rendered to the viewContainer
, and is ready to use.
Parameters:
-
view
String | ViewThe name of a view defined in theviews
object, or a view instance which should become this app'sactiveView
. -
[config]
Object optionalOptional configuration to use when creating a new view instance. This config object can also be used to update an existing or preserved view's attributes whenoptions.update
istrue
. -
[options]
Object optionalOptional object containing any of the following properties:-
[callback]
Function optionalOptional callback function to call after new
activeView
is ready to use, the function will be passed:-
view
ViewA reference to the newactiveView
.
-
-
[prepend=false]
Boolean optionalWhether the
view
should be prepended instead of appended to theviewContainer
. -
[render]
Boolean optionalWhether the
view
should be rendered. Note: If no value is specified, a view instance will only be rendered if it's newly created by this method. -
[transition]
Boolean | String optionalOptional transition override. A transition can be specified which will override the default, or
false
for no transition. -
[update=false]
Boolean optionalWhether an existing view should have its attributes updated by passing the
config
object to itssetAttrs()
method. Note: This option does not have an effect if theview
instance is created as a result of calling this method.
-
-
[callback]
Function optionalOptional callback Function to call after the newactiveView
is ready to use. **Note:** this will overrideoptions.callback
and it can be specified as either the third or fourth argument. The function will be passed the following:-
view
ViewA reference to the new
activeView
.
-
Example:
var app = new Y.App({
views: {
usersView: {
// Imagine that Y.UsersView
has been defined.
type: Y.UsersView
}
},
transitions: true,
users : new Y.ModelList()
});
app.route('/users/', function () {
this.showView('usersView', {users: this.get('users')});
});
app.render();
app.navigate('/uses/');
// => Creates a new Y.UsersView
and transitions to it.
subscribe
()
deprecated
toString
()
String
Returns:
unsubscribe
()
deprecated
unsubscribeAll
-
type
Parameters:
-
type
StringThe type, or name of the event
upgrade
()
Boolean
Returns:
true
if the URL was upgraded, false
otherwise.
Properties
_allowAdHocAttrs
Boolean
protected
Y.Base
that it should create ad-hoc attributes for config
properties passed to View's constructor. This makes it possible to
instantiate a view and set a bunch of attributes without having to subclass
Y.View
and declare all those attributes first.
Default: true
_dispatched
Boolean
protected
_dispatch()
has been called since this router was
instantiated.
Default: undefined
_dispatching
Boolean
protected
Default: undefined
_historyEvents
EventHandle
protected
history:change
or hashchange
event
subscription.
_html5
Boolean
protected
html5
attribute for internal use.
_params
Object
protected
name
-> RegExp | Function.
_ready
Boolean
protected
ready
event has fired yet.
Default: undefined
_regexPathParam
RegExp
protected
:
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.
2. Parameter name, if specified, otherwise it is a wildcard match.
_regexURL
RegExp
protected
_regexUrlOrigin
RegExp
protected
_regexUrlQuery
RegExp
protected
?
character, and discarding the hash portion of the URL if any.
_routes
Array
protected
_viewInfoMap
Object
protected
Y.stamp()
) to view-info object in views
.
This mapping is used to tie a specific view instance back to its metadata by
adding a reference to the the related view info on the views
object.
Default: {}
containerTemplate
String
Default: "<div/>"
events
Object
container
element. Events are attached
to the container, and delegation is used so that subscribers are only
notified of events that occur on elements inside the container that match
the specified selectors. This allows the container's contents to be re-
rendered as needed without losing event subscriptions.
Event handlers can be specified either as functions or as strings that map
to function names on this view instance or its prototype.
The this
object in event handlers will refer to this view instance. If
you'd prefer this
to be something else, use Y.bind()
to bind a custom
this
object.
Default: {}
Example:
var view = new Y.View({
events: {
// Call this.toggle()
whenever the element with the id
// "toggle-button" is clicked.
'#toggle-button': {click: 'toggle'},
// Call this.hoverOn()
when the mouse moves over any element
// with the "hoverable" class, and this.hoverOff()
when the
// mouse moves out of any element with the "hoverable" class.
'.hoverable': {
mouseover: 'hoverOn',
mouseout : 'hoverOff'
}
}
});
name
String
deprecated
template
Mixed
Y.Node
instance, a Mustache template, or anything else your little heart
desires.
How this template gets used is entirely up to you and your custom
render()
method.
Default: ''
transitions
Object
activeView
changes.
The following are types of changes for which transitions can be defined that
correspond to the relationship between the new and previous activeView
:
* navigate
: The default transition to use when changing the activeView
of the application.
* toChild
: The transition to use when the new activeView
is configured
as a child of the previously active view via its parent
property as
defined in this app's views
.
* toParent
: The transition to use when the new activeView
is
configured as the parent
of the previously active view as defined in
this app's views
.
**Note:** Transitions are an opt-in feature and will only be used in
browsers which support native CSS3 transitions.
Default: { navigate: 'fade', toChild : 'slideLeft', toParent: 'slideRight' }
views
Object
type
: Function or a string representing the view constructor to use to
create view instances. If a string is used, the constructor function is
assumed to be on the Y
object; e.g. "SomeView"
-> Y.SomeView
.
* preserve
: Boolean for whether the view instance should be retained. By
default, the view instance will be destroyed when it is no longer the
activeView
. If true
the view instance will simply be removed()
from the DOM when it is no longer active. This is useful when the view
is frequently used and may be expensive to re-create.
* parent
: String to another named view in this hash that represents the
parent view within the application's view hierarchy; e.g. a "photo"
view could have "album"
has its parent
view. This parent/child
relationship is a useful cue for things like transitions.
* instance
: Used internally to manage the current instance of this named
view. This can be used if your view instance is created up-front, or if
you would rather manage the View lifecycle, but you probably should just
let this be handled for you.
If views
are specified at instantiation time, the metadata in the views
Object here will be used as defaults when creating the instance's views
.
Every Y.App
instance gets its own copy of a views
object so this Object
on the prototype will not be polluted.
Default: {}
Example:
// Imagine that Y.UsersView
and Y.UserView
have been defined.
var app = new Y.App({
views: {
users: {
type : Y.UsersView,
preserve: true
},
user: {
type : Y.UserView,
parent: 'users'
}
}
});
Attributes
activeView
View
readonly
activeView
use the
showView()
method.
Default: null
addPjaxParam
Boolean
true
, a "pjax=1" query parameter will be appended to all URLs
requested via Pjax.
Browsers ignore HTTP request headers when caching content, so if the
same URL is used to request a partial Pjax page and a full page, the
browser will cache them under the same key and may later load the
cached partial page when the user actually requests a full page (or vice
versa).
To prevent this, we can add a bogus query parameter to the URL so that
Pjax URLs will always be cached separately from non-Pjax URLs.
Default: true
allowFallThrough
Boolean
window.location
when calling navigate()
if no routes match the specified URL.
Default: true
config
Object | Undefined
The application configuration. It is dispatched to the others application attributes/properties at build time.
container
HTMLElement | Node | String
<body>
Node, but you can override this in
a subclass, or by passing in a custom container
config value at
instantiation time.
When container
is overridden by a subclass or passed as a config
option at instantiation time, it may be provided as a selector string, a
DOM element, or a Y.Node
instance. During initialization, this app's
create()
method will be called to convert the container into a
Y.Node
instance if it isn't one already and stamp it with the CSS
class: "yui3-app"
.
The container is not added to the page automatically. This allows you to
have full control over how and when your app is actually rendered to
the page.
Default: Y.one('body')
contentCreationDefaultLanguageCode
String
readonly
Default language code, as defined by the current siteaccess language config.
Default: "eng-GB"
contentSelector
String
example.html
but only use
the content within an element with the id "pjax-content", you'd set
contentSelector
to "#pjax-content".
If not set, the entire page will be used.
Default: null
destroyed
Boolean
readonly
Default: false
html5
Boolean
serverRouting
and will default
accordingly.
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.
initialized
Boolean
readonly
Default: false
interfaceLanguages
Array
readonly
List of preferred languages in which the interface should be translated.
Default: ['en']
linkSelector
String | Function
href
URL using the enhanced, pjax, behavior will be
attempted; and the browser's default way to navigate to new pages will
be the fallback.
By default this selector will match _all_ links on the page.
Default: "a"
localesMap
Object
readonly
Holds the Locales conversion map between eZ Locale codes and POSIX ones. See locale.yml
Default: {}
params
Object
name
-> RegExp | Function.
If a param handler regex or function returns a value of false
, null
,
undefined
, or NaN
, the current route will not match and be skipped.
All other return values will be used in place of the original param
value parsed from the URL.
This attribute is intended to be used to set params at init time, or to
completely reset all params after init. To add params after init without
resetting all existing params, use the param()
method.
Default: `{}`
root
String
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: `''`
Example:
router.set('root', '/myapp');
router.route('/foo', function () { ... });
Y.log(router.hasRoute('/foo')); // => false
Y.log(router.hasRoute('/myapp/foo')); // => true
// Updates the URL to: "/myapp/foo"
router.save('/foo');
routes
Object
path
: String or regex representing the path to match. See the docs
for the route()
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 the route()
method for more details.
If a route object contains a regex
or regexp
property, or if its
path
is a regular express, then the route will be considered to be
fully-processed. Any fully-processed routes may contain the following
properties:
* regex
: The regular expression representing the path to match, this
property may also be named regexp
for greater compatibility.
* keys
: Array of named path parameters used to populate req.params
objects when dispatching to route handlers.
Any additional data contained on these route objects will be retained.
This is useful to store extra metadata about a route; e.g., a name
to
give routes logical names.
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: `[]`
scrollToTop
Boolean
Default: true
serverRouting
Boolean
undefined
: The best form of URLs will be chosen based on the
capabilities of the browser. Given no information about the server
environmentm a balanced approach to routing and navigation is
chosen.
The server should be capable of handling full-path requests, since
full-URLs will be generated by browsers using HTML5 history. If this
is a client-side-only app the server could handle full-URL requests
by sending a redirect back to the root with a hash-based URL, e.g:
Request: http://example.com/users/1
Redirect to: http://example.com/#/users/1
* true
: The server is *fully* capable of properly handling requests
to all full-path URLs the app can produce.
This is the best option for progressive-enhancement because it will
cause **all URLs to always have full-paths**, which means the server
will be able to accurately handle all URLs this app produces. e.g.
http://example.com/users/1
To meet this strict full-URL requirement, browsers which are not
capable of using HTML5 history will make requests to the server
resulting in full-page reloads.
* false
: The server is *not* capable of properly handling requests
to all full-path URLs the app can produce, therefore all routing
will be handled by this App instance.
Be aware that this will cause **all URLs to always be hash-based**,
even in browsers that are capable of using HTML5 history. e.g.
http://example.com/#/users/1
A single-page or client-side-only app where the server sends a
"shell" page with JavaScript to the client might have this
restriction. If you're setting this to false
, read the following:
**Note:** When this is set to false
, the server will *never* receive
the full URL because browsers do not send the fragment-part to the
server, that is everything after and including the "#".
Consider the following example:
URL shown in browser: http://example.com/#/users/1
URL sent to server: http://example.com/
You should feel bad about hurting our precious web if you forcefully set
either serverRouting
or html5
to false
, because you're basically
punching the web in the face here with your lossy URLs! Please make sure
you know what you're doing and that you understand the implications.
Ideally you should always prefer full-path URLs (not /#/foo/), and want
full-page reloads when the client's browser is not capable of enhancing
the experience using the HTML5 history APIs. Setting this to true
is
the best option for progressive-enhancement (and graceful-degradation).
Default: undefined
systemLanguageList
Object
readonly
System language list provided with config. The list is hash containing language objects and is indexed by languageCode.
Default: {}
titleSelector
String
<title>
element,
but you could customize it to extract the title from an <h1>
, or from
any other element, if that's more appropriate for the content you're
loading.
Default: "title"
transitions
Boolean | Object
true
for the defaults which are specified by the
transitions
prototype property.
**Note:** Transitions are an opt-in feature and will only be used in
browsers which support native CSS3 transitions.
Default: false
viewContainer
HTMLElement | Node | String
views
will be rendered when they become
the activeView
.
The view container node serves as the container to hold the app's
activeView
. Each time the activeView
is set via showView()
, the
previous view will be removed from this node, and the new active view's
container
node will be appended.
The default view container is a <div>
Node, but you can override this
in a subclass, or by passing in a custom viewContainer
config value at
instantiation time. The viewContainer
may be provided as a selector
string, DOM element, or a Y.Node
instance (having the viewContainer
and the container
be the same node is also supported).
The app's render()
method will stamp the view container with the CSS
class "yui3-app-views"
and append it to the app's container
node if
it isn't already, and any activeView
will be appended to this node if
it isn't already.
Default: Y.Node.create(this.containerTemplate)
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
EventFacadeEvent 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
EventFacadeEvent object, with a cfg property which refers to the configuration object passed to the constructor.
ready
Event Payload:
-
dispatched
Booleantrue
if routes have already been dispatched (most likely due to a history change).