lib/yuilib/3.13.0/button-core/button-core.js

   1 /*
   2 YUI 3.13.0 (build 508226d)
   3 Copyright 2013 Yahoo! Inc. All rights reserved.
   4 Licensed under the BSD License.
   5 http://yuilibrary.com/license/
   6 */
   7
   8 YUI.add('button-core', function (Y, NAME) {
   9
  10 /**
  11  * Provides an interface for working with button-like DOM nodes
  12  *
  13  * @module button-core
  14  * @since 3.5.0
  15  */
  16 var getClassName = Y.ClassNameManager.getClassName,
  17     AttributeCore = Y.AttributeCore;
  18
  19 /**
  20  * Creates a button
  21  *
  22  * @class ButtonCore
  23  * @uses AttributeCore
  24  * @param config {Object} Configuration object
  25  * @constructor
  26  */
  27 function ButtonCore(config) {
  28     this.initializer(config);
  29 }
  30
  31 ButtonCore.prototype = {
  32
  33     /**
  34      *
  35      * @property TEMPLATE
  36      * @type {String}
  37      * @default <button/>
  38      */
  39     TEMPLATE: '<button/>',
  40
  41     /**
  42      *
  43      * @property constructor
  44      * @type {Object}
  45      * @default ButtonCore
  46      * @private
  47      */
  48     constructor: ButtonCore,
  49
  50     /**
  51      * @method initializer
  52      * @description Internal init() handler.
  53      * @param config {Object} Config object.
  54      * @private
  55      */
  56     initializer: function(config) {
  57         this._initNode(config);
  58         this._initAttributes(config);
  59         this._renderUI(config);
  60     },
  61
  62     /**
  63      * @method _initNode
  64      * @description Node initializer
  65      * @param config {Object} Config object.
  66      * @private
  67      */
  68     _initNode: function(config) {
  69         if (config.host) {
  70             this._host = Y.one(config.host);
  71         } else {
  72             this._host = Y.Node.create(this.TEMPLATE);
  73         }
  74     },
  75
  76     /**
  77      * @method _initAttributes
  78      * @description  Attribute initializer
  79      * @param config {Object} Config object.
  80      * @private
  81      */
  82     _initAttributes: function(config) {
  83         AttributeCore.call(this, ButtonCore.ATTRS, config);
  84     },
  85
  86     /**
  87      * @method renderUI
  88      * @description Renders any UI/DOM elements for Button instances
  89      * @param config {Object} Config object.
  90      * @private
  91      */
  92     _renderUI: function() {
  93         var node = this.getNode(),
  94             nodeName = node.get('nodeName').toLowerCase();
  95
  96         // Set some default node attributes
  97         node.addClass(ButtonCore.CLASS_NAMES.BUTTON);
  98
  99         if (nodeName !== 'button' && nodeName !== 'input') {
 100             node.set('role', 'button');
 101         }
 102     },
 103
 104     /**
 105      * @method enable
 106      * @description Sets the button's `disabled` DOM attribute to `false`
 107      * @public
 108      */
 109     enable: function() {
 110         this.set('disabled', false);
 111     },
 112
 113     /**
 114      * @method disable
 115      * @description Sets the button's `disabled` DOM attribute to `true`
 116      * @public
 117      */
 118     disable: function() {
 119         this.set('disabled', true);
 120     },
 121
 122     /**
 123      * @method getNode
 124      * @description Gets the button's host node
 125      * @return {Node} The host node instance
 126      * @public
 127      */
 128     getNode: function() {
 129         if (!this._host) {
 130             // If this._host doesn't exist, that means this._initNode
 131             // was never executed, meaning this is likely a Widget and
 132             // the host node should point to the boundingBox.
 133             this._host = this.get('boundingBox');
 134         }
 135
 136         return this._host;
 137     },
 138
 139     /**
 140      * @method _getLabel
 141      * @description Getter for a button's `label` ATTR
 142      * @return {String} The text label of the button
 143      * @private
 144      */
 145     _getLabel: function () {
 146         var node = this.getNode(),
 147             label = ButtonCore._getTextLabelFromNode(node);
 148
 149         return label;
 150     },
 151
 152     /**
 153      * @method _getLabelHTML
 154      * @description Getter for a button's `labelHTML` ATTR
 155      * @return {HTML} The HTML label of the button
 156      * @private
 157      */
 158     _getLabelHTML: function () {
 159         var node = this.getNode(),
 160             labelHTML = ButtonCore._getHTMLFromNode(node);
 161
 162         return labelHTML;
 163     },
 164
 165     /**
 166      * @method _setLabel
 167      * @description Setter for a button's `label` ATTR
 168      * @param value (String) The value to set for `label`
 169      * @param name (String) The name of this ATTR (`label`)
 170      * @param opts (Object) Additional options
 171      *    @param opts.src (String) A string identifying the callee.
 172      *        `internal` will not sync this value with the `labelHTML` ATTR
 173      * @return {String} The text label for the given node
 174      * @private
 175      */
 176     _setLabel: function (value, name, opts) {
 177         var label = Y.Escape.html(value);
 178
 179         if (!opts || opts.src !== 'internal') {
 180             this.set('labelHTML', label, {src: 'internal'});
 181         }
 182
 183         return label;
 184     },
 185
 186     /**
 187      * @method _setLabelHTML
 188      * @description Setter for a button's `labelHTML` ATTR
 189      * @param value (HTML) The value to set for `labelHTML`
 190      * @param name (String) The name of this ATTR (`labelHTML`)
 191      * @param opts (Object) Additional options
 192      *    @param opts.src (String) A string identifying the callee.
 193      *        `internal` will not sync this value with the `label` ATTR
 194      * @return {HTML} The HTML label for the given node
 195      * @private
 196      */
 197     _setLabelHTML: function (value, name, opts) {
 198         var node = this.getNode(),
 199             labelNode = ButtonCore._getLabelNodeFromParent(node),
 200             nodeName = node.get('nodeName').toLowerCase();
 201
 202         if (nodeName === 'input') {
 203             labelNode.set('value', value);
 204         }
 205         else {
 206             labelNode.setHTML(value);
 207         }
 208
 209         if (!opts || opts.src !== 'internal') {
 210             this.set('label', value, {src: 'internal'});
 211         }
 212
 213         return value;
 214     },
 215
 216     /**
 217      * @method _setDisabled
 218      * @description Setter for the `disabled` ATTR
 219      * @param value {boolean}
 220      * @private
 221      */
 222     _setDisabled: function(value) {
 223         var node = this.getNode();
 224
 225         node.getDOMNode().disabled = value; // avoid rerunning setter when this === node
 226         node.toggleClass(ButtonCore.CLASS_NAMES.DISABLED, value);
 227
 228         return value;
 229     }
 230 };
 231
 232 // ButtonCore inherits from AttributeCore
 233 Y.mix(ButtonCore.prototype, AttributeCore.prototype);
 234
 235 /**
 236  * Attribute configuration.
 237  *
 238  * @property ATTRS
 239  * @type {Object}
 240  * @protected
 241  * @static
 242  */
 243 ButtonCore.ATTRS = {
 244
 245     /**
 246      * The text of the button's label
 247      *
 248      * @config label
 249      * @type String
 250      */
 251     label: {
 252         setter: '_setLabel',
 253         getter: '_getLabel',
 254         lazyAdd: false
 255     },
 256
 257     /**
 258      * The HTML of the button's label
 259      *
 260      * This attribute accepts HTML and inserts it into the DOM **without**
 261      * sanitization.  This attribute should only be used with HTML that has
 262      * either been escaped (using `Y.Escape.html`), or sanitized according to
 263      * the requirements of your application.
 264      *
 265      * If all you need is support for text labels, please use the `label`
 266      * attribute instead.
 267      *
 268      * @config labelHTML
 269      * @type HTML
 270      */
 271     labelHTML: {
 272         setter: '_setLabelHTML',
 273         getter: '_getLabelHTML',
 274         lazyAdd: false
 275     },
 276
 277     /**
 278      * The button's enabled/disabled state
 279      *
 280      * @config disabled
 281      * @type Boolean
 282      */
 283     disabled: {
 284         value: false,
 285         setter: '_setDisabled',
 286         lazyAdd: false
 287     }
 288 };
 289
 290 /**
 291  * Name of this component.
 292  *
 293  * @property NAME
 294  * @type String
 295  * @static
 296  */
 297 ButtonCore.NAME = "button";
 298
 299 /**
 300  * Array of static constants used to identify the classnames applied to DOM nodes
 301  *
 302  * @property CLASS_NAMES
 303  * @type {Object}
 304  * @public
 305  * @static
 306  */
 307 ButtonCore.CLASS_NAMES = {
 308     BUTTON  : getClassName('button'),
 309     DISABLED: getClassName('button', 'disabled'),
 310     SELECTED: getClassName('button', 'selected'),
 311     LABEL   : getClassName('button', 'label')
 312 };
 313
 314 /**
 315  * Array of static constants used to for applying ARIA states
 316  *
 317  * @property ARIA_STATES
 318  * @type {Object}
 319  * @private
 320  * @static
 321  */
 322 ButtonCore.ARIA_STATES = {
 323     PRESSED : 'aria-pressed',
 324     CHECKED : 'aria-checked'
 325 };
 326
 327 /**
 328  * Array of static constants used to for applying ARIA roles
 329  *
 330  * @property ARIA_ROLES
 331  * @type {Object}
 332  * @private
 333  * @static
 334  */
 335 ButtonCore.ARIA_ROLES = {
 336     BUTTON  : 'button',
 337     CHECKBOX: 'checkbox',
 338     TOGGLE  : 'toggle'
 339 };
 340
 341 /**
 342  * Finds the label node within a button
 343  *
 344  * @method _getLabelNodeFromParent
 345  * @param node {Node} The parent node
 346  * @return {Node} The label node
 347  * @private
 348  * @static
 349  */
 350 ButtonCore._getLabelNodeFromParent = function (node) {
 351     var labelNode = (node.one('.' + ButtonCore.CLASS_NAMES.LABEL) || node);
 352
 353     return labelNode;
 354 };
 355
 356 /**
 357  * Gets a text label from a node
 358  *
 359  * @method _getTextLabelFromNode
 360  * @param node {Node} The parent node
 361  * @return {String} The text label for a given node
 362  * @private
 363  * @static
 364  */
 365 ButtonCore._getTextLabelFromNode = function (node) {
 366     var labelNode = ButtonCore._getLabelNodeFromParent(node),
 367         nodeName = labelNode.get('nodeName').toLowerCase(),
 368         label = labelNode.get(nodeName === 'input' ? 'value' : 'text');
 369
 370     return label;
 371 };
 372
 373 /**
 374  * A utility method that gets an HTML label from a given node
 375  *
 376  * @method _getHTMLFromNode
 377  * @param node {Node} The parent node
 378  * @return {HTML} The HTML label for a given node
 379  * @private
 380  * @static
 381  */
 382 ButtonCore._getHTMLFromNode = function (node) {
 383     var labelNode = ButtonCore._getLabelNodeFromParent(node),
 384         label = labelNode.getHTML();
 385
 386     return label;
 387 };
 388
 389 /**
 390  * Gets the disabled attribute from a node
 391  *
 392  * @method _getDisabledFromNode
 393  * @param node {Node} The parent node
 394  * @return {boolean} The disabled state for a given node
 395  * @private
 396  * @static
 397  */
 398 ButtonCore._getDisabledFromNode = function (node) {
 399     return node.get('disabled');
 400 };
 401
 402 // Export ButtonCore
 403 Y.ButtonCore = ButtonCore;
 404
 405
 406 }, '3.13.0', {"requires": ["attribute-core", "classnamemanager", "node-base", "escape"]});