kevinmwangi / morpheus

A Brilliant Animator

_  _ ____ ____ ___  _  _ ____ _  _ ____
|\/| |  | |__/ |__] |__| |___ |  | [__
|  | |__| |  \ |    |  | |___ |__| ___]

---

A Brilliant Animator.

Morpheus lets you "tween anything" in parallel on multiple elements; from colors to integers of any unit (px, em, %, etc), with easing transitions and bezier curves, including CSS3 transforms (roate, scale, skew, & translate) -- all in a single high-performant loop utilizing the CPU-friendly requestAnimationFrame standard.

It looks like this:

var anim = morpheus(elements, {
  // CSS
    left: -50
  , top: 100
  , width: '+=50'
  , height: '-=50px'
  , fontSize: '30px'
  , color: '#f00'
  , transform: 'rotate(30deg) scale(+=3)'
  , "background-color": '#f00'

    // API
  , duration: 500
  , easing: easings.easeOut
  , bezier: [[100, 200], [200, 100]]
  , complete: function () {
      console.log('done')
    }
})

// stop an animation
anim.stop()

// jump to the end of an animation and run 'complete' callback
anim.stop(true)

General Tweening

morpheus.tween(1000,
  function (position) {
    // do stuff with position...
    // like for example, use bezier curve points :)
    var xy = morpheus.bezier([[startX, startY], <[n control points]>, [endX, endY]], position)
  },
  function () {
    console.log('done')
  },
  easings.bounce,
  100, // start
  300 // end
)

API

/**
  * morpheus:
  * @param element(s): HTMLElement(s)
  * @param options: mixed bag between CSS Style properties & animation options
  *  - {n} CSS properties|values
  *     - value can be strings, integers,
  *     - or callback function that receives element to be animated. method must return value to be tweened
  *     - relative animations start with += or -= followed by integer
  *  - duration: time in ms - defaults to 1000(ms)
  *  - easing: a transition method - defaults to an 'easeOut' algorithm
  *  - complete: a callback method for when all elements have finished
  *  - bezier: array of arrays containing x|y coordinates that define the bezier points. defaults to none
  *     - this may also be a function that receives element to be animated. it must return a value
  * @return animation instance
  */

See the live examples

Language LTR - RTL support

For those who run web services that support languages spanning from LTR to RTL, you can use the drop-in plugin filed called rtltr.js found in the src directory which will automatically mirror all animations without having to change your implementation. It's pretty rad.

Browser support

Grade A & C Browsers according to Yahoo's Graded Browser Support. CSS3 transforms are only supported in browsers that support the transform specification.

Ender integration

Got Ender? No? Get it.

$ npm install ender -g

Add Morpheus to your existing Ender build

$ ender add morpheus

Write code like a boss:

$('#content .boosh').animate({
  left: 911,
  complete: function () {
    console.log('boosh')
  }
})

Usage Notes

Color

If you're serious about *color animation*, there's a few precautions you'll need to take ahead of time. In order to morph *from* one color to another, you need to make sure the elements you're animating *have an inherited color style* to start with. Furthermore, those styles need to be represented in rgb, or hex, and not a named color (like red, or orange) -- that is unless you want to write code to map the [color conversion](http://www.w3schools.com/css/css_colornames.asp) yourself.

Therefore, at minimum, you need to set a color before animating.

element.style.color = '#ff0';
morpheus(element, {
  color: '#000'
})

With Bonzo installed in Ender.

$('div.things').css('color', '#ff0').animate({
  color: '#000'
})

Units

If you're considering animating by a CSS unit of measurement like em, pt, or %, like-wise to color animation, you must set the size ahead of time before animating:

$('div.intro')
  .css({
      fontSize: '2em'
    , width: '50%'
  })
  .animate({
      fontSize: '+=1.5em'
    , width: '100%'
  })

You also get two other fancy fading hooks

$('p').fadeIn(250, function () {
  console.log('complete')
})

$('p').fadeOut(500, function () {
  console.log('complete')
})

Transforms

Transforms can be animated in browsers that support them (IE9, FF, Chrome, Safari, Opera). morpheus.transform provides a shortcut to the correct style property for the browser (webkitTransform, MozTransform, etc). Like animating on units or color, you must set the property ahead of time before animating:

element.style[morpheus.transform] = 'rotate(30deg) scale(1)'
morpheus(element, {
  transform: 'rotate(0deg) scale(+=3)'
})

AMD Support

require('morpheus.js', function (morpheus) {
  morpheus(elements, config)
})

or as usual with ender

var morpheus = require('morpheus')

Developers

If you're looking to contribute. Add your changes to src/morpheus.js Then run the following

npm install .
make
open tests/tests.html

Morpheus (c) Dustin Diaz 2011 - License MIT

Happy Morphing!