Toggling Elements

You can flip elements from being visible or hidden and back using the toggle method. Listing 10-2 gives an example.

Listing 10-2.  Using the toggle Method to Switch Element Visibility

...
<script type="text/javascript">
    $(document).ready(function() {
        $("<button>Toggle</button>").appendTo("#buttonDiv")
            .click(function(e) {
                $("div.dcell:first-child").toggle();
                e.preventDefault();
            });
    });
</script>
...

In Listing 10-2 I add a single button to the document, and when it is clicked, I use the toggle element to change the visibility of the div.dcell elements that are the first children of their parents. You can see the effect in Figure 10-3.

Toggling in One Direction

You can pass a boolean argument to the toggle method to restrict the way that visibility is toggled. If you pass true as the argument, then only hidden elements will be shown (visible elements will not be hidden). If you pass false as the argument, then you get the opposite effect. Visible elements will be hidden, but hidden elements will not be made visible. Listing 10-3 shows the use of this flavor of the toggle method. The script in Listing 10-3 creates the effect shown in Figure 10-3.

Listing 10-3.  Using the toggle Method in One Direction

...
<script type="text/javascript">
    $(document).ready(function() {
        $("<button>Toggle</button>").appendTo("#buttonDiv")
            .click(function(e) {
                $("div.dcell:first-child").toggle(false);
                e.preventDefault();
            });
    });
</script>
...

Animating the Visibility of Elements

You can animate the process of showing and hiding elements by passing a time span to the show, hide, or toggle methods. The process of showing and hiding elements is then performed gradually, over the specified period. Table 10-3 shows the different time span arguments you can use.

Listing 10-4 shows how you can animate showing and hiding elements.

Listing 10-4.  Animating the Visibility of Elements

...
<script type="text/javascript">
    $(document).ready(function() {
          
        $("<button>Toggle</button>").appendTo("#buttonDiv")
            .click(function(e) {
                $("img").toggle("fast", "linear");
                e.preventDefault();
            });
              
    });
</script>
...

In Listing 10-4, I have used the fast value to specify that toggling the visibility of the img elements in the document should be done over a period of 600 milliseconds.

I have also provided an additional argument, which specifies the style of the animation, known as the easing style or easing function. Two easing styles are available, swing and linear. When animating with the swing style, the animation starts slowly, speeds up, and then slows down again as the animation reaches conclusion. The linear style maintains a constant pace throughout the animation. If you omit the argument, swing is used. You can see the effect of the animation as it hides elements in Figure 10-4. It is difficult to show animation in this way, but you’ll get a sense of what happens.

As the figure shows, the animation effect reduces the size of the image in both dimensions and decreases the opacity. At the end of the animation, the img elements are invisible. Figure 10-5 shows what happens if you click the Toggle button again to make the img elements visible.

Using Effect Callbacks

You can supply a function as an argument to the show, hide, and toggle methods, and the function will be called when these methods finish performing their effect. This can be useful for updating other elements to reflect the change in status, as shown in Listing 10-5.

Listing 10-5.  Using an Event Callback

...
<script type="text/javascript">
    $(document).ready(function() {
  
        var hiddenRow = "#row2";
        var visibleRow = "#row1";
          
        $(hiddenRow).hide();
          
        function switchRowVariables() {
            var temp = hiddenRow;
            hiddenRow = visibleRow;
            visibleRow = temp;
        }
  
        function hideVisibleElement() {
            $(visibleRow).hide("fast", showHiddenElement);
        }
              
        function showHiddenElement() {
            $(hiddenRow).show("fast", switchRowVariables);
        }
          
        $("<button>Switch</button>").insertAfter("#buttonDiv button")
            .click(function(e) {
                hideVisibleElement();
                e.preventDefault();
            });
    });
</script>
...

To make Listing 10-5 clearer, I have broken down the effect activities into separate functions. To get set up, I hide one of the div elements that acts as a row in my CSS table layout and define two variables that I use to track which row is visible and which row is not. I add a button element to the document, and when this is clicked I call the hideVisibleElement function, which uses the hide method to animate hiding the visible row.

...
$(visibleRow).hide("fast",showHiddenElement);
...

I specify the name of the function I want performed when the effect has completed, in this case showHiddenElement.

This function uses the show method to animate revealing the element, as follows:

...
$(hiddenRow).show("fast",switchRowVariables);
...

Once again, I specify a function to perform at the end of the effect. In this case, it is the switchRowVariables function, which shuffles the variables that track visibility so that you perform the effects on the right elements the next time the button is clicked. The result is that when the button is clicked, the current row is replaced by the hidden row, with a quick animation to make the transition less jarring to the user. Figure 10-6 shows the effect (although, once again, the true effect becomes apparent only when you load the example in the browser).

