Add intro/outro, initial, final, and better during animations

Author: ClickerMonkey

README.md

@@ -8,16 +8,14 @@
 - Node: `npm install anim8js-scrollmagic`
 - Download: [anim8js-scrollmagic](https://raw.githubusercontent.com/anim8js/anim8js-scrollmagic/master/build/anim8js-scrollmagic.js)
 
+### Index
+- [Examples](#examples)
+- [Documentation](#documentation)
+
 ### Examples
 ```javascript
 new ScrollMagic.Scene({triggerElement: '#trigger', duration: '100%'})
   .addTo( controller )
-  // Generic Transitioning (any state to AFTER scene)
-  .transition('*', 'AFTER', function() {
-    this.animator('#element', function() {
-      this.queue('wiggle inf');
-    });
-  })
   // Triggered when transitioning from outside to inside scene
   .enter(function() {
     this.animator('#element', function() {
@@ -51,6 +49,12 @@ new ScrollMagic.Scene({triggerElement: '#trigger', duration: '100%'})
       this.play('wiggle');
     });
   })
+  // Generic Transitioning (any state to AFTER scene)
+  .transition('*', 'AFTER', function() {
+    this.animator('#element', function() {
+      this.queue('wiggle inf');
+    });
+  })
   // Multiple
   listen('enter before *>AFTER', function() {
     // Execute on enter, when we go before the scene, and when we go after the scene
@@ -61,3 +65,45 @@ new ScrollMagic.Scene({triggerElement: '#trigger', duration: '100%'})
   .setBackwards( true )
 ;
 ```
+
+### Documentation
+
+This plugin works by detecting events relative to the current scene, and invoking
+a function which builds commands to play when the event is triggered.
+
+**Events (occurs when you...)**
+- `after`: go from inside the scene to AFTER, or if you land on the page AFTER the scene.
+- `fromAfter`: go from AFTER the scene to anywhere else
+- `before`: go from inside the scene to BEFORE or if you land on the page BEFORE the scene.
+- `fromBefore`: go from BEFORE the scene to anywhere else
+- `enter`: go from outside the scene to inside or if you land on the page in the scene
+- `exit`: go from inside the scene to outside
+- `any`: go from any state to another
+- `start`: land on the page
+- `startBefore`: land on the page before the scene
+- `startAfter`: land on the page after the scene
+- `startDuring`: land on the page inside the scene
+- `intro`: same as enter except it applies the initial state of the animations if the user lands on the page BEFORE the scene
+- `outro`: same as exit except it applies the final state of the animations if the user lands on the page AFTER the scene
+- `during`: are scrolling through the scene. animations are interpolated from start to finish over the duration of the scene
+
+You can listen for events by using the event name as a function and passing a function, or by using the following functions:
+
+- `listen`: animate on multiple events specified in a space-delimited string or array of strings
+- `transition`: animate when from one state to another - the events above use this function
+
+**Build Commands**
+- `animator( subject or query, function which makes animator calls )`
+- `animators( subjects or query, function which makes animators calls )`
+- `movie( movie, function which makes movie player calls )`
+- `player( player, function which makes movie player calls )`
+
+**Quick Animate**
+This allows you to add animations in a shorthand manner:
+- `animate( event, build, subject, subject method, subject arguments... )`
+
+**Backwards**
+ScrollMagic works by having the user scroll down or to the right of a page. If
+you set a scene to backwards with `setBackwards( true )` then the BEFORE/AFTER and
+progress through a scene is swapped for anim8js functions. This allows you to have
+scroll up and scroll left pages (make sure to set the scrollbar the whole way to the bottom/right when you initialize your scenes)

bower.json

@@ -1,6 +1,6 @@
 {
   "name": "anim8js-scrollmagic",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "homepage": "http://anim8js.github.io/anim8js-scrollmagic",
   "authors": [
     "Philip Diffenderfer <pdiffenderfer@gmail.com>"

build/anim8js-scrollmagic.js

@@ -1,4 +1,4 @@
-/* anim8js-scrollmagic 1.0.2 - anim8 ScrollMagic by Philip Diffenderfer */
+/* anim8js-scrollmagic 1.0.3 - anim8 ScrollMagic by Philip Diffenderfer */
 // UMD (Universal Module Definition)
 (function (root, factory)
 {
@@ -116,7 +116,7 @@ Scene.getInvokeCallback = function(callback)
 // .transition('*', 'AFTER')     "enter"
 // .transition(null, 'DURING')    "start on during"
 // .transition('AFTER', 'DURING') "enter from after"
-Scene.transition = function(expectedPrevious, expectedCurrent, getCalls)
+Scene.transition = function(expectedPrevious, expectedCurrent, getCalls, onStateChange)
 {
   var builder = new CallEventBuilder(getCalls);
   var previous = Events.INITIAL;
@@ -126,6 +126,11 @@ Scene.transition = function(expectedPrevious, expectedCurrent, getCalls)
   {
     if (previous !== current)
     {
+      if (onStateChange)
+      {
+        onStateChange.call( this, current, previous, progress, builder );
+      }
+
       if (this.isEventMatch( previous, expectedPrevious ) &&
           this.isEventMatch( current, expectedCurrent ))
       {
@@ -192,6 +197,33 @@ Scene.startDuring = function(getCalls)
   return this.transition( Events.INITIAL, Events.DURING, getCalls );
 };
 
+// Special Enter / Exit Events
+Scene.intro = function(getCalls)
+{
+  var onStateChange = function(current, previous, progress, builder)
+  {
+    if ((previous === Events.INITIAL && current === this.getBefore()) || current === Events.DURING)
+    {
+      builder.executeInitials( current, progress );
+    }
+  };
+
+  return this.transition( Events.ANY, Events.DURING, getCalls, onStateChange );
+};
+
+Scene.outro = function(getCalls)
+{
+  var onStateChange = function(current, previous, progress, builder)
+  {
+    if (previous === Events.INITIAL && current === this.getAfter())
+    {
+      builder.executeFinals( current, progress );
+    }
+  };
+
+  return this.transition( Events.DURING, Events.ANY, getCalls, onStateChange );
+};
+
 // Special During Event
 Scene.during = function(getCalls)
 {
@@ -311,16 +343,28 @@ Class.define( CallBuilder,
   init: function(getCalls)
   {
     this.calls = [];
+    this.initials = [];
+    this.finals = [];
 
     getCalls.call( this, this );
   },
   execute: function()
   {
-    var calls = this.calls;
-
-    for (var i = 0; i < calls.length; i++)
+    this.executeList( this.calls, arguments );
+  },
+  executeInitials: function()
+  {
+    this.executeList( this.initials, arguments );
+  },
+  executeFinals: function()
+  {
+    this.executeList( this.finals, arguments );
+  },
+  executeList: function(list, args)
+  {
+    for (var i = 0; i < list.length; i++)
     {
-      calls[ i ].apply( this, arguments );
+      list[ i ].apply( this, args );
     }
   },
   call: function(callback)
@@ -329,14 +373,42 @@ Class.define( CallBuilder,
 
     return this;
   },
-  callWith: function(context, getCalls)
+  initial: function(callback)
+  {
+    this.initials.push( callback );
+
+    return this;
+  },
+  final: function(callback)
+  {
+    this.finals.push( callback );
+
+    return this;
+  },
+  callWith: function(context, getCalls, getInitial, getFinal)
   {
     if (context)
     {
       this.call(function()
       {
         getCalls.apply( context, arguments );
       });
+
+      if (getInitial)
+      {
+        this.initial(function()
+        {
+          getInitial.apply( context, arguments );
+        });
+      }
+
+      if (getFinal)
+      {
+        this.final(function()
+        {
+          getFinal.apply( context, arguments );
+        });
+      }
     }
 
     return this;
@@ -353,15 +425,15 @@ Class.extend( CallEventBuilder, CallBuilder,
 {
   animator: function(query, getCalls)
   {
-    return this.callWith( ScrollMagic.getAnimator( query ), getCalls );
+    return this.callWith( ScrollMagic.getAnimator( query ), getCalls, createAnimatorInitial( getCalls ), createAnimatorFinal( getCalls ) );
   },
   animators: function(query, getCalls)
   {
-    return this.callWith( ScrollMagic.getAnimators( query ), getCalls );
+    return this.callWith( ScrollMagic.getAnimators( query ), getCalls, createAnimatorInitial( getCalls ), createAnimatorFinal( getCalls ) );
   },
   player: function(player, getCalls)
   {
-    return this.callWith( player, getCalls );
+    return this.callWith( player, getCalls, createMovieInitial( getCalls ), createMovieFinal() );
   },
   movie: function(movie, getCalls)
   {
@@ -370,6 +442,45 @@ Class.extend( CallEventBuilder, CallBuilder,
 });
 
 
+function createAnimatorInitial(getCalls)
+{
+  return function()
+  {
+    this.stop().restore();
+    getCalls.apply( this, arguments );
+    this.preupdate( 0 ).update( 0 ).apply().stop();
+  };
+}
+
+function createAnimatorFinal(getCalls)
+{
+  return function()
+  {
+    this.stop().restore();
+    getCalls.apply( this, arguments );
+    this.preupdate( 0 ).update( 0 ).end().apply();
+  };
+}
+
+function createMovieInitial(getCalls)
+{
+  return function()
+  {
+    getCalls.apply( this, arguments );
+
+    this.pause().apply( this.time, true );
+  };
+}
+
+function createMovieFinal()
+{
+  return function()
+  {
+    this.end( true, true );
+  };
+}
+
+
 function CallDuringBuilder(getCalls)
 {
   this.init( getCalls );
@@ -409,6 +520,15 @@ Class.extend( CallDuringBuilder, CallBuilder,
         var attrimator = attrimators[ i ];
         var prop = properties[ i ];
         var value = attrimator.valueAtSearch( now, animator.frame[ prop ] );
+        if (value === false) {
+          var last = attrimator;
+          var lastTime = now;
+          while (last.next) {
+            lastTime -= last.totalTime();
+            last = last.next;
+          }
+          value = last.valueAt( lastTime, animator.frame[ prop ] );
+        }
         if (value !== false) {
           animator.updated[ prop ] = true;
           animator.frame[ prop ] = value;

build/anim8js-scrollmagic.min.js

@@ -1,6 +1,6 @@
 {
   "name": "anim8js-scrollmagic",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "anim8 ScrollMagic",
   "author": "Philip Diffenderfer",
   "license": "MIT",