Updated April 13, 2023
Definition of jQuery when
The jQuery when() function is used to run the callback function based on zero or more Thenable objects or Deferred object. This function is a built-in function in jQuery. The when() function accepts a enable object (an object which exposes a then method and returns a promise). The enable objects are usually Deferred objects which represent asynchronous events.
Syntax:
jQuery.when(deferreds);Parameters:
- deferreds – This is not an optional parameter, that specifies zero or more objects of Thenable objects.
- Return value – The return value of this function is a promise (promise is an object with a thenable object that is a then method conforms to the specification).
Working of the jQuery when() function
The jQuery when() function gives a way to execute one or more objects of the callback function. The object when we pass to the when() function, will return promise objects which conform to the specification with the passed thenable object. Then when the object has been accepted or rejected it will call the respective callback function to execute. If we o not pass any objects to the jQuery when() function, then the function returns an accepted (resolved) promise object’s state.
Examples for jQuery when() function
Next, we write the HTML code to understand this function more clearly with the following example, where the when() function is used to execute the function without passing any object, as below.
Example #1
Code:
<!doctype html>
<html lang = "en">
<head>
<meta charset="utf-8">
<title> This is an example for jQuery when function </title>
<script src = "https://ajax.googleapis.com/ajax/libs/jquery/3.3.1/jquery.min.js">
</script>
</head>
<script>
var def = $.Deferred();
function func() {
$.when().then(function(a) {
$( "body" ).css( "color", "red" ).text(
"when() method called this text() method." );
});
}
</script>
<body>
<h1 style = "color:green;"> This is an example for when() function. </h1>
<button onclick = "func();"> click here to call the callback function.
</button>
</body>
</html>Output:
Once we click on the “click here to call the callback function.” button the output is:
As in the above program the Deferred object is created, but it is not passing to the when() function. To the when() function no object is passing as a parameter, so If we do not passes any parameters at all, the jQuery.when() function will return a resolved promise that way we are getting the printed message, which is texting inside the callback function, as we can see in the output.
Example of jQuery when () function for single parameter passing-
Next, we write the HTML code to understand the jQuery when() function, where the when() function is used to execute the function and passing a single object to the function, as below –
Example #2
Code:
<!doctype html>
<html lang = "en">
<head>
<meta charset="utf-8">
<title> This is an example for jQuery when function </title>
<script src = "https://ajax.googleapis.com/ajax/libs/jquery/3.3.1/jquery.min.js">
</script>
</head>
<script>
function func() {
$.when( { test1 : 123, test2 : 345 } ).then(function( x ) {
var msg = "when() function is called this alert() method. The object passed values are " +x.test1+ " and " +x.test2+ ".";
alert( msg );
});
}
</script>
<body style="text-align:center;">
<h1 style = "color:red;"> This is an example for when() function with single object. </h1>
<button onclick = "func();"> click here to call the callback function. </button>
</body>
</html>Output:
Once we click on the “click here to call the callback function.” button, the output is:
As in the above program an object is created which contains two properties and is directly passing to the when() function. To the when() function single object is passing as a parameter which is not a Deferred or a Promise, so If we pass non Deferred or a Promise object as parameters, the jQuery.when() function will treat it as a resolved Deferred and callback function attache will be executed. The done Callbacks are passed as above the original parameter, so the fail Callbacks, if we have set, are never called because the Deferred is never rejected.
Example of jQuery when () function for multiple parameter passing.
Next, we write the HTML code to understand this function, where the when() function is used to execute the function and passing multiple objects to the function, as below.
Example #3
Code:
<!doctype html>
<html lang = "en">
<head>
<meta charset="utf-8">
<title> This is an example for jQuery when function </title>
<script src = "https://ajax.googleapis.com/ajax/libs/jquery/3.3.1/jquery.min.js">
</script>
</head>
<script>
var dobj1 = $.Deferred();
var dobj2 = $.Deferred();
var dobj3 = $.Deferred();
function func() {
$.when( dobj1, dobj2, dobj3 ).done(function ( p1, p2, p3 ) {
$('div').append(p1)
$('div').append("<br>")
$('div').append(p2)
$('div').append("<br>")
$('div').append(p3)
});
// p1 value is undefined
dobj1.resolve();
// p2 value is single string value.
dobj2.resolve( "This is single string value." );
// p3 value is multiple integer values.
dobj3.resolve( 11, 21, 34, 42, 55 );
}
</script>
<body >
<h1 > This is an example for when() function with multiple objects. </h1>
<button onclick = "func();" style = "background : red;"> click here to call the callback function. </button>
<div></div>
</body>
</html>Output:
Click this button “click here to call the callback function.” to iterate all the properties of an object.
As in the above program, the three objects are created and which are passing to the when() function. To the when() function multiple objects are passing as a parameter which is a Deferred or Promise objects. Later in the event a first Deferred object is resolved to no value, so the respective doneCallback argument is undefined. The second Deferred object is resolved to a single string value, so the respective parameter will be having that value. The third Deferred object is resolved to multiple integer values, so the respective parameter will have an array of those values.
Conclusion
The jQuery when function is a built-in function in jQuery, which is used to execute the callback function based on zero or more Tenable objects.
Recommended Articles
This is a guide to jQuery when. Here we also discuss the definition, methods, Working of the jQuery when() function with example. You may also have a look at the following articles to learn more –
