TimelineLite Control

Topics covered in this GreenSock tutorial:

Adding play & pause buttons, Adding reverse, resume, & restart buttons, Making an intelligent play button, Adding timescale buttons, Configuring a jQuery UI slider

Exercise Preview

Photo courtesy of istockphoto: Image #11068094

Exercise Overview

TimelineLite is a very powerful tool: it can store thousands of animations and yet the entire group can be controlled as easily as a single tween. As you saw in the previous exercise, multiple tweens can be added at once with precise control over their start times. You can sequence tweens, leave gaps in­ between, or overlap as much as you want. You can even nest timelines inside of timelines!

In this exercise, you will dig deeper into controlling a TimelineLite’s playback, speed, and direction. You’ll code a controller that will allow us to pause, play, and reverse the INTO THE WIND animation. We will also create a scrubbing bar to move smoothly through the animation. In the final live site, it wouldn’t make sense for this panel to be visible on this page, but this type of controller can be a great help during the developing and debugging process.

Previewing the Finished Animation

1. To take a look at the animation we’ll be building, open up Google Chrome.

2. Hit Cmd–O (Mac) or Ctrl–O (Windows), navigate to Desktop > Class Files > yourname-GSAP Class > TimelineLite Control, and double–click on finished.html.

   This is the same animation from the previous exercise, except now there is a control panel with various buttons and a slider.

3. Try playing around with the various buttons (their names are pretty self-explanatory) and use the slider to move through the animation, noticing that the animation pauses when you stop moving the slider bar.

   The slider is a jQuery UI component that makes it easy to scrub through the animation sequence and analyze every aspect in detail.

Examining the DOM Structure & JavaScript

1. In a code editor, open start.html from the TimelineLite Control folder.

2. Let’s look at the HTML structure of the document on lines 13–22 (the controller div that contains the buttons and slider), paying special attention to the areas shown in bold below:

   <div id="controller">
      <button id="play">play()</button>
      <button id="pause">pause()</button>
      <button id="reverse">reverse()</button>
      <button id="resume">resume()</button>
      <button id="restart">restart()</button>
      <button id="fastSpeed">timeScale(4)</button>
      <button id="normalSpeed">timeScale(1)</button>
      <div id="slider"></div>
   </div>
   

   This is a fairly basic HTML setup. Each button has its own ID that will make it very easy to assign individual click functions. The slider div is completely empty at this point. Let’s start by adding functionality to the play and pause buttons.

Adding Functionality to the Play & Pause Buttons

TimelineLite has several methods associated with it for the kind of debugging we’ll do in the exercise: play(), pause(), reverse(), resume(), restart(), and timeScale(). The buttons in the DOM have been appropriately labeled to reflect these methods. Now we just need to code them up so they’re functional.

1. Add the following code around line 71 of start.html:

   $("#play").click(function(){
   
   });
   

   By now, the syntax of this code should look familiar. You’re targeting the button with the ID of play. We are using the standard jQuery click() method so the button performs a function when it is clicked. Let’s add that function now.

2. Finish coding the play() button by adding the following bold code:

   $("#play").click(function(){
      tl.play();
   });
   

   Remember that the variable tl refers to the TimelineLite we built in the last exercise. Now that we’ve coded the play() button, we’re ready to code the pause().

3. The code for the pause button is going to look very similar. Copy the play button code and paste it once below, as follows:

   $("#play").click(function(){
      tl.play();
   });
   
   $("#play").click(function(){
      tl.play();
   });
   

4. Make the following changes shown in bold:

   $("#play").click(function(){
      tl.play();
   });
   
   $("#pause").click(function(){
      tl.pause();
   });
   

5. Let’s test out the play and pause buttons! Save the file and preview start.html in the browser. Immediately test out the pause and play buttons. They’re working perfectly, and we only needed to add those few lines of code.

   NOTE: If the timeline plays until the end before you had time to hit the pause button, just reload the page; clicking the play button will not restart the animation from the beginning (though we’ll work on adding this functionality later).

6. Switch back to your code editor.

Adding Reverse, Resume, & Restart Buttons

1. Let’s add the functionality for the reverse and resume buttons. Copy the pause button code and paste it twice, for a total of three identical chunks of code.

2. To add functionality to the reverse and resume buttons, make the changes shown in bold below:

   $("#pause").click(function(){
      tl.pause();
   });
   
   $("#reverse").click(function(){
      tl.reverse();
   });
   
   $("#resume").click(function(){
      tl.resume();
   });
   

3. Save the file and preview start.html in the browser. Test out the new buttons, noticing that after hitting reverse() and pausing, hitting the resume() button will continue to show the animation in reverse. (The play() button will always play forwards, but the resume() button will honor whether the animation was going backwards or forwards before the pause.)

