API Docs for: 3.17.2
Show:

File: button/js/core.js

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