You wouldn’t usually need to break out the individual functions as I did, so Listing 10-6 shows the same example rewritten using a terser set of inline functions.

Listing 10-6.  Using Inline Callback Functions

...
<script type="text/javascript">
    $(document).ready(function() {
          
        var hiddenRow = "#row2";
        var visibleRow = "#row1";
          
        $(hiddenRow).hide();
          
        $("<button>Switch</button>").insertAfter("#buttonDiv button")
            .click(function(e) {
                $(visibleRow).hide("fast", function() {
                    $(hiddenRow).show("fast", function() {
                        var temp = hiddenRow;
                        hiddenRow = visibleRow;
                        visibleRow = temp;
                    });
                });
                  
                e.preventDefault();
            });
    });
</script>
...

Creating Looping Effects

You can use the callback functions to produce effects that are performed in a loop. Listing 10-7 demonstrates.

Listing 10-7.  Using Callback Functions to Create a Looping Effect

...
<script type="text/javascript">
    $(document).ready(function() {
          
        $("<button>Toggle</button>").insertAfter("#buttonDiv button")
            .click(function(e) {
                performEffect();
                e.preventDefault();
            });
          
        function performEffect() {
            $("h1").toggle("slow", performEffect)
        }
    });
</script>
...

In this example, clicking the button leads to the performEffect function being executed. This function uses the toggle method to change the visibility of the h1 element in the document and passes itself as the callback argument. The result is that the h1 element loops between being visible and hidden, as shown in Figure 10-7.

Using Relative Target Property Values

You can also specify your animation targets using relative values. You specify an increase by prefixing a value with += and a decrease with -=. Listing 10-14 shows the use of relative values.

Listing 10-14.  Using Relative Values in a Custom Animation Effect

...
<script type="text/javascript">
    $(document).ready(function() {
                  
        $("form").css({"position": "fixed", "top": "70px", "z-index": "2"});
        $("h1").css({"position": "fixed", "z-index": "1", "min-width": "0"});
          
        $("<button>Animate</button>").insertAfter("#buttonDiv button")
            .click(function(e) {
                $("h1").animate({
                    height: "+=100",
                    width: "-=700"
                });
                                  
                e.preventDefault();
            });
    });
</script>
...

Displaying the Items in the Effect Queue

You can use the queue method to inspect the contents of the effects queue. This is not entirely helpful because the queue contains one of two types of data object. If an effect is being executed, then the corresponding item in the queue is the string value inprogress. If the effect is not being executed, the item in the queue is the function that will be invoked (although the function doesn’t reveal which animation function will be performed). That said, inspecting the content is a good place to start with the queue, and Listing 10-16 shows how it can be done.

Listing 10-16.  Inspecting the Contents of the Effect Queue

...
<script type="text/javascript">
    $(document).ready(function () {
  
        $("h1").css({ "position": "fixed", "z-index": "1", "min-width": "0" });
        $("form").remove();
        $("<table border=1></table>")
            .appendTo("body").css({
                position: "fixed", "z-index": "2",
                "border-collapse": "collapse", top: 100
            });
  
        var timespan = "slow";
  
        cycleEffects();
        printQueue();
  
        function cycleEffects() {
            $("h1")
            .animate({ left: "+=100" }, timespan)
            .animate({ left: "-=100" }, timespan)
            .animate({ height: 223, width: 700 }, timespan)
            .animate({ height: 30, width: 500 }, timespan)
            .slideUp(timespan)
            .slideDown(timespan, cycleEffects);
        }
  
        function printQueue() {
            var q = $("h1").queue();
            var qtable = $("table");
            qtable.html("<tr><th>Queue Length:</th><td>" + q.length + "</td></tr>");
            for (var i = 0; i < q.length; i++) {
                var baseString = "<tr><th>" + i + ":</th><td>";
                if (q[i] == "inprogress") {
                    $("table").append(baseString + "In Progress</td></tr>");
                } else {
                    $("table").append(baseString + q[i] + "</td></tr>");
                }
            }
            setTimeout(printQueue, 500);
        }
    });
</script>
...

I don’t need the form element in this example, so I have removed it from the DOM and replaced it with a simple table that I’ll use to display the contents of the effect queue. I have added a repeating function called printQueue that calls the queue method and displays the number of items and a little detail about each of them in the table. As I say, the items in the queue are not especially useful in their own right, but they do give you an overall picture of what is going on. Figure 10-15 shows how jQuery progresses through the effects queue.

