Yahoo! UI Library

base  3.0.0pr2

Yahoo! UI Library > base > Base
Search:
 
Filters

Class Base - uses Attribute

Known Subclasses:
Drag Plugin Drop Widget plugin.Anim DDM

Provides a base class for managed attribute based objects, which handles the chaining of initializer and destructor methods across the hierarchy during init and destroy lifecycle methods and handles automatic configuration of registered Attributes, through the static ATTRS property.

The Base class also handles prefixing of event types with the static NAME property for all events fired from instances of classes derived from Base.

Constructor

Base ( config )
Parameters:
config <Object> Object literal of configuration property name/value pairs

Properties

_buildCfg - private static final Object

The build configuration for the Base class. Defines the static fields which need to be aggregated, when this class is used as the main class passed to the Base.build method.

ATTRS - static Object

Object literal defining the set of attributes which will be available for instances of this class, and how they are configured. See Attributes addAtt method for a description of configuration options available for each attribute.

NAME - static String

Name string to be used to identify instances of this class, for example in prefixing events.

Classes extending Base, should define their own static NAME property.

name - String

The name string to be used to identify this instance of object.

Properties inherited from Attribute:

Methods

_defDestroyFn

protected void _defDestroyFn ( e )
Default destroy event handler
Parameters:
e <Event.Facade> Event object
Returns: void

_defInitFn

protected void _defInitFn ( e , config )
Default init event handler
Parameters:
e <Event.Facade> Event object
config <Object> Object literal of configuration property name/value pairs
Returns: void

_destroyHierarchy

private void _destroyHierarchy ( )
Destroys the class hierarchy rooted at this base class by invoking the descructor method on the prototype of each class in the hierarchy.
Returns: void

_getClasses

protected Function[] _getClasses ( )
Returns the top down class hierarchy for this object, with Base being the first class in the array.
Returns: Function[]
An Array of classes (constructor functions), making up the class heirarchy for this object

_initHierarchy

private void _initHierarchy ( userConf )
Initializes the class hierarchy rooted at this base class, 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:
userConf <Object> Object literal containing attribute name/value pairs
Returns: void

_prefixEvtType

private String _prefixEvtType ( type )
Utility method to prefix the event name with the name property of the instance, if absent
Parameters:
type <String> The event name
Returns: String
The prefixed event name

after

Event.Handle after ( type , fn , context , args* )

Subscribe to a custom event hosted by this object. The supplied callback will execute after any listeners added via the subscribe method, and after the default function, if configured for the event, has executed.

Overrides Event.Target's after method, to add the name prefix of the instance to the event type, if absent.

Parameters:
type <String> The type of event to subscribe to. If the type string does not contain a prefix ("prefix:eventType"), the name property of the instance will be used as the default prefix.
fn <Function> The subscribed callback function
context <Object> Optional execution context for the callback
args* <Any*> 0..n params to supply to the callback
Returns: Event.Handle
Event handle which can be used to unsubscribe the subscribed callback.

build

static Function build ( main , extensions , cfg )

Builds a constructor function (class) from the main function, and array of extension functions (classes) provided.

The cfg object literal supports the following properties

dynamic <boolean>

If true (default), a completely new class is created which extends the main class, and acts as the host on which the extension classes are augmented.

If false, the extensions classes are augmented directly to the main class, modifying the main classes prototype.

aggregates <String[]>
An array of static property names, which will get aggregated on to the built class, in addition to the default properties build will always aggregate as defined by the main class' _buildCfg property.
Parameters:
main <Function> The main class on which to base the built class
extensions <Function[]> The set of extension classes which will be augmented/aggregated to the built class.
cfg <Object>
Returns: Function
A custom class, created from the provided main and extension classes

create

static Object create ( main , extensions , args* )

Creates a new object instance, based on a dynamically created custom class. The custom class is created from the main class passed in as the first parameter along with the list of extension classes passed in as the second parameter using Base.build with "dynamic" set to true. See the documentation for Base.build method to see how the main class and extension classes are used.

Any arguments following the 2nd argument are passed as arguments to the constructor of the newly created class used to create the instance.

Parameters:
main <Function> The main class on which the instance it to be based. This class will be extended to create the class for the custom instance
extensions <Array> The list of extension classes used to augment the main class with.
args* <Any*> 0..n arguments to pass to the constructor of the newly created class, when creating the instance.
Returns: Object
An instance of the custom class

