Examples

Few examples on how to use Signals for custom event dispatching, check the documentation for a a full reference of available methods and properties.

Setup code (required for all examples)

  //store local reference for brevity
  var Signal = signals.Signal;
  
  //custom object that dispatch signals
  var myObject = {
    started : new Signal(), //past tense is the recommended signal naming convention
    stopped : new Signal()
  };

Basic

Single Listener

  function onStarted(param1, param2){
    alert(param1 + param2);
  }
  myObject.started.add(onStarted); //add listener
  myObject.started.dispatch('foo', 'bar'); //dispatch signal passing custom parameters
  myObject.started.remove(onStarted); //remove a single listener

Multiple Listeners

  function onStopped(){
    alert('stopped');
  }
  function onStopped2(){
    alert('stopped listener 2');
  }
  myObject.stopped.add(onStopped);
  myObject.stopped.add(onStopped2);
  myObject.stopped.dispatch();
  myObject.stopped.removeAll(); //remove all listeners of the `stopped` signal

Multiple Dispatchs

  var i = 0;
  myObject.started.add(function(){
    i += 1;
    alert(i);
  });
  myObject.started.dispatch(); //will alert 1
  myObject.started.dispatch(); //will alert 2

Multiple Dispatchs + addOnce()

  var i = 0;
  myObject.started.addOnce(function(){
    i += 1;
    alert(i);
  });
  myObject.started.dispatch(); //will alert 1
  myObject.started.dispatch(); //nothing happens

Enable/Disable Signal

  var i = 0;
  myObject.started.add(function(){
    i += 1;
    alert(i);
  });
  myObject.started.dispatch(); //will alert 1
  myObject.started.disable();
  myObject.started.dispatch(); //nothing happens
  myObject.started.enable();
  myObject.started.dispatch(); //will alert 2

Stop/Halt Propagation (method 1)

  myObject.started.add(function(){
    myObject.started.halt(); //prevent next listeners on the queue from being executed
  });
  myObject.started.add(function(){
    alert('second listener'); //won't be called since first listener stops propagation
  });
  myObject.started.dispatch();

Stop/Halt Propagation (method 2)

  myObject.started.add(function(){
    return false; //if handler returns `false` will also stop propagation
  });
  myObject.started.add(function(){
    alert('second listener'); //won't be called since first listener stops propagation
  });
  myObject.started.dispatch();

Set execution context of the listener handler

  var foo = 'bar';
  var obj = {
    foo : 10
  };
  
  function handler1(){
    alert(this.foo);
  }
  function handler2(){
    alert(this.foo);
  }
  //note that you cannot add the same handler twice to the same signal without removing it first
  myObject.started.add(handler1); //default execution context
  myObject.started.add(handler2, obj); //set a different execution context
  myObject.started.dispatch(); //first handler will alert "bar", second will alert "10".

Advanced

Enable/Disable a single SignalBinding

  var handler1 = function(){
    alert('foo bar');
  };
  var handler2 = function(){
    alert('lorem ipsum');
  };
  var binding1 = myObject.started.add(handler1); //methods `add()` and `addOnce()` returns a SignalBinding object
  myObject.started.add(handler2);
  myObject.started.dispatch(); //will alert "foo bar" than "lorem ipsum"
  binding1.disable(); //disable a single binding
  myObject.started.dispatch(); //will alert "lorem ipsum"
  alert(binding1.isEnabled()); //will alert "false"
  binding1.enable();
  myObject.started.dispatch(); //will alert "foo bar" than "lorem ipsum"

Manually execute a signal handler

  var handler = function(){
    alert('foo bar');
  };
  var binding = myObject.started.add(handler); //methods `add()` and `addOnce()` returns a SignalBinding object
  binding.execute(); //will alert "foo bar"

Retrieve a signal handler from binding

  var binding = myObject.started.add(function(){
    alert('foo bar');
  });
  var handler = binding.listener; //reference to the anonimous function

Check if binding will execute only once

  var binding1 = myObject.started.add(function(){
    alert('foo bar');
  });
  var binding2 = myObject.started.addOnce(function(){
    alert('foo bar');
  });
  alert(binding1.isOnce()); //alert "false"
  alert(binding2.isOnce()); //alert "true"

Change listener execution context on-the-fly

  var foo = 'bar';
  var obj = {
    foo : "it's over 9000!"
  };
  var binding = myObject.started.add(function(){
    alert(this.foo);
  });
  myObject.started.dispatch(); //will alert "bar"
  binding.listenerScope = obj;
  myObject.started.dispatch(); //will alert "it's over 9000!"

Back to Home