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     Y.log('constructor called', 'life', 'widget');

    71 

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

    73     this._strings = {};

    74 

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

    76 }

    77 

    78 /**

    79  * The build configuration for the Widget class.

    80  * <p>

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

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

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

    84  * </p>

    85  * @property _buildCfg

    86  * @type Object

    87  * @static

    88  * @final

    89  * @private

    90  */

    91 Widget._buildCfg = {

    92     aggregates : ["HTML_PARSER"]

    93 };

    94 

    95 /**

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

    97  * <p>

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

    99  * and to classify events fired by the widget.

   100  * </p>

   101  *

   102  * @property Widget.NAME

   103  * @type String

   104  * @static

   105  */

   106 Widget.NAME = WIDGET;

   107 

   108 /**

   109  * Constant used to identify state changes originating from

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

   111  *

   112  * @property Widget.UI_SRC

   113  * @type String

   114  * @static

   115  * @final

   116  */

   117 Widget.UI_SRC = "ui";

   118 

   119 var UI = Widget.UI_SRC;

   120 

   121 /**

   122  * Static property used to define the default attribute 

   123  * configuration for the Widget.

   124  * 

   125  * @property Widget.ATTRS

   126  * @type Object

   127  * @static

   128  */

   129 Widget.ATTRS = {

   130 

   131     /**

   132      * Flag indicating whether or not this object

   133      * has been through the render lifecycle phase.

   134      *

   135      * @attribute rendered

   136      * @readOnly

   137      * @default false

   138      * @type boolean

   139      */

   140     rendered: {

   141         value:false,

   142         readOnly:true

   143     },

   144 

   145     /**

   146     * @attribute boundingBox

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

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

   149     * for skinning.

   150     * @type Node

   151     */

   152     boundingBox: {

   153         value:null,

   154         setter: function(node) {

   155             return this._setBoundingBox(node);

   156         },

   157         writeOnce: true

   158     },

   159 

   160     /**

   161     * @attribute contentBox

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

   163     * houses its content.

   164     * @type Node

   165     */

   166     contentBox: {

   167         value:null,

   168         setter: function(node) {

   169             return this._setContentBox(node);

   170         },

   171         writeOnce: true

   172     },

   173 

   174     /**

   175     * @attribute tabIndex

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

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

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

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

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

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

   182     * @type Number

   183 	* @default null

   184     */

   185     tabIndex: {

   186 

   187 		value: 0,

   188 		validator: function (val) {

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

   190         }

   191 

   192     },

   193 

   194     /**

   195     * @attribute focused

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

   197 	* has focus.

   198     * @readOnly

   199     * @default false

   200     * @type boolean

   201     */

   202     focused: {

   203         value: false,

   204         readOnly:true

   205     },

   206 

   207     /**

   208     * @attribute disabled

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

   210     * is left to the specific classes extending widget.

   211     * @default false

   212     * @type boolean

   213     */

   214     disabled: {

   215         value: false

   216     },

   217 

   218     /**

   219     * @attribute visible

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

   221     * @default true

   222     * @type boolean

   223     */

   224     visible: {

   225         value: true

   226     },

   227 

   228     /**

   229     * @attribute height

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

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

   232     * @default ""

   233     * @type {String | Number}

   234     */

   235     height: {

   236         value: EMPTY

   237     },

   238 

   239     /**

   240     * @attribute width

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

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

   243     * @default ""

   244     * @type {String | Number}

   245     */

   246     width: {

   247         value: EMPTY

   248     },

   249 

   250     /**

   251      * @attribute moveStyles

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

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

   254      * @default false

   255      * @type boolean

   256      */

   257     moveStyles: {

   258         value: false

   259     },

   260 

   261     /**

   262      * @attribute locale

   263      * @description

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

   265      * return/set strings for this locale.

   266      * @default "en"

   267      * @type String

   268      */

   269     locale : {

   270         value: "en"

   271     },

   272 

   273     /**

   274      * @attribute strings

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

   276      * @default null

   277      * @type Object

   278      */

   279     strings: {

   280         setter: function(val) {

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

   282         },

   283 

   284         getter: function() {

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

   286         }

   287     }

   288 };

   289 

   290 /**

   291  * Cached lowercase version of Widget.NAME

   292  *

   293  * @property Widget._NAME_LOWERCASE

   294  * @private

   295  * @static

   296  */

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

   298 

   299 /**

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

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

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

   303  * the prefix and widget class name).

   304  * <p>

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

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

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

   308  * </p>

   309  * @method getClassName

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

   311  */

   312 Widget.getClassName = function() {

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

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

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

   316 };

   317 

   318 /**

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

   320  * <p>

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

   322  * return the widget instance.

   323  * </p>

   324  * @method Widget.getByNode

   325  * @static

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

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

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

   329  */

   330 Widget.getByNode = function(node) {

   331     var widget,

   332         bbMarker = Widget.getClassName();

   333 

   334     node = Node.get(node);

   335     if (node) {

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

   337         if (node) {

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

   339         }

   340     }

   341 

   342     return widget || null;

   343 };

   344 

   345 /**

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

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

   348  * <pre>

   349  *   {

   350  *       // Set single Node references using selector syntax 

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

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

   353  *       // Set NodeList references using selector syntax 

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

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

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

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

   358  *       label: function(contentBox) {

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

   360  *       }

   361  *   }

   362  * </pre>

   363  * 

   364  * @property Widget.HTML_PARSER

   365  * @type Object

   366  * @static

   367  */

   368 Widget.HTML_PARSER = {};

   369 

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

   371 

   372 	/**

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

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

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

   376 	 * e.g. 

   377 	 * <code>

   378 	 * <pre>

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

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

   381 	 *

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

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

   384 	 * </pre>

   385 	 * </code>

   386 	 *

   387 	 * @method getClassName

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

   389 	 */

   390 	getClassName: function () {

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

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

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

   394 	},

   395 

   396     /**

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

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

   399      *

   400      * @method initializer

   401      * @protected

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

   403      */

   404     initializer: function(config) {

   405         Y.log('initializer called', 'life', 'widget');

   406 

   407         /**

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

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

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

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

   412          * after listeners).

   413          * 

   414          * @event widget:contentUpdate

   415          * @preventable false

   416          * @param {EventFacade} e The Event Facade

   417          */

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

   419 

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

   421 

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

   423         if (nodeId) {

   424             _instances[nodeId] = this;

   425         }

   426 

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

   428         if (htmlConfig) {

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

   430         }

   431     },

   432 

   433     /**

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

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

   436      * list of registered widgets.

   437      *

   438      * @method destructor

   439      * @protected

   440      */

   441     destructor: function() {

   442         Y.log('destructor called', 'life', 'widget');

   443 

   444         var boundingBox = this.get(BOUNDING_BOX);

   445         

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

   447 

   448         var nodeId = boundingBox.get(ID);

   449         if (nodeId && nodeId in _instances) {

   450             delete _instances[nodeId];

   451         }

   452     },

   453 

   454     /**

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

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

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

   458      * for the progressive enhancement use case).

   459      * <p>

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

   461      * widget.

   462      * </p>

   463      * <p>

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

   465      * the actual work.

   466      * </p>

   467      *

   468      * @method render

   469      * @chainable

   470      * @final 

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

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

   473      * <p>

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

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

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

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

   478      * </p>

   479      */

   480     render: function(parentNode) {

   481 

   482         if (this.get(DESTROYED)) {

   483             Y.log("Render failed; widget has been destroyed", "error", "widget");

   484             return;

   485         }

   486 

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

   488              /**

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

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

   491              * <p>

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

   493              * before the widget is rendered.

   494              * </p>

   495              * <p>

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

   497              * after rendering is complete.

   498              * </p>

   499              *

   500              * @event widget:render

   501              * @preventable _defRenderFn

   502              * @param {EventFacade} e The Event Facade

   503              */

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

   505 

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

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

   508                 parentNode = null;

   509             }

   510 

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

   512         }

   513 

   514         return this;

   515     },

   516 

   517     /**

   518      * Default render handler

   519      *

   520      * @method _defRenderFn

   521      * @protected

   522      * @param {EventFacade} e The Event object

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

   524      */

   525     _defRenderFn : function(e) {

   526 

   527             this._renderUI(e.parentNode);

   528             this._bindUI();

   529             this._syncUI();

   530 

   531             this.renderer();

   532 

   533             this._set(RENDERED, true);

   534     },

   535 

   536     /** 

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

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

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

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

   541      * 

   542      * @method renderer

   543      * @protected

   544      */

   545     renderer: function() {

   546         this.renderUI();

   547         this.bindUI();

   548         this.syncUI();

   549     },

   550 

   551     /**

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

   553      * 

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

   555      * automatically for the class hierarchy.

   556      * 

   557      * @method bindUI

   558      * @protected

   559      */

   560     bindUI: function() {},

   561 

   562     /**

   563      * Adds nodes to the DOM 

   564      * 

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

   566      * automatically for the class hierarchy.

   567      * 

   568      * @method renderUI

   569      * @protected

   570      */

   571     renderUI: function() {},

   572 

   573     /**

   574      * Refreshes the rendered UI, based on Widget State

   575      * 

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

   577      * automatically for the class hierarchy.

   578      *

   579      * @method syncUI

   580      * 

   581      */

   582     syncUI: function(){},

   583 

   584     /**

   585     * @method hide

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

   587     */

   588     hide: function() {

   589         return this.set(VISIBLE, false);

   590     },

   591 

   592     /**

   593     * @method show

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

   595     */

   596     show: function() {

   597         return this.set(VISIBLE, true);

   598     },

   599 

   600     /**

   601     * @method focus

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

   603     * attribute to "true".

   604     */

   605     focus: function () {

   606         return this._set(FOCUSED, true);

   607     },

   608 

   609     /**

   610     * @method blur

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

   612     * to "false"

   613     */            

   614     blur: function () {

   615         return this._set(FOCUSED, false);

   616     },

   617 

   618     /**

   619     * @method enable

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

   621     */

   622     enable: function() {

   623         return this.set(DISABLED, false);

   624     },

   625 

   626     /**

   627     * @method disabled

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

   629     */

   630     disable: function() {

   631         return this.set(DISABLED, true);

   632     },

   633 

   634     /**

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

   636      * instance, to retrieve config data values.

   637      * 

   638      * @method _parseHTML

   639      * @private 

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

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

   642      */

   643     _parseHTML : function(node) {

   644  

   645         var schema = this._getHtmlParser(),

   646             data,

   647             val;

   648 

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

   650 

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

   652                 val = null;

   653 

   654                 if (L.isFunction(v)) {

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

   656                 } else {

   657                     if (L.isArray(v)) {

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

   659                     } else {

   660                         val = node.query(v);

   661                     }

   662                 }

   663 

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

   665                     data = data || {};

   666                     data[k] = val;

   667                 }

   668 

   669             }, this);

   670         }

   671 

   672         return data;

   673     },

   674 

   675     /**

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

   677      *

   678      * @method _moveStyles

   679      * @private

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

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

   682      */

   683     _moveStyles: function(nodeFrom, nodeTo) {

   684 

   685         var styles = this.WRAP_STYLES,

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

   687             contentBox = this.get(CONTENT_BOX),

   688             xy = [0,0],

   689             h, w;

   690 

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

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

   693         }

   694 

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

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

   697         }

   698 

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

   700             xy = nodeFrom.getXY();

   701             nodeTo.setStyles({

   702                 right: 'auto',

   703                 bottom: 'auto'

   704             });

   705 

   706             nodeFrom.setStyles({

   707                 right: 'auto',

   708                 bottom: 'auto'

   709             });

   710         }

   711 

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

   713             var s = nodeFrom.getStyle(k);

   714             nodeTo.setStyle(k, s);

   715             if (v === false) {

   716                 nodeFrom.setStyle(k, '');

   717             } else {

   718                 nodeFrom.setStyle(k, v);

   719             }

   720         });

   721 

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

   723             nodeTo.setXY(xy);

   724         }

   725 

   726         if (h) {

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

   728         }

   729 

   730         if (w) {

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

   732         }

   733     },

   734 

   735     /**

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

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

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

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

   740     * to the current document's body.

   741     *

   742     * @method _renderBox

   743     * @private

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

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

   746     */

   747     _renderBox: function(parentNode) {

   748 

   749         var contentBox = this.get(CONTENT_BOX),

   750             boundingBox = this.get(BOUNDING_BOX),

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

   752             body;

   753 

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

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

   756                 this._moveStyles(contentBox, boundingBox);

   757             }

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

   759             if (contentBox.inDoc(doc)) {

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

   761             }

   762             boundingBox.appendChild(contentBox);

   763         }

   764 

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

   766             body = Node.get(BODY);

   767             if (body.get(FIRST_CHILD)) {

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

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

   770             } else {

   771                 body.appendChild(boundingBox);

   772             }

   773         } else {

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

   775                 parentNode.appendChild(boundingBox);

   776             }

   777         }

   778     },

   779 

   780     /**

   781     * Setter for the boundingBox attribute

   782     *

   783     * @method _setBoundingBox

   784     * @private

   785     * @param Node/String

   786     * @return Node

   787     */

   788     _setBoundingBox: function(node) {

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

   790     },

   791 

   792     /**

   793     * Setter for the contentBox attribute

   794     *

   795     * @method _setContentBox

   796     * @private

   797     * @param {Node|String} node

   798     * @return Node

   799     */

   800     _setContentBox: function(node) {

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

   802     },

   803 

   804     /**

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

   806      * the provided template if not found.

   807      *

   808      * @method _setBox

   809      * @private

   810      *

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

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

   813      * @return {Node} The node

   814      */

   815     _setBox : function(node, template) {

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

   817 

   818         var sid = Y.stamp(node);

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

   820             node.set(ID, sid);

   821         }

   822         return node;

   823     },

   824 

   825     /**

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

   827      *

   828      * @method _renderUI

   829      * @protected

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

   831      */

   832     _renderUI: function(parentNode) {

   833         this._renderBoxClassNames();

   834         this._renderBox(parentNode);

   835     },

   836 

   837      /**

   838       * Applies standard class names to the boundingBox and contentBox

   839       * 

   840       * @method _renderBoxClassNames

   841       * @protected

   842       */

   843     _renderBoxClassNames : function() {

   844         var classes = this._getClasses(),

   845             boundingBox = this.get(BOUNDING_BOX),

   846             contentBox = this.get(CONTENT_BOX),

   847             name, i;

   848 

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

   850 

   851         // Start from Widget Sub Class

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

   853             name = classes[i].NAME;

   854             if (name) {

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

   856             }

   857         }

   858 

   859         // Use instance based name for content box

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

   861     },

   862 

   863     /**

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

   865      *

   866      * @method _bindUI

   867      * @protected

   868      */

   869     _bindUI: function() {

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

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

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

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

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

   875 

   876         this._bindDOMListeners();

   877     },

   878 

   879     /**

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

   881      * 

   882      * @method _bindDOMListeners

   883      * @protected

   884      */

   885     _bindDOMListeners : function() {

   886 

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

   888 

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

   890 

   891 		//	Fix for Webkit:

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

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

   894 		//	correct value.

   895 		

   896 		if (Y.UA.webkit) {

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

   898 		}

   899 

   900     },

   901 

   902     /**

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

   904      *

   905      * @method _syncUI

   906      * @protected

   907      */

   908     _syncUI: function() {

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

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

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

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

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

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

   915     },

   916 

   917     /**

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

   919      * 

   920      * @method _uiSetHeight

   921      * @protected

   922      * @param {String | Number} val

   923      */

   924     _uiSetHeight: function(val) {

   925         if (L.isNumber(val)) {

   926             val = val + this.DEF_UNIT;

   927         }

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

   929     },

   930 

   931     /**

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

   933      *

   934      * @method _uiSetWidth

   935      * @protected

   936      * @param {String | Number} val

   937      */

   938     _uiSetWidth: function(val) {

   939         if (L.isNumber(val)) {

   940             val = val + this.DEF_UNIT;

   941         }

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

   943     },

   944 

   945     /**

   946      * Sets the visible state for the UI

   947      * 

   948      * @method _uiSetVisible

   949      * @protected

   950      * @param {boolean} val

   951      */

   952     _uiSetVisible: function(val) {

   953 

   954         var box = this.get(BOUNDING_BOX), 

   955             sClassName = this.getClassName(HIDDEN);

   956 

   957         if (val === true) { 

   958             box.removeClass(sClassName); 

   959         } else {

   960             box.addClass(sClassName); 

   961         }

   962     },

   963 

   964     /**

   965      * Sets the disabled state for the UI

   966      * 

   967      * @protected

   968      * @param {boolean} val

   969      */

   970     _uiSetDisabled: function(val) {

   971 

   972         var box = this.get(BOUNDING_BOX), 

   973             sClassName = this.getClassName(DISABLED);

   974 

   975         if (val === true) {

   976             box.addClass(sClassName);

   977         } else {

   978             box.removeClass(sClassName);

   979         }

   980     },

   981 

   982 

   983     /**

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

   985     *

   986     * @method _uiSetTabIndex

   987     * @protected

   988     * @param Number

   989     */

   990     _uiSetTabIndex: function(index) {

   991 

   992 		var boundingBox = this.get(BOUNDING_BOX);

   993 

   994 		if (L.isNumber(index)) {

   995 			boundingBox.set(TAB_INDEX, index);

   996 		}

   997 		else {

   998 			boundingBox.removeAttribute(TAB_INDEX);

   999 		}

  1000 

  1001     },

  1002 

  1003 

  1004     /**

  1005      * Sets the focused state for the UI

  1006      *

  1007      * @protected

  1008      * @param {boolean} val

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

  1010      * the UI.     

  1011      */

  1012     _uiSetFocused: function(val, src) {

  1013 

  1014         var box = this.get(BOUNDING_BOX),

  1015             sClassName = this.getClassName(FOCUSED);

  1016 

  1017         if (val === true) {

  1018             box.addClass(sClassName);

  1019             if (src !== UI) {

  1020                 box.focus();

  1021             }

  1022         } else {

  1023             box.removeClass(sClassName);

  1024             if (src !== UI) {

  1025                 box.blur();

  1026             }

  1027         }

  1028     },

  1029 

  1030 

  1031 

  1032     /**

  1033      * Default visible attribute state change handler

  1034      *

  1035      * @method _afterVisibleChange

  1036      * @protected

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

  1038      */

  1039     _afterVisibleChange: function(evt) {

  1040         this._uiSetVisible(evt.newVal);

  1041     },

  1042 

  1043     /**

  1044      * Default disabled attribute state change handler

  1045      * 

  1046      * @method _afterDisabledChange

  1047      * @protected

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

  1049      */

  1050     _afterDisabledChange: function(evt) {

  1051         this._uiSetDisabled(evt.newVal);

  1052     },

  1053 

  1054     /**

  1055      * Default height attribute state change handler

  1056      * 

  1057      * @method _afterHeightChange

  1058      * @protected

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

  1060      */

  1061     _afterHeightChange: function(evt) {

  1062         this._uiSetHeight(evt.newVal);

  1063     },

  1064 

  1065     /**

  1066      * Default widget attribute state change handler

  1067      * 

  1068      * @method _afterWidthChange

  1069      * @protected

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

  1071      */

  1072     _afterWidthChange: function(evt) {

  1073         this._uiSetWidth(evt.newVal);

  1074     },

  1075 

  1076     /**

  1077      * Default focused attribute state change handler

  1078      * 

  1079      * @method _afterFocusedChange

  1080      * @protected

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

  1082      */

  1083     _afterFocusedChange: function(evt) {

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

  1085     },

  1086 

  1087 	/**

  1088 	* @method _onDocMouseDown

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

  1090 	* widget's bounding box.

  1091 	* @protected

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

  1093 	*/

  1094 	_onDocMouseDown: function (evt) {

  1095 

  1096 		if (this._hasDOMFocus) {

  1097  			this._onFocus(evt);

  1098 		}

  1099 		

  1100 	},

  1101 

  1102     /**

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

  1104      * 

  1105      * @method _onFocus

  1106      * @protected

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

  1108      */

  1109     _onFocus: function (evt) {

  1110 

  1111 		var target = evt.target,

  1112 			boundingBox = this.get(BOUNDING_BOX),

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

  1114 

  1115 		this._hasDOMFocus = bFocused;

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

  1117 

  1118     },

  1119 

  1120     /**

  1121      * Generic toString implementation for all widgets.

  1122      *

  1123      * @method toString

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

  1125      */

  1126     toString: function() {

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

  1128     },

  1129 

  1130     /**

  1131      * Default unit to use for dimension values

  1132      * 

  1133      * @property DEF_UNIT

  1134      */

  1135     DEF_UNIT : "px",

  1136