deferred.promise()

jQuery

previous page next page

deferred.promise()

Categories: Deferred Object

deferred.promise( [target ] ) Returns: Promise

Description: Return a Deferred's Promise object.

  • version added: 1.5deferred.promise( [target ] )

    • target
      Type: Object
      Object onto which the promise methods have to be attached

The deferred.promise() method allows an asynchronous function to prevent other code from interfering with the progress or status of its internal request. The Promise exposes only the Deferred methods needed to attach additional handlers or determine the state (then, done, fail, always, pipe, progress, and state), but not ones that change the state (resolve, reject, notify, resolveWith, rejectWith, and notifyWith).

If target is provided, deferred.promise() will attach the methods onto it and then return this object rather than create a new one. This can be useful to attach the Promise behavior to an object that already exists.

If you are creating a Deferred, keep a reference to the Deferred so that it can be resolved or rejected at some point. Return only the Promise object via deferred.promise() so other code can register callbacks or inspect the current state.

For more information, see the documentation for Deferred object.

Examples:

Example: Create a Deferred and set two timer-based functions to either resolve or reject the Deferred after a random interval. Whichever one fires first "wins" and will call one of the callbacks. The second timeout has no effect since the Deferred is already complete (in a resolved or rejected state) from the first timeout action. Also set a timer-based progress notification function, and call a progress handler that adds "working..." to the document body.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
 
                                  

                                    

                                      
                                        function asyncEvent(){
                                      
                                    

                                  

                                  

                                    

                                          var dfd = new jQuery.Deferred();
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                          // Resolve after a random interval
                                    

                                  

                                  

                                    

                                          setTimeout(function(){
                                    

                                  

                                  

                                    

                                              dfd.resolve("hurray");
                                    

                                  

                                  

                                    

                                          }, Math.floor(400+Math.random()*2000));
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                          // Reject after a random interval
                                    

                                  

                                  

                                    

                                          setTimeout(function(){
                                    

                                  

                                  

                                    

                                              dfd.reject("sorry");
                                    

                                  

                                  

                                    

                                          }, Math.floor(400+Math.random()*2000));
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                          // Show a "working..." message every half-second
                                    

                                  

                                  

                                    

                                          setTimeout(function working(){
                                    

                                  

                                  

                                    

                                              if ( dfd.state() === "pending" ) {
                                    

                                  

                                  

                                    

                                                  dfd.notify("working... ");
                                    

                                  

                                  

                                    

                                                  setTimeout(working, 500);
                                    

                                  

                                  

                                    

                                              }
                                    

                                  

                                  

                                    

                                          }, 1);
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                          // Return the Promise so caller can't change the Deferred
                                    

                                  

                                  

                                    

                                          return dfd.promise();
                                    

                                  

                                  

                                    

                                      }
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                      
                                        // Attach a done, fail, and progress handler for the asyncEvent
                                      
                                    

                                  

                                  

                                    

                                      $.when( asyncEvent() ).then(
                                    

                                  

                                  

                                    

                                          function(status){
                                    

                                  

                                  

                                    

                                              alert( status+', things are going well' );
                                    

                                  

                                  

                                    

                                          },
                                    

                                  

                                  

                                    

                                          function(status){
                                    

                                  

                                  

                                    

                                              alert( status+', you fail this time' );
                                    

                                  

                                  

                                    

                                          },
                                    

                                  

                                  

                                    

                                          function(status){
                                    

                                  

                                  

                                    

                                              $("body").append(status);
                                    

                                  

                                  

                                    

                                          }
                                    

                                  

                                  

                                    

                                      );

Example: Use the target argument to promote an existing object to a Promise:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
 
                                  

                                    

                                      
                                        // Existing object
                                      
                                    

                                  

                                  

                                    

                                      var obj = {
                                    

                                  

                                  

                                    

                                        hello: function( name ) {
                                    

                                  

                                  

                                    

                                          alert( "Hello " + name );
                                    

                                  

                                  

                                    

                                        }
                                    

                                  

                                  

                                    

                                      },
                                    

                                  

                                  

                                    

                                      
                                        // Create a Deferred
                                      
                                    

                                  

                                  

                                    

                                      defer = $.Deferred();
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                      
                                        // Set object as a promise
                                      
                                    

                                  

                                  

                                    

                                      defer.promise( obj );
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                      
                                        // Resolve the deferred
                                      
                                    

                                  

                                  

                                    

                                      defer.resolve( "John" );
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                      
                                        // Use the object as a Promise
                                      
                                    

                                  

                                  

                                    

                                      obj.done(function( name ) {
                                    

                                  

                                  

                                    

                                        obj.hello( name ); // will alert "Hello John"
                                    

                                  

                                  

                                    

                                      }).hello( "Karl" ); // will alert "Hello Karl"
 POWERED BYHERONOTE
previous page start next page