YUI Library Examples: Overlay: Animation Plugin

+ +

Overlay: Animation Plugin

+ + + +

Creating an Animation Plugin For Overlay

+ +

Setting Up The YUI Instance

+ +

For this example, we'll pull in the overlay module, along with the anim and plugin modules. The anim module provides the animation utility, and plugin will provide +the Plugin base class which we'll extend to create our AnimPlugin. The code to set up our sandbox instance is shown below:

+ + + +

Using the overlay module will also pull down the default CSS required for overlay, on top of which we only need to add our required look/feel CSS for the example.

+ +

AnimPlugin Class Structure

+ +

The AnimPlugin class will extend the Plugin base class. Since Plugin derives from Base, we follow the same pattern we use for widgets and other utilities which extend Base to setup our new class.

+ +

Namely:

+ +

Setting up the constructor to invoke the superclass constructor
Setting up a NAME property, to identify the class
Setting up the default attributes, using the ATTRS property
Providing prototype implementations for anything we want executed during initialization and destruction using the initializer and destructor lifecycle methods

+ +

Additionally, since this is a plugin, we provide a NS property for the class, which defines the property which will refer to the AnimPlugin instance on the host class (e.g. overlay.fx will be an instance of AnimPlugin)

. + +

This basic structure is shown below:

+ +

+    /* Animation Plugin Constructor */
+    function AnimPlugin(config) {
+        AnimPlugin.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
+     */
+    AnimPlugin.NS = "fx";
+
+    /*
+     * The NAME of the AnimPlugin class. Used to prefix events generated
+     * by the plugin class.
+     */
+    AnimPlugin.NAME = "animPlugin";
+
+    /*
+     * The default set of attributes for the AnimPlugin class.
+     */
+    AnimPlugin.ATTRS = {
+
+        /*
+         * Default duration. Used by the default animation implementations
+         */
+        duration : {
+            value: 0.2
+        },
+
+        /*
+         * Default animation instance used for showing the widget (opacity fade-in)
+         */
+        animVisible : {
+            valueFn : function() {
+                ...
+            }
+        },
+
+        /*
+         * Default animation instance used for hiding the widget (opacity fade-out)
+         */
+        animHidden : {
+            valueFn : function() {
+                ...
+            }
+        }
+    }
+
+    /*
+     * Extend the base plugin class
+     */
+    Y.extend(AnimPlugin, Y.Plugin, {
+
+        // Lifecycle methods
+        initializer : function(config) { ... },
+        destructor : function() { ... },
+
+        // Other plugin specific methods
+        _uiAnimSetVisible : function(val) { ... },
+        _uiSetVisible : function(val) { ... },
+        ...
+    });
+

+ +

Attributes: animVisible, animHidden

+ +

The animVisible and animHidden attributes use Attribute's valueFn support to set up instance based default values for the attributes.

+ +

The animHidden attribute is pretty straight forward and simply returns the Animation instance bound to the bounding box of the Overlay to provide a fade-out animation:

+ + + +

The animVisible attribute is a little more interesting:

+ + + +

It essentially does the same thing as animHidden; setting up an Animation instance to provide an opacity based fade-in. However it also sets up a listener which will attempt to cleanup the opacity state of the Overlay when the plugin is unplugged from the Overlay. When a plugin is unplugged, it is destroyed.

+ +

Lifecycle Methods: initializer, destructor

+ +

In the initializer, we set up listeners on the animation instances (using _bindAnimVisible, _bindAnimHidden), which invoke the original visibility handling to make the Overlay visible before starting the animVisible animation and hide it after the animHidden animation is complete.

+ +

+    initializer : function(config) {
+        this._bindAnimVisible();
+        this._bindAnimHidden();
+
+        this.after("animVisibleChange", this._bindAnimVisible);
+        this.after("animHiddenChange", this._bindAnimHidden);
+
+        // Override default _uiSetVisible method, with custom animated method
+        this.doBefore("_uiSetVisible", this._uiAnimSetVisible);
+    }
+
+    ...
+
+    _bindAnimVisible : function() {
+        var animVisible = this.get("animVisible");
+
+        animVisible.on("start", Y.bind(function() {
+            // Setup original visibility handling (for show) before starting to animate
+            this._uiSetVisible(true);
+        }, this));
+    },
+
+    _bindAnimHidden : function() {
+        var animHidden = this.get("animHidden");
+
+        animHidden.after("end", Y.bind(function() {
+            // Setup original visibility handling (for hide) after completing animation
+            this._uiSetVisible(false);
+        }, this));
+    }
+

+ +

+However the key part of the initializer method is the call to this.doBefore("_uiSetVisible", this._uiAnimSetVisible) (line 9). Plugin's doBefore and doAfter methods, will let you set up both before/after event listeners, as well as inject code to be executed before or after a given method on the host object (in this case the Overlay) is invoked. +

+For the animation plugin, we want to change how the Overlay updates its UI in response to changes to the visible attribute. Instead of simply flipping visibility (through the application of the yui-overlay-hidden class), we want to fade the Overlay in and out. Therefore, we inject our custom animation method, _uiSetAnimVisible, before the Overlay's _uiSetVisible. +

+ +

Using Plugin's doBefore/doAfter methods to setup any event listeners and method injection code on the host object (Overlay), ensures that the custom behavior is removed when the plugin is unplugged from the host, restoring it's original behavior.

+ +

The destructor simply calls destroy on the animation instances used, and lets them perform their own cleanup (as defined in the discussion on attributes):

+ + + +

The Animated Visibility Method

+ +

The _uiAnimSetVisible method is the method we use to over-ride the default visibility handling for the Overlay. Instead of simply adding or removing the yui-overlay-hidden class, it starts the appropriate animation depending on whether or not visible is being set to true or false:

+ + + +

Since this method is injected before the default method which handles visibility changes for Overlay (_uiSetVisibility), we invoke Y.Do.Halt() to prevent the original method from being invoked, since we'd like to invoke it in response to the animation starting or completing. +Y.Do is YUI's aop infrastructure and is used under the hood by Plugin's doBefore and doAfter methods when injecting code

. + +

The Original Visibility Method

+ +

The original visiblity handling for Overlay is replicated in the AnimPlugin's _uiSetVisible method and is invoked before starting the animVisible animation and after completing the animHidden animation as described above.

+ + + +

NOTE: We're evaluating whether or not Y.Do may provide access to the original method for a future release, which would make this replicated code unnecessary.

+ +

Using The Plugin

+ +

All objects which derive from Base are Plugin Hosts. They provide plug and unplug methods to allow users to add/remove plugins to/from existing instances. They also allow the user to specify the set of plugins to be applied to a new instance, along with their configurations, as part of the constructor arguments:

+ + + +

We use the constructor support to setup the AnimPlugin for the instance with a custom value for its duration attribute as shown on line 11 above.

+ +

NOTE: In the interests of keeping the example focused on the plugin infrastructure, we turn off shimming for the overlay. If we needed to enable shimming, In IE6, we'd need to remove the alpha opacity filter set on the shim while animating, to have IE animate the contents of the Overlay correctly.

+ +

The example also uses the plug and unplug methods, to add and remove the custom animation behavior after the instance is created:

+ + +

YUI Library Examples: Overlay: Animation Plugin

Overlay: Animation Plugin

Creating an Animation Plugin For Overlay

Setting Up The YUI Instance

AnimPlugin Class Structure

Attributes: animVisible, animHidden

Lifecycle Methods: initializer, destructor

The Animated Visibility Method

The Original Visibility Method

Using The Plugin

+ Overlay Examples:

More Overlay Resources: