Add back `ajax.transport` support

This adds back the `ajax.transport` option, which allows anyone to
use their own AJAX backend. By default, `jQuery.ajax` is used as the
default transport backend.

**Breaking change:** Instead of taking `params` that contains a
`success` and `error` keys for the callback, two new callback
parameters are passed alongside of `params` that should be called
when the request succeeds or fails.

This closes https://github.com/select2/select2/issues/2987.

dist/js/select2.amd.full.js

@@ -2652,7 +2652,7 @@ define('select2/data/ajax',[
   'jquery'
 ], function (ArrayAdapter, Utils, $) {
   function AjaxAdapter ($element, options) {
-    this.ajaxOptions = options.get('ajax');
+    this.ajaxOptions = this._applyDefaults(options.get('ajax'));
 
     if (this.ajaxOptions.processResults != null) {
       this.processResults = this.ajaxOptions.processResults;
@@ -2663,6 +2663,26 @@ define('select2/data/ajax',[
 
   Utils.Extend(AjaxAdapter, ArrayAdapter);
 
+  AjaxAdapter.prototype._applyDefaults = function (options) {
+    var defaults = {
+      data: function (params) {
+        return {
+          q: params.term
+        };
+      },
+      transport: function (params, success, failure) {
+        var $request = $.ajax(params);
+
+        $request.then(success);
+        $request.fail(failure);
+
+        return $request;
+      }
+    };
+
+    return $.extend({}, defaults, options, true);
+  };
+
   AjaxAdapter.prototype.processResults = function (results) {
     return results;
   };
@@ -2689,9 +2709,7 @@ define('select2/data/ajax',[
     }
 
     function request () {
-      var $request = $.ajax(options);
-
-      $request.success(function (data) {
+      var $request = options.transport(options, function (data) {
         var results = self.processResults(data, params);
 
         if (console && console.error) {
@@ -2705,6 +2723,8 @@ define('select2/data/ajax',[
         }
 
         callback(results);
+      }, function () {
+        // TODO: Handle AJAX errors
       });
 
       self._request = $request;

dist/js/select2.amd.js

@@ -2652,7 +2652,7 @@ define('select2/data/ajax',[
   'jquery'
 ], function (ArrayAdapter, Utils, $) {
   function AjaxAdapter ($element, options) {
-    this.ajaxOptions = options.get('ajax');
+    this.ajaxOptions = this._applyDefaults(options.get('ajax'));
 
     if (this.ajaxOptions.processResults != null) {
       this.processResults = this.ajaxOptions.processResults;
@@ -2663,6 +2663,26 @@ define('select2/data/ajax',[
 
   Utils.Extend(AjaxAdapter, ArrayAdapter);
 
+  AjaxAdapter.prototype._applyDefaults = function (options) {
+    var defaults = {
+      data: function (params) {
+        return {
+          q: params.term
+        };
+      },
+      transport: function (params, success, failure) {
+        var $request = $.ajax(params);
+
+        $request.then(success);
+        $request.fail(failure);
+
+        return $request;
+      }
+    };
+
+    return $.extend({}, defaults, options, true);
+  };
+
   AjaxAdapter.prototype.processResults = function (results) {
     return results;
   };
@@ -2689,9 +2709,7 @@ define('select2/data/ajax',[
     }
 
     function request () {
-      var $request = $.ajax(options);
-
-      $request.success(function (data) {
+      var $request = options.transport(options, function (data) {
         var results = self.processResults(data, params);
 
         if (console && console.error) {
@@ -2705,6 +2723,8 @@ define('select2/data/ajax',[
         }
 
         callback(results);
+      }, function () {
+        // TODO: Handle AJAX errors
       });
 
       self._request = $request;

dist/js/select2.full.js

@@ -3090,7 +3090,7 @@ define('select2/data/ajax',[
   'jquery'
 ], function (ArrayAdapter, Utils, $) {
   function AjaxAdapter ($element, options) {
-    this.ajaxOptions = options.get('ajax');
+    this.ajaxOptions = this._applyDefaults(options.get('ajax'));
 
     if (this.ajaxOptions.processResults != null) {
       this.processResults = this.ajaxOptions.processResults;
@@ -3101,6 +3101,26 @@ define('select2/data/ajax',[
 
   Utils.Extend(AjaxAdapter, ArrayAdapter);
 
+  AjaxAdapter.prototype._applyDefaults = function (options) {
+    var defaults = {
+      data: function (params) {
+        return {
+          q: params.term
+        };
+      },
+      transport: function (params, success, failure) {
+        var $request = $.ajax(params);
+
+        $request.then(success);
+        $request.fail(failure);
+
+        return $request;
+      }
+    };
+
+    return $.extend({}, defaults, options, true);
+  };
+
   AjaxAdapter.prototype.processResults = function (results) {
     return results;
   };
@@ -3127,9 +3147,7 @@ define('select2/data/ajax',[
     }
 
     function request () {
-      var $request = $.ajax(options);
-
-      $request.success(function (data) {
+      var $request = options.transport(options, function (data) {
         var results = self.processResults(data, params);
 
         if (console && console.error) {
@@ -3143,6 +3161,8 @@ define('select2/data/ajax',[
         }
 
         callback(results);
+      }, function () {
+        // TODO: Handle AJAX errors
       });
 
       self._request = $request;

dist/js/select2.js

@@ -3090,7 +3090,7 @@ define('select2/data/ajax',[
   'jquery'
 ], function (ArrayAdapter, Utils, $) {
   function AjaxAdapter ($element, options) {
-    this.ajaxOptions = options.get('ajax');
+    this.ajaxOptions = this._applyDefaults(options.get('ajax'));
 
     if (this.ajaxOptions.processResults != null) {
       this.processResults = this.ajaxOptions.processResults;
@@ -3101,6 +3101,26 @@ define('select2/data/ajax',[
 
   Utils.Extend(AjaxAdapter, ArrayAdapter);
 
+  AjaxAdapter.prototype._applyDefaults = function (options) {
+    var defaults = {
+      data: function (params) {
+        return {
+          q: params.term
+        };
+      },
+      transport: function (params, success, failure) {
+        var $request = $.ajax(params);
+
+        $request.then(success);
+        $request.fail(failure);
+
+        return $request;
+      }
+    };
+
+    return $.extend({}, defaults, options, true);
+  };
+
   AjaxAdapter.prototype.processResults = function (results) {
     return results;
   };
@@ -3127,9 +3147,7 @@ define('select2/data/ajax',[
     }
 
     function request () {
-      var $request = $.ajax(options);
-
-      $request.success(function (data) {
+      var $request = options.transport(options, function (data) {
         var results = self.processResults(data, params);
 
         if (console && console.error) {
@@ -3143,6 +3161,8 @@ define('select2/data/ajax',[
         }
 
         callback(results);
+      }, function () {
+        // TODO: Handle AJAX errors
       });
 
       self._request = $request;

docs/options.html

@@ -88,12 +88,12 @@ $("select").select2({
     </p>
 
 <pre class="prettyprint linenums">
-  $("select").select2({
-    ajax: {
-      url: "http://example.org/api/test",
-      cache: "true"
-    }
-  });
+$("select").select2({
+  ajax: {
+    url: "http://example.org/api/test",
+    cache: "true"
+  }
+});
 </pre>
 
     <p>
@@ -562,6 +562,25 @@ ajax: {
     return {
       results: data
     };
+  },
+  // You can use a custom AJAX transport function if you do not want to use the
+  // default one provided by jQuery.
+  //
+  // @param params The object containing the parameters used to generate the
+  //   request.
+  // @param success A callback function that takes `data`, the results from the
+  //   request.
+  // @param failure A callback function that indicates that the request could
+  //   not be completed.
+  // @returns An object that has an `abort` function that can be called to abort
+  //   the request if needed.
+  transport: function (params, success, failure) {
+    var $request = $.ajax(params);
+
+    $request.then(success);
+    $request.fail(failure);
+
+    return $request;
   }
 }
 </pre>

src/js/select2/data/ajax.js

@@ -4,7 +4,7 @@ define([
   'jquery'
 ], function (ArrayAdapter, Utils, $) {
   function AjaxAdapter ($element, options) {
-    this.ajaxOptions = options.get('ajax');
+    this.ajaxOptions = this._applyDefaults(options.get('ajax'));
 
     if (this.ajaxOptions.processResults != null) {
       this.processResults = this.ajaxOptions.processResults;
@@ -15,6 +15,26 @@ define([
 
   Utils.Extend(AjaxAdapter, ArrayAdapter);
 
+  AjaxAdapter.prototype._applyDefaults = function (options) {
+    var defaults = {
+      data: function (params) {
+        return {
+          q: params.term
+        };
+      },
+      transport: function (params, success, failure) {
+        var $request = $.ajax(params);
+
+        $request.then(success);
+        $request.fail(failure);
+
+        return $request;
+      }
+    };
+
+    return $.extend({}, defaults, options, true);
+  };
+
   AjaxAdapter.prototype.processResults = function (results) {
     return results;
   };
@@ -41,9 +61,7 @@ define([
     }
 
     function request () {
-      var $request = $.ajax(options);
-
-      $request.success(function (data) {
+      var $request = options.transport(options, function (data) {
         var results = self.processResults(data, params);
 
         if (console && console.error) {
@@ -57,6 +75,8 @@ define([
         }
 
         callback(results);
+      }, function () {
+        // TODO: Handle AJAX errors
       });
 
       self._request = $request;