4. Keep experimenting with all four buttons until the behavior of each is clear to you.

5. Switch back to your code editor.

6. Copy the code for the resume button and paste it once below. Make the following changes in bold:

   $("#restart").click(function(){
      tl.restart();
   });
   

   The restart() method plays the timeline from the beginning (that is, from the absolute time of 0).

7. Save the file and preview the page in the browser. Test out the restart() button to see that it will always start the animation over from the beginning.

8. Let the animation play completely and then hit the play() button. Hmm, it should restart the animation, but it isn’t working. Let’s make it behave more intelligently, so it restarts the timeline when the timeline is complete.

Making an Intelligent Play Button

It is important to understand that in TimelineLite, the entire timeline’s progress is based on a scale from 0 to 1. The value 0 refers to the very beginning, 0.5 to the halfway point, and 1 to the very end of the timeline.

TimelineLite’s progress() method uses these values (from 0 to 1) to refer to the position of a virtual playhead. This is how the progress() method is used:

tl.progress() gets the progress
tl.progress(0.5) sets the progress to 0.5 (halfway through the timeline)

In order to create an intelligent play() button that performs a restart() function only when the timeline has finished, we are going to add a little conditional logic that basically says, “If the timeline’s progress is less than 1, then continue playing as usual. Otherwise (else), restart the timeline.” Let’s see what that code looks like!

1. Switch back to your code editor.

2. Add the following bold if statement to the play() button code as follows:

   $("#play").click(function(){
      if(tl.progress() < 1){
          tl.play();
      }
   });
   

   This is the part that says “If the timeline’s progress is less than 1, then continue playing as usual.” Now let’s introduce the else statement.

3. Add the following bold code:

   $("#play").click(function(){
      if(tl.progress() < 1){
         tl.play();
      } else {
         tl.restart();
      }
   });
   

   The else statement makes the play() button perform the restart() function in the case that the timeline is done playing. Now we have an intelligent play button!

4. Save the file and preview the page in the browser. Let the animation play until the end, then try clicking the play() button. Because progress() is equal to 1 when the timeline is finished playing, it will restart! Then you can click pause() and play() to make sure that the normal behavior of the play() button is preserved.

Adding Timescale Buttons

TimelineLite has a timeScale() method that behaves just like the timeScale() method in TweenLite. This makes it easy to play the animation in slow motion or with accelerated speed. For example, timeScale(0.5) will play the timeline at half-speed and timeScale(2) will play the timeline at double-speed.

1. Add the following bold code beneath the restart button code:

   $("#fastSpeed").click(function(){
      tl.timeScale(4);
   });
   

   This will play the animation at “warp speed,” four times as fast as normal. We should add the functionality to reset the speed to normal, too.

2. Copy the code you just wrote and paste it once below.

3. Make the following changes shown in bold:

   $("#fastSpeed").click(function(){
      tl.timeScale(4);
   });
   
   $("#normal Speed").click(function(){
      tl.timeScale(1);
   });
   

4. Save the file and preview the page in the browser. Test out the new buttons, noticing that the timeScale(4) button remains in effect until you click the timeScale(1) button to reset the speed to regular.

   The timeScale() method is very useful. Imagine if you had a timeline with a hundred tweens and the client told you, “It’s great, but I’d like the whole thing to be a bit zippier.” Rather than adjusting the time of each tween, you could simply set tl.timeScale(1.2) for the entire timeline!

Adding a jQuery UI Slider

Let’s add a jQuery UI slider that will allow us to scrub through our animation with a great deal of control. This slider will make it easy to investigate the subtle timing nuances and effects that we put into our animations.

What is jQuery UI? It is a collection of UI components (sliders, buttons, date-pickers, spinners, and more) that are extremely easy to integrate into your own projects. They’ve also been battle-tested in all the major browsers. You can learn more about jQuery UI at jqueryui.com

We’ve saved you the trouble of downloading jQuery UI and simply placed all the necessary files for the slider in the TimelineLite Control > js > jqueryUI folder. Feel free to explore this folder, but it’s not necessary that you understand all the components in order to get the slider working.

What IS important for you to understand is that there are two files that we need to link to: the CSS file that handles the styling of the slider and the jQuery UI minified JavaScript file.

1. Make sure you’re viewing start.html in your code editor. Look at line 7, where we have already linked to the slider’s CSS:

   <link rel="stylesheet" href="js/jqueryUI/css/ui-lightness/jquery-ui-1.10.3.custom.min.css">
   

2. Look around line 41, where we have loaded the jQuery UI minified JavaScript file:

   <script src="js/jqueryUI/js/jquery-ui-1.10.3.custom.min.js"></script>
   

   Now that we’re sure that the CSS and JavaScript files are linked correctly, we can see the magic of jQuery UI in action.

