Skip to content

Commit eb8623b

Browse files
committed
Effects: Merge 2 articles on queues
1 parent fa001a6 commit eb8623b

File tree

3 files changed

+112
-245
lines changed

3 files changed

+112
-245
lines changed

order.json

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -59,8 +59,7 @@
5959
"effects": [
6060
"intro-to-effects",
6161
"custom-effects",
62-
"queue-and-dequeue-explained",
63-
"uses-of-queue-and-dequeue"
62+
"queue-and-dequeue-explained"
6463
]
6564
},
6665
{

page/effects/queue-and-dequeue-explained.md

Lines changed: 111 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -4,53 +4,135 @@
44
"source": "http://jqueryfordesigners.com/api-queue-dequeue/"
55
}</script>
66

7-
When you use the `.animate()`, `.show()`, `.hide()`, `.slideUp()`, etc. effect methods, you're adding a job to the effects queue. By default, using `.queue()` and passing a function, will add it to the effects queue. So we're creating our own bespoke animation step:
7+
Queues are the foundation for all animations in jQuery, they allow a series functions to be executed asynchronously on an element. Methods such as `.slideUp()`, `.slideDown()`, `.fadeIn()`, and `.fadeOut()` all use `.animate()`, which leverages *queues* to build up the series of steps that will transition one or more CSS values throughout the duration of the animation.
8+
9+
We can pass a callback function to the `.animate()` method, which will execute once the animation has completed.
810

911
```
1012
$( ".box" )
11-
.animate({
13+
.animate( {
1214
height: 20
13-
}, "slow" )
14-
.queue(function() {
15+
}, "slow", function() {
1516
$( "#title" ).html( "We're in the animation, baby!" );
16-
});
17+
} );
1718
```
1819

19-
As I said though, these methods come in pairs, so anything you add using `.queue()`, you need to dequeue to allow the process to continue. In the code above, if I chained more animations on, until I call `$( this ).dequeue()`, the subsequent animations wouldn't run:
20+
## Queues As Callbacks
21+
22+
Instead of passing a callback as an argument, we can add another function to the *queue* that will act as our callback. This will execute after all of the steps in the animation have completed.
2023

2124
```
2225
$( ".box" )
23-
.animate({
26+
.animate( {
2427
height: 20
25-
}, "slow" )
26-
.queue(function() {
28+
}, "slow")
29+
.queue( function() {
2730
$( "#title" ).html( "We're in the animation, baby!" );
28-
$( this ).dequeue();
29-
}).animate({
30-
height: 150
31-
});
31+
} );
32+
3233
```
3334

34-
Keeping in mind that the animation won't continue until we've explicitly called `.dequeue()`, we can easily create a pausing plugin, by adding a step in the queue that sets a timer and triggers after `delay` milliseconds, at which time, it dequeues the element:
35+
To add multiple functions to the queue, you can call `.queue()` multiple times.
3536

3637
```
37-
$.fn.pause = function( delay ) {
38-
return this.queue(function() {
39-
var elem = this;
40-
setTimeout(function() {
41-
return $( elem ).dequeue();
42-
}, delay );
43-
});
44-
};
45-
4638
$( ".box" )
47-
.animate({
39+
.animate( {
4840
height: 20
4941
}, "slow" )
50-
.pause( 1000 )
51-
.animate({
52-
height: 150
53-
});
42+
.queue( function() {
43+
console.log('I fired!');
44+
} )
45+
.animate( {
46+
height: 50
47+
}, "fast" )
48+
.queue( function() {
49+
console.log('I fired too!');
50+
} );
51+
```
52+
53+
If you ran this example, you will have seen that the last animation never runs and the last callback doesn't fire. This is because we basically never told jQuery to continue. Inside of the first queued function, you will need to call `.dequeue()` to move forward to the next function in the queue.
54+
55+
```
56+
.queue( function() {
57+
console.log('I fired!');
58+
$( this ).dequeue();
59+
} )
60+
```
61+
62+
Another way of *dequeuing* is by calling the function that is passed to your callback. That function will automatically call `.dequeue()` for you.
63+
64+
```
65+
.queue( function(next) {
66+
console.log('I fired!');
67+
next();
68+
} )
69+
```
70+
71+
## Custom Queues
72+
73+
Up to this point all of our animation and queue examples have been using the default queue name which is `fx`. Elements can have multiple queues attached to them, and we can give each of these queues a different name. We can specify a custom queue name as the first argument to the `.queue()` method.
74+
75+
```
76+
$( ".box" )
77+
.queue( "steps", function( next ) {
78+
console.log( "Step 1" );
79+
next();
80+
} )
81+
.queue( "steps", function( next ) {
82+
console.log( "Step 2" );
83+
next();
84+
} )
85+
.dequeue( "steps" );
5486
```
5587

56-
Remember that the first argument for `.queue()` and `.dequeue()` is `fx`, and that in all of these examples I'm not including it because jQuery sets the argument to `fx` by default — so I don't have to specify it.
88+
Notice that we have to call the `.dequeue()` method passing it the name of our custom queue to start the execution. Every queue except for the default, `fx`, has to be manually kicked off by calling `.dequeue()` and passing it the name of the queue.
89+
90+
## Clearing The Queue
91+
92+
Since queues are just a set of ordered operations, our application may have some logic in place that needs to prevent the remaining queue entries from executing. We can do this by calling the `.clearQueue()` method, which will empty the queue.
93+
94+
```
95+
$( ".box" )
96+
.queue( "steps", function( next ) {
97+
console.log( "I fired" );
98+
next();
99+
} )
100+
.clearQueue( "steps" )
101+
.dequeue( "steps" );
102+
```
103+
104+
In this example, nothing will happen as we removed everything from the `steps` queue.
105+
106+
Another way of clearing the queue is to call `.stop( true )`. That will stop the currently running animations and will clear the queue.
107+
108+
## Replacing The Queue
109+
110+
When you pass an array of functions as second argument to `.queue()`, that array will replace the queue.
111+
112+
```
113+
$( ".box" )
114+
.queue( "steps", function( next ) {
115+
console.log( "I won't fire" );
116+
next();
117+
} )
118+
.queue( "steps", [
119+
function( next ) {
120+
console.log( "I fired!" );
121+
next();
122+
}
123+
] )
124+
.dequeue( "steps" );
125+
```
126+
127+
You can also call `.queue()` without passing it functions, which will return the queue of that element as an array.
128+
129+
```
130+
$( ".box" ).queue( "steps", function( next ) {
131+
console.log( "I fired!" );
132+
next();
133+
} );
134+
135+
console.log( $( ".box" ).queue( "steps" ) );
136+
137+
$('.box').dequeue( "steps" );
138+
```

page/effects/uses-of-queue-and-dequeue.md

Lines changed: 0 additions & 214 deletions
This file was deleted.

0 commit comments

Comments
 (0)