[Summary view] [Print] [Text view]

   1  /*
   2  YUI 3.17.2 (build 9c3c78e)
   3  Copyright 2014 Yahoo! Inc. All rights reserved.
   4  Licensed under the BSD License.
   5  http://yuilibrary.com/license/
   6  */
   7  
   8  YUI.add('widget-buttons', function (Y, NAME) {
   9  
  10  /**
  11  Provides header/body/footer button support for Widgets that use the
  12  `WidgetStdMod` extension.
  13  
  14  @module widget-buttons
  15  @since 3.4.0
  16  **/
  17  
  18  var YArray  = Y.Array,
  19      YLang   = Y.Lang,
  20      YObject = Y.Object,
  21  
  22      ButtonPlugin = Y.Plugin.Button,
  23      Widget       = Y.Widget,
  24      WidgetStdMod = Y.WidgetStdMod,
  25  
  26      getClassName = Y.ClassNameManager.getClassName,
  27      isArray      = YLang.isArray,
  28      isNumber     = YLang.isNumber,
  29      isString     = YLang.isString,
  30      isValue      = YLang.isValue;
  31  
  32  // Utility to determine if an object is a Y.Node instance, even if it was
  33  // created in a different YUI sandbox.
  34  function isNode(node) {
  35      return !!node.getDOMNode;
  36  }
  37  
  38  /**
  39  Provides header/body/footer button support for Widgets that use the
  40  `WidgetStdMod` extension.
  41  
  42  This Widget extension makes it easy to declaratively configure a widget's
  43  buttons. It adds a `buttons` attribute along with button- accessor and mutator
  44  methods. All button nodes have the `Y.Plugin.Button` plugin applied.
  45  
  46  This extension also includes `HTML_PARSER` support to seed a widget's `buttons`
  47  from those which already exist in its DOM.
  48  
  49  @class WidgetButtons
  50  @extensionfor Widget
  51  @since 3.4.0
  52  **/
  53  function WidgetButtons() {
  54      // Has to be setup before the `initializer()`.
  55      this._buttonsHandles = {};
  56  }
  57  
  58  WidgetButtons.ATTRS = {
  59      /**
  60      Collection containing a widget's buttons.
  61  
  62      The collection is an Object which contains an Array of `Y.Node`s for every
  63      `WidgetStdMod` section (header, body, footer) which has one or more buttons.
  64      All button nodes have the `Y.Plugin.Button` plugin applied.
  65  
  66      This attribute is very flexible in the values it will accept. `buttons` can
  67      be specified as a single Array, or an Object of Arrays keyed to a particular
  68      section.
  69  
  70      All specified values will be normalized to this type of structure:
  71  
  72          {
  73              header: [...],
  74              footer: [...]
  75          }
  76  
  77      A button can be specified as a `Y.Node`, config Object, or String name for a
  78      predefined button on the `BUTTONS` prototype property. When a config Object
  79      is provided, it will be merged with any defaults provided by a button with
  80      the same `name` defined on the `BUTTONS` property.
  81  
  82      See `addButton()` for the detailed list of configuration properties.
  83  
  84      For convenience, a widget's buttons will always persist and remain rendered
  85      after header/body/footer content updates. Buttons should be removed by
  86      updating this attribute or using the `removeButton()` method.
  87  
  88      @example
  89          {
  90              // Uses predefined "close" button by string name.
  91              header: ['close'],
  92  
  93              footer: [
  94                  {
  95                      name  : 'cancel',
  96                      label : 'Cancel',
  97                      action: 'hide'
  98                  },
  99  
 100                  {
 101                      name     : 'okay',
 102                      label    : 'Okay',
 103                      isDefault: true,
 104  
 105                      events: {
 106                          click: function (e) {
 107                              this.hide();
 108                          }
 109                      }
 110                  }
 111              ]
 112          }
 113  
 114      @attribute buttons
 115      @type Object
 116      @default {}
 117      @since 3.4.0
 118      **/
 119      buttons: {
 120          getter: '_getButtons',
 121          setter: '_setButtons',
 122          value : {}
 123      },
 124  
 125      /**
 126      The current default button as configured through this widget's `buttons`.
 127  
 128      A button can be configured as the default button in the following ways:
 129  
 130        * As a config Object with an `isDefault` property:
 131          `{label: 'Okay', isDefault: true}`.
 132  
 133        * As a Node with a `data-default` attribute:
 134          `<button data-default="true">Okay</button>`.
 135  
 136      This attribute is **read-only**; anytime there are changes to this widget's
 137      `buttons`, the `defaultButton` will be updated if needed.
 138  
 139      **Note:** If two or more buttons are configured to be the default button,
 140      the last one wins.
 141  
 142      @attribute defaultButton
 143      @type Node
 144      @default null
 145      @readOnly
 146      @since 3.5.0
 147      **/
 148      defaultButton: {
 149          readOnly: true,
 150          value   : null
 151      }
 152  };
 153  
 154  /**
 155  CSS classes used by `WidgetButtons`.
 156  
 157  @property CLASS_NAMES
 158  @type Object
 159  @static
 160  @since 3.5.0
 161  **/
 162  WidgetButtons.CLASS_NAMES = {
 163      button : getClassName('button'),
 164      buttons: Widget.getClassName('buttons'),
 165      primary: getClassName('button', 'primary')
 166  };
 167  
 168  WidgetButtons.HTML_PARSER = {
 169      buttons: function (srcNode) {
 170          return this._parseButtons(srcNode);
 171      }
 172  };
 173  
 174  /**
 175  The list of button configuration properties which are specific to
 176  `WidgetButtons` and should not be passed to `Y.Plugin.Button.createNode()`.
 177  
 178  @property NON_BUTTON_NODE_CFG
 179  @type Array
 180  @static
 181  @since 3.5.0
 182  **/
 183  WidgetButtons.NON_BUTTON_NODE_CFG = [
 184      'action', 'classNames', 'context', 'events', 'isDefault', 'section'
 185  ];
 186  
 187  WidgetButtons.prototype = {
 188      // -- Public Properties ----------------------------------------------------
 189  
 190      /**
 191      Collection of predefined buttons mapped by name -> config.
 192  
 193      These button configurations will serve as defaults for any button added to a
 194      widget's buttons which have the same `name`.
 195  
 196      See `addButton()` for a list of possible configuration values.
 197  
 198      @property BUTTONS
 199      @type Object
 200      @default {}
 201      @see addButton()
 202      @since 3.5.0
 203      **/
 204      BUTTONS: {},
 205  
 206      /**
 207      The HTML template to use when creating the node which wraps all buttons of a
 208      section. By default it will have the CSS class: "yui3-widget-buttons".
 209  
 210      @property BUTTONS_TEMPLATE
 211      @type String
 212      @default "<span />"
 213      @since 3.5.0
 214      **/
 215      BUTTONS_TEMPLATE: '<span />',
 216  
 217      /**
 218      The default section to render buttons in when no section is specified.
 219  
 220      @property DEFAULT_BUTTONS_SECTION
 221      @type String
 222      @default Y.WidgetStdMod.FOOTER
 223      @since 3.5.0
 224      **/
 225      DEFAULT_BUTTONS_SECTION: WidgetStdMod.FOOTER,
 226  
 227      // -- Protected Properties -------------------------------------------------
 228  
 229      /**
 230      A map of button node `_yuid` -> event-handle for all button nodes which were
 231      created by this widget.
 232  
 233      @property _buttonsHandles
 234      @type Object
 235      @protected
 236      @since 3.5.0
 237      **/
 238  
 239      /**
 240      A map of this widget's `buttons`, both name -> button and
 241      section:name -> button.
 242  
 243      @property _buttonsMap
 244      @type Object
 245      @protected
 246      @since 3.5.0
 247      **/
 248  
 249      /**
 250      Internal reference to this widget's default button.
 251  
 252      @property _defaultButton
 253      @type Node
 254      @protected
 255      @since 3.5.0
 256      **/
 257  
 258      // -- Lifecycle Methods ----------------------------------------------------
 259  
 260      initializer: function () {
 261          // Require `Y.WidgetStdMod`.
 262          if (!this._stdModNode) {
 263              Y.error('WidgetStdMod must be added to a Widget before WidgetButtons.');
 264          }
 265  
 266          // Creates button mappings and sets the `defaultButton`.
 267          this._mapButtons(this.get('buttons'));
 268          this._updateDefaultButton();
 269  
 270          // Bound with `Y.bind()` to make more extensible.
 271          this.after({
 272              buttonsChange      : Y.bind('_afterButtonsChange', this),
 273              defaultButtonChange: Y.bind('_afterDefaultButtonChange', this)
 274          });
 275  
 276          Y.after(this._bindUIButtons, this, 'bindUI');
 277          Y.after(this._syncUIButtons, this, 'syncUI');
 278      },
 279  
 280      destructor: function () {
 281          // Detach all event subscriptions this widget added to its `buttons`.
 282          YObject.each(this._buttonsHandles, function (handle) {
 283              handle.detach();
 284          });
 285  
 286          delete this._buttonsHandles;
 287          delete this._buttonsMap;
 288          delete this._defaultButton;
 289      },
 290  
 291      // -- Public Methods -------------------------------------------------------
 292  
 293      /**
 294      Adds a button to this widget.
 295  
 296      The new button node will have the `Y.Plugin.Button` plugin applied, be added
 297      to this widget's `buttons`, and rendered in the specified `section` at the
 298      specified `index` (or end of the section when no `index` is provided). If
 299      the section does not exist, it will be created.
 300  
 301      This fires the `buttonsChange` event and adds the following properties to
 302      the event facade:
 303  
 304        * `button`: The button node or config object to add.
 305  
 306        * `section`: The `WidgetStdMod` section (header/body/footer) where the
 307          button will be added.
 308  
 309        * `index`: The index at which the button will be in the section.
 310  
 311        * `src`: "add"
 312  
 313      **Note:** The `index` argument will be passed to the Array `splice()`
 314      method, therefore a negative value will insert the `button` that many items
 315      from the end. The `index` property on the `buttonsChange` event facade is
 316      the index at which the `button` was added.
 317  
 318      @method addButton
 319      @param {Node|Object|String} button The button to add. This can be a `Y.Node`
 320          instance, config Object, or String name for a predefined button on the
 321          `BUTTONS` prototype property. When a config Object is provided, it will
 322          be merged with any defaults provided by any `srcNode` and/or a button
 323          with the same `name` defined on the `BUTTONS` property. The following
 324          are the possible configuration properties beyond what Node plugins
 325          accept by default:
 326        @param {Function|String} [button.action] The default handler that should
 327          be called when the button is clicked. A String name of a Function that
 328          exists on the `context` object can also be provided. **Note:**
 329          Specifying a set of `events` will override this setting.
 330        @param {String|String[]} [button.classNames] Additional CSS classes to add
 331          to the button node.
 332        @param {Object} [button.context=this] Context which any `events` or
 333          `action` should be called with. Defaults to `this`, the widget.
 334          **Note:** `e.target` will access the button node in the event handlers.
 335        @param {Boolean} [button.disabled=false] Whether the button should be
 336          disabled.
 337        @param {String|Object} [button.events="click"] Event name, or set of
 338          events and handlers to bind to the button node. **See:** `Y.Node.on()`,
 339          this value is passed as the first argument to `on()`.
 340        @param {Boolean} [button.isDefault=false] Whether the button is the
 341          default button.
 342        @param {String} [button.label] The visible text/value displayed in the
 343          button.
 344        @param {String} [button.name] A name which can later be used to reference
 345          this button. If a button is defined on the `BUTTONS` property with this
 346          same name, its configuration properties will be merged in as defaults.
 347        @param {String} [button.section] The `WidgetStdMod` section (header, body,
 348          footer) where the button should be added.
 349        @param {Node} [button.srcNode] An existing Node to use for the button,
 350          default values will be seeded from this node, but are overriden by any
 351          values specified in the config object. By default a new &lt;button&gt;
 352          node will be created.
 353        @param {String} [button.template] A specific template to use when creating
 354          a new button node (e.g. "&lt;a /&gt;"). **Note:** Specifying a `srcNode`
 355          will overide this.
 356      @param {String} [section="footer"] The `WidgetStdMod` section
 357          (header/body/footer) where the button should be added. This takes
 358          precedence over the `button.section` configuration property.
 359      @param {Number} [index] The index at which the button should be inserted. If
 360          not specified, the button will be added to the end of the section. This
 361          value is passed to the Array `splice()` method, therefore a negative
 362          value will insert the `button` that many items from the end.
 363      @chainable
 364      @see Plugin.Button.createNode()
 365      @since 3.4.0
 366      **/
 367      addButton: function (button, section, index) {
 368          var buttons = this.get('buttons'),
 369              sectionButtons, atIndex;
 370  
 371          // Makes sure we have the full config object.
 372          if (!isNode(button)) {
 373              button = this._mergeButtonConfig(button);
 374              section || (section = button.section);
 375          }
 376  
 377          section || (section = this.DEFAULT_BUTTONS_SECTION);
 378          sectionButtons = buttons[section] || (buttons[section] = []);
 379          isNumber(index) || (index = sectionButtons.length);
 380  
 381          // Insert new button at the correct position.
 382          sectionButtons.splice(index, 0, button);
 383  
 384          // Determine the index at which the `button` now exists in the array.
 385          atIndex = YArray.indexOf(sectionButtons, button);
 386  
 387          this.set('buttons', buttons, {
 388              button : button,
 389              section: section,
 390              index  : atIndex,
 391              src    : 'add'
 392          });
 393  
 394          return this;
 395      },
 396  
 397      /**
 398      Returns a button node from this widget's `buttons`.
 399  
 400      @method getButton
 401      @param {Number|String} name The string name or index of the button.
 402      @param {String} [section="footer"] The `WidgetStdMod` section
 403          (header/body/footer) where the button exists. Only applicable when
 404          looking for a button by numerical index, or by name but scoped to a
 405          particular section.
 406      @return {Node} The button node.
 407      @since 3.5.0
 408      **/
 409      getButton: function (name, section) {
 410          if (!isValue(name)) { return; }
 411  
 412          var map = this._buttonsMap,
 413              buttons;
 414  
 415          section || (section = this.DEFAULT_BUTTONS_SECTION);
 416  
 417          // Supports `getButton(1, 'header')` signature.
 418          if (isNumber(name)) {
 419              buttons = this.get('buttons');
 420              return buttons[section] && buttons[section][name];
 421          }
 422  
 423          // Looks up button by name or section:name.
 424          return arguments.length > 1 ? map[section + ':' + name] : map[name];
 425      },
 426  
 427      /**
 428      Removes a button from this widget.
 429  
 430      The button will be removed from this widget's `buttons` and its DOM. Any
 431      event subscriptions on the button which were created by this widget will be
 432      detached. If the content section becomes empty after removing the button
 433      node, then the section will also be removed.
 434  
 435      This fires the `buttonsChange` event and adds the following properties to
 436      the event facade:
 437  
 438        * `button`: The button node to remove.
 439  
 440        * `section`: The `WidgetStdMod` section (header/body/footer) where the
 441          button should be removed from.
 442  
 443        * `index`: The index at which the button exists in the section.
 444  
 445        * `src`: "remove"
 446  
 447      @method removeButton
 448      @param {Node|Number|String} button The button to remove. This can be a
 449          `Y.Node` instance, index, or String name of a button.
 450      @param {String} [section="footer"] The `WidgetStdMod` section
 451          (header/body/footer) where the button exists. Only applicable when
 452          removing a button by numerical index, or by name but scoped to a
 453          particular section.
 454      @chainable
 455      @since 3.5.0
 456      **/
 457      removeButton: function (button, section) {
 458          if (!isValue(button)) { return this; }
 459  
 460          var buttons = this.get('buttons'),
 461              index;
 462  
 463          // Shortcut if `button` is already an index which is needed for slicing.
 464          if (isNumber(button)) {
 465              section || (section = this.DEFAULT_BUTTONS_SECTION);
 466              index  = button;
 467              button = buttons[section][index];
 468          } else {
 469              // Supports `button` being the string name.
 470              if (isString(button)) {
 471                  // `getButton()` is called this way because its behavior is
 472                  // different based on the number of arguments.
 473                  button = this.getButton.apply(this, arguments);
 474              }
 475  
 476              // Determines the `section` and `index` at which the button exists.
 477              YObject.some(buttons, function (sectionButtons, currentSection) {
 478                  index = YArray.indexOf(sectionButtons, button);
 479  
 480                  if (index > -1) {
 481                      section = currentSection;
 482                      return true;
 483                  }
 484              });
 485          }
 486  
 487          // Button was found at an appropriate index.
 488          if (button && index > -1) {
 489              // Remove button from `section` array.
 490              buttons[section].splice(index, 1);
 491  
 492              this.set('buttons', buttons, {
 493                  button : button,
 494                  section: section,
 495                  index  : index,
 496                  src    : 'remove'
 497              });
 498          }
 499  
 500          return this;
 501      },
 502  
 503      // -- Protected Methods ----------------------------------------------------
 504  
 505      /**
 506      Binds UI event listeners. This method is inserted via AOP, and will execute
 507      after `bindUI()`.
 508  
 509      @method _bindUIButtons
 510      @protected
 511      @since 3.4.0
 512      **/
 513      _bindUIButtons: function () {
 514          // Event handlers are bound with `bind()` to make them more extensible.
 515          var afterContentChange = Y.bind('_afterContentChangeButtons', this);
 516  
 517          this.after({
 518              visibleChange      : Y.bind('_afterVisibleChangeButtons', this),
 519              headerContentChange: afterContentChange,
 520              bodyContentChange  : afterContentChange,
 521              footerContentChange: afterContentChange
 522          });
 523      },
 524  
 525      /**
 526      Returns a button node based on the specified `button` node or configuration.
 527  
 528      The button node will either be created via `Y.Plugin.Button.createNode()`,
 529      or when `button` is specified as a node already, it will by `plug()`ed with
 530      `Y.Plugin.Button`.
 531  
 532      @method _createButton
 533      @param {Node|Object} button Button node or configuration object.
 534      @return {Node} The button node.
 535      @protected
 536      @since 3.5.0
 537      **/
 538      _createButton: function (button) {
 539          var config, buttonConfig, nonButtonNodeCfg,
 540              i, len, action, context, handle;
 541  
 542          // Makes sure the exiting `Y.Node` instance is from this YUI sandbox and
 543          // is plugged with `Y.Plugin.Button`.
 544          if (isNode(button)) {
 545              return Y.one(button.getDOMNode()).plug(ButtonPlugin);
 546          }
 547  
 548          // Merge `button` config with defaults and back-compat.
 549          config = Y.merge({
 550              context: this,
 551              events : 'click',
 552              label  : button.value
 553          }, button);
 554  
 555          buttonConfig     = Y.merge(config);
 556          nonButtonNodeCfg = WidgetButtons.NON_BUTTON_NODE_CFG;
 557  
 558          // Remove all non-button Node config props.
 559          for (i = 0, len = nonButtonNodeCfg.length; i < len; i += 1) {
 560              delete buttonConfig[nonButtonNodeCfg[i]];
 561          }
 562  
 563          // Create the button node using the button Node-only config.
 564          button = ButtonPlugin.createNode(buttonConfig);
 565  
 566          context = config.context;
 567          action  = config.action;
 568  
 569          // Supports `action` as a String name of a Function on the `context`
 570          // object.
 571          if (isString(action)) {
 572              action = Y.bind(action, context);
 573          }
 574  
 575          // Supports all types of crazy configs for event subscriptions and
 576          // stores a reference to the returned `EventHandle`.
 577          handle = button.on(config.events, action, context);
 578          this._buttonsHandles[Y.stamp(button, true)] = handle;
 579  
 580          // Tags the button with the configured `name` and `isDefault` settings.
 581          button.setData('name', this._getButtonName(config));
 582          button.setData('default', this._getButtonDefault(config));
 583  
 584          // Add any CSS classnames to the button node.
 585          YArray.each(YArray(config.classNames), button.addClass, button);
 586  
 587          return button;
 588      },
 589  
 590      /**
 591      Returns the buttons container for the specified `section`, passing a truthy
 592      value for `create` will create the node if it does not already exist.
 593  
 594      **Note:** It is up to the caller to properly insert the returned container
 595      node into the content section.
 596  
 597      @method _getButtonContainer
 598      @param {String} section The `WidgetStdMod` section (header/body/footer).
 599      @param {Boolean} create Whether the buttons container should be created if
 600          it does not already exist.
 601      @return {Node} The buttons container node for the specified `section`.
 602      @protected
 603      @see BUTTONS_TEMPLATE
 604      @since 3.5.0
 605      **/
 606      _getButtonContainer: function (section, create) {
 607          var sectionClassName = WidgetStdMod.SECTION_CLASS_NAMES[section],
 608              buttonsClassName = WidgetButtons.CLASS_NAMES.buttons,
 609              contentBox       = this.get('contentBox'),
 610              containerSelector, container;
 611  
 612          // Search for an existing buttons container within the section.
 613          containerSelector = '.' + sectionClassName + ' .' + buttonsClassName;
 614          container         = contentBox.one(containerSelector);
 615  
 616          // Create the `container` if it doesn't already exist.
 617          if (!container && create) {
 618              container = Y.Node.create(this.BUTTONS_TEMPLATE);
 619              container.addClass(buttonsClassName);
 620          }
 621  
 622          return container;
 623      },
 624  
 625      /**
 626      Returns whether or not the specified `button` is configured to be the
 627      default button.
 628  
 629      When a button node is specified, the button's `getData()` method will be
 630      used to determine if the button is configured to be the default. When a
 631      button config object is specified, the `isDefault` prop will determine
 632      whether the button is the default.
 633  
 634      **Note:** `<button data-default="true"></button>` is supported via the
 635      `button.getData('default')` API call.
 636  
 637      @method _getButtonDefault
 638      @param {Node|Object} button The button node or configuration object.
 639      @return {Boolean} Whether the button is configured to be the default button.
 640      @protected
 641      @since 3.5.0
 642      **/
 643      _getButtonDefault: function (button) {
 644          var isDefault = isNode(button) ?
 645                  button.getData('default') : button.isDefault;
 646  
 647          if (isString(isDefault)) {
 648              return isDefault.toLowerCase() === 'true';
 649          }
 650  
 651          return !!isDefault;
 652      },
 653  
 654      /**
 655      Returns the name of the specified `button`.
 656  
 657      When a button node is specified, the button's `getData('name')` method is
 658      preferred, but will fallback to `get('name')`, and the result will determine
 659      the button's name. When a button config object is specified, the `name` prop
 660      will determine the button's name.
 661  
 662      **Note:** `<button data-name="foo"></button>` is supported via the
 663      `button.getData('name')` API call.
 664  
 665      @method _getButtonName
 666      @param {Node|Object} button The button node or configuration object.
 667      @return {String} The name of the button.
 668      @protected
 669      @since 3.5.0
 670      **/
 671      _getButtonName: function (button) {
 672          var name;
 673  
 674          if (isNode(button)) {
 675              name = button.getData('name') || button.get('name');
 676          } else {
 677              name = button && (button.name || button.type);
 678          }
 679  
 680          return name;
 681      },
 682  
 683      /**
 684      Getter for the `buttons` attribute. A copy of the `buttons` object is
 685      returned so the stored state cannot be modified by the callers of
 686      `get('buttons')`.
 687  
 688      This will recreate a copy of the `buttons` object, and each section array
 689      (the button nodes are *not* copied/cloned.)
 690  
 691      @method _getButtons
 692      @param {Object} buttons The widget's current `buttons` state.
 693      @return {Object} A copy of the widget's current `buttons` state.
 694      @protected
 695      @since 3.5.0
 696      **/
 697      _getButtons: function (buttons) {
 698          var buttonsCopy = {};
 699  
 700          // Creates a new copy of the `buttons` object.
 701          YObject.each(buttons, function (sectionButtons, section) {
 702              // Creates of copy of the array of button nodes.
 703              buttonsCopy[section] = sectionButtons.concat();
 704          });
 705  
 706          return buttonsCopy;
 707      },
 708  
 709      /**
 710      Adds the specified `button` to the buttons map (both name -> button and
 711      section:name -> button), and sets the button as the default if it is
 712      configured as the default button.
 713  
 714      **Note:** If two or more buttons are configured with the same `name` and/or
 715      configured to be the default button, the last one wins.
 716  
 717      @method _mapButton
 718      @param {Node} button The button node to map.
 719      @param {String} section The `WidgetStdMod` section (header/body/footer).
 720      @protected
 721      @since 3.5.0
 722      **/
 723      _mapButton: function (button, section) {
 724          var map       = this._buttonsMap,
 725              name      = this._getButtonName(button),
 726              isDefault = this._getButtonDefault(button);
 727  
 728          if (name) {
 729              // name -> button
 730              map[name] = button;
 731  
 732              // section:name -> button
 733              map[section + ':' + name] = button;
 734          }
 735  
 736          isDefault && (this._defaultButton = button);
 737      },
 738  
 739      /**
 740      Adds the specified `buttons` to the buttons map (both name -> button and
 741      section:name -> button), and set the a button as the default if one is
 742      configured as the default button.
 743  
 744      **Note:** This will clear all previous button mappings and null-out any
 745      previous default button! If two or more buttons are configured with the same
 746      `name` and/or configured to be the default button, the last one wins.
 747  
 748      @method _mapButtons
 749      @param {Node[]} buttons The button nodes to map.
 750      @protected
 751      @since 3.5.0
 752      **/
 753      _mapButtons: function (buttons) {
 754          this._buttonsMap    = {};
 755          this._defaultButton = null;
 756  
 757          YObject.each(buttons, function (sectionButtons, section) {
 758              var i, len;
 759  
 760              for (i = 0, len = sectionButtons.length; i < len; i += 1) {
 761                  this._mapButton(sectionButtons[i], section);
 762              }
 763          }, this);
 764      },
 765  
 766      /**
 767      Returns a copy of the specified `config` object merged with any defaults
 768      provided by a `srcNode` and/or a predefined configuration for a button
 769      with the same `name` on the `BUTTONS` property.
 770  
 771      @method _mergeButtonConfig
 772      @param {Object|String} config Button configuration object, or string name.
 773      @return {Object} A copy of the button configuration object merged with any
 774          defaults.
 775      @protected
 776      @since 3.5.0
 777      **/
 778      _mergeButtonConfig: function (config) {
 779          var buttonConfig, defConfig, name, button, tagName, label;
 780  
 781          // Makes sure `config` is an Object and a copy of the specified value.
 782          config = isString(config) ? {name: config} : Y.merge(config);
 783  
 784          // Seeds default values from the button node, if there is one.
 785          if (config.srcNode) {
 786              button  = config.srcNode;
 787              tagName = button.get('tagName').toLowerCase();
 788              label   = button.get(tagName === 'input' ? 'value' : 'text');
 789  
 790              // Makes sure the button's current values override any defaults.
 791              buttonConfig = {
 792                  disabled : !!button.get('disabled'),
 793                  isDefault: this._getButtonDefault(button),
 794                  name     : this._getButtonName(button)
 795              };
 796  
 797              // Label should only be considered when not an empty string.
 798              label && (buttonConfig.label = label);
 799  
 800              // Merge `config` with `buttonConfig` values.
 801              Y.mix(config, buttonConfig, false, null, 0, true);
 802          }
 803  
 804          name      = this._getButtonName(config);
 805          defConfig = this.BUTTONS && this.BUTTONS[name];
 806  
 807          // Merge `config` with predefined default values.
 808          if (defConfig) {
 809              Y.mix(config, defConfig, false, null, 0, true);
 810          }
 811  
 812          return config;
 813      },
 814  
 815      /**
 816      `HTML_PARSER` implementation for the `buttons` attribute.
 817  
 818      **Note:** To determine a button node's name its `data-name` and `name`
 819      attributes are examined. Whether the button should be the default is
 820      determined by its `data-default` attribute.
 821  
 822      @method _parseButtons
 823      @param {Node} srcNode This widget's srcNode to search for buttons.
 824      @return {null|Object} `buttons` Config object parsed from this widget's DOM.
 825      @protected
 826      @since 3.5.0
 827      **/
 828      _parseButtons: function (srcNode) {
 829          var buttonSelector = '.' + WidgetButtons.CLASS_NAMES.button,
 830              sections       = ['header', 'body', 'footer'],
 831              buttonsConfig  = null;
 832  
 833          YArray.each(sections, function (section) {
 834              var container = this._getButtonContainer(section),
 835                  buttons   = container && container.all(buttonSelector),
 836                  sectionButtons;
 837  
 838              if (!buttons || buttons.isEmpty()) { return; }
 839  
 840              sectionButtons = [];
 841  
 842              // Creates a button config object for every button node found and
 843              // adds it to the section. This way each button configuration can be
 844              // merged with any defaults provided by predefined `BUTTONS`.
 845              buttons.each(function (button) {
 846                  sectionButtons.push({srcNode: button});
 847              });
 848  
 849              buttonsConfig || (buttonsConfig = {});
 850              buttonsConfig[section] = sectionButtons;
 851          }, this);
 852  
 853          return buttonsConfig;
 854      },
 855  
 856      /**
 857      Setter for the `buttons` attribute. This processes the specified `config`
 858      and returns a new `buttons` object which is stored as the new state; leaving
 859      the original, specified `config` unmodified.
 860  
 861      The button nodes will either be created via `Y.Plugin.Button.createNode()`,
 862      or when a button is already a Node already, it will by `plug()`ed with
 863      `Y.Plugin.Button`.
 864  
 865      @method _setButtons
 866      @param {Array|Object} config The `buttons` configuration to process.
 867      @return {Object} The processed `buttons` object which represents the new
 868          state.
 869      @protected
 870      @since 3.5.0
 871      **/
 872      _setButtons: function (config) {
 873          var defSection = this.DEFAULT_BUTTONS_SECTION,
 874              buttons    = {};
 875  
 876          function processButtons(buttonConfigs, currentSection) {
 877              if (!isArray(buttonConfigs)) { return; }
 878  
 879              var i, len, button, section;
 880  
 881              for (i = 0, len = buttonConfigs.length; i < len; i += 1) {
 882                  button  = buttonConfigs[i];
 883                  section = currentSection;
 884  
 885                  if (!isNode(button)) {
 886                      button = this._mergeButtonConfig(button);
 887                      section || (section = button.section);
 888                  }
 889  
 890                  // Always passes through `_createButton()` to make sure the node
 891                  // is decorated as a button.
 892                  button = this._createButton(button);
 893  
 894                  // Use provided `section` or fallback to the default section.
 895                  section || (section = defSection);
 896  
 897                  // Add button to the array of buttons for the specified section.
 898                  (buttons[section] || (buttons[section] = [])).push(button);
 899              }
 900          }
 901  
 902          // Handle `config` being either an Array or Object of Arrays.
 903          if (isArray(config)) {
 904              processButtons.call(this, config);
 905          } else {
 906              YObject.each(config, processButtons, this);
 907          }
 908  
 909          return buttons;
 910      },
 911  
 912      /**
 913      Syncs this widget's current button-related state to its DOM. This method is
 914      inserted via AOP, and will execute after `syncUI()`.
 915  
 916      @method _syncUIButtons
 917      @protected
 918      @since 3.4.0
 919      **/
 920      _syncUIButtons: function () {
 921          this._uiSetButtons(this.get('buttons'));
 922          this._uiSetDefaultButton(this.get('defaultButton'));
 923          this._uiSetVisibleButtons(this.get('visible'));
 924      },
 925  
 926      /**
 927      Inserts the specified `button` node into this widget's DOM at the specified
 928      `section` and `index` and updates the section content.
 929  
 930      The section and button container nodes will be created if they do not
 931      already exist.
 932  
 933      @method _uiInsertButton
 934      @param {Node} button The button node to insert into this widget's DOM.
 935      @param {String} section The `WidgetStdMod` section (header/body/footer).
 936      @param {Number} index Index at which the `button` should be positioned.
 937      @protected
 938      @since 3.5.0
 939      **/
 940      _uiInsertButton: function (button, section, index) {
 941          var buttonsClassName = WidgetButtons.CLASS_NAMES.button,
 942              buttonContainer  = this._getButtonContainer(section, true),
 943              sectionButtons   = buttonContainer.all('.' + buttonsClassName);
 944  
 945          // Inserts the button node at the correct index.
 946          buttonContainer.insertBefore(button, sectionButtons.item(index));
 947  
 948          // Adds the button container to the section content.
 949          this.setStdModContent(section, buttonContainer, 'after');
 950      },
 951  
 952      /**
 953      Removes the button node from this widget's DOM and detaches any event
 954      subscriptions on the button that were created by this widget. The section
 955      content will be updated unless `{preserveContent: true}` is passed in the
 956      `options`.
 957  
 958      By default the button container node will be removed when this removes the
 959      last button of the specified `section`; and if no other content remains in
 960      the section node, it will also be removed.
 961  
 962      @method _uiRemoveButton
 963      @param {Node} button The button to remove and destroy.
 964      @param {String} section The `WidgetStdMod` section (header/body/footer).
 965      @param {Object} [options] Additional options.
 966        @param {Boolean} [options.preserveContent=false] Whether the section
 967          content should be updated.
 968      @protected
 969      @since 3.5.0
 970      **/
 971      _uiRemoveButton: function (button, section, options) {
 972          var yuid    = Y.stamp(button, this),
 973              handles = this._buttonsHandles,
 974              handle  = handles[yuid],
 975              buttonContainer, buttonClassName;
 976  
 977          if (handle) {
 978              handle.detach();
 979          }
 980  
 981          delete handles[yuid];
 982  
 983          button.remove();
 984  
 985          options || (options = {});
 986  
 987          // Remove the button container and section nodes if needed.
 988          if (!options.preserveContent) {
 989              buttonContainer = this._getButtonContainer(section);
 990              buttonClassName = WidgetButtons.CLASS_NAMES.button;
 991  
 992              // Only matters if we have a button container which is empty.
 993              if (buttonContainer &&
 994                      buttonContainer.all('.' + buttonClassName).isEmpty()) {
 995  
 996                  buttonContainer.remove();
 997                  this._updateContentButtons(section);
 998              }
 999          }
1000      },
1001  
1002      /**
1003      Sets the current `buttons` state to this widget's DOM by rendering the
1004      specified collection of `buttons` and updates the contents of each section
1005      as needed.
1006  
1007      Button nodes which already exist in the DOM will remain intact, or will be
1008      moved if they should be in a new position. Old button nodes which are no
1009      longer represented in the specified `buttons` collection will be removed,
1010      and any event subscriptions on the button which were created by this widget
1011      will be detached.
1012  
1013      If the button nodes in this widget's DOM actually change, then each content
1014      section will be updated (or removed) appropriately.
1015  
1016      @method _uiSetButtons
1017      @param {Object} buttons The current `buttons` state to visually represent.
1018      @protected
1019      @since 3.5.0
1020      **/
1021      _uiSetButtons: function (buttons) {
1022          var buttonClassName = WidgetButtons.CLASS_NAMES.button,
1023              sections        = ['header', 'body', 'footer'];
1024  
1025          YArray.each(sections, function (section) {
1026              var sectionButtons  = buttons[section] || [],
1027                  numButtons      = sectionButtons.length,
1028                  buttonContainer = this._getButtonContainer(section, numButtons),
1029                  buttonsUpdated  = false,
1030                  oldNodes, i, button, buttonIndex;
1031  
1032              // When there's no button container, there are no new buttons or old
1033              // buttons that we have to deal with for this section.
1034              if (!buttonContainer) { return; }
1035  
1036              oldNodes = buttonContainer.all('.' + buttonClassName);
1037  
1038              for (i = 0; i < numButtons; i += 1) {
1039                  button      = sectionButtons[i];
1040                  buttonIndex = oldNodes.indexOf(button);
1041  
1042                  // Buttons already rendered in the Widget should remain there or
1043                  // moved to their new index. New buttons will be added to the
1044                  // current `buttonContainer`.
1045                  if (buttonIndex > -1) {
1046                      // Remove button from existing buttons nodeList since its in
1047                      // the DOM already.
1048                      oldNodes.splice(buttonIndex, 1);
1049  
1050                      // Check that the button is at the right position, if not,
1051                      // move it to its new position.
1052                      if (buttonIndex !== i) {
1053                          // Using `i + 1` because the button should be at index
1054                          // `i`; it's inserted before the node which comes after.
1055                          buttonContainer.insertBefore(button, i + 1);
1056                          buttonsUpdated = true;
1057                      }
1058                  } else {
1059                      buttonContainer.appendChild(button);
1060                      buttonsUpdated = true;
1061                  }
1062              }
1063  
1064              // Safely removes the old button nodes which are no longer part of
1065              // this widget's `buttons`.
1066              oldNodes.each(function (button) {
1067                  this._uiRemoveButton(button, section, {preserveContent: true});
1068                  buttonsUpdated = true;
1069              }, this);
1070  
1071              // Remove leftover empty button containers and updated the StdMod
1072              // content area.
1073              if (numButtons === 0) {
1074                  buttonContainer.remove();
1075                  this._updateContentButtons(section);
1076                  return;
1077              }
1078  
1079              // Adds the button container to the section content.
1080              if (buttonsUpdated) {
1081                  this.setStdModContent(section, buttonContainer, 'after');
1082              }
1083          }, this);
1084      },
1085  
1086      /**
1087      Adds the "yui3-button-primary" CSS class to the new `defaultButton` and
1088      removes it from the old default button.
1089  
1090      @method _uiSetDefaultButton
1091      @param {Node} newButton The new `defaultButton`.
1092      @param {Node} oldButton The old `defaultButton`.
1093      @protected
1094      @since 3.5.0
1095      **/
1096      _uiSetDefaultButton: function (newButton, oldButton) {
1097          var primaryClassName = WidgetButtons.CLASS_NAMES.primary;
1098  
1099          if (newButton) { newButton.addClass(primaryClassName); }
1100          if (oldButton) { oldButton.removeClass(primaryClassName); }
1101      },
1102  
1103      /**
1104      Focuses this widget's `defaultButton` if there is one and this widget is
1105      visible.
1106  
1107      @method _uiSetVisibleButtons
1108      @param {Boolean} visible Whether this widget is visible.
1109      @protected
1110      @since 3.5.0
1111      **/
1112      _uiSetVisibleButtons: function (visible) {
1113          if (!visible) { return; }
1114  
1115          var defaultButton = this.get('defaultButton');
1116          if (defaultButton) {
1117              defaultButton.focus();
1118          }
1119      },
1120  
1121      /**
1122      Removes the specified `button` from the buttons map (both name -> button and
1123      section:name -> button), and nulls-out the `defaultButton` if it is
1124      currently the default button.
1125  
1126      @method _unMapButton
1127      @param {Node} button The button node to remove from the buttons map.
1128      @param {String} section The `WidgetStdMod` section (header/body/footer).
1129      @protected
1130      @since 3.5.0
1131      **/
1132      _unMapButton: function (button, section) {
1133          var map  = this._buttonsMap,
1134              name = this._getButtonName(button),
1135              sectionName;
1136  
1137          // Only delete the map entry if the specified `button` is mapped to it.
1138          if (name) {
1139              // name -> button
1140              if (map[name] === button) {
1141                  delete map[name];
1142              }
1143  
1144              // section:name -> button
1145              sectionName = section + ':' + name;
1146              if (map[sectionName] === button) {
1147                  delete map[sectionName];
1148              }
1149          }
1150  
1151          // Clear the default button if its the specified `button`.
1152          if (this._defaultButton === button) {
1153              this._defaultButton = null;
1154          }
1155      },
1156  
1157      /**
1158      Updates the `defaultButton` attribute if it needs to be updated by comparing
1159      its current value with the protected `_defaultButton` property.
1160  
1161      @method _updateDefaultButton
1162      @protected
1163      @since 3.5.0
1164      **/
1165      _updateDefaultButton: function () {
1166          var defaultButton = this._defaultButton;
1167  
1168          if (this.get('defaultButton') !== defaultButton) {
1169              this._set('defaultButton', defaultButton);
1170          }
1171      },
1172  
1173      /**
1174      Updates the content attribute which corresponds to the specified `section`.
1175  
1176      The method updates the section's content to its current `childNodes`
1177      (text and/or HTMLElement), or will null-out its contents if the section is
1178      empty. It also specifies a `src` of `buttons` on the change event facade.
1179  
1180      @method _updateContentButtons
1181      @param {String} section The `WidgetStdMod` section (header/body/footer) to
1182          update.
1183      @protected
1184      @since 3.5.0
1185      **/
1186      _updateContentButtons: function (section) {
1187          // `childNodes` return text nodes and HTMLElements.
1188          var sectionContent = this.getStdModNode(section).get('childNodes');
1189  
1190          // Updates the section to its current contents, or null if it is empty.
1191          this.set(section + 'Content', sectionContent.isEmpty() ? null :
1192              sectionContent, {src: 'buttons'});
1193      },
1194  
1195      // -- Protected Event Handlers ---------------------------------------------
1196  
1197      /**
1198      Handles this widget's `buttonsChange` event which fires anytime the
1199      `buttons` attribute is modified.
1200  
1201      **Note:** This method special-cases the `buttons` modifications caused by
1202      `addButton()` and `removeButton()`, both of which set the `src` property on
1203      the event facade to "add" and "remove" respectively.
1204  
1205      @method _afterButtonsChange
1206      @param {EventFacade} e
1207      @protected
1208      @since 3.4.0
1209      **/
1210      _afterButtonsChange: function (e) {
1211          var buttons = e.newVal,
1212              section = e.section,
1213              index   = e.index,
1214              src     = e.src,
1215              button;
1216  
1217          // Special cases `addButton()` to only set and insert the new button.
1218          if (src === 'add') {
1219              // Make sure we have the button node.
1220              button = buttons[section][index];
1221  
1222              this._mapButton(button, section);
1223              this._updateDefaultButton();
1224              this._uiInsertButton(button, section, index);
1225  
1226              return;
1227          }
1228  
1229          // Special cases `removeButton()` to only remove the specified button.
1230          if (src === 'remove') {
1231              // Button node already exists on the event facade.
1232              button = e.button;
1233  
1234              this._unMapButton(button, section);
1235              this._updateDefaultButton();
1236              this._uiRemoveButton(button, section);
1237  
1238              return;
1239          }
1240  
1241          this._mapButtons(buttons);
1242          this._updateDefaultButton();
1243          this._uiSetButtons(buttons);
1244      },
1245  
1246      /**
1247      Handles this widget's `headerContentChange`, `bodyContentChange`,
1248      `footerContentChange` events by making sure the `buttons` remain rendered
1249      after changes to the content areas.
1250  
1251      These events are very chatty, so extra caution is taken to avoid doing extra
1252      work or getting into an infinite loop.
1253  
1254      @method _afterContentChangeButtons
1255      @param {EventFacade} e
1256      @protected
1257      @since 3.5.0
1258      **/
1259      _afterContentChangeButtons: function (e) {
1260          var src     = e.src,
1261              pos     = e.stdModPosition,
1262              replace = !pos || pos === WidgetStdMod.REPLACE;
1263  
1264          // Only do work when absolutely necessary.
1265          if (replace && src !== 'buttons' && src !== Widget.UI_SRC) {
1266              this._uiSetButtons(this.get('buttons'));
1267          }
1268      },
1269  
1270      /**
1271      Handles this widget's `defaultButtonChange` event by adding the
1272      "yui3-button-primary" CSS class to the new `defaultButton` and removing it
1273      from the old default button.
1274  
1275      @method _afterDefaultButtonChange
1276      @param {EventFacade} e
1277      @protected
1278      @since 3.5.0
1279      **/
1280      _afterDefaultButtonChange: function (e) {
1281          this._uiSetDefaultButton(e.newVal, e.prevVal);
1282      },
1283  
1284      /**
1285      Handles this widget's `visibleChange` event by focusing the `defaultButton`
1286      if there is one.
1287  
1288      @method _afterVisibleChangeButtons
1289      @param {EventFacade} e
1290      @protected
1291      @since 3.5.0
1292      **/
1293      _afterVisibleChangeButtons: function (e) {
1294          this._uiSetVisibleButtons(e.newVal);
1295      }
1296  };
1297  
1298  Y.WidgetButtons = WidgetButtons;
1299  
1300  
1301  }, '3.17.2', {"requires": ["button-plugin", "cssbutton", "widget-stdmod"]});