[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-autohide', function (Y, NAME) {
   9  
  10  /**
  11   * A widget-level extension that provides ability to hide widget when
  12   * certain events occur.
  13   *
  14   * @module widget-autohide
  15   * @author eferraiuolo, tilomitra
  16   * @since 3.4.0
  17   */
  18  
  19  
  20  var WIDGET_AUTOHIDE    = 'widgetAutohide',
  21      AUTOHIDE            = 'autohide',
  22      CLICK_OUTSIDE     = 'clickoutside',
  23      FOCUS_OUTSIDE     = 'focusoutside',
  24      DOCUMENT            = 'document',
  25      KEY                 = 'key',
  26      PRESS_ESCAPE         = 'esc',
  27      BIND_UI             = 'bindUI',
  28      SYNC_UI             = "syncUI",
  29      RENDERED            = "rendered",
  30      BOUNDING_BOX        = "boundingBox",
  31      VISIBLE             = "visible",
  32      CHANGE              = 'Change',
  33  
  34      getCN               = Y.ClassNameManager.getClassName;
  35  
  36  /**
  37   * The WidgetAutohide class provides the hideOn attribute which can
  38   * be used to hide the widget when certain events occur.
  39   *
  40   * @class WidgetAutohide
  41   * @param {Object} config User configuration object
  42   */
  43  function WidgetAutohide(config) {
  44      Y.after(this._bindUIAutohide, this, BIND_UI);
  45      Y.after(this._syncUIAutohide, this, SYNC_UI);
  46  
  47  
  48      if (this.get(RENDERED)) {
  49          this._bindUIAutohide();
  50          this._syncUIAutohide();
  51      }
  52  
  53  }
  54  
  55  /**
  56  * Static property used to define the default attribute
  57  * configuration introduced by WidgetAutohide.
  58  *
  59  * @property ATTRS
  60  * @static
  61  * @type Object
  62  */
  63  WidgetAutohide.ATTRS = {
  64  
  65  
  66      /**
  67       * @attribute hideOn
  68       * @type array
  69       *
  70       * @description An array of objects corresponding to the nodes, events, and keycodes to hide the widget on.
  71       * The implementer can supply an array of objects, with each object having the following properties:
  72       * <p>eventName: (string, required): The eventName to listen to.</p>
  73       * <p>node: (Y.Node, optional): The Y.Node that will fire the event (defaults to the boundingBox of the widget)</p>
  74       * <p>keyCode: (string, optional): If listening for key events, specify the keyCode</p>
  75       * <p>By default, this attribute consists of one object which will cause the widget to hide if the
  76       * escape key is pressed.</p>
  77       */
  78      hideOn: {
  79          validator: Y.Lang.isArray,
  80          valueFn  : function() {
  81              return [
  82                  {
  83                      node: Y.one(DOCUMENT),
  84                      eventName: KEY,
  85                      keyCode: PRESS_ESCAPE
  86                  }
  87              ];
  88          }
  89      }
  90  };
  91  
  92  WidgetAutohide.prototype = {
  93      // *** Instance Members *** //
  94  
  95          _uiHandlesAutohide : null,
  96  
  97          // *** Lifecycle Methods *** //
  98  
  99          destructor : function () {
 100  
 101              this._detachUIHandlesAutohide();
 102          },
 103  
 104          /**
 105           * Binds event listeners to the widget.
 106           * <p>
 107           * This method in invoked after bindUI is invoked for the Widget class
 108           * using YUI's aop infrastructure.
 109           * </p>
 110           * @method _bindUIAutohide
 111           * @protected
 112           */
 113          _bindUIAutohide : function () {
 114  
 115              this.after(VISIBLE+CHANGE, this._afterHostVisibleChangeAutohide);
 116              this.after("hideOnChange", this._afterHideOnChange);
 117          },
 118  
 119          /**
 120           * Syncs up the widget based on its current state. In particular, removes event listeners if
 121           * widget is not visible, and attaches them otherwise.
 122           * <p>
 123           * This method in invoked after syncUI is invoked for the Widget class
 124           * using YUI's aop infrastructure.
 125           * </p>
 126           * @method _syncUIAutohide
 127           * @protected
 128           */
 129          _syncUIAutohide : function () {
 130  
 131              this._uiSetHostVisibleAutohide(this.get(VISIBLE));
 132          },
 133  
 134          // *** Private Methods *** //
 135  
 136          /**
 137           * Removes event listeners if widget is not visible, and attaches them otherwise.
 138           *
 139           * @method _uiSetHostVisibleAutohide
 140           * @protected
 141           */
 142          _uiSetHostVisibleAutohide : function (visible) {
 143  
 144              if (visible) {
 145                  //this._attachUIHandlesAutohide();
 146                  Y.later(1, this, '_attachUIHandlesAutohide');
 147              } else {
 148                  this._detachUIHandlesAutohide();
 149              }
 150          },
 151  
 152          /**
 153           * Iterates through all objects in the hideOn attribute and creates event listeners.
 154           *
 155           * @method _attachUIHandlesAutohide
 156           * @protected
 157           */
 158          _attachUIHandlesAutohide : function () {
 159  
 160              if (this._uiHandlesAutohide) { return; }
 161  
 162              var bb = this.get(BOUNDING_BOX),
 163                  hide = Y.bind(this.hide,this),
 164                  uiHandles = [],
 165                  self = this,
 166                  hideOn = this.get('hideOn'),
 167                  i = 0,
 168                  o = {node: undefined, ev: undefined, keyCode: undefined};
 169  
 170                  //push all events on which the widget should be hidden
 171                  for (; i < hideOn.length; i++) {
 172  
 173                      o.node = hideOn[i].node;
 174                      o.ev = hideOn[i].eventName;
 175                      o.keyCode = hideOn[i].keyCode;
 176  
 177                      //no keycode or node defined
 178                      if (!o.node && !o.keyCode && o.ev) {
 179                          uiHandles.push(bb.on(o.ev, hide));
 180                      }
 181  
 182                      //node defined, no keycode (not a keypress)
 183                      else if (o.node && !o.keyCode && o.ev) {
 184                          uiHandles.push(o.node.on(o.ev, hide));
 185                      }
 186  
 187                      //node defined, keycode defined, event defined (its a key press)
 188                      else if (o.node && o.keyCode && o.ev) {
 189                          uiHandles.push(o.node.on(o.ev, hide, o.keyCode));
 190                      }
 191  
 192                      else {
 193                          Y.log('The event with name "'+o.ev+'" could not be attached.');
 194                      }
 195  
 196                  }
 197  
 198              this._uiHandlesAutohide = uiHandles;
 199          },
 200  
 201          /**
 202           * Detaches all event listeners created by this extension
 203           *
 204           * @method _detachUIHandlesAutohide
 205           * @protected
 206           */
 207          _detachUIHandlesAutohide : function () {
 208  
 209              Y.each(this._uiHandlesAutohide, function(h){
 210                  h.detach();
 211              });
 212              this._uiHandlesAutohide = null;
 213          },
 214  
 215          /**
 216           * Default function called when the visibility of the widget changes. Determines
 217           * whether to attach or detach event listeners based on the visibility of the widget.
 218           *
 219           * @method _afterHostVisibleChangeAutohide
 220           * @protected
 221           */
 222          _afterHostVisibleChangeAutohide : function (e) {
 223  
 224              this._uiSetHostVisibleAutohide(e.newVal);
 225          },
 226  
 227          /**
 228           * Default function called when hideOn Attribute is changed. Remove existing listeners and create new listeners.
 229           *
 230           * @method _afterHideOnChange
 231           * @protected
 232           */
 233          _afterHideOnChange : function(e) {
 234              this._detachUIHandlesAutohide();
 235  
 236              if (this.get(VISIBLE)) {
 237                  this._attachUIHandlesAutohide();
 238              }
 239          }
 240  };
 241  
 242  Y.WidgetAutohide = WidgetAutohide;
 243  
 244  
 245  }, '3.17.2', {"requires": ["base-build", "event-key", "event-outside", "widget"]});