Listing 10-16 is hard to portray in static images. I recommend you load the document into a browser to see for yourself. When the cycleEffects function is first called, there are six items in the effects queue, the first of which is shown as being in progress. The others are instances of an anonymous function that manages an animation. After each effect is completed, jQuery removes the item from the queue. At the end of the last effect, the cycleEffects function is called again, which puts six items in the queue again.

Stopping Effects and Clearing the Queue

You can use the stop and finish methods to interrupt the effect that jQuery is currently performing. For the stop method, you can provide two optional arguments to this method, both of which are boolean values. If you pass true as the first argument, then all of the other effects are removed from the queue and will not be performed. If you pass true as the second argument, then the CSS properties that are being animated by the current animation will be immediately set to their final values.

The default value for both arguments is false, which means that only the current effect is removed from the queue and that the properties that were being animated are left at the values they were set to at the moment the effect was interrupted. If you don’t clear the queue, jQuery will move on to the next effect and begin executing it as normal. Listing 10-17 provides an example of using the stop method.

Listing 10-17.  Using the stop Method

...
<script type="text/javascript">
    $(document).ready(function () {
  
        $("h1").css({ "position": "fixed", "z-index": "1", "min-width": "0" });
        $("form").remove();
  
        $("<table border=1></table>")
            .appendTo("body").css({
                position: "fixed", "z-index": "2",
                "border-collapse": "collapse", top: 100
            });
  
        $("<button>Stop</button><button>Start</button>")
          .appendTo($("<div/>").appendTo("body")
            .css({
                position: "fixed", "z-index": "2",
                "border-collapse": "collapse", top: 100, left: 200
            })).click(function (e) {
                $(this).text() == "Stop" ? $("h1").stop(true, true) : cycleEffects();
            });
  
        var timespan = "slow";
  
        cycleEffects();
        printQueue();
  
        function cycleEffects() {
            $("h1")
            .animate({ left: "+=100" }, timespan)
            .animate({ left: "-=100" }, timespan)
            .animate({ height: 223, width: 700 }, timespan)
            .animate({ height: 30, width: 500 }, timespan)
            .slideUp(timespan)
            .slideDown(timespan, cycleEffects);
        }
  
        function printQueue() {
            var q = $("h1").queue();
            var qtable = $("table");
            qtable.html("<tr><th>Queue Length:</th><td>" + q.length + "</td></tr>");
  
            for (var i = 0; i < q.length; i++) {
                var baseString = "<tr><th>" + i + ":</th><td>";
                if (q[i] == "inprogress") {
                    $("table").append(baseString + "In Progress</td></tr>");
                } else {
                    $("table").append(baseString + q[i] + "</td></tr>");
                }
            }
            setTimeout(printQueue, 500);
        }
    });
</script>
...

To demonstrate the stop method, I have added two buttons to the document. When the Stop button is clicked, I call the stop method, passing in two true arguments. This has the effect of clearing the rest of the effect queue and snapping the element to the target values for the property that was being animated. Since callback functions are not invoked when the stop method is used, the loop of cycleEffects method calls is broken, and animation is brought to a halt. When the Start button is clicked, the cycleEffects method is called and the animation resumes.

The finish method has a similar effect to calling stop(true, true), but differs in the way that it handles the CSS properties that are being animated. When calling stop(true, true), the CSS properties that are being animated by the current effect jump to their final values, but when using the finish method, the CSS properties being animated by the current effect and all of the queued effects jump to their final values. You can see how I have applied the finish method in Listing 10-18.

Listing 10-18.  Using the finish method

...
<script type="text/javascript">
    $(document).ready(function () {
  
        $("h1").css({ "position": "fixed", "z-index": "1", "min-width": "0" });
        $("form").remove();
  
        $("<table border=1></table>")
            .appendTo("body").css({
                position: "fixed", "z-index": "2",
                "border-collapse": "collapse", top: 100
            });
  
        var finishAnimations = false;
  
        $("<button>Stop</button><button>Start</button>")
          .appendTo($("<div/>").appendTo("body")
            .css({
                position: "fixed", "z-index": "2",
                "border-collapse": "collapse", top: 100, left: 200
            })).click(function (e) {
                if ($(this).text() == "Stop") {
                    finishAnimations = true;
                    $("h1").finish();
                } else {
                    finishAnimations = false;
                    cycleEffects();
                }
            });
  
        var timespan = "slow";
  
        cycleEffects();
        printQueue();
  
        function cycleEffects() {
            $("h1")
            .animate({ left: "+=100" }, timespan)
            .animate({ left: "-=100" }, timespan)
            .animate({ height: 223, width: 700 }, timespan)
            .animate({ height: 30, width: 500 }, timespan)
            .slideUp(timespan)
            .slideDown(timespan, function () {
                if (!finishAnimations) {
                    cycleEffects();
                }
            });
        }
  
        function printQueue() {
            var q = $("h1").queue();
            var qtable = $("table");
            qtable.html("<tr><th>Queue Length:</th><td>" + q.length + "</td></tr>");
  
            for (var i = 0; i < q.length; i++) {
                var baseString = "<tr><th>" + i + ":</th><td>";
                if (q[i] == "inprogress") {
                    $("table").append(baseString + "In Progress</td></tr>");
                } else {
                    $("table").append(baseString + q[i] + "</td></tr>");
                }
            }
            setTimeout(printQueue, 500);
        }
    });
