The Callbacks Object JQ Home  <<  JQ Advanced  <<  The Callbacks Object

In this lesson we investigate the jQuery Callbacks object and how to utilize it for use in our webpages.

Using callback methods it becomes easy to create detailed lists of callbacks which we can pass arguments to for processing.

  • Internally the jQuery.Callbacks() function is used to provide the base functionality for the jQuery.ajax() method and the Deferred object.
  • The jQuery.Callbacks() method can be also be utilized in a similar way to define functionality for new components.
  • The default behaviour of a callbacks lists is the same as an event callback list and so the list can be 'fired' multiple times. This default behaviour can be modified using the optional 'flags' parameter when creating the list.

Creating Callbacks Objects

Callbacks objects can be created using the new special operator with the jQuery.Callbacks() constructor or by using the jQuery.Callbacks() constructor alone, which is the way we will create Callbacks objects for this lesson.

Examples of both methods of instantiation are shown below:


// With the new special operator
var callbacksObj = new jQuery.Callbacks();

// Without the new special operator
var callbacksObj = jQuery.Callbacks();

Callbacks Object Methods

Callbacks Object Methods Description
jQuery.Callbacks()Callbacks list object constructor for managing callback lists.
callbacks.add()Add callback(s) to a callback list.
callbacks.disable()Disable callback list.
callbacks.empty()Empty a callback list.
callbacks.fire()Invoke the callback list with the specified arguments.
callbacks.fired()Determine whether the callback list has already been invoked.
callbacks.fireWith()Invoke the callback list with the specified context and arguments.
callbacks.has()Determine whether the callback list contains the specified callback.
callbacks.lock()Lock a callback list.
callbacks.locked()Determine whether the callback list is in a locked state.
callbacks.remove()Remove callback(s) from a callback list.

The jQuery.Callbacks() Method Top

jQuery.Callbacks( [flags] ) - callbacks list object for managing callback lists, optionally behavioured using flags.

In the example below when we press the button the first time we add the aFunc(value, div) and bFunc(value, div) functions to our callbacks list and fire them off.

For examples of flag use with this method see the reference section for jQuery.Callbacks( once ), jQuery.Callbacks( memory ), jQuery.Callbacks( stopOnFalse ) and jQuery.Callbacks( unique ).


$(function(){
  $('#btn1').one('click', function(){
    var ourCallbacks = $.Callbacks();
    ourCallbacks.add( aFunc );
    ourCallbacks.fire( 'The aFunc function was fired from our callbacks. <br>', '#div1');
    ourCallbacks.add( bFunc );
    ourCallbacks.fire( 'The bFunc function was fired from our callbacks. <br>', '#div1');
  });
  function aFunc( value, div ){
    $(div).append( value);
  }
  function bFunc( value, div ){
    aFunc('Passing bFunc function value to aFunc. <br>', div);
  }
});

div1. Some initial text.

Press the button below to action the above code:

The callbacks.add() and callbacks.fire() Methods Top

callbacks.add( callbacks ) - Add callback(s) to a callback list.

callbacks.fire( arguments ) - Invoke the callback list with the specified arguments.

In the example below when we press the button the first time, we add the aFunc(value, div) and bFunc(value, div) functions to our callbacks list and fire them off.


$(function(){
  $('#btn6').one('click', function(){
    var ourCallbacks = $.Callbacks();
    ourCallbacks.add( aFunc );
    ourCallbacks.fire( 'The aFunc function was fired from our callbacks. <br>', '#div6');
    ourCallbacks.add( bFunc );
    ourCallbacks.fire( 'The bFunc function was fired from our callbacks. <br>', '#div6');
  });
  function aFunc( value, div ){
    $(div).append( value);
  }
  function bFunc( value, div ){
    aFunc('Passing bFunc function value to aFunc. <br>', div);
  }
});

div6. Some initial text.

Press the button below to action the above code:

The callbacks.disable() Method Top

Disable a callback list.

In the example below when we press the button the first time, we add the aFunc(value, div) function to our callbacks list and then fire the list off. After this we disable the list and then try to add and fire the bFunc(value, div) function. Because the callback list is now disabled nothing happens.


