API Docs for: 3.8.0
Show:

File: widget-anim/js/WidgetAnim.js

  1. /**
  2.  * Provides a plugin which can be used to animate widget visibility changes.
  3.  *
  4.  * @module widget-anim
  5.  */
  6. var BOUNDING_BOX = "boundingBox",
  7.     HOST = "host",
  8.     NODE = "node",
  9.     OPACITY = "opacity",
  10.     EMPTY_STR = "",
  11.     VISIBLE = "visible",
  12.     DESTROY = "destroy",
  13.     HIDDEN = "hidden",

  14.     RENDERED = "rendered",
  15.    
  16.     START = "start",
  17.     END = "end",

  18.     DURATION = "duration",
  19.     ANIM_SHOW = "animShow",
  20.     ANIM_HIDE = "animHide",

  21.     _UI_SET_VISIBLE = "_uiSetVisible",
  22.    
  23.     ANIM_SHOW_CHANGE = "animShowChange",
  24.     ANIM_HIDE_CHANGE = "animHideChange";

  25. /**
  26.  * A plugin class which can be used to animate widget visibility changes.
  27.  *
  28.  * @class WidgetAnim
  29.  * @extends Plugin.Base
  30.  * @namespace Plugin
  31.  */
  32. function WidgetAnim(config) {
  33.     WidgetAnim.superclass.constructor.apply(this, arguments);
  34. }

  35. /**
  36.  * The namespace for the plugin. This will be the property on the widget, which will
  37.  * reference the plugin instance, when it's plugged in.
  38.  *
  39.  * @property NS
  40.  * @static
  41.  * @type String
  42.  * @default "anim"
  43.  */
  44. WidgetAnim.NS = "anim";

  45. /**
  46.  * The NAME of the WidgetAnim class. Used to prefix events generated
  47.  * by the plugin class.
  48.  *
  49.  * @property NAME
  50.  * @static
  51.  * @type String
  52.  * @default "pluginWidgetAnim"
  53.  */
  54. WidgetAnim.NAME = "pluginWidgetAnim";

  55. /**
  56.  * Pre-Packaged Animation implementations, which can be used for animShow and animHide attribute
  57.  * values.
  58.  *
  59.  * @property ANIMATIONS
  60.  * @static
  61.  * @type Object
  62.  * @default "pluginWidgetAnim"
  63.  */
  64. WidgetAnim.ANIMATIONS = {

  65.     fadeIn : function() {

  66.         var widget = this.get(HOST),
  67.             boundingBox = widget.get(BOUNDING_BOX),
  68.            
  69.             anim = new Y.Anim({
  70.                 node: boundingBox,
  71.                 to: { opacity: 1 },
  72.                 duration: this.get(DURATION)
  73.             });

  74.         // Set initial opacity, to avoid initial flicker
  75.         if (!widget.get(VISIBLE)) {
  76.             boundingBox.setStyle(OPACITY, 0);
  77.         }

  78.         // Clean up, on destroy. Where supported, remove
  79.         // opacity set using style. Else make 100% opaque
  80.         anim.on(DESTROY, function() {
  81.             this.get(NODE).setStyle(OPACITY, (Y.UA.ie) ? 1 : EMPTY_STR);
  82.         });

  83.         return anim;
  84.     },

  85.     fadeOut : function() {
  86.         return new Y.Anim({
  87.             node: this.get(HOST).get(BOUNDING_BOX),
  88.             to: { opacity: 0 },
  89.             duration: this.get(DURATION)
  90.         });
  91.     }
  92. };

  93. /**
  94.  * Static property used to define the default attribute
  95.  * configuration for the plugin.
  96.  *
  97.  * @property ATTRS
  98.  * @type Object
  99.  * @static
  100.  */
  101. WidgetAnim.ATTRS = {

  102.     /**
  103.      * Default duration in seconds. Used as the default duration for the default animation implementations
  104.      *
  105.      * @attribute duration
  106.      * @type Number
  107.      * @default 0.2 (seconds
  108.      */
  109.     duration : {
  110.         value: 0.2
  111.     },

  112.     /**
  113.      * Default animation instance used for showing the widget (opacity fade-in)
  114.      *
  115.      * @attribute animShow
  116.      * @type Anim
  117.      * @default WidgetAnim.ANIMATIONS.fadeIn
  118.      */
  119.     animShow : {
  120.         valueFn: WidgetAnim.ANIMATIONS.fadeIn
  121.     },

  122.     /**
  123.      * Default animation instance used for hiding the widget (opacity fade-out)
  124.      *
  125.      * @attribute animHide
  126.      * @type Anim
  127.      * @default WidgetAnim.ANIMATIONS.fadeOut
  128.      */
  129.     animHide : {
  130.         valueFn: WidgetAnim.ANIMATIONS.fadeOut
  131.     }
  132. };

  133. Y.extend(WidgetAnim, Y.Plugin.Base, {

  134.     /**
  135.      * The initializer lifecycle implementation. Modifies the host widget's
  136.      * visibililty implementation to add animation.
  137.      *
  138.      * @method initializer
  139.      * @param {Object} config The user configuration for the plugin  
  140.      */
  141.     initializer : function(config) {
  142.         this._bindAnimShow();
  143.         this._bindAnimHide();

  144.         this.after(ANIM_SHOW_CHANGE, this._bindAnimShow);
  145.         this.after(ANIM_HIDE_CHANGE, this._bindAnimHide);

  146.         // Override default _uiSetVisible method, with custom animated method
  147.         this.beforeHostMethod(_UI_SET_VISIBLE, this._uiAnimSetVisible);
  148.     },

  149.     /**
  150.      * The initializer destructor implementation. Responsible for destroying the configured
  151.      * animation instances.
  152.      *
  153.      * @method destructor
  154.      */
  155.     destructor : function() {
  156.         this.get(ANIM_SHOW).destroy();
  157.         this.get(ANIM_HIDE).destroy();
  158.     },

  159.     /**
  160.      * The injected method used to override the host widget's _uiSetVisible implementation with
  161.      * an animated version of the same.
  162.      *
  163.      * <p>This method replaces the default _uiSetVisible handler
  164.      * Widget provides, by injecting itself before _uiSetVisible,
  165.      * and preventing the default behavior. </p>
  166.      *
  167.      * @method _uiAnimSetVisible
  168.      * @protected
  169.      * @param {boolean} val true, if making the widget visible. false, if hiding it.
  170.      */
  171.     _uiAnimSetVisible : function(val) {
  172.         if (this.get(HOST).get(RENDERED)) {
  173.             if (val) {
  174.                 this.get(ANIM_HIDE).stop();
  175.                 this.get(ANIM_SHOW).run();
  176.             } else {
  177.                 this.get(ANIM_SHOW).stop();
  178.                 this.get(ANIM_HIDE).run();
  179.             }
  180.             return new Y.Do.Prevent();
  181.         }
  182.     },

  183.     /**
  184.      * The original Widget _uiSetVisible implementation. This currently needs to be replicated,
  185.      * so it can be invoked before or after the animation starts or stops, since the original
  186.      * methods is not available to the AOP implementation.
  187.      *
  188.      * @method _uiSetVisible
  189.      * @param {boolean} val true, if making the widget visible. false, if hiding it.
  190.      * @private
  191.      */
  192.     _uiSetVisible : function(val) {
  193.         var host = this.get(HOST),
  194.             hiddenClass = host.getClassName(HIDDEN);

  195.         host.get(BOUNDING_BOX).toggleClass(hiddenClass, !val);
  196.     },

  197.     /**
  198.      * Binds a listener to invoke the original visibility handling when the animShow animation is started
  199.      *
  200.      * @method _bindAnimShow
  201.      * @private
  202.      */
  203.     _bindAnimShow : function() {
  204.         // Setup original visibility handling (for show) before starting to animate
  205.         this.get(ANIM_SHOW).on(START,
  206.             Y.bind(function() {
  207.                 this._uiSetVisible(true);
  208.             }, this));
  209.     },

  210.     /**
  211.      * Binds a listener to invoke the original visibility handling when the animHide animation is complete
  212.      *
  213.      * @method _bindAnimHide
  214.      * @private
  215.      */
  216.     _bindAnimHide : function() {
  217.         // Setup original visibility handling (for hide) after completing animation
  218.         this.get(ANIM_HIDE).after(END,
  219.             Y.bind(function() {
  220.                 this._uiSetVisible(false);
  221.             }, this));
  222.     }
  223. });

  224. Y.namespace("Plugin").WidgetAnim = WidgetAnim;

  225.