Angular Bullet

Angular Bullet is an ultra lightweight and simple to use pub-sub library, with AMD/module support and an intuitive API. It was built to facilitate a simple and consistent system of communication across AngularJS applications and includes only the bare essentials typically needed to achieve this. The main advantage of Angular Bullet over using $rootScope is that it has an 'off' method, which removes the need to keep track of and deregister event handlers.

Usage

You can install via npm with the following command in your command prompt:

npm install angular-bullet --save

Or you can install via Bower instead, if that's your thing:

bower install angular-bullet

Otherwise, simply grab the source code from Github.

Include Angular Bullet in your application

If using CommonJS then simply require Angular Bullet as per usual, prior to setting up your AngularJS modules:

require("angular-bullet");

Otherwise use a regular script tag:

<script type="application/javascript" src="path/to/angular-bullet.js"></script>

Then ensure that you include Angular Bullet in your module definition:

var CoolApp = angular.module("CoolApp", ["angular-bullet"]);

You can then inject it where necessary, for example:

CoolApp.controller("MainCtrl", ["angularBullet", MainCtrl]);

function MainCtrl (angularBullet)
{
    angularBullet.trigger("hello");
}

API

.on()

angularBullet.on("someMessageName", callback);

Register a callback function to get called whenever the specified message is triggered.

Example usage:

function helloCallback () {
    console.log("hello there :)");
}
 
// Register the 'helloCallback' function to be called whenever the 'hello' message is triggered:
    
angularBullet.on("hello", helloCallback);
    

// Somewhere later in the application...
    
    
// Trigger the 'hello' message – Angular Bullet will call the 'helloCallback' function:
    
angularBullet.trigger("hello");

.off()

angularBullet.off("someMessageName"[, callback]);

Remove either all callback functions or a specific callback function registered against the specified message.

Example usage:

function helloCallback () {
    console.log("hello there :)");
}

function anotherCallback () {
    console.log("hello again :)");
}


angularBullet.on("hello", helloCallback);
angularBullet.on("hello", anotherCallback);


// Somewhere later in the application...


// Trigger the 'hello' message – Angular Bullet will call both the 'helloCallback' and 'anotherCallback' functions:

angularBullet.trigger("hello");


// Remove all callback functions associated with the 'hello' message:
angularBullet.off("hello");

// Attempt to trigger the 'hello' message again – Angular Bullet won't call any functions:
angularBullet.trigger("hello");

Example usage removing a specific callback:

function helloCallback () {
    console.log("hello there :)");
}

function anotherCallback () {
    console.log("hello again :)");
}


angularBullet.on("hello", helloCallback);
angularBullet.on("hello", anotherCallback);


// Somewhere later in the application...


// Trigger the 'hello' message – Angular Bullet will call both the 'helloCallback' and 'anotherCallback' functions:

angularBullet.trigger("hello");


// Remove only the 'anotherCallback' function associated with the 'hello' message:
angularBullet.off("hello", anotherCallback);

// Trigger the 'hello' message again – Angular Bullet will only call the 'helloCallback' function:
angularBullet.trigger("hello");

.once()

angularBullet.once("someMessageName", callback);

This function behaves in the same way as the the 'on' function, except that – once registered – the callback function will only be called a single time when the specified message is triggered.

Example usage:

function helloCallback () {
    console.log("hello there :)");
}


// Register the 'helloCallback' function to be called whenever the 'hello' message is triggered:

angularBullet.once("hello", helloCallback);


// Somewhere later in the application...


// Trigger the 'hello' message – Angular Bullet will call the 'helloCallback' function:

angularBullet.trigger("hello");


// Attempt to trigger the 'hello' message again – Angular Bullet won't call any functions this time:

angularBullet.trigger("hello");

.trigger()

angularBullet.trigger("someMessageName"[, data]);

This function will call all callback functions registered against the specified message, optionally passing in custom data as a payload.

Example usage:

function helloCallback () {
    console.log("hello there :)");
}


// Register the 'helloCallback' function to be called whenever the 'hello' message is triggered:

angularBullet.on("hello", helloCallback);


// Somewhere later in the application...


// Trigger the 'hello' message – Angular Bullet will call the 'helloCallback' function:

angularBullet.trigger("hello");

Example usage with custom data:

function userAddedCallback (data) {
    console.log(data);
}


// Register the 'userAddedCallback' function to be called whenever the 'user-added' message is triggered:

angularBullet.on("user-added", userAddedCallback);


// Somewhere later in the application...


// Create some custom data:

var customData = {
    someProp : "bro",
    someOtherProp : "awesome!"
};


// Trigger the 'user-added' message – Angular Bullet will call the 'helloCallback' function and
// pass in the custom data that you created, which will be sent to the function as a parameter:

angularBullet.trigger("user-added", customData);

Important!

Make sure that you use the 'off' method to de-register any listeners when AngularJS sends a '$destroy' event to a $scope, otherwise Angular Bullet could keep a reference to functions that no longer need to exist, potentially creating a memory leak.

An easy way to do this is to listen for the '$destroy' event and act on it accordingly:

function UserLoginViewController ($scope, angularBullet)
{
    angularBullet.on("someEventName", functionA);
    angularBullet.on("anotherEventName", functionB);

    $scope.$on("$destroy", destroyHandler);

    function functionA ()
    {
        // code...
    }

    function functionB ()
    {
        // code...
    }

    function destroyHandler ()
    {
        angularBullet.off("someEventName", functionA);
        angularBullet.off("anotherEventName", functionB);
    }
}

About the Project

Angular Bullet was developed and is currently maintained by Ivan Hayes.

Head over to the Github project page to find out more. Go ahead and star the project to keep up with its latest developments :-)