$(function(){
  $('#btn7').one('click', function(){
    var ourCallbacks = $.Callbacks();
    ourCallbacks.add( aFunc );
    ourCallbacks.fire( 'The aFunc function was fired from our callbacks. <br>', '#div7');
    ourCallbacks.disable();
    ourCallbacks.add( bFunc );
    ourCallbacks.fire( 'The bFunc function was fired from our callbacks. <br>', '#div7');
  });
  function aFunc( value, div ){
    $(div).append( value);
  }
  function bFunc( value, div ){
    aFunc('Passing bFunc function value to aFunc. <br>', div);
  }
});

div7. Some initial text.

Press the button below to action the above code:

The callbacks.empty() Method Top

Empty a callback list.

In the example below when we press the button the first time, we add the aFunc(value, div) and the bFunc(value, div) functions to our callbacks list. After this we empty the list and then try to fire the callbacks list. Because the callback list has been emptied nothing happens.


$(function(){
  $('#btn8').one('click', function(){
    var ourCallbacks = $.Callbacks();
    ourCallbacks.add( aFunc );
    ourCallbacks.add( bFunc );
    ourCallbacks.empty();
    ourCallbacks.fire( 'The aFunc function was fired from our callbacks. <br>', '#div8');
    ourCallbacks.fire( 'The bFunc function was fired from our callbacks. <br>', '#div8');
  });
  function aFunc( value, div ){
    $(div).append( value);
  }
  function bFunc( value, div ){
    aFunc('Passing bFunc function value to aFunc. <br>', div);
  }
});

div8. Some initial text.

Press the button below to action the above code:

The callbacks.fired() Method Top

Determine whether the callback list has already been invoked.

In the example below when we press the button the first time, we add the aFunc(value, div) and bFunc(value, div) functions to our callbacks lists. We then alert whether they have been fired, fire them off, and then test again whether they have been fired.


$(function(){
  $('#btn9').one('click', function(){
    var ourCallbacks = $.Callbacks();
    ourCallbacks.add( aFunc );
    ourCallbacks.add( bFunc );
    $('#div9').append( 'Have callbacks been fired? ' + ourCallbacks.fired() + '<br>');
    ourCallbacks.fire( 'The aFunc function was fired from our callbacks. <br>', '#div9');
    ourCallbacks.fire( 'The bFunc function was fired from our callbacks. <br>', '#div9');
    $('#div9').append( 'Have callbacks been fired? ' + ourCallbacks.fired() + '<br>');
  });
  function aFunc( value, div ){
    $(div).append( value);
  }
  function bFunc( value, div ){
    aFunc('Passing bFunc function value to aFunc. <br>', div);
  }
});

div9. Some initial text.

Press the button below to action the above code:

The callbacks.fireWith() Method Top

callbacks.fireWith([context] [, arguments]) - Invoke the callback list with the specified context and arguments.

In the example below when we press the button the first time, we add the aFunc(value, div) and bFunc(value, div) functions to our callbacks list and fire them off with a context and array of arguments.


