1 /*

     2 Copyright (c) 2009, Yahoo! Inc. All rights reserved.

     3 Code licensed under the BSD License:

     4 http://developer.yahoo.net/yui/license.txt

     5 version: 3.0.0b1

     6 build: 1163

     7 */

     8 YUI.add('widget', function(Y) {

     9 

    10 /**

    11  * Provides the base Widget class

    12  *

    13  * @module widget

    14  */

    15 

    16 // Local Constants

    17 var L = Y.Lang,

    18     O = Y.Object,

    19     Node = Y.Node,

    20     ClassNameManager = Y.ClassNameManager,

    21 

    22     WIDGET = "widget",

    23     CONTENT = "content",

    24     VISIBLE = "visible",

    25     HIDDEN = "hidden",

    26     DISABLED = "disabled",

    27     FOCUSED = "focused",

    28     WIDTH = "width",

    29     HEIGHT = "height",

    30     EMPTY = "",

    31     HYPHEN = "-",

    32     BOUNDING_BOX = "boundingBox",

    33     CONTENT_BOX = "contentBox",

    34     PARENT_NODE = "parentNode",

    35     FIRST_CHILD = "firstChild",

    36     OWNER_DOCUMENT = "ownerDocument",

    37     BODY = "body",

    38 	TAB_INDEX = "tabIndex",

    39     LOCALE = "locale",

    40     INIT_VALUE = "initValue",

    41     ID = "id",

    42     RENDER = "render",

    43     RENDERED = "rendered",

    44     DESTROYED = "destroyed",

    45 

    46     ContentUpdate = "contentUpdate",

    47 

    48     // Widget nodeid-to-instance map for now, 1-to-1.

    49     _instances = {};

    50 

    51 /**

    52  * A base class for widgets, providing:

    53  * <ul>

    54  *    <li>The render lifecycle method, in addition to the init and destroy 

    55  *        lifecycle methods provide by Base</li>

    56  *    <li>Abstract methods to support consistent MVC structure across 

    57  *        widgets: renderer, renderUI, bindUI, syncUI</li>

    58  *    <li>Support for common widget attributes, such as boundingBox, contentBox, visible, 

    59  *        disabled, focused, strings</li>

    60  * </ul>

    61  *

    62  * @param config {Object} Object literal specifying widget configuration 

    63  * properties.

    64  *

    65  * @class Widget

    66  * @constructor

    67  * @extends Base

    68  */

    69 function Widget(config) {

    70 

    71     this._yuid = Y.guid(WIDGET);

    72     this._strings = {};

    73 

    74     Widget.superclass.constructor.apply(this, arguments);

    75 }

    76 

    77 /**

    78  * The build configuration for the Widget class.

    79  * <p>

    80  * Defines the static fields which need to be aggregated,

    81  * when this class is used as the main class passed to 

    82  * the <a href="Base.html#method_build">Base.build</a> method.

    83  * </p>

    84  * @property _buildCfg

    85  * @type Object

    86  * @static

    87  * @final

    88  * @private

    89  */

    90 Widget._buildCfg = {

    91     aggregates : ["HTML_PARSER"]

    92 };

    93 

    94 /**

    95  * Static property provides a string to identify the class.

    96  * <p>

    97  * Currently used to apply class identifiers to the bounding box 

    98  * and to classify events fired by the widget.

    99  * </p>

   100  *

   101  * @property Widget.NAME

   102  * @type String

   103  * @static

   104  */

   105 Widget.NAME = WIDGET;

   106 

   107 /**

   108  * Constant used to identify state changes originating from

   109  * the DOM (as opposed to the JavaScript model).

   110  *

   111  * @property Widget.UI_SRC

   112  * @type String

   113  * @static

   114  * @final

   115  */

   116 Widget.UI_SRC = "ui";

   117 

   118 var UI = Widget.UI_SRC;

   119 

   120 /**

   121  * Static property used to define the default attribute 

   122  * configuration for the Widget.

   123  * 

   124  * @property Widget.ATTRS

   125  * @type Object

   126  * @static

   127  */

   128 Widget.ATTRS = {

   129 

   130     /**

   131      * Flag indicating whether or not this object

   132      * has been through the render lifecycle phase.

   133      *

   134      * @attribute rendered

   135      * @readOnly

   136      * @default false

   137      * @type boolean

   138      */

   139     rendered: {

   140         value:false,

   141         readOnly:true

   142     },

   143 

   144     /**

   145     * @attribute boundingBox

   146     * @description The outermost DOM node for the Widget, used for sizing and positioning 

   147     * of a Widget as well as a containing element for any decorator elements used 

   148     * for skinning.

   149     * @type Node

   150     */

   151     boundingBox: {

   152         value:null,

   153         setter: function(node) {

   154             return this._setBoundingBox(node);

   155         },

   156         writeOnce: true

   157     },

   158 

   159     /**

   160     * @attribute contentBox

   161     * @description A DOM node that is a direct descendent of a Widget's bounding box that 

   162     * houses its content.

   163     * @type Node

   164     */

   165     contentBox: {

   166         value:null,

   167         setter: function(node) {

   168             return this._setContentBox(node);

   169         },

   170         writeOnce: true

   171     },

   172 

   173     /**

   174     * @attribute tabIndex

   175     * @description Number (between -32767 to 32767) indicating the widget's 

   176 	* position in the default tab flow.  The value is used to set the 

   177 	* "tabIndex" attribute on the widget's bounding box.  Negative values allow

   178 	* the widget to receive DOM focus programmatically (by calling the focus

   179 	* method), while being removed from the default tab flow.  A value of 

   180 	* null removes the "tabIndex" attribute from the widget's bounding box.

   181     * @type Number

   182 	* @default null

   183     */

   184     tabIndex: {

   185 

   186 		value: 0,

   187 		validator: function (val) {

   188             return (L.isNumber(val) || L.isNull(val));

   189         }

   190 

   191     },

   192 

   193     /**

   194     * @attribute focused

   195     * @description Boolean indicating if the Widget, or one of its descendants, 

   196 	* has focus.

   197     * @readOnly

   198     * @default false

   199     * @type boolean

   200     */

   201     focused: {

   202         value: false,

   203         readOnly:true

   204     },

   205 

   206     /**

   207     * @attribute disabled

   208     * @description Boolean indicating if the Widget should be disabled. The disabled implementation

   209     * is left to the specific classes extending widget.

   210     * @default false

   211     * @type boolean

   212     */

   213     disabled: {

   214         value: false

   215     },

   216 

   217     /**

   218     * @attribute visible

   219     * @description Boolean indicating weather or not the Widget is visible.

   220     * @default true

   221     * @type boolean

   222     */

   223     visible: {

   224         value: true

   225     },

   226 

   227     /**

   228     * @attribute height

   229     * @description String with units, or number, representing the height of the Widget. If a number is provided,

   230     * the default unit, defined by the Widgets DEF_UNIT, property is used.

   231     * @default ""

   232     * @type {String | Number}

   233     */

   234     height: {

   235         value: EMPTY

   236     },

   237 

   238     /**

   239     * @attribute width

   240     * @description String with units, or number, representing the width of the Widget. If a number is provided,

   241     * the default unit, defined by the Widgets DEF_UNIT, property is used.

   242     * @default ""

   243     * @type {String | Number}

   244     */

   245     width: {

   246         value: EMPTY

   247     },

   248 

   249     /**

   250      * @attribute moveStyles

   251      * @description Flag defining whether or not style properties from the content box

   252      * should be moved to the bounding box when wrapped (as defined by the WRAP_STYLES property)

   253      * @default false

   254      * @type boolean

   255      */

   256     moveStyles: {

   257         value: false

   258     },

   259 

   260     /**

   261      * @attribute locale

   262      * @description

   263      * The default locale for the widget. NOTE: Using get/set on the "strings" attribute will

   264      * return/set strings for this locale.

   265      * @default "en"

   266      * @type String

   267      */

   268     locale : {

   269         value: "en"

   270     },

   271 

   272     /**

   273      * @attribute strings

   274      * @description Collection of strings used to label elements of the Widget's UI.

   275      * @default null

   276      * @type Object

   277      */

   278     strings: {

   279         setter: function(val) {

   280             return this._setStrings(val, this.get(LOCALE));

   281         },

   282 

   283         getter: function() {

   284             return this.getStrings(this.get(LOCALE));

   285         }

   286     }

   287 };

   288 

   289 /**

   290  * Cached lowercase version of Widget.NAME

   291  *

   292  * @property Widget._NAME_LOWERCASE

   293  * @private

   294  * @static

   295  */

   296 Widget._NAME_LOWERCASE = Widget.NAME.toLowerCase();

   297 

   298 /**

   299  * Generate a standard prefixed classname for the Widget, prefixed by the default prefix defined

   300  * by the <code>Y.config.classNamePrefix</code> attribute used by <code>ClassNameManager</code> and 

   301  * <code>Widget.NAME.toLowerCase()</code> (e.g. "yui-widget-xxxxx-yyyyy", based on default values for 

   302  * the prefix and widget class name).

   303  * <p>

   304  * The instance based version of this method can be used to generate standard prefixed classnames,

   305  * based on the instances NAME, as opposed to Widget.NAME. This method should be used when you

   306  * need to use a constant class name across different types instances.

   307  * </p>

   308  * @method getClassName

   309  * @param {String*} args* 0..n strings which should be concatenated, using the default separator defined by ClassNameManager, to create the class name

   310  */

   311 Widget.getClassName = function() {

   312 	var args = Y.Array(arguments, 0, true);

   313 	args.splice(0, 0, this._NAME_LOWERCASE);

   314 	return ClassNameManager.getClassName.apply(ClassNameManager, args);

   315 };

   316 

   317 /**

   318  * Returns the widget instance whose bounding box contains, or is, the given node. 

   319  * <p>

   320  * In the case of nested widgets, the nearest bounding box ancestor is used to

   321  * return the widget instance.

   322  * </p>

   323  * @method Widget.getByNode

   324  * @static

   325  * @param node {Node | String} The node for which to return a Widget instance. If a selector

   326  * string is passed in, which selects more than one node, the first node found is used.

   327  * @return {Widget} Widget instance, or null if not found.

   328  */

   329 Widget.getByNode = function(node) {

   330     var widget,

   331         bbMarker = Widget.getClassName();

   332 

   333     node = Node.get(node);

   334     if (node) {

   335         node = (node.hasClass(bbMarker)) ? node : node.ancestor("." + bbMarker);

   336         if (node) {

   337             widget = _instances[node.get(ID)];

   338         }

   339     }

   340 

   341     return widget || null;

   342 };

   343 

   344 /**

   345  * Object hash, defining how attribute values are to be parsed from

   346  * markup contained in the widget's content box. e.g.:

   347  * <pre>

   348  *   {

   349  *       // Set single Node references using selector syntax 

   350  *       // (selector is run through node.query)

   351  *       titleNode: "span.yui-title",

   352  *       // Set NodeList references using selector syntax 

   353  *       // (array indicates selector is to be run through node.queryAll)

   354  *       listNodes: ["li.yui-item"],

   355  *       // Set other attribute types, using a parse function. 

   356  *       // Context is set to the widget instance.

   357  *       label: function(contentBox) {

   358  *           return contentBox.query("span.title").get("innerHTML");

   359  *       }

   360  *   }

   361  * </pre>

   362  * 

   363  * @property Widget.HTML_PARSER

   364  * @type Object

   365  * @static

   366  */

   367 Widget.HTML_PARSER = {};

   368 

   369 Y.extend(Widget, Y.Base, {

   370 

   371 	/**

   372 	 * Returns a class name prefixed with the the value of the 

   373 	 * <code>YUI.config.classNamePrefix</code> attribute + the instances <code>NAME</code> property.

   374 	 * Uses <code>YUI.config.classNameDelimiter</code> attribute to delimit the provided strings.

   375 	 * e.g. 

   376 	 * <code>

   377 	 * <pre>

   378 	 *    // returns "yui-slider-foo-bar", for a slider instance

   379 	 *    var scn = slider.getClassName('foo','bar');

   380 	 *

   381 	 *    // returns "yui-overlay-foo-bar", for an overlay instance

   382 	 *    var ocn = slider.getClassName('foo','bar');

   383 	 * </pre>

   384 	 * </code>

   385 	 *

   386 	 * @method getClassName

   387 	 * @param {String}+ One or more classname bits to be joined and prefixed

   388 	 */

   389 	getClassName: function () {

   390 		var args = Y.Array(arguments, 0, true);

   391 		args.splice(0, 0, this._name);

   392 		return ClassNameManager.getClassName.apply(ClassNameManager, args);

   393 	},

   394 

   395     /**

   396      * Initializer lifecycle implementation for the Widget class. Registers the 

   397      * widget instance, and runs through the Widget's HTML_PARSER definition. 

   398      *

   399      * @method initializer

   400      * @protected

   401      * @param  config {Object} Configuration object literal for the widget

   402      */

   403     initializer: function(config) {

   404 

   405         /**

   406          * Notification event, which widget implementations can fire, when

   407          * they change the content of the widget. This event has no default

   408          * behavior and cannot be prevented, so the "on" or "after"

   409          * moments are effectively equivalent (with on listeners being invoked before 

   410          * after listeners).

   411          * 

   412          * @event widget:contentUpdate

   413          * @preventable false

   414          * @param {EventFacade} e The Event Facade

   415          */

   416         this.publish(ContentUpdate, { preventable:false });

   417 

   418 		this._name = this.constructor.NAME.toLowerCase();

   419 

   420         var nodeId = this.get(BOUNDING_BOX).get(ID);

   421         if (nodeId) {

   422             _instances[nodeId] = this;

   423         }

   424 

   425         var htmlConfig = this._parseHTML(this.get(CONTENT_BOX));

   426         if (htmlConfig) {

   427             Y.aggregate(config, htmlConfig, false);

   428         }

   429     },

   430 

   431     /**

   432      * Descructor lifecycle implementation for the Widget class. Purges events attached

   433      * to the bounding box (and all child nodes) and removes the Widget from the 

   434      * list of registered widgets.

   435      *

   436      * @method destructor

   437      * @protected

   438      */

   439     destructor: function() {

   440 

   441         var boundingBox = this.get(BOUNDING_BOX);

   442         

   443         Y.Event.purgeElement(boundingBox, true);

   444 

   445         var nodeId = boundingBox.get(ID);

   446         if (nodeId && nodeId in _instances) {

   447             delete _instances[nodeId];

   448         }

   449     },

   450 

   451     /**

   452      * Establishes the initial DOM for the widget. Invoking this

   453      * method will lead to the creating of all DOM elements for

   454      * the widget (or the manipulation of existing DOM elements 

   455      * for the progressive enhancement use case).

   456      * <p>

   457      * This method should only be invoked once for an initialized

   458      * widget.

   459      * </p>

   460      * <p>

   461      * It delegates to the widget specific renderer method to do

   462      * the actual work.

   463      * </p>

   464      *

   465      * @method render

   466      * @chainable

   467      * @final 

   468      * @param  parentNode {Object | String} Optional. The Node under which the 

   469      * Widget is to be rendered. This can be a Node instance or a CSS selector string. 

   470      * <p>

   471      * If the selector string returns more than one Node, the first node will be used 

   472      * as the parentNode. NOTE: This argument is required if both the boundingBox and contentBox

   473      * are not currently in the document. If it's not provided, the Widget will be rendered

   474      * to the body of the current document in this case.

   475      * </p>

   476      */

   477     render: function(parentNode) {

   478 

   479         if (this.get(DESTROYED)) {

   480             return;

   481         }

   482 

   483         if (!this.get(RENDERED)) {

   484              /**

   485              * Lifcyle event for the render phase, fired prior to rendering the UI 

   486              * for the widget (prior to invoking the widgets renderer method).

   487              * <p>

   488              * Subscribers to the "on" moment of this event, will be notified 

   489              * before the widget is rendered.

   490              * </p>

   491              * <p>

   492              * Subscribers to the "after" momemt of this event, will be notified

   493              * after rendering is complete.

   494              * </p>

   495              *

   496              * @event widget:render

   497              * @preventable _defRenderFn

   498              * @param {EventFacade} e The Event Facade

   499              */

   500             this.publish(RENDER, {queuable:false, defaultFn: this._defRenderFn});

   501 

   502             parentNode = (parentNode) ? Node.get(parentNode) : null;

   503             if (parentNode && !parentNode.inDoc()) {

   504                 parentNode = null;

   505             }

   506 

   507             this.fire(RENDER, {parentNode: parentNode});

   508         }

   509 

   510         return this;

   511     },

   512 

   513     /**

   514      * Default render handler

   515      *

   516      * @method _defRenderFn

   517      * @protected

   518      * @param {EventFacade} e The Event object

   519      * @param {Node} parentNode The parent node to render to, if passed in to the <code>render</code> method

   520      */

   521     _defRenderFn : function(e) {

   522 

   523             this._renderUI(e.parentNode);

   524             this._bindUI();

   525             this._syncUI();

   526 

   527             this.renderer();

   528 

   529             this._set(RENDERED, true);

   530     },

   531 

   532     /** 

   533      * Creates DOM (or manipulates DOM for progressive enhancement)

   534      * This method is invoked by render() and is not chained 

   535      * automatically for the class hierarchy (like initializer, destructor) 

   536      * so it should be chained manually for subclasses if required.

   537      * 

   538      * @method renderer

   539      * @protected

   540      */

   541     renderer: function() {

   542         this.renderUI();

   543         this.bindUI();

   544         this.syncUI();

   545     },

   546 

   547     /**

   548      * Configures/Sets up listeners to bind Widget State to UI/DOM

   549      * 

   550      * This method is not called by framework and is not chained 

   551      * automatically for the class hierarchy.

   552      * 

   553      * @method bindUI

   554      * @protected

   555      */

   556     bindUI: function() {},

   557 

   558     /**

   559      * Adds nodes to the DOM 

   560      * 

   561      * This method is not called by framework and is not chained 

   562      * automatically for the class hierarchy.

   563      * 

   564      * @method renderUI

   565      * @protected

   566      */

   567     renderUI: function() {},

   568 

   569     /**

   570      * Refreshes the rendered UI, based on Widget State

   571      * 

   572      * This method is not called by framework and is not chained

   573      * automatically for the class hierarchy.

   574      *

   575      * @method syncUI

   576      * 

   577      */

   578     syncUI: function(){},

   579 

   580     /**

   581     * @method hide

   582     * @description Shows the Module element by setting the "visible" attribute to "false".

   583     */

   584     hide: function() {

   585         return this.set(VISIBLE, false);

   586     },

   587 

   588     /**

   589     * @method show

   590     * @description Shows the Module element by setting the "visible" attribute to "true".

   591     */

   592     show: function() {

   593         return this.set(VISIBLE, true);

   594     },

   595 

   596     /**

   597     * @method focus

   598     * @description Causes the Widget to receive the focus by setting the "focused" 

   599     * attribute to "true".

   600     */

   601     focus: function () {

   602         return this._set(FOCUSED, true);

   603     },

   604 

   605     /**

   606     * @method blur

   607     * @description Causes the Widget to lose focus by setting the "focused" attribute 

   608     * to "false"

   609     */            

   610     blur: function () {

   611         return this._set(FOCUSED, false);

   612     },

   613 

   614     /**

   615     * @method enable

   616     * @description Set the Widget's "disabled" attribute to "false".

   617     */

   618     enable: function() {

   619         return this.set(DISABLED, false);

   620     },

   621 

   622     /**

   623     * @method disabled

   624     * @description Set the Widget's "disabled" attribute to "true".

   625     */

   626     disable: function() {

   627         return this.set(DISABLED, true);

   628     },

   629 

   630     /**

   631      * Utilitity method used to apply the <code>HTML_PARSER</code> configuration for the 

   632      * instance, to retrieve config data values.

   633      * 

   634      * @method _parseHTML

   635      * @private 

   636      * @param  node {Node} Root node to use to parse markup for configuration data

   637      * @return config {Object} configuration object, with values found in the HTML, populated

   638      */

   639     _parseHTML : function(node) {

   640  

   641         var schema = this._getHtmlParser(),

   642             data,

   643             val;

   644 

   645         if (schema && node && node.hasChildNodes()) {

   646 

   647             O.each(schema, function(v, k, o) {

   648                 val = null;

   649 

   650                 if (L.isFunction(v)) {

   651                     val = v.call(this, node);

   652                 } else {

   653                     if (L.isArray(v)) {

   654                         val = node.queryAll(v[0]);

   655                     } else {

   656                         val = node.query(v);

   657                     }

   658                 }

   659 

   660                 if (val !== null && val !== undefined) {

   661                     data = data || {};

   662                     data[k] = val;

   663                 }

   664 

   665             }, this);

   666         }

   667 

   668         return data;

   669     },

   670 

   671     /**

   672      * Moves a pre-defined set of style rules (WRAP_STYLES) from one node to another.

   673      *

   674      * @method _moveStyles

   675      * @private

   676      * @param {Node} nodeFrom The node to gather the styles from

   677      * @param {Node} nodeTo The node to apply the styles to

   678      */

   679     _moveStyles: function(nodeFrom, nodeTo) {

   680 

   681         var styles = this.WRAP_STYLES,

   682             pos = nodeFrom.getStyle('position'),

   683             contentBox = this.get(CONTENT_BOX),

   684             xy = [0,0],

   685             h, w;

   686 

   687         if (!this.get('height')) {

   688             h = contentBox.get('offsetHeight');

   689         }

   690 

   691         if (!this.get('width')) {

   692             w = contentBox.get('offsetWidth');

   693         }

   694 

   695         if (pos === 'absolute') {

   696             xy = nodeFrom.getXY();

   697             nodeTo.setStyles({

   698                 right: 'auto',

   699                 bottom: 'auto'

   700             });

   701 

   702             nodeFrom.setStyles({

   703                 right: 'auto',

   704                 bottom: 'auto'

   705             });

   706         }

   707 

   708         Y.each(styles, function(v, k) {

   709             var s = nodeFrom.getStyle(k);

   710             nodeTo.setStyle(k, s);

   711             if (v === false) {

   712                 nodeFrom.setStyle(k, '');

   713             } else {

   714                 nodeFrom.setStyle(k, v);

   715             }

   716         });

   717 

   718         if (pos === 'absolute') {

   719             nodeTo.setXY(xy);

   720         }

   721 

   722         if (h) {

   723             this.set('height', h);

   724         }

   725 

   726         if (w) {

   727             this.set('width', w);

   728         }

   729     },

   730 

   731     /**

   732     * Helper method to collect the boundingBox and contentBox, set styles and append to the provided parentNode, if not

   733     * already a child. The owner document of the boundingBox, or the owner document of the contentBox will be used 

   734     * as the document into which the Widget is rendered if a parentNode is node is not provided. If both the boundingBox and

   735     * the contentBox are not currently in the document, and no parentNode is provided, the widget will be rendered 

   736     * to the current document's body.

   737     *

   738     * @method _renderBox

   739     * @private

   740     * @param {Node} parentNode The parentNode to render the widget to. If not provided, and both the boundingBox and

   741     * the contentBox are not currently in the document, the widget will be rendered to the current document's body.

   742     */

   743     _renderBox: function(parentNode) {

   744 

   745         var contentBox = this.get(CONTENT_BOX),

   746             boundingBox = this.get(BOUNDING_BOX),

   747             doc = boundingBox.get(OWNER_DOCUMENT) || contentBox.get(OWNER_DOCUMENT),

   748             body;

   749 

   750         if (!boundingBox.compareTo(contentBox.get(PARENT_NODE))) {

   751             if (this.get('moveStyles')) {

   752                 this._moveStyles(contentBox, boundingBox);

   753             }

   754             // If contentBox box is already in the document, have boundingBox box take it's place

   755             if (contentBox.inDoc(doc)) {

   756                 contentBox.get(PARENT_NODE).replaceChild(boundingBox, contentBox);

   757             }

   758             boundingBox.appendChild(contentBox);

   759         }

   760 

   761         if (!boundingBox.inDoc(doc) && !parentNode) {

   762             body = Node.get(BODY);

   763             if (body.get(FIRST_CHILD)) {

   764                 // Special case when handling body as default (no parentNode), always try to insert.

   765                 body.insertBefore(boundingBox, body.get(FIRST_CHILD));

   766             } else {

   767                 body.appendChild(boundingBox);

   768             }

   769         } else {

   770             if (parentNode && !parentNode.compareTo(boundingBox.get(PARENT_NODE))) {

   771                 parentNode.appendChild(boundingBox);

   772             }

   773         }

   774     },

   775 

   776     /**

   777     * Setter for the boundingBox attribute

   778     *

   779     * @method _setBoundingBox

   780     * @private

   781     * @param Node/String

   782     * @return Node

   783     */

   784     _setBoundingBox: function(node) {

   785         return this._setBox(node, this.BOUNDING_TEMPLATE);

   786     },

   787 

   788     /**

   789     * Setter for the contentBox attribute

   790     *

   791     * @method _setContentBox

   792     * @private

   793     * @param {Node|String} node

   794     * @return Node

   795     */

   796     _setContentBox: function(node) {

   797         return this._setBox(node, this.CONTENT_TEMPLATE);

   798     },

   799 

   800     /**

   801      * Helper method to set the bounding/content box, or create it from

   802      * the provided template if not found.

   803      *

   804      * @method _setBox

   805      * @private

   806      *

   807      * @param {Node|String} node The node reference

   808      * @param {String} template HTML string template for the node

   809      * @return {Node} The node

   810      */

   811     _setBox : function(node, template) {

   812         node = Node.get(node) || Node.create(template);

   813 

   814         var sid = Y.stamp(node);

   815         if (!node.get(ID)) {

   816             node.set(ID, sid);

   817         }

   818         return node;

   819     },

   820 

   821     /**

   822      * Initializes the UI state for the Widget's bounding/content boxes.

   823      *

   824      * @method _renderUI

   825      * @protected

   826      * @param {Node} The parent node to rendering the widget into

   827      */

   828     _renderUI: function(parentNode) {

   829         this._renderBoxClassNames();

   830         this._renderBox(parentNode);

   831     },

   832 

   833      /**

   834       * Applies standard class names to the boundingBox and contentBox

   835       * 

   836       * @method _renderBoxClassNames

   837       * @protected

   838       */

   839     _renderBoxClassNames : function() {

   840         var classes = this._getClasses(),

   841             boundingBox = this.get(BOUNDING_BOX),

   842             contentBox = this.get(CONTENT_BOX),

   843             name, i;

   844 

   845         boundingBox.addClass(Widget.getClassName());

   846 

   847         // Start from Widget Sub Class

   848         for (i = classes.length-3; i >= 0; i--) {

   849             name = classes[i].NAME;

   850             if (name) {

   851                 boundingBox.addClass(ClassNameManager.getClassName(name.toLowerCase()));

   852             }

   853         }

   854 

   855         // Use instance based name for content box

   856         contentBox.addClass(this.getClassName(CONTENT));

   857     },

   858 

   859     /**

   860      * Sets up DOM and CustomEvent listeners for the widget.

   861      *

   862      * @method _bindUI

   863      * @protected

   864      */

   865     _bindUI: function() {

   866         this.after('visibleChange', this._afterVisibleChange);

   867         this.after('disabledChange', this._afterDisabledChange);

   868         this.after('heightChange', this._afterHeightChange);

   869         this.after('widthChange', this._afterWidthChange);

   870         this.after('focusedChange', this._afterFocusedChange);

   871 

   872         this._bindDOMListeners();

   873     },

   874 

   875     /**

   876      * Sets up DOM listeners, on elements rendered by the widget.

   877      * 

   878      * @method _bindDOMListeners

   879      * @protected

   880      */

   881     _bindDOMListeners : function() {

   882 

   883 		var oDocument = this.get(BOUNDING_BOX).get("ownerDocument");

   884 

   885 		oDocument.on("focus", this._onFocus, this);

   886 

   887 		//	Fix for Webkit:

   888 		//	Document doesn't receive focus in Webkit when the user mouses 

   889 		//	down on it, so the "focused" attribute won't get set to the 

   890 		//	correct value.

   891 		

   892 		if (Y.UA.webkit) {

   893 			oDocument.on("mousedown", this._onDocMouseDown, this);

   894 		}

   895 

   896     },

   897 

   898     /**

   899      * Updates the widget UI to reflect the attribute state.

   900      *

   901      * @method _syncUI

   902      * @protected

   903      */

   904     _syncUI: function() {

   905         this._uiSetVisible(this.get(VISIBLE));

   906         this._uiSetDisabled(this.get(DISABLED));

   907         this._uiSetHeight(this.get(HEIGHT));

   908         this._uiSetWidth(this.get(WIDTH));

   909         this._uiSetFocused(this.get(FOCUSED));

   910 		this._uiSetTabIndex(this.get(TAB_INDEX));

   911     },

   912 

   913     /**

   914      * Sets the height on the widget's bounding box element

   915      * 

   916      * @method _uiSetHeight

   917      * @protected

   918      * @param {String | Number} val

   919      */

   920     _uiSetHeight: function(val) {

   921         if (L.isNumber(val)) {

   922             val = val + this.DEF_UNIT;

   923         }

   924         this.get(BOUNDING_BOX).setStyle(HEIGHT, val);

   925     },

   926 

   927     /**

   928      * Sets the width on the widget's bounding box element

   929      *

   930      * @method _uiSetWidth

   931      * @protected

   932      * @param {String | Number} val

   933      */

   934     _uiSetWidth: function(val) {

   935         if (L.isNumber(val)) {

   936             val = val + this.DEF_UNIT;

   937         }

   938         this.get(BOUNDING_BOX).setStyle(WIDTH, val);

   939     },

   940 

   941     /**

   942      * Sets the visible state for the UI

   943      * 

   944      * @method _uiSetVisible

   945      * @protected

   946      * @param {boolean} val

   947      */

   948     _uiSetVisible: function(val) {

   949 

   950         var box = this.get(BOUNDING_BOX), 

   951             sClassName = this.getClassName(HIDDEN);

   952 

   953         if (val === true) { 

   954             box.removeClass(sClassName); 

   955         } else {

   956             box.addClass(sClassName); 

   957         }

   958     },

   959 

   960     /**

   961      * Sets the disabled state for the UI

   962      * 

   963      * @protected

   964      * @param {boolean} val

   965      */

   966     _uiSetDisabled: function(val) {

   967 

   968         var box = this.get(BOUNDING_BOX), 

   969             sClassName = this.getClassName(DISABLED);

   970 

   971         if (val === true) {

   972             box.addClass(sClassName);

   973         } else {

   974             box.removeClass(sClassName);

   975         }

   976     },

   977 

   978 

   979     /**

   980     * Set the tabIndex on the widget's rendered UI

   981     *

   982     * @method _uiSetTabIndex

   983     * @protected

   984     * @param Number

   985     */

   986     _uiSetTabIndex: function(index) {

   987 

   988 		var boundingBox = this.get(BOUNDING_BOX);

   989 

   990 		if (L.isNumber(index)) {

   991 			boundingBox.set(TAB_INDEX, index);

   992 		}

   993 		else {

   994 			boundingBox.removeAttribute(TAB_INDEX);

   995 		}

   996 

   997     },

   998 

   999 

  1000     /**

  1001      * Sets the focused state for the UI

  1002      *

  1003      * @protected

  1004      * @param {boolean} val

  1005      * @param {string} src String representing the source that triggered an update to 

  1006      * the UI.     

  1007      */

  1008     _uiSetFocused: function(val, src) {

  1009 

  1010         var box = this.get(BOUNDING_BOX),

  1011             sClassName = this.getClassName(FOCUSED);

  1012 

  1013         if (val === true) {

  1014             box.addClass(sClassName);

  1015             if (src !== UI) {

  1016                 box.focus();

  1017             }

  1018         } else {

  1019             box.removeClass(sClassName);

  1020             if (src !== UI) {

  1021                 box.blur();

  1022             }

  1023         }

  1024     },

  1025 

  1026 

  1027 

  1028     /**

  1029      * Default visible attribute state change handler

  1030      *

  1031      * @method _afterVisibleChange

  1032      * @protected

  1033      * @param {EventFacade} evt The event facade for the attribute change

  1034      */

  1035     _afterVisibleChange: function(evt) {

  1036         this._uiSetVisible(evt.newVal);

  1037     },

  1038 

  1039     /**

  1040      * Default disabled attribute state change handler

  1041      * 

  1042      * @method _afterDisabledChange

  1043      * @protected

  1044      * @param {EventFacade} evt The event facade for the attribute change

  1045      */

  1046     _afterDisabledChange: function(evt) {

  1047         this._uiSetDisabled(evt.newVal);

  1048     },

  1049 

  1050     /**

  1051      * Default height attribute state change handler

  1052      * 

  1053      * @method _afterHeightChange

  1054      * @protected

  1055      * @param {EventFacade} evt The event facade for the attribute change

  1056      */

  1057     _afterHeightChange: function(evt) {

  1058         this._uiSetHeight(evt.newVal);

  1059     },

  1060 

  1061     /**

  1062      * Default widget attribute state change handler

  1063      * 

  1064      * @method _afterWidthChange

  1065      * @protected

  1066      * @param {EventFacade} evt The event facade for the attribute change

  1067      */

  1068     _afterWidthChange: function(evt) {

  1069         this._uiSetWidth(evt.newVal);

  1070     },

  1071 

  1072     /**

  1073      * Default focused attribute state change handler

  1074      * 

  1075      * @method _afterFocusedChange

  1076      * @protected

  1077      * @param {EventFacade} evt The event facade for the attribute change

  1078      */

  1079     _afterFocusedChange: function(evt) {

  1080         this._uiSetFocused(evt.newVal, evt.src);

  1081     },

  1082 

  1083 	/**

  1084 	* @method _onDocMouseDown

  1085 	* @description "mousedown" event handler for the owner document of the 

  1086 	* widget's bounding box.

  1087 	* @protected

  1088     * @param {EventFacade} evt The event facade for the DOM focus event

  1089 	*/

  1090 	_onDocMouseDown: function (evt) {

  1091 

  1092 		if (this._hasDOMFocus) {

  1093  			this._onFocus(evt);

  1094 		}

  1095 		

  1096 	},

  1097 

  1098     /**

  1099      * DOM focus event handler, used to sync the state of the Widget with the DOM

  1100      * 

  1101      * @method _onFocus

  1102      * @protected

  1103      * @param {EventFacade} evt The event facade for the DOM focus event

  1104      */

  1105     _onFocus: function (evt) {

  1106 

  1107 		var target = evt.target,

  1108 			boundingBox = this.get(BOUNDING_BOX),

  1109 			bFocused = (boundingBox.compareTo(target) || boundingBox.contains(target));

  1110 

  1111 		this._hasDOMFocus = bFocused;

  1112         this._set(FOCUSED, bFocused, { src: UI });

  1113 

  1114     },

  1115 

  1116     /**

  1117      * Generic toString implementation for all widgets.

  1118      *

  1119      * @method toString

  1120      * @return {String} The default string value for the widget [ displays the NAME of the instance, and the unique id ]

  1121      */

  1122     toString: function() {

  1123         return this.constructor.NAME + "[" + this._yuid + "]";

  1124     },

  1125 

  1126     /**

  1127      * Default unit to use for dimension values

  1128      * 

  1129      * @property DEF_UNIT

  1130      */

  1131     DEF_UNIT : "px",

  1132 

  1133     /**

  1134      * Static property defining the markup template for content box.

  1135      *

  1136      * @property CONTENT_TEMPLATE