File: widget-anim/js/WidgetAnim.js
/**
* Provides a plugin which can be used to animate widget visibility changes.
*
* @module widget-anim
*/
var BOUNDING_BOX = "boundingBox",
HOST = "host",
NODE = "node",
OPACITY = "opacity",
EMPTY_STR = "",
VISIBLE = "visible",
DESTROY = "destroy",
HIDDEN = "hidden",
RENDERED = "rendered",
START = "start",
END = "end",
DURATION = "duration",
ANIM_SHOW = "animShow",
ANIM_HIDE = "animHide",
_UI_SET_VISIBLE = "_uiSetVisible",
ANIM_SHOW_CHANGE = "animShowChange",
ANIM_HIDE_CHANGE = "animHideChange";
/**
* A plugin class which can be used to animate widget visibility changes.
*
* @class WidgetAnim
* @extends Plugin.Base
* @namespace Plugin
*/
function WidgetAnim(config) {
WidgetAnim.superclass.constructor.apply(this, arguments);
}
/**
* The namespace for the plugin. This will be the property on the widget, which will
* reference the plugin instance, when it's plugged in.
*
* @property NS
* @static
* @type String
* @default "anim"
*/
WidgetAnim.NS = "anim";
/**
* The NAME of the WidgetAnim class. Used to prefix events generated
* by the plugin class.
*
* @property NAME
* @static
* @type String
* @default "pluginWidgetAnim"
*/
WidgetAnim.NAME = "pluginWidgetAnim";
/**
* Pre-Packaged Animation implementations, which can be used for animShow and animHide attribute
* values.
*
* @property ANIMATIONS
* @static
* @type Object
* @default "pluginWidgetAnim"
*/
WidgetAnim.ANIMATIONS = {
fadeIn : function() {
var widget = this.get(HOST),
boundingBox = widget.get(BOUNDING_BOX),
anim = new Y.Anim({
node: boundingBox,
to: { opacity: 1 },
duration: this.get(DURATION)
});
// Set initial opacity, to avoid initial flicker
if (!widget.get(VISIBLE)) {
boundingBox.setStyle(OPACITY, 0);
}
// Clean up, on destroy. Where supported, remove
// opacity set using style. Else make 100% opaque
anim.on(DESTROY, function() {
this.get(NODE).setStyle(OPACITY, (Y.UA.ie) ? 1 : EMPTY_STR);
});
return anim;
},
fadeOut : function() {
return new Y.Anim({
node: this.get(HOST).get(BOUNDING_BOX),
to: { opacity: 0 },
duration: this.get(DURATION)
});
}
};
/**
* Static property used to define the default attribute
* configuration for the plugin.
*
* @property ATTRS
* @type Object
* @static
*/
WidgetAnim.ATTRS = {
/**
* Default duration in seconds. Used as the default duration for the default animation implementations
*
* @attribute duration
* @type Number
* @default 0.2 (seconds
*/
duration : {
value: 0.2
},
/**
* Default animation instance used for showing the widget (opacity fade-in)
*
* @attribute animShow
* @type Anim
* @default WidgetAnim.ANIMATIONS.fadeIn
*/
animShow : {
valueFn: WidgetAnim.ANIMATIONS.fadeIn
},
/**
* Default animation instance used for hiding the widget (opacity fade-out)
*
* @attribute animHide
* @type Anim
* @default WidgetAnim.ANIMATIONS.fadeOut
*/
animHide : {
valueFn: WidgetAnim.ANIMATIONS.fadeOut
}
};
Y.extend(WidgetAnim, Y.Plugin.Base, {
/**
* The initializer lifecycle implementation. Modifies the host widget's
* visibililty implementation to add animation.
*
* @method initializer
* @param {Object} config The user configuration for the plugin
*/
initializer : function(config) {
this._bindAnimShow();
this._bindAnimHide();
this.after(ANIM_SHOW_CHANGE, this._bindAnimShow);
this.after(ANIM_HIDE_CHANGE, this._bindAnimHide);
// Override default _uiSetVisible method, with custom animated method
this.beforeHostMethod(_UI_SET_VISIBLE, this._uiAnimSetVisible);
},
/**
* The initializer destructor implementation. Responsible for destroying the configured
* animation instances.
*
* @method destructor
*/
destructor : function() {
this.get(ANIM_SHOW).destroy();
this.get(ANIM_HIDE).destroy();
},
/**
* The injected method used to override the host widget's _uiSetVisible implementation with
* an animated version of the same.
*
* <p>This method replaces the default _uiSetVisible handler
* Widget provides, by injecting itself before _uiSetVisible,
* and preventing the default behavior. </p>
*
* @method _uiAnimSetVisible
* @protected
* @param {boolean} val true, if making the widget visible. false, if hiding it.
*/
_uiAnimSetVisible : function(val) {
if (this.get(HOST).get(RENDERED)) {
if (val) {
this.get(ANIM_HIDE).stop();
this.get(ANIM_SHOW).run();
} else {
this.get(ANIM_SHOW).stop();
this.get(ANIM_HIDE).run();
}
return new Y.Do.Prevent();
}
},
/**
* The original Widget _uiSetVisible implementation. This currently needs to be replicated,
* so it can be invoked before or after the animation starts or stops, since the original
* methods is not available to the AOP implementation.
*
* @method _uiSetVisible
* @param {boolean} val true, if making the widget visible. false, if hiding it.
* @private
*/
_uiSetVisible : function(val) {
var host = this.get(HOST),
hiddenClass = host.getClassName(HIDDEN);
host.get(BOUNDING_BOX).toggleClass(hiddenClass, !val);
},
/**
* Binds a listener to invoke the original visibility handling when the animShow animation is started
*
* @method _bindAnimShow
* @private
*/
_bindAnimShow : function() {
// Setup original visibility handling (for show) before starting to animate
this.get(ANIM_SHOW).on(START,
Y.bind(function() {
this._uiSetVisible(true);
}, this));
},
/**
* Binds a listener to invoke the original visibility handling when the animHide animation is complete
*
* @method _bindAnimHide
* @private
*/
_bindAnimHide : function() {
// Setup original visibility handling (for hide) after completing animation
this.get(ANIM_HIDE).after(END,
Y.bind(function() {
this._uiSetVisible(false);
}, this));
}
});
Y.namespace("Plugin").WidgetAnim = WidgetAnim;