Create a gist now

Instantly share code, notes, and snippets.

@gnarf /effects-1-8.md Secret
Created Jun 16, 2012

What would you like to do?
Draft documentation for jQuery 1.8 Effects. Please contribute comments.

jQuery 1.8 Effects - New Features

Animation Factory

The effects core now uses a new factory jQuery.Animation( element, props, opts ) which is responsible for creating an animation object.

It returns a promise, with these additional properties:

  • elem: Object The element being animatied
  • props: Object The final value of each property animating
  • opts: Object The animation options
  • originalProps: Object The original properties before being filtered
  • originalOpts: Object The original options before being filtered
  • startTime: Number The numeric value of new Date() when the animation began
  • duration: Number The duration specified in ms
  • stop( gotoEnd ): Function Stops the animation early, optionally going to the end.
  • createTween( propName, finalValue, easing ): Function Explained in the Tween section.
  • tweens: Array The animations tweens (also explained in the Tween section).

The promise will be resolved when the animation reaches its end, and rejected when terminated early. The context of callbacks attached to the promise will be the element, and the arguments will be the Animation object and a boolean jumpedToEnd which when true means the animation was stopped with gotoEnd, when undefined the animation completed naturally.

Promise state - Quick Overview:

Note: Remember that jQuery.fn.stop( clearQueue, gotoEnd ) takes the clearQueue parameter first, but the Animation.stop( gotoEnd ) doesn't have that option.

  • .stop( gotoEnd = true ) calls:

    • done( anim, jumpedToEnd = true )
    • always( anim, jumpedToEnd = true )
  • .stop( gotoEnd = false ) calls:

    • fail( anim, jumpedToEnd = false )
    • always( anim, jumpedToEnd = false )
  • natural completion calls:

    • done( anim, jumpedToEnd = undefined )
    • always( anim, jumpedToEnd = undefined )

The promise will also be notified via the progress callback in each frame (for each element) after setting values.

New Animation Options / Callbacks:

We added new callbacks progress, always, done, and fail to the jQuery.fn.animate (and friends) options object which will attach callbacks to the promise:

  • progress: function( anim, progress, remainingMs )
  • always: function( anim, jumpedToEnd )
  • done: function( anim, jumpedToEnd )
  • fail: function( anim, jumpedToEnd )

Also, we added start: function( anim ) which will be called after the prefilters have been processed and tweens have been created.

All callbacks will be called with this === element

Prefilters

During the initial setup, jQuery.Animation will call any callbacks that have been registered through jQuery.Animation.prefilter( function( element, props, opts ) ).

The prefilter will have this set to an animation object, and you can modify any of the props or opts however you need. The prefilter may return its own promise which also implements stop(), in which case, processing of prefilters stops. If the prefilter is not trying to override the animation entirely, it should return undefined or some other falsy value.

Tweens

There is a new factory jQuery.Tween( elem, options, prop, end, easing, unit ) which replaces the jQuery.fx objects. The format of the Tween object is very similar to the old fx object in order to maintain backwards compatability with jQuery.fx.step functions.

  • elem: The element being animated
  • prop: The property being animated
  • easing: The easing used
  • options: A reference to the animation options
  • start: The starting value of the tween
  • now: The current value of the tween
  • end: The ending value of the tween
  • unit: The CSS unit for the tween
  • cur(): Reads the current value for property from the element
  • run( progress ): progress is a number from 0 to 1. Updates the value for the property on the animated elemd.

Tweeners

A "Tweener" is a function responsible for creating a tween object, and you might want to override these if you want to implement complex values ( like a clip/transform array matrix ) in a single property.

You can override the default process for creating a tween in order to provide your own tween object by using jQuery.Animation.tweener( props, callback( prop, value ) ). props is a space separated list of properties to be passed to your tweener, or "*" if it should be called for all properties. The callback will be called with this being an Animation object. The tweener function will generally start with var tween = this.createTween( prop, value );, but doesn't nessecarily need to use the jQuery.Tween() factory.

If you want to create your own tween, you can push a new object that has a run( progress ) function that sets the value you want onto the .tweens array on the animation. The tween is considered to have been created, and it will stop calling other tweeners if your tweener returns any truthy value.

Tween Hooks

jQuery.Tween.propHooks[ prop ] is a hook point that replaces jQuery.fx.step[ prop ] (which is being deprecated.) These hooks are used by the tween to get and set values on elements.

jQuery.Tween.propHooks[ property ] = {
    get: function( tween ) {
         // get tween.prop from tween.elem and return it
    },
    set: function( tween ) {
         // set tween.prop on tween.elem to tween.now + tween.unit
    }
}

Plugging in a different timer loop

The default jQuery timers use a single setInterval to call each of the tick functions in the jQuery.timers array.

jQuery.fx.tick(): Calls .run() on each object in the jQuery.timers array, removing it from the array if .run() returns a falsy value. Calls jQuery.fx.stop() whenever there are no timers remaining.

jQuery.fx.stop(): overridable Clears up the setInterval

jQuery.fx.timer( tickFunction ): overridable Creates a setInterval if one doesn't already exist, and pushes tickFunction to the jQuery.timers array. tickFunction should also have anim, elem, and queue properties that reference the animation object, animated element, and queue option to facilitate jQuery.fn.stop()

By overriding fx.timer and fx.stop you should be able to implement any animation tick behaviour you desire. (like using requestAnimationFrame instead of setTimeout.)

There is an example of overriding the timer loop in jquery.requestAnimationFrame

Deprecations

  • jQuery.fx.step functions are being replaced by jQuery.Tween.propHooks and may eventually be removed, but are still supported via the default tween propHook.

Looks really good. Now I just have to figure out how to get this into the new docs site. :)

Owner

gnarf commented Sep 3, 2012

@dmethvin - I oppened an issue about this.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment