2 Copyright (c) 2009, Yahoo! Inc. All rights reserved.
3 Code licensed under the BSD License:
4 http://developer.yahoo.net/yui/license.txt
8 * Provides Attribute configurations.
9 * @namespace YAHOO.util
12 * @param hash {Object} The intial Attribute.
13 * @param {YAHOO.util.AttributeProvider} The owner of the Attribute instance.
16 YAHOO.util.Attribute = function(hash, owner) {
19 this.configure(hash, true);
23 YAHOO.util.Attribute.prototype = {
25 * The name of the attribute.
32 * The value of the attribute.
39 * The owner of the attribute.
41 * @type YAHOO.util.AttributeProvider
46 * Whether or not the attribute is read only.
53 * Whether or not the attribute can only be written once.
60 * The attribute's initial configuration.
62 * @property _initialConfig
68 * Whether or not the attribute's value has been set.
76 * A function to call when setting the attribute's value.
77 * The method receives the new value as the first arg and the attribute name as the 2nd
84 * The function to use when setting the attribute's value.
85 * The setter receives the new value as the first arg and the attribute name as the 2nd
86 * The return value of the setter replaces the value passed to set().
93 * The function to use when getting the attribute's value.
94 * The getter receives the new value as the first arg and the attribute name as the 2nd
95 * The return value of the getter will be used as the return from get().
102 * The validator to use when setting the attribute's value.
103 * @property validator
110 * Retrieves the current value of the attribute.
112 * @return {any} The current value of the attribute.
114 getValue: function() {
115 var val = this.value;
118 val = this.getter.call(this.owner, this.name, val);
125 * Sets the value of the attribute and fires beforeChange and change events.
127 * @param {Any} value The value to apply to the attribute.
128 * @param {Boolean} silent If true the change events will not be fired.
129 * @return {Boolean} Whether or not the value was set.
131 setValue: function(value, silent) {
138 prevValue: this.getValue(),
142 if (this.readOnly || ( this.writeOnce && this._written) ) {
143 return false; // write not allowed
146 if (this.validator && !this.validator.call(owner, value) ) {
147 return false; // invalid value
151 beforeRetVal = owner.fireBeforeChangeEvent(event);
152 if (beforeRetVal === false) {
158 value = this.setter.call(owner, value, this.name);
159 if (value === undefined) {
164 this.method.call(owner, value, this.name);
167 this.value = value; // TODO: set before calling setter/method?
168 this._written = true;
173 this.owner.fireChangeEvent(event);
180 * Allows for configuring the Attribute's properties.
182 * @param {Object} map A key-value map of Attribute properties.
183 * @param {Boolean} init Whether or not this should become the initial config.
185 configure: function(map, init) {
189 this._written = false; // reset writeOnce
192 this._initialConfig = this._initialConfig || {};
194 for (var key in map) {
195 if ( map.hasOwnProperty(key) ) {
196 this[key] = map[key];
198 this._initialConfig[key] = map[key];
205 * Resets the value to the initial config value.
207 * @return {Boolean} Whether or not the value was set.
209 resetValue: function() {
210 return this.setValue(this._initialConfig.value);
214 * Resets the attribute config to the initial config state.
215 * @method resetConfig
217 resetConfig: function() {
218 this.configure(this._initialConfig, true);
222 * Resets the value to the current value.
223 * Useful when values may have gotten out of sync with actual properties.
225 * @return {Boolean} Whether or not the value was set.
227 refresh: function(silent) {
228 this.setValue(this.value, silent);
233 var Lang = YAHOO.util.Lang;
236 Copyright (c) 2006, Yahoo! Inc. All rights reserved.
237 Code licensed under the BSD License:
238 http://developer.yahoo.net/yui/license.txt
242 * Provides and manages YAHOO.util.Attribute instances
243 * @namespace YAHOO.util
244 * @class AttributeProvider
245 * @uses YAHOO.util.EventProvider
247 YAHOO.util.AttributeProvider = function() {};
249 YAHOO.util.AttributeProvider.prototype = {
252 * A key-value map of Attribute configurations
254 * @protected (may be used by subclasses and augmentors)
260 * Returns the current value of the attribute.
262 * @param {String} key The attribute whose value will be returned.
263 * @return {Any} The current value of the attribute.
266 this._configs = this._configs || {};
267 var config = this._configs[key];
269 if (!config || !this._configs.hasOwnProperty(key)) {
273 return config.getValue();
277 * Sets the value of a config.
279 * @param {String} key The name of the attribute
280 * @param {Any} value The value to apply to the attribute
281 * @param {Boolean} silent Whether or not to suppress change events
282 * @return {Boolean} Whether or not the value was set.
284 set: function(key, value, silent){
285 this._configs = this._configs || {};
286 var config = this._configs[key];
292 return config.setValue(value, silent);
296 * Returns an array of attribute names.
297 * @method getAttributeKeys
298 * @return {Array} An array of attribute names.
300 getAttributeKeys: function(){
301 this._configs = this._configs;
304 for (key in this._configs) {
305 if ( Lang.hasOwnProperty(this._configs, key) &&
306 !Lang.isUndefined(this._configs[key]) ) {
307 keys[keys.length] = key;
315 * Sets multiple attribute values.
316 * @method setAttributes
317 * @param {Object} map A key-value map of attributes
318 * @param {Boolean} silent Whether or not to suppress change events
320 setAttributes: function(map, silent){
321 for (var key in map) {
322 if ( Lang.hasOwnProperty(map, key) ) {
323 this.set(key, map[key], silent);
329 * Resets the specified attribute's value to its initial value.
331 * @param {String} key The name of the attribute
332 * @param {Boolean} silent Whether or not to suppress change events
333 * @return {Boolean} Whether or not the value was set
335 resetValue: function(key, silent){
336 this._configs = this._configs || {};
337 if (this._configs[key]) {
338 this.set(key, this._configs[key]._initialConfig.value, silent);
345 * Sets the attribute's value to its current value.
347 * @param {String | Array} key The attribute(s) to refresh
348 * @param {Boolean} silent Whether or not to suppress change events
350 refresh: function(key, silent) {
351 this._configs = this._configs || {};
352 var configs = this._configs;
354 key = ( ( Lang.isString(key) ) ? [key] : key ) ||
355 this.getAttributeKeys();
357 for (var i = 0, len = key.length; i < len; ++i) {
358 if (configs.hasOwnProperty(key[i])) {
359 this._configs[key[i]].refresh(silent);
365 * Adds an Attribute to the AttributeProvider instance.
367 * @param {String} key The attribute's name
368 * @param {Object} map A key-value map containing the
369 * attribute's properties.
370 * @deprecated Use setAttributeConfig
372 register: function(key, map) {
373 this.setAttributeConfig(key, map);
378 * Returns the attribute's properties.
379 * @method getAttributeConfig
380 * @param {String} key The attribute's name
382 * @return {object} A key-value map containing all of the
383 * attribute's properties.
385 getAttributeConfig: function(key) {
386 this._configs = this._configs || {};
387 var config = this._configs[key] || {};
388 var map = {}; // returning a copy to prevent overrides
390 for (key in config) {
391 if ( Lang.hasOwnProperty(config, key) ) {
392 map[key] = config[key];
400 * Sets or updates an Attribute instance's properties.
401 * @method setAttributeConfig
402 * @param {String} key The attribute's name.
403 * @param {Object} map A key-value map of attribute properties
404 * @param {Boolean} init Whether or not this should become the intial config.
406 setAttributeConfig: function(key, map, init) {
407 this._configs = this._configs || {};
409 if (!this._configs[key]) {
411 this._configs[key] = this.createAttribute(map);
413 this._configs[key].configure(map, init);
418 * Sets or updates an Attribute instance's properties.
419 * @method configureAttribute
420 * @param {String} key The attribute's name.
421 * @param {Object} map A key-value map of attribute properties
422 * @param {Boolean} init Whether or not this should become the intial config.
423 * @deprecated Use setAttributeConfig
425 configureAttribute: function(key, map, init) {
426 this.setAttributeConfig(key, map, init);
430 * Resets an attribute to its intial configuration.
431 * @method resetAttributeConfig
432 * @param {String} key The attribute's name.
435 resetAttributeConfig: function(key){
436 this._configs = this._configs || {};
437 this._configs[key].resetConfig();
440 // wrapper for EventProvider.subscribe
441 // to create events on the fly
442 subscribe: function(type, callback) {
443 this._events = this._events || {};
445 if ( !(type in this._events) ) {
446 this._events[type] = this.createEvent(type);
449 YAHOO.util.EventProvider.prototype.subscribe.apply(this, arguments);
453 this.subscribe.apply(this, arguments);
456 addListener: function() {
457 this.subscribe.apply(this, arguments);
461 * Fires the attribute's beforeChange event.
462 * @method fireBeforeChangeEvent
463 * @param {String} key The attribute's name.
464 * @param {Obj} e The event object to pass to handlers.
466 fireBeforeChangeEvent: function(e) {
468 type += e.type.charAt(0).toUpperCase() + e.type.substr(1) + 'Change';
470 return this.fireEvent(e.type, e);
474 * Fires the attribute's change event.
475 * @method fireChangeEvent
476 * @param {String} key The attribute's name.
477 * @param {Obj} e The event object to pass to the handlers.
479 fireChangeEvent: function(e) {
481 return this.fireEvent(e.type, e);
484 createAttribute: function(map) {
485 return new YAHOO.util.Attribute(map, this);
489 YAHOO.augment(YAHOO.util.AttributeProvider, YAHOO.util.EventProvider);
493 // internal shorthand
494 var Dom = YAHOO.util.Dom,
495 AttributeProvider = YAHOO.util.AttributeProvider,
502 * Element provides an wrapper object to simplify adding
503 * event listeners, using dom methods, and managing attributes.
505 * @namespace YAHOO.util
506 * @requires yahoo, dom, event
510 * Element provides an wrapper object to simplify adding
511 * event listeners, using dom methods, and managing attributes.
513 * @uses YAHOO.util.AttributeProvider
515 * @param el {HTMLElement | String} The html element that
516 * represents the Element.
517 * @param {Object} map A key-value map of initial config names and values
519 var Element = function(el, map) {
520 this.init.apply(this, arguments);
523 Element.DOM_EVENTS = {
542 Element.prototype = {
544 * Dom events supported by the Element instance.
545 * @property DOM_EVENTS
550 DEFAULT_HTML_SETTER: function(value, key) {
551 var el = this.get('element');
561 DEFAULT_HTML_GETTER: function(key) {
562 var el = this.get('element'),
573 * Wrapper for HTMLElement method.
574 * @method appendChild
575 * @param {YAHOO.util.Element || HTMLElement} child The element to append.
576 * @return {HTMLElement} The appended DOM element.
578 appendChild: function(child) {
579 child = child.get ? child.get('element') : child;
580 return this.get('element').appendChild(child);
584 * Wrapper for HTMLElement method.
585 * @method getElementsByTagName
586 * @param {String} tag The tagName to collect
587 * @return {HTMLCollection} A collection of DOM elements.
589 getElementsByTagName: function(tag) {
590 return this.get('element').getElementsByTagName(tag);
594 * Wrapper for HTMLElement method.
595 * @method hasChildNodes
596 * @return {Boolean} Whether or not the element has childNodes
598 hasChildNodes: function() {
599 return this.get('element').hasChildNodes();
603 * Wrapper for HTMLElement method.
604 * @method insertBefore
605 * @param {HTMLElement} element The HTMLElement to insert
606 * @param {HTMLElement} before The HTMLElement to insert
607 * the element before.
608 * @return {HTMLElement} The inserted DOM element.
610 insertBefore: function(element, before) {
611 element = element.get ? element.get('element') : element;
612 before = (before && before.get) ? before.get('element') : before;
614 return this.get('element').insertBefore(element, before);
618 * Wrapper for HTMLElement method.
619 * @method removeChild
620 * @param {HTMLElement} child The HTMLElement to remove
621 * @return {HTMLElement} The removed DOM element.
623 removeChild: function(child) {
624 child = child.get ? child.get('element') : child;
625 return this.get('element').removeChild(child);
629 * Wrapper for HTMLElement method.
630 * @method replaceChild
631 * @param {HTMLElement} newNode The HTMLElement to insert
632 * @param {HTMLElement} oldNode The HTMLElement to replace
633 * @return {HTMLElement} The replaced DOM element.
635 replaceChild: function(newNode, oldNode) {
636 newNode = newNode.get ? newNode.get('element') : newNode;
637 oldNode = oldNode.get ? oldNode.get('element') : oldNode;
638 return this.get('element').replaceChild(newNode, oldNode);
643 * Registers Element specific attributes.
644 * @method initAttributes
645 * @param {Object} map A key-value map of initial attribute configs
647 initAttributes: function(map) {
651 * Adds a listener for the given event. These may be DOM or
652 * customEvent listeners. Any event that is fired via fireEvent
653 * can be listened for. All handlers receive an event object.
654 * @method addListener
655 * @param {String} type The name of the event to listen for
656 * @param {Function} fn The handler to call when the event fires
657 * @param {Any} obj A variable to pass to the handler
658 * @param {Object} scope The object to use for the scope of the handler
660 addListener: function(type, fn, obj, scope) {
662 scope = scope || this;
664 var Event = YAHOO.util.Event,
665 el = this.get('element') || this.get('id'),
669 if (specialTypes[type] && !Event._createMouseDelegate) {
674 if (!this._events[type]) { // create on the fly
676 if (el && this.DOM_EVENTS[type]) {
677 Event.on(el, type, function(e, matchedEl) {
679 // Supplement IE with target, currentTarget relatedTarget
681 if (e.srcElement && !e.target) {
682 e.target = e.srcElement;
685 if ((e.toElement && !e.relatedTarget) || (e.fromElement && !e.relatedTarget)) {
686 e.relatedTarget = Event.getRelatedTarget(e);
689 if (!e.currentTarget) {
690 e.currentTarget = el;
693 // Note: matchedEl el is passed back for delegated listeners
694 self.fireEvent(type, e, matchedEl);
698 this.createEvent(type, {scope: this});
701 return YAHOO.util.EventProvider.prototype.subscribe.apply(this, arguments); // notify via customEvent
706 * Alias for addListener
708 * @param {String} type The name of the event to listen for
709 * @param {Function} fn The function call when the event fires
710 * @param {Any} obj A variable to pass to the handler
711 * @param {Object} scope The object to use for the scope of the handler
714 return this.addListener.apply(this, arguments);
718 * Alias for addListener
720 * @param {String} type The name of the event to listen for
721 * @param {Function} fn The function call when the event fires
722 * @param {Any} obj A variable to pass to the handler
723 * @param {Object} scope The object to use for the scope of the handler
725 subscribe: function() {
726 return this.addListener.apply(this, arguments);
730 * Remove an event listener
731 * @method removeListener
732 * @param {String} type The name of the event to listen for
733 * @param {Function} fn The function call when the event fires
735 removeListener: function(type, fn) {
736 return this.unsubscribe.apply(this, arguments);
740 * Wrapper for Dom method.
742 * @param {String} className The className to add
744 addClass: function(className) {
745 Dom.addClass(this.get('element'), className);
749 * Wrapper for Dom method.
750 * @method getElementsByClassName
751 * @param {String} className The className to collect
752 * @param {String} tag (optional) The tag to use in
753 * conjunction with class name
754 * @return {Array} Array of HTMLElements
756 getElementsByClassName: function(className, tag) {
757 return Dom.getElementsByClassName(className, tag,
758 this.get('element') );
762 * Wrapper for Dom method.
764 * @param {String} className The className to add
765 * @return {Boolean} Whether or not the element has the class name
767 hasClass: function(className) {
768 return Dom.hasClass(this.get('element'), className);
772 * Wrapper for Dom method.
773 * @method removeClass
774 * @param {String} className The className to remove
776 removeClass: function(className) {
777 return Dom.removeClass(this.get('element'), className);
781 * Wrapper for Dom method.
782 * @method replaceClass
783 * @param {String} oldClassName The className to replace
784 * @param {String} newClassName The className to add
786 replaceClass: function(oldClassName, newClassName) {
787 return Dom.replaceClass(this.get('element'),
788 oldClassName, newClassName);
792 * Wrapper for Dom method.
794 * @param {String} property The style property to set
795 * @param {String} value The value to apply to the style property
797 setStyle: function(property, value) {
798 return Dom.setStyle(this.get('element'), property, value); // TODO: always queuing?
802 * Wrapper for Dom method.
804 * @param {String} property The style property to retrieve
805 * @return {String} The current value of the property
807 getStyle: function(property) {
808 return Dom.getStyle(this.get('element'), property);
812 * Apply any queued set calls.
815 fireQueue: function() {
816 var queue = this._queue;
817 for (var i = 0, len = queue.length; i < len; ++i) {
818 this[queue[i][0]].apply(this, queue[i][1]);
823 * Appends the HTMLElement into either the supplied parentNode.
825 * @param {HTMLElement | Element} parentNode The node to append to
826 * @param {HTMLElement | Element} before An optional node to insert before
827 * @return {HTMLElement} The appended DOM element.
829 appendTo: function(parent, before) {
830 parent = (parent.get) ? parent.get('element') : Dom.get(parent);
832 this.fireEvent('beforeAppendTo', {
833 type: 'beforeAppendTo',
838 before = (before && before.get) ?
839 before.get('element') : Dom.get(before);
840 var element = this.get('element');
850 if (element.parent != parent) {
852 parent.insertBefore(element, before);
854 parent.appendChild(element);
859 this.fireEvent('appendTo', {
868 var configs = this._configs || {},
869 el = configs.element; // avoid loop due to 'element'
871 if (el && !configs[key] && !YAHOO.lang.isUndefined(el.value[key]) ) {
872 this._setHTMLAttrConfig(key);
875 return AttributeProvider.prototype.get.call(this, key);
878 setAttributes: function(map, silent) {
879 // set based on configOrder
881 configOrder = this._configOrder;
883 // set based on configOrder
884 for (var i = 0, len = configOrder.length; i < len; ++i) {
885 if (map[configOrder[i]] !== undefined) {
886 done[configOrder[i]] = true;
887 this.set(configOrder[i], map[configOrder[i]], silent);
891 // unconfigured (e.g. Dom attributes)
892 for (var att in map) {
893 if (map.hasOwnProperty(att) && !done[att]) {
894 this.set(att, map[att], silent);
899 set: function(key, value, silent) {
900 var el = this.get('element');
902 this._queue[this._queue.length] = ['set', arguments];
903 if (this._configs[key]) {
904 this._configs[key].value = value; // so "get" works while queueing
910 // set it on the element if not configured and is an HTML attribute
911 if ( !this._configs[key] && !YAHOO.lang.isUndefined(el[key]) ) {
912 this._setHTMLAttrConfig(key);
915 return AttributeProvider.prototype.set.apply(this, arguments);
918 setAttributeConfig: function(key, map, init) {
919 this._configOrder.push(key);
920 AttributeProvider.prototype.setAttributeConfig.apply(this, arguments);
923 createEvent: function(type, config) {
924 this._events[type] = true;
925 return AttributeProvider.prototype.createEvent.apply(this, arguments);
928 init: function(el, attr) {
929 this._initElement(el, attr);
932 destroy: function() {
933 var el = this.get('element');
934 YAHOO.util.Event.purgeElement(el, true); // purge DOM listeners recursively
935 this.unsubscribeAll(); // unsubscribe all custom events
937 if (el && el.parentNode) {
938 el.parentNode.removeChild(el); // pull from the DOM
941 // revert initial configs
945 this._configOrder = [];
948 _initElement: function(el, attr) {
949 this._queue = this._queue || [];
950 this._events = this._events || {};
951 this._configs = this._configs || {};
952 this._configOrder = [];
954 attr.element = attr.element || el || null;
956 var isReady = false; // to determine when to init HTMLElement and content
958 var DOM_EVENTS = Element.DOM_EVENTS;
959 this.DOM_EVENTS = this.DOM_EVENTS || {};
961 for (var event in DOM_EVENTS) {
962 if (DOM_EVENTS.hasOwnProperty(event)) {
963 this.DOM_EVENTS[event] = DOM_EVENTS[event];
967 if (typeof attr.element === 'string') { // register ID for get() access
968 this._setHTMLAttrConfig('id', { value: attr.element });
971 if (Dom.get(attr.element)) {
973 this._initHTMLElement(attr);
974 this._initContent(attr);
977 YAHOO.util.Event.onAvailable(attr.element, function() {
978 if (!isReady) { // otherwise already done
979 this._initHTMLElement(attr);
982 this.fireEvent('available', { type: 'available', target: Dom.get(attr.element) });
985 YAHOO.util.Event.onContentReady(attr.element, function() {
986 if (!isReady) { // otherwise already done
987 this._initContent(attr);
989 this.fireEvent('contentReady', { type: 'contentReady', target: Dom.get(attr.element) });
993 _initHTMLElement: function(attr) {
995 * The HTMLElement the Element instance refers to.
999 this.setAttributeConfig('element', {
1000 value: Dom.get(attr.element),
1005 _initContent: function(attr) {
1006 this.initAttributes(attr);
1007 this.setAttributes(attr, true);
1013 * Sets the value of the property and fires beforeChange and change events.
1015 * @method _setHTMLAttrConfig
1016 * @param {YAHOO.util.Element} element The Element instance to
1017 * register the config to.
1018 * @param {String} key The name of the config to register
1019 * @param {Object} map A key-value map of the config's params
1021 _setHTMLAttrConfig: function(key, map) {
1022 var el = this.get('element');
1026 map.setter = map.setter || this.DEFAULT_HTML_SETTER;
1027 map.getter = map.getter || this.DEFAULT_HTML_GETTER;
1029 map.value = map.value || el[key];
1030 this._configs[key] = new YAHOO.util.Attribute(map, this);
1035 * Fires when the Element's HTMLElement can be retrieved by Id.
1036 * <p>See: <a href="#addListener">Element.addListener</a></p>
1037 * <p><strong>Event fields:</strong><br>
1038 * <code><String> type</code> available<br>
1039 * <code><HTMLElement>
1040 * target</code> the HTMLElement bound to this Element instance<br>
1041 * <p><strong>Usage:</strong><br>
1042 * <code>var handler = function(e) {var target = e.target};<br>
1043 * myTabs.addListener('available', handler);</code></p>
1048 * Fires when the Element's HTMLElement subtree is rendered.
1049 * <p>See: <a href="#addListener">Element.addListener</a></p>
1050 * <p><strong>Event fields:</strong><br>
1051 * <code><String> type</code> contentReady<br>
1052 * <code><HTMLElement>
1053 * target</code> the HTMLElement bound to this Element instance<br>
1054 * <p><strong>Usage:</strong><br>
1055 * <code>var handler = function(e) {var target = e.target};<br>
1056 * myTabs.addListener('contentReady', handler);</code></p>
1057 * @event contentReady
1061 * Fires before the Element is appended to another Element.
1062 * <p>See: <a href="#addListener">Element.addListener</a></p>
1063 * <p><strong>Event fields:</strong><br>
1064 * <code><String> type</code> beforeAppendTo<br>
1065 * <code><HTMLElement/Element>
1066 * target</code> the HTMLElement/Element being appended to
1067 * <p><strong>Usage:</strong><br>
1068 * <code>var handler = function(e) {var target = e.target};<br>
1069 * myTabs.addListener('beforeAppendTo', handler);</code></p>
1070 * @event beforeAppendTo
1074 * Fires after the Element is appended to another Element.
1075 * <p>See: <a href="#addListener">Element.addListener</a></p>
1076 * <p><strong>Event fields:</strong><br>
1077 * <code><String> type</code> appendTo<br>
1078 * <code><HTMLElement/Element>
1079 * target</code> the HTMLElement/Element being appended to
1080 * <p><strong>Usage:</strong><br>
1081 * <code>var handler = function(e) {var target = e.target};<br>
1082 * myTabs.addListener('appendTo', handler);</code></p>
1086 YAHOO.augment(Element, AttributeProvider);
1087 YAHOO.util.Element = Element;
1090 YAHOO.register("element", YAHOO.util.Element, {version: "2.8.0r4", build: "2449"});