$(function(){
  $('#btn14').one('click', function(){
    var ourCallbacks = $.Callbacks();
    ourCallbacks.add( aFunc );
    ourCallbacks.add( bFunc );
    ourCallbacks.fireWith( window, ['Callbacks list called from the callbacks.fireWith()
                                     method. <br>','#div14']);
  });
  function aFunc( value, div ){
    $(div).append( value);
  }
  function bFunc( value, div ){
    aFunc('Passing bFunc function value to aFunc. <br>', div);
  }
});

div14. Some initial text.

Press the button below to action the above code:

The callbacks.has() and callbacks.remove() Methods Top

callbacks.has( callback ) - Determine whether the callback list contains the specified callback.

callbacks.remove( callback ) - Remove callback(s) from a callback list.

In the example below when we press the button the first time, we add the aFunc function and fire this off. We then add and remove the bFunc function from our callbacks list. We then use the callbacks.has() method to see if the aFunc and bFunc functions exist in the callback list and output a message for each function.


$(function(){
  $('#btn13').one('click', function(){
    var ourCallbacks = $.Callbacks();
    ourCallbacks.add( aFunc );
    ourCallbacks.fire( 'The aFunc function was fired from our callbacks. <br>', '#div13');
    ourCallbacks.add( bFunc );
    ourCallbacks.remove( bFunc );
    $('#div13').append( 'Callbacks list contains aFunc? ' + ourCallbacks.has(aFunc) + '<br>');
    $('#div13').append( 'Callbacks list contains bFunc? ' + ourCallbacks.has(bFunc) + '<br>');
  });
  function aFunc( value, div ){
    $(div).append( value);
  }
  function bFunc( value, div ){
    aFunc('Passing bFunc function value to aFunc. <br>', div);
  }
});

div13. Some initial text.

Press the button below to action the above code:

The callbacks.lock() and callbacks.locked() Methods Top

callbacks.lock() - Lock a callback list.

callbacks.locked() - Determine whether the callback list is in a locked state.

In the example below when we press the button the first time, we add the aFunc(value, div) function to our callbacks list and then fire the list off. We then check to see if the callbacks list has been locked using the callbacks.locked() method, which returns false. After this we lock the list and then try to add and fire the bFunc(value, div) function. Because the callback list is now locked nothing happens. We then check to see if the callbacks list has been locked using the callbacks.locked() method, which now returns true.


$(function(){
  $('#btn12').one('click', function(){
    var ourCallbacks = $.Callbacks();
    ourCallbacks.add( aFunc );
    ourCallbacks.fire( 'The aFunc function was fired from our callbacks. <br>', '#div12');
    $('#div12').append( 'Has callbacks list been locked? ' + ourCallbacks.locked() + '<br>');
    ourCallbacks.lock();
    ourCallbacks.add( bFunc );
    ourCallbacks.fire( 'The bFunc function was fired from our callbacks. <br>', '#div12');
    $('#div12').append( 'Has callbacks list been locked? ' + ourCallbacks.locked()  + '<br>');
  });
  function aFunc( value, div ){
    $(div).append( value);
  }
  function bFunc( value, div ){
    aFunc('Passing bFunc function value to aFunc. <br>', div);
  }
});

div12. Some initial text.

Press the button below to action the above code:

Using The Callbacks Object In A Publisher / Subscriber Scenario.

The Observer pattern, also known as the Publisher / Subscriber (pub/sub) pattern is the promotion of loose coupling in applications and defines a one-to-many relationship between a set of objects. Therefore when the state of the Observed object (Publisher) changes, the Observer objects (Subscribers) are notified.

Following is an implementation of a Pub / Sub system using only callback lists, using the $.Callbacks object as a topics queue.


$(function(){
  $('#btn15').one('click', function(){
    // Call this anonymous function passing (jQuery)
    (function($) {
      var topics = {};
      $.Topic = function( id ) {
        var ourCallback,
            topic = id && topics[ id ];
        if ( !topic ) {
            ourCallback = $.Callbacks();
            topic = {
               subscribe: ourCallback.add,
               publish: ourCallback.fire,
               unsubscribe: ourCallback.remove
            };
            if ( id ) {
                topics[ id ] = topic;
            }
        }
        return topic;
      };
    })(jQuery);
    // Subscribers
    $.Topic( 'Tottenham' ).subscribe( div1 );
    $.Topic( 'Millwall' ).subscribe( div2 );
    $.Topic( 'West Ham' ).subscribe( div1 );
    $.Topic( 'Birmingham' ).subscribe( div2 );
    // Publisher
    $.Topic( 'Tottenham' ).publish( 'Tottenham playing' );
    $.Topic( 'West Ham' ).publish( 'West Ham playing' );
    $.Topic( 'Birmingham' ).publish( 'Birmingham playing' );
    $.Topic( 'Millwall' ).publish( 'Millwall playing' );
    $.Topic( 'West Ham' ).publish( 'West Ham ended!' );
    $.Topic( 'Millwall' ).publish( 'Millwall ended!' );
    $.Topic( 'Birmingham' ).publish( 'Birmingham ended!' );
    $.Topic( 'Tottenham' ).publish( 'Tottenham ended!' );
  });

  function div1(value){
    $('#div15').append( value + '<br>');
  }
  function div2(value){
    $('#div16').append( value + '<br>');
  }
});

div15. Some initial text.

div16. Some initial text.

Press the button below to action the above code:

Lesson 6 Complete

In this lesson we looked at the the Callbacks object.

Reference

Methods

Events - .one() method
Manipulation - .append() method
Callbacks Object - jQuery.Callbacks() method
Callbacks Object - callbacks.add() method
Callbacks Object - callbacks.disable() method
Callbacks Object - callbacks.empty() method
Callbacks Object - callbacks.fire() method
Callbacks Object - callbacks.fired() method
Callbacks Object - callbacks.fireWith() method
Callbacks Object - callbacks.has() method
Callbacks Object - callbacks.lock() method
Callbacks Object - callbacks.locked() method
Callbacks Object - callbacks.remove() method