</script>
...

When using the finish method, care must be taken with effect loops, such as the one in Listing 10-18. In order to determine the final CSS values for all of the animated properties, the finish method needs to execute all of the effects—albeit without any time delays—and that means that any callback functions are executed as well.

In Listing 10-18, the last effect defined in the cycleEffects function sets up the next effect loop, as follows:

...
.slideDown(timespan, cycleEffects);
...

The finish method doesn’t prevent new effects being added to the queue and it doesn’t keep track of the state of the queue when it is called. This means that the finish method will call the cycleEffects method, which adds effects to the queue, which the finish method then executes, triggering the callback, which adds effects to the queue . . . and so on. The overall effect is to immediately exhaust the JavaScript call stack.

To avoid this, I have added a variable called finishAnimations, which I set in response to the button elements being clicked and I check before adding the next set of effects to the queue, as follows:

...
.slideDown(timespan, function () {
    if (!finishAnimations) {
        cycleEffects();
    }
});
...

Inserting a Delay into the Queue

You can use the delay method to introduce a pause between two effects in the queue. The argument to this method is the number of milliseconds that the delay should last for. Listing 10-19 shows the use of this method to introduce one-second delays into the effect queue.

Listing 10-19.  Using the delay Method

...
function cycleEffects() {
    $("h1")
    .animate({ left: "+=100" }, timespan)
    .animate({ left: "-=100" }, timespan)
    .delay(1000)
    .animate({ height: 223, width: 700 }, timespan)
    .animate({ height: 30, width: 500 }, timespan)
    .delay(1000)
    .slideUp(timespan)
    .slideDown(timespan, function () {
        if (!finishAnimations) {
            cycleEffects();
        }
    });
}
...

Inserting Functions into the Queue

You can add your own functions into the queue using the queue method, and they will be executed just as the standard effect methods are. You can use this feature to start other animations, gracefully exit a chain of animations based on an external variable, or, well, do anything that you need. Listing 10-20 contains an example.

Listing 10-20.  Inserting a Custom Function into the Queue

...
function cycleEffects() {
    $("h1")
    .animate({ left: "+=100" }, timespan)
    .animate({ left: "-=100" }, timespan)
    .queue(function () {
        $("body").fadeTo(timespan, 0).fadeTo(timespan, 1);
        $(this).dequeue();
    })
    .delay(1000)
    .animate({ height: 223, width: 700 }, timespan)
    .animate({ height: 30, width: 500 }, timespan)
    .delay(1000)
    .slideUp(timespan)
    .slideDown(timespan, function () {
        if (!finishAnimations) {
            cycleEffects();
        }
    });
}
...

The this variable is set to the jQuery object that the method was called on. This is useful because you must make sure to call the dequeue method at some point in your function in order to move the queue onto the next effect or function. In this example, I used the queue method to add a function that fades the body element to fully transparent and back.

Alternatively, you can accept a single argument to the function, which is the next function in the queue. In this situation, you must invoke the function to move the queue to the next effect, as shown in Listing 10-21.

Listing 10-21.  Using the Argument Passed to the Custom Function

...
function cycleEffects() {
    $("h1")
    .animate({ left: "+=100" }, timespan)
    .animate({ left: "-=100" }, timespan)
    .queue(function (nextFunction) {
        $("body").fadeTo(timespan, 0).fadeTo(timespan, 1);
        nextFunction();
    })
    .delay(1000)
    .animate({ height: 223, width: 700 }, timespan)
    .animate({ height: 30, width: 500 }, timespan)
    .delay(1000)
    .slideUp(timespan)
    .slideDown(timespan, function () {
        if (!finishAnimations) {
            cycleEffects();
        }
    });
}
...