ventage

    2.3.0 • Public • Published

    Ventage

    Ventage is a simple eventing library for JavaScript objects.

    Installation

    Ventage may be installed as a bower package:

    $ bower install ventage
    

    It may also be installed as a CommonJS module:

    $ npm install ventage
    

    In the browser it may be used:

    • as a require.js AMD module
    • as a CommonJS module with Browserify
    • as a direct <script> reference

    Usage

    Creating Ventage objects

    Ventage is designed to be used as a prototype for your custom objects. You can accomplish this in several ways.

    as the prototype to a constructor function

    function View() {
      this.render = function () {
        this.trigger('rendering');
        // other code
        this.trigger('rendered');
      };
    }
     
    View.prototype = new Ventage();

    by setting up the prototype chain manually

    var databaseObject = Object.create(new Ventage());
    databaseObject.connect = function () {
        // connection code
        this.trigger('connected');
      }
    };

    by using the Ventage factory function

    var poll = Ventage.create({
      start: function () {
        var self = this;
        setInterval(function () {
          var result = self.ping('http://localhost');
          self.trigger('polled', result);
        }, 100);
      }
    });

    by instantiating Ventage objects directly

    var v = new Ventage();
    v.on('foo', onFoo);
    v.trigger('foo', 'bar');

    Using Ventage objects

    Client objects can subscribe to events raised by Ventage objects.

    var v = new Ventage();
    v.on('message', function (sender, content) {
      console.log('message from %s: %s', sender, content);
    });
    v.trigger('message', 334455, 'hello, world!');

    subscribing to events

    The on() method accepts three arguments:

    • event name
    • callback function
    • (optional) context object

    If a context argument is passed to the on() method, it will be used as the value of this within the callback function.

    triggering events

    The trigger() method accepts a single event name argument, and a variable number of data arguments that will be passed, in order, to any callback associated with the event.

    By default, trigger() will invoke callbacks synchronously. To change this behavior, you can:

    • pass a boolean value to the Ventage constructor to indicate whether the object should always trigger callbacks asynchronously; or
    • invoke the triggerAsync() method manually when you want callbacks to be called asynchronously

    The triggerAsync() method accepts the same arguments as trigger().

    unsubscribing from events

    To unsubscribe from events, use the off() method. It takes three arguments:

    • (optional) event name
    • (optional) callback reference
    • (optional) context object

    If off() is called with no arguments, it will unsubscribe all callbacks from all events. This has the same effect as calling clear().

    If off() is called with an event name only, it will unsubscribe all callbacks from that event.

    If off() is called with an event name and a callback reference, it will unsubscribe only that callback from the event. If the callback was subscribed with a specific context, it is necessary to provide that context to the off() method to unsubscribe the callback.

    piping events

    Events may be piped from one Ventage instance to another. This means that events triggered on one instance will also be triggered, with the same arguments, on the other.

    var v1 = new Ventage();
    var v2 = new Ventage();
    var callbackHandle = v1.pipe('alert', v2);
    v2.on('alert', function () {
      console.log('Danger, Will Robinson!');
    });
    v1.trigger('alert'); // v2 event will trigger as well
    v1.off('alert', callbackHandle, v2);

    The context for a piped event is always the receiving Ventage object (in the code above, v2).

    The callback handle is returned from pipe() so that it may later be used to unsubscribe from the piped event.

    subscribing to wildcard events

    Currently Ventage supports a single wildcard event, *, which is invoked for any event triggered on a Ventage object.

    var v = new Ventage();
    var count = 0;
    v.on('*', function () {
      count += 1;
    });
    v.trigger('foo');
    v.trigger('bar');
    v.trigger('baz');
    console.log(count); // 3

    License

    MIT License

    Install

    npm i ventage

    DownloadsWeekly Downloads

    0

    Version

    2.3.0

    License

    LICENSE

    Last publish

    Collaborators

    • nicholascloud