Customizing AJAX

A Breeze client makes AJAX calls by means of an AJAX adapter. The default Breeze AJAX adapter wraps the jQuery.ajax method and assumes your client app is running with jQuery.

You can configure that adapter to suit your application needs; it's best to do so when the application starts.

For example, you can set fixed headers for every Breeze AJAX request.

 // get the current default Breeze AJAX adapter
 var ajaxAdapter = breeze.config.getAdapterInstance("ajax");
 // set fixed headers
 ajaxAdapter.defaultSettings = {
       headers: { 
           // any headers that you want to specify.
           "X-Test-Header": "foo2" 
       },
};

You can intercept individual AJAX calls and add your headers selectively, based on the request, by setting up a beforeSend interceptor.

 // get the current default Breeze AJAX adapter
 var ajaxAdapter = breeze.config.getAdapterInstance("ajax");
 // specify a request interception function
 ajaxAdapter.defaultSettings = {
       beforeSend: function(xhr, settings) {
           // examine the XHR and customize the headers accordingly.
           if (isFooRequest(xhr)) {
               xhr.setRequestHeader("x-Test-Before-Send-Header", "foo");
           }
       }
 };

Use the AngularJS $http adapter

Many Angular developers prefer to use Angular's native $http AJAX component; we do.

Breeze v.1.4.4 added an 'angular' ajax adapter that wraps$http. You could designate this as your ajax adapter as follows:

angular.module('app').run(['$http', function($http) {
    // tell the adapter to use your app module's $http for ajax calls
    var ajax = breeze.config.initializeAdapterInstance('ajax', 'angular');
    ajax.setHttp($http);
}]);

However, there's a much better way to prepare Breeze for Angular, a way that not only engages the Breeze 'angular' ajax adapter but also configures Breeze to us Angular $q promises and chooses the best Breeze 'modelLibrary' adapter for data binding with Angular.

It's an Angular module from our own Breeze Labs, the "Breeze Angular Service". You can download it from github or install the package as described here. After installation, you wire it up when your app boots:

angular.module('app', ['breeze.angular'])
       // merely depending on the 'breeze' service configures Breeze for Angular
       .run(['breeze', function() {/* noop - unless you want do do something */}]);

Internally, the "Breeze Angular Service" makes the same call shown above ... as well as other configurations.

Write your own adapter

You can write your own JavaScript AJAX adapter, one that either replaces or extends the default adapter.

An AJAX adapter is a constructor function. Aside from the initialize method common to all Breeze adapters, an AJAX adapter only has one method, ajax.  You typically register the adapter with breeze in the last step of the JavaScript module that defines it. For example:

breeze.config.registerAdapter("ajax", myAjaxAdapter); 

Review the breeze.ajax.jQuery.js plugin in the /Scripts/Adapters directory of the Breeze download for an example.

Then you'd make your adapter the default adapter when the application starts:

breeze.config.initializeAdapterInstance("ajax", "myAjaxAdapter", /*isDefault = */ true);