# deferred.then()

## deferred.then ( doneFilter, failFilter, progressFilter ) Returns: Promise version added: 1.8

- doneFilter
  Type: Function
  A function that is called when the Deferred is resolved.

- failFilter
  Type: Function
  An optional function that is called when the Deferred is rejected.

- progressFilter
  Type: Function
  An optional function that is called when progress notifications are sent to the Deferred.

## deferred.then ( doneCallbacks, failCallbacks ) Returns: Promise version added: 1.5

- doneCallbacks
  Type: Function
  A function, or array of functions, called when the Deferred is resolved.

- failCallbacks
  Type: Function
  A function, or array of functions, called when the Deferred is rejected.

## deferred.then ( doneCallbacks, failCallbacks, progressCallbacks ) Returns: Promise version added: 1.7

- doneCallbacks
  Type: Function
  A function, or array of functions, called when the Deferred is resolved.

- failCallbacks
  Type: Function
  A function, or array of functions, called when the Deferred is rejected.

- progressCallbacks
  Type: Function
  A function, or array of functions, called when the Deferred notifies progress.

Description: Add handlers to be called when the Deferred object is resolved, rejected, or still in progress.

Prior to jQuery 1.8, the arguments could be a function or an array of functions.

For all signatures, the arguments can be `null` if no callback of that type is desired. Alternatively, use `.done()`, `.fail()` or `.progress()` to set only one type of callback without filtering status or values.

As of jQuery 1.8, the `deferred.then()` method returns a new promise that can filter the status and values of a deferred through a function, replacing the now-deprecated `deferred.pipe()` method. The `doneFilter` and `failFilter` functions filter the original deferred's resolved / rejected status and values. The `progressFilter` function filters any calls to the original deferred's `notify` or `notifyWith` methods. These filter functions can return a new value to be passed along to the promise's `.done()` or `.fail()` callbacks, or they can return another observable object (Deferred, Promise, etc) which will pass its resolved / rejected status and values to the promise's callbacks. If the filter function used is `null`, or not specified, the promise will be resolved or rejected with the same values as the original.

Callbacks are executed in the order they were added. Since `deferred.then` returns a Promise, other methods of the Promise object can be chained to this one, including additional `.then()` methods.

## Examples:

#### Example: Since the jQuery.get method returns a jqXHR object, which is derived from a Deferred object, we can attach handlers using the .then method.

    $.get( "test.php" ).then(
      function() {
        alert( "$.get succeeded" );
      }, function() {
        alert( "$.get failed!" );
      }
    );

#### Example: Filter the resolve value:

    <!doctype html>
    <html lang="en">
    <head>
      <meta charset="utf-8">
      <title>css demo</title>

      <script src="//code.jquery.com/jquery-1.10.2.js"></script>
    </head>
    <body>

    <button>Filter Resolve</button>
    <p></p>

    <script>

    var filterResolve = function() {
      var defer = $.Deferred(),
        filtered = defer.then(function( value ) {
          return value * 2;
        });

      defer.resolve( 5 );
      filtered.done(function( value ) {
        $( "p" ).html( "Value is ( 2*5 = ) 10: " + value );
      });
    };

    $( "button" ).on( "click", filterResolve );

    </script>

    </body>
    </html>

#### Demo:

#### Example: Filter reject value:

    var defer = $.Deferred(),
      filtered = defer.then( null, function( value ) {
        return value * 3;
      });

    defer.reject( 6 );
    filtered.fail(function( value ) {
      alert( "Value is ( 3*6 = ) 18: " + value );
    });

#### Example: Chain tasks:

    var request = $.ajax( url, { dataType: "json" } ),
      chained = request.then(function( data ) {
        return $.ajax( url2, { data: { user: data.userId } } );
      });

    chained.done(function( data ) {
      // data retrieved from url2 as provided by the first request
    });