`.promise()`S2C Home « Objects « `.promise()`

Promise resolution.

Description

The .promise() Deferred method, returns a dynamically generated Promise that is resolved once all collection bound actions of a certain type have ended.

A Promise object provides the following subset of methods of the Deferred object: deferred.then(), deferred.done(), deferred.fail(), deferred.always(), deferred.pipe() and deferred.progress() methods or determine the state through the deferred.state() method.
Ensure you keep a reference to the original Deferred object, so it can eventually be resolved or rejected. The returned Promise is linked to a Deferred object via the element's data, stored via the .data() method for an element. Because the .remove() method removes the element's data as well as the element itself, it will prevent any of the element's unresolved Promises from resolving. When it's necessary to remove an element from the DOM before its Promise is resolved, use the .detach() method instead, followed up by the .removeData() method.

Syntax

Signature	Description
`.promise( [type] [, target] )`	Return a dynamically generated Promise that is resolved once all collection bound actions of a certain type have ended, optionally passing a queue type and/or a target object.

Parameters

Parameter	Description	Type
`type`	The type of queue that needs to be observed. The default queue is named 'fx' and has certain properties that are not shared with named queues: The 'fx' queue will automatically `.dequeue()` the next function on the queue and run it if the queue hasn't started. When `.dequeue()` is used on a function from the 'fx' queue, it will `unshift()` the string 'inprogress', into the [0] location of the array, thus flagging that the 'fx' queue is currently executing. Being the default, the 'fx' queue is called by `.animate()` and any other function that calls it by default.	`String`
`target`	Object to attach the promise methods to.	`PlainObject`

Return

A Promise object.

`.promise( [type] [, target] )` ExamplesTop

Return a dynamically generated Promise that is resolved once all collection bound actions of a certain type have ended, optionally passing a queue type and/or a target object.

In the following example when we press the button the first time, we fire off some animations. We use the .promise() method which gets resolved when all the animations have completed and we display a message.


$(function(){
  $('#btn3').one('click', function(){
    $('#curry1').fadeIn();
    $('#curry2').slideDown('slow').slideUp('fast');
    $('#curry3').fadeIn(2000).fadeOut('fast');
    $('#curry1, #curry2, #curry3').promise().done(function() {
      $('#div1').append('Animations completed!');
    });
  });
});