destroy

final Base destroy ( )

Destroy lifecycle method. Fires the destroy event, prior to invoking destructors for the class hierarchy.

Subscribers to the destroy event can invoke preventDefault on the event object, to prevent destruction from proceeding.

Returns: Base
A reference to this object
Chainable: This method is chainable.

fire

boolean fire ( type , args* )

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.

Overrides Event.Target's fire method, to add the name prefix of the instance to the event type, if absent.

Parameters:
type <String|Object> The type of the event, or an object that contains a 'type' property. If the type does not contain a prefix ("prefix:eventType"), the name property of the instance will be used as the default prefix.
args* <Any*> 0..n Additional arguments to pass to subscribers.
Returns: boolean
The return value from Event Target's fire method.

init

final Base init ( config )
Init lifecycle method, invoked during construction. Fires the init event prior to invoking initializers on the class hierarchy.
Parameters:
config <Object> Object literal of configuration property name/value pairs
Returns: Base
A reference to this object
Chainable: This method is chainable.

publish

Event.Custom 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.

Overrides Event.Target's publish method, to add the name prefix of the instance to the event type, if absent.

Parameters:
type <String> The type, or name of the event. If the type does not contain a prefix ("prefix:eventType"), the name property of the instance will be used as the default prefix.
opts <Object> Optional config params (see Event.Target publish for details)
Returns: Event.Custom
The published custom event object

subscribe

Event.Handle subscribe ( type , fn , context , args* )

Subscribe to a custom event hosted by this object.

Overrides Event.Target's subscribe method, to add the name prefix of the instance to the event type, if absent.

Parameters:
type <String> The type of event to subscribe to. If the type string does not contain a prefix ("prefix:eventType"), the name property of the instance will be used as the default prefix.
fn <Function> The subscribed callback function, invoked when the event is fired.
context <Object> Optional execution context for the callback.
args* <Any*> 0..n params to supply to the callback
Returns: Event.Handle
An event handle which can be used to unsubscribe the subscribed callback.

toString

String toString ( )
Default toString implementation. Provides the constructor NAME and the instance ID.
Returns: String
String representation for this object

unsubscribe

boolean unsubscribe ( type , fn , context )

Unsubscribes one or more listeners the from the specified event.

Overrides Event.Target's unsubscribe method, to add the name prefix of the instance to the event type, if absent.

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. If the type string does not contain a prefix ("prefix:eventType"), the name property of the instance will be used as the default prefix.
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: boolean
true if the subscriber was found and detached.

unsubscribeAll

int 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.

Overrides Event.Target's unsubscribeAll method, to add the name prefix of the instance to the event type, if absent.

Parameters:
type <String> The type, or name of the event. If the type string does not contain a prefix ("prefix:eventType"), the name property of the instance will be used as the default prefix
Returns: int
The number of listeners unsubscribed

Events

destroy

destroy ( e )

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).

Parameters:
e <Event.Facade> Event object
Preventable: This event is preventable by method e.preventDefault(). The default function executed by this event is _defDestroyFn.

destroyedChange

destroyedChange ( event )
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:
event <Event.Facade> An Event Facade object with the following attribute specific properties added:
prevVal
The value of the attribute, prior to it being set
newVal
The value the attribute is to be set to
attrName
The name of the attribute being set
subAttrName
If setting a property within the attribute's value, the name of the sub-attribute property being set

init

init ( e , config )

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).

Parameters:
e <Event.Facade> Event object
config <object> Object literal of configuration name/value pairs
Preventable: This event is preventable by method e.preventDefault(). The default function executed by this event is _defInitFn.

initializedChange

initializedChange ( event )
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:
event <Event.Facade> An Event Facade object with the following attribute specific properties added:
prevVal
The value of the attribute, prior to it being set
newVal
The value the attribute is to be set to
attrName
The name of the attribute being set
subAttrName
If setting a property within the attribute's value, the name of the sub-attribute property being set

Configuration Attributes

destroyed - boolean

Flag indicating whether or not this object has been through the destroy lifecycle phase.
Default Value: false

initialized - boolean

Flag indicating whether or not this object has been through the init lifecycle phase.
Default Value: false

Classes

Files

Properties

Configuration Attributes

Copyright © 2008 Yahoo! Inc. All rights reserved.