3. Add the following code beneath the timeScale(1) code, around line 103:

   $("#slider").slider();
   

   This code finds our slider div (the empty div that we noticed at the beginning of the exercise) and then calls jQuery UI’s slider() method. This is all the code that we need to make the slider work.

4. Save the file and preview the page in the browser. The nifty jQuery UI slider has been inserted into our empty div! It looks very nice, and you can drag the slider back and forth, but it’s not controlling the timeline yet. We’ll need to configure it with a few additional parameters.

Configuring the jQuery UI Slider

We will create a configuration object for the slider to give it some basic parameters:

For additional information about the slider, check out api.jqueryui.com/slider

1. Return to your code editor and add the following bold code to the slider to give it basic functionality:

   $("#slider").slider({
      min: 0,
      max: 100,
      step: 10,
      slide: function ( event, ui ) {
         console.log("value = " + ui.value);
      }
   });
   

2. Save the file and preview the page in Chrome (so we can use its DevTools). Try dragging the slider and notice that it doesn’t move smoothly, but progresses jerkily.

   NOTE: The slider does not control the animation yet. We are just fine-tuning the general functionality of the slider first.

3. Hit Cmd–Opt–J (Mac) or Ctrl–Shift–J (Windows) to bring up the Console tab of Chrome’s DevTools.

4. Notice that the Console prints out values that are multiples of ten. This is because we set step: 10 and max: 100 so there are only ten steps on our slider. Let’s make it slide with greater precision.

5. Leave the DevTools open in Chrome and switch to your code editor.

6. Make the following change shown in bold:

   $("#slider").slider({
      min: 0,
      max: 100,
      step: 0.1,
      slide: function ( event, ui ) {
         console.log("value = " + ui.value);
      }
   });
   

7. Save the file and preview the page in Chrome. Wow, the slider moves much more smoothly when you drag it, and you can see in Chrome’s Console that there are many more number values for its steps.

8. Leave the DevTools open in Chrome and switch to your code editor.

   There is one hitch in our plan. We need the value of the slider to be applied to the progress() of the timeline and progress() needs a value between 0 and 1. We will have to make a slight modification.

9. Make the following changes shown in bold:

   $("#slider").slider({
      min: 0,
      max: 1,
      step: 0.001,
      slide: function ( event, ui ) {
         console.log("value = " + ui.value);
      }
   });
   

10. Save the file and preview the page in Chrome. Move the slider and notice that the values in Chrome’s Console are all between 0 and 1. Excellent, now we are ready to connect the slider to the timeline!

11. Switch to your code editor.

    We want to apply the new values generated by the slider (all between 0 and 1) to the progress() of the timeline, so that we can scrub the slider to get a position in the timeline.

12. Add the following bold code:

    $("#slider").slider({
       min: 0,
       max: 1,
       step: 0.001,
       slide: function ( event, ui ) {
          console.log("value = " + ui.value);
          tl.progress(ui.value);
       }
    });
    

    This line is where the magic happens. Let’s check out what it does.

13. Save the file and preview the page in Chrome. Drag the slider, noticing that it now controls the progress of the animation! Amazing.

    But wait—if we release the slider, the timeline continues playing. Let’s make it so the timeline pauses when we release the slider.

14. Switch to your code editor.

15. Add the following bold code (around line 109):

    slide: function ( event, ui ) {
       console.log("value = " + ui.value);
       tl.pause();
       tl.progress(ui.value);
    }
    

16. Save the file and preview the page in the browser. Test out the slider—now when we drag the slider, the timeline is paused.

17. Try hitting the play() button and notice that the slider’s position does not move. This is a problem, because it ought to move along with the timeline’s progress—but it won’t be hard to fix!

18. Switch to your code editor.

19. TimelineLite has event callbacks, just like TweenLite and TweenMax. We set them up in the same way, by adding them to the vars object in the TimelineLite constructor function. Find the TimelineLite constructor, around line 60:

    tl = new TimelineLite();
    

20. Add the following bold code so it reads:

    tl = new TimelineLite({onUpdate:updateSlider});
    

    This tells the timeline that every time it updates, it should perform a function called updateSlider. Now we need to add that function.

21. Scroll down to around line 114 and add the following beneath the slider code:

    function updateSlider() {
       $("#slider").slider( "value", tl.progress() );
    }
    

    Here, you set the "value" of the slider so the slider position is equal to the progress() of the timeline.

22. Save the file and preview the page in the browser. The slider now moves along with the progress of the timeline, and all of the various buttons are still working correctly, too. Perfect!

    You can take the code from this TimelineLite controller and use it to test and debug any of your own animations in the future!

Adding Interactivity to the Animation in a Bonus Exercise

If you have time, take a crack at the bonus exercise Fancy Rollovers with TimelineLite at the back of the book. You’ll learn how to add mouseover events to make this animation interactive.