jssource/src_files/include/javascript/yui3/build/widget/widget.js

   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.0
   6 build: 1549
   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
1137      * @type String
1138      */
1139     CONTENT_TEMPLATE : "<div></div>",
1140
1141     /**
1142      * Static property defining the markup template for bounding box.
1143      *
1144      * @property BOUNDING_TEMPLATE
1145      * @type String
1146      */
1147     BOUNDING_TEMPLATE : "<div></div>",
1148
1149     /**
1150      * Static property listing the styles that are mimiced on the bounding box from the content box.
1151      *
1152      * @property WRAP_STYLES
1153      * @type Object
1154      */
1155     WRAP_STYLES : {
1156         height: '100%',
1157         width: '100%',
1158         zIndex: false,
1159         position: 'static',
1160         top: '0',
1161         left: '0',
1162         bottom: '',
1163         right: '',
1164         padding: '',
1165         margin: ''
1166     },
1167
1168     /**
1169      * Sets strings for a particular locale, merging with any existing
1170      * strings which may already be defined for the locale.
1171      *
1172      * @method _setStrings
1173      * @protected
1174      * @param {Object} strings The hash of string key/values to set
1175      * @param {Object} locale The locale for the string values being set
1176      */
1177     _setStrings : function(strings, locale) {
1178         var strs = this._strings;
1179         locale = locale.toLowerCase();
1180
1181         if (!strs[locale]) {
1182             strs[locale] = {};
1183         }
1184
1185         Y.aggregate(strs[locale], strings, true);
1186         return strs[locale];
1187     },
1188
1189     /**
1190      * Returns the strings key/value hash for a paricular locale, without locale lookup applied.
1191      *
1192      * @method _getStrings
1193      * @protected
1194      * @param {Object} locale
1195      */
1196     _getStrings : function(locale) {
1197         return this._strings[locale.toLowerCase()];
1198     },
1199
1200     /**
1201      * Gets the entire strings hash for a particular locale, performing locale lookup.
1202      * <p>
1203      * If no values of the key are defined for a particular locale the value for the
1204      * default locale (in initial locale set for the class) is returned.
1205      * </p>
1206      * @method getStrings
1207      * @param {String} locale (optional) The locale for which the string value is required. Defaults to the current locale, if not provided.
1208      */
1209     // TODO: Optimize/Cache. Clear cache on _setStrings call.
1210     getStrings : function(locale) {
1211
1212         locale = (locale || this.get(LOCALE)).toLowerCase();
1213
1214
1215         var defLocale = this.getDefaultLocale().toLowerCase(),
1216             defStrs = this._getStrings(defLocale),
1217             strs = (defStrs) ? Y.merge(defStrs) : {},
1218             localeSegments = locale.split(HYPHEN);
1219
1220         // If locale is different than the default, or needs lookup support
1221         if (locale !== defLocale || localeSegments.length > 1) {
1222             var lookup = "";
1223             for (var i = 0, l = localeSegments.length; i < l; ++i) {
1224                 lookup += localeSegments[i];
1225
1226
1227                 var localeStrs = this._getStrings(lookup);
1228                 if (localeStrs) {
1229                     Y.aggregate(strs, localeStrs, true);
1230                 }
1231                 lookup += HYPHEN;
1232             }
1233         }
1234
1235         return strs;
1236     },
1237
1238     /**
1239      * Gets the string for a particular key, for a particular locale, performing locale lookup.
1240      * <p>
1241      * If no values if defined for the key, for the given locale, the value for the
1242      * default locale (in initial locale set for the class) is returned.
1243      * </p>
1244      * @method getString
1245      * @param {String} key The key.
1246      * @param {String} locale (optional) The locale for which the string value is required. Defaults to the current locale, if not provided.
1247      */
1248     getString : function(key, locale) {
1249
1250         locale = (locale || this.get(LOCALE)).toLowerCase();
1251
1252
1253         var defLocale = (this.getDefaultLocale()).toLowerCase(),
1254             strs = this._getStrings(defLocale) || {},
1255             str = strs[key],
1256             idx = locale.lastIndexOf(HYPHEN);
1257
1258         // If locale is different than the default, or needs lookup support
1259         if (locale !== defLocale || idx != -1) {
1260             do {
1261
1262                 strs = this._getStrings(locale);
1263                 if (strs && key in strs) {
1264                     str = strs[key];
1265                     break;
1266                 }
1267                 idx = locale.lastIndexOf(HYPHEN);
1268                 // Chop of last locale segment
1269                 if (idx != -1) {
1270                     locale = locale.substring(0, idx);
1271                 }
1272
1273             } while (idx != -1);
1274         }
1275
1276         return str;
1277     },
1278
1279     /**
1280      * Returns the default locale for the widget (the locale value defined by the
1281      * widget class, or provided by the user during construction).
1282      *
1283      * @method getDefaultLocale
1284      * @return {String} The default locale for the widget
1285      */
1286     getDefaultLocale : function() {
1287         return this._conf.get(LOCALE, INIT_VALUE);
1288     },
1289
1290     /**
1291      * Private stings hash, used to store strings in locale specific buckets.
1292      *
1293      * @property _strings
1294      * @private
1295      * @type Object
1296      */
1297     _strings: null,
1298
1299     /**
1300      * Gets the HTML_PARSER definition for this instance, by merging HTML_PARSER
1301      * definitions across the class hierarchy.
1302      *
1303      * @method _getHtmlParser
1304      * @return {Object} HTML_PARSER definition for this instance
1305      */
1306     _getHtmlParser : function() {
1307         if (!this._HTML_PARSER) {
1308             var classes = this._getClasses(),
1309                 parser = {},
1310                 i, p;
1311
1312             for (i = classes.length - 1; i >= 0; i--) {
1313                 p = classes[i].HTML_PARSER;
1314                 if (p) {
1315                     Y.mix(parser, p, true);
1316                 }
1317             }
1318
1319             this._HTML_PARSER = parser;
1320         }
1321
1322         return this._HTML_PARSER;
1323     }
1324 });
1325
1326 Y.Widget = Widget;
1327
1328
1329 }, '3.0.0' ,{requires:['attribute', 'event-focus', 'base', 'node', 'classnamemanager']});