# Yahoo! UI Library

### node-flick 3.3.0

Yahoo! UI Library > node-flick > NodeFlick.js (source view)
Search:
Filters Show Private Show Protected Show Deprecated

    /**
     * Provide a simple Flick plugin, which can be used along with the "flick" gesture event, to
     * animate the motion of the host node in response to a (mouse or touch) flick gesture.
     *
     * <p>The current implementation is designed to move the node, relative to the bounds of a parent node and is suitable
     * for scroll/carousel type implementations. Future versions will remove that constraint, to allow open ended movement within
     * the document.</p>
     *
     * @module node-flick
     */

        var HOST = "host",
            PARENT_NODE = "parentNode",
            BOUNDING_BOX = "boundingBox",
            OFFSET_HEIGHT = "offsetHeight",
            OFFSET_WIDTH = "offsetWidth",
            SCROLL_HEIGHT = "scrollHeight",
            SCROLL_WIDTH = "scrollWidth",
            BOUNCE = "bounce",
            MIN_DISTANCE = "minDistance",
            MIN_VELOCITY = "minVelocity",
            BOUNCE_DISTANCE = "bounceDistance",
            DECELERATION = "deceleration",
            STEP = "step",
            DURATION = "duration",
            EASING = "easing",
            FLICK = "flick",

            getClassName = Y.ClassNameManager.getClassName;

        /**
         * A plugin class which can be used to animate the motion of a node, in response to a flick gesture.
         *
         * @class Flick
         * @namespace Plugin
         * @param {Object} config The initial attribute values for the plugin
         */
        function Flick(config) {
            Flick.superclass.constructor.apply(this, arguments);
        }

        Flick.ATTRS = {

            /**
             * Drag coefficent for inertial scrolling. The closer to 1 this
             * value is, the less friction during scrolling.
             *
             * @attribute deceleration
             * @default 0.98
             */
            deceleration : {
                value: 0.98
            },

            /**
             * Drag coefficient for intertial scrolling at the upper
             * and lower boundaries of the scrollview. Set to 0 to
             * disable "rubber-banding".
             *
             * @attribute bounce
             * @type Number
             * @default 0.7
             */
            bounce : {
                value: 0.7
            },

            /**
             * The bounce distance in pixels
             *
             * @attribute bounceDistance
             * @type Number
             * @default 150
             */
            bounceDistance : {
                value: 150
            },

            /**
             * The minimum flick gesture velocity (px/ms) at which to trigger the flick response
             *
             * @attribute minVelocity
             * @type Number
             * @default 0
             */
            minVelocity : {
                value: 0
            },

            /**
             * The minimum flick gesture distance (px) for which to trigger the flick response
             *
             * @attribute minVelocity
             * @type Number
             * @default 10
             */
            minDistance : {
                value: 10
            },

            /**
             * The constraining box relative to which the flick animation and bounds should be calculated.
             *
             * @attribute boundingBox
             * @type Node
             * @default parentNode
             */
            boundingBox : {
                valueFn : function() {
                    return this.get(HOST).get(PARENT_NODE);
                }
            },

            /**
             * The constraining box relative to which the flick animation and bounds should be calculated.
             *
             * @attribute boundingBox
             * @type Node
             * @default parentNode
             */
            step : {
                value:10
            },

            /**
             * The custom duration to apply to the flick animation. By default,
             * the animation duration is controlled by the deceleration factor.
             *
             * @attribute duration
             * @type Number
             * @default null
             */
            duration : {
                value:null
            },

            /**
             * The custom transition easing to use for the flick animation. If not
             * provided defaults to internally to Flick.EASING, or Flick.SNAP_EASING based
             * on whether or not we're animating the flick or bounce step.
             *
             * @attribute easing
             * @type String
             * @default null
             */
            easing : {
                value:null
            }
        };

        /**
         * The NAME of the Flick class. Used to prefix events generated
         * by the plugin.
         *
         * @property Flick.NAME
         * @static
         * @type String
         * @default "pluginFlick"
         */
        Flick.NAME = "pluginFlick";

        /**
         * The namespace for the plugin. This will be the property on the node, which will
         * reference the plugin instance, when it's plugged in.
         *
         * @property Flick.NS
         * @static
         * @type String
         * @default "flick"
         */
        Flick.NS = "flick";

        Y.extend(Flick, Y.Plugin.Base, {

            /**
             * The initializer lifecycle implementation.
             *
             * @method initializer
             * @param {Object} config The user configuration for the plugin
             */
            initializer : function(config) {
                this._node = this.get(HOST);

                this._renderClasses();
                this.setBounds();

                this._node.on(FLICK, Y.bind(this._onFlick, this), {
                    minDistance : this.get(MIN_DISTANCE),
                    minVelocity : this.get(MIN_VELOCITY)
                });
            },

            /**
             * Sets the min/max boundaries for the flick animation,
             * based on the boundingBox dimensions.
             *
             * @method setBounds
             */
            setBounds : function () {
                var box = this.get(BOUNDING_BOX),
                    node = this._node,

                    boxHeight = box.get(OFFSET_HEIGHT),
                    boxWidth = box.get(OFFSET_WIDTH),

                    contentHeight = node.get(SCROLL_HEIGHT),
                    contentWidth = node.get(SCROLL_WIDTH);

                if (contentHeight > boxHeight) {
                    this._maxY = contentHeight - boxHeight;
                    this._minY = 0;
                    this._scrollY = true;
                }

                if (contentWidth > boxWidth) {
                    this._maxX = contentWidth - boxWidth;
                    this._minX = 0;
                    this._scrollX = true;
                }

                this._x = this._y = 0;

                node.set("top", this._y + "px");
                node.set("left", this._x + "px");
            },

            /**
             * Adds the CSS classes, necessary to set up overflow/position properties on the
             * node and boundingBox.
             *
             * @method _renderClasses
             * @protected
             */
            _renderClasses : function() {
                this.get(BOUNDING_BOX).addClass(Flick.CLASS_NAMES.box);
                this._node.addClass(Flick.CLASS_NAMES.content);
            },

            /**
             * The flick event listener. Kicks off the flick animation.
             *
             * @method _onFlick
             * @param e {EventFacade} The flick event facade, containing e.flick.distance, e.flick.velocity etc.
             * @protected
             */
            _onFlick: function(e) {
                this._v = e.flick.velocity;
                this._flick = true;
                this._flickAnim();
            },

            /**
             * Executes a single frame in the flick animation
             *
             * @method _flickFrame
             * @protected
             */
            _flickAnim: function() {

                var y = this._y,
                    x = this._x,

                    maxY = this._maxY,
                    minY = this._minY,
                    maxX = this._maxX,
                    minX = this._minX,
                    velocity = this._v,

                    step = this.get(STEP),
                    deceleration = this.get(DECELERATION),
                    bounce = this.get(BOUNCE);

                this._v = (velocity * deceleration);

                this._snapToEdge = false;

                if (this._scrollX) {
                    x = x - (velocity * step);
                }

                if (this._scrollY) {
                    y = y - (velocity * step);
                }

                if (Math.abs(velocity).toFixed(4) <= Flick.VELOCITY_THRESHOLD) {

                    this._flick = false;

                    this._killTimer(!(this._exceededYBoundary || this._exceededXBoundary));

                    if (this._scrollX) {
                        if (x < minX) {
                            this._snapToEdge = true;
                            this._setX(minX);
                        } else if (x > maxX) {
                            this._snapToEdge = true;
                            this._setX(maxX);
                        }
                    }

                    if (this._scrollY) {
                        if (y < minY) {
                            this._snapToEdge = true;
                            this._setY(minY);
                        } else if (y > maxY) {
                            this._snapToEdge = true;
                            this._setY(maxY);
                        }
                    }

                } else {

                    if (this._scrollX && (x < minX || x > maxX)) {
                        this._exceededXBoundary = true;
                        this._v *= bounce;
                    }

                    if (this._scrollY && (y < minY || y > maxY)) {
                        this._exceededYBoundary = true;
                        this._v *= bounce;
                    }

                    if (this._scrollX) {
                        this._setX(x);
                    }

                    if (this._scrollY) {
                        this._setY(y);
                    }

                    this._flickTimer = Y.later(step, this, this._flickAnim);
                }
            },

            /**
             * Internal utility method to set the X offset position
             *
             * @param {Number} val
             * @private
             */
            _setX : function(val) {
                this._move(val, null, this.get(DURATION), this.get(EASING));
            },

            /**
             * Internal utility method to set the Y offset position
             *
             * @param {Number} val
             * @private
             */
            _setY : function(val) {
                this._move(null, val, this.get(DURATION), this.get(EASING));
            },

            /**
             * Internal utility method to move the node to a given XY position,
             * using transitions, if specified.
             *
             * @param {Number} x The X offset position
             * @param {Number} y The Y offset position
             * @param {Number} duration The duration to use for the transition animation
             * @param {String} easing The easing to use for the transition animation.
             *
             * @private
             */
            _move: function(x, y, duration, easing) {

                if (x !== null) {
                    x = this._bounce(x);
                } else {
                    x = this._x;
                }

                if (y !== null) {
                    y = this._bounce(y);
                } else {
                    y = this._y;
                }

                duration = duration || this._snapToEdge ? Flick.SNAP_DURATION : 0;
                easing = easing || this._snapToEdge ? Flick.SNAP_EASING : Flick.EASING;

                this._x = x;
                this._y = y;

                this._anim(x, y, duration, easing);
            },

            /**
             * Internal utility method to perform the transition step
             *
             * @param {Number} x The X offset position
             * @param {Number} y The Y offset position
             * @param {Number} duration The duration to use for the transition animation
             * @param {String} easing The easing to use for the transition animation.
             *
             * @private
             */
            _anim : function(x, y, duration, easing) {
                var xn = x * -1,
                    yn = y * -1,

                    transition = {
                        duration : duration / 1000,
                        easing : easing
                    };

                Y.log("Transition: duration, easing:" + transition.duration, transition.easing, "node-flick");

                if (Y.Transition.useNative) {
                    transition.transform = 'translate('+ (xn) + 'px,' + (yn) +'px)';
                } else {
                    transition.left = xn + 'px';
                    transition.top = yn + 'px';
                }

                this._node.transition(transition);
            },

            /**
             * Internal utility method to constrain the offset value
             * based on the bounce criteria.
             *
             * @param {Number} x The offset value to constrain.
             * @param {Number} max The max offset value.
             *
             * @private
             */
            _bounce : function(val, max) {
                var bounce = this.get(BOUNCE),
                    dist = this.get(BOUNCE_DISTANCE),
                    min = bounce ? -dist : 0;

                max = bounce ? max + dist : max;

                if(!bounce) {
                    if(val < min) {
                        val = min;
                    } else if(val > max) {
                        val = max;
                    }
                }
                return val;
            },

            /**
             * Stop the animation timer
             *
             * @method _killTimer
             * @private
             */
            _killTimer: function() {
                if(this._flickTimer) {
                    this._flickTimer.cancel();
                }
            }

        }, {

            /**
             * The threshold used to determine when the decelerated velocity of the node
             * is practically 0.
             *
             * @property Flick.VELOCITY_THRESHOLD
             * @static
             * @type Number
             * @default 0.015
             */
            VELOCITY_THRESHOLD : 0.015,

            /**
             * The duration to use for the bounce snap-back transition
             *
             * @property Flick.SNAP_DURATION
             * @static
             * @type Number
             * @default 400
             */
             SNAP_DURATION : 400,

            /**
             * The default easing to use for the main flick movement transition
             *
             * @property Flick.EASING
             * @static
             * @type String
             * @default 'cubic-bezier(0, 0.1, 0, 1.0)'
             */
            EASING : 'cubic-bezier(0, 0.1, 0, 1.0)',

            /**
             * The default easing to use for the bounce snap-back transition
             *
             * @property Flick.SNAP_EASING
             * @static
             * @type String
             * @default 'ease-out'
             */
            SNAP_EASING : 'ease-out',

            /**
             * The default CSS class names used by the plugin
             *
             * @property Flick.CLASS_NAMES
             * @static
             * @type Object
             */
            CLASS_NAMES : {
                box: getClassName(Flick.NS),
                content: getClassName(Flick.NS, "content")
            }
        });

        Y.Plugin.Flick = Flick;

Copyright © 2011 Yahoo! Inc. All rights reserved.