react-frau-events

A React mixin to mix custom event listener/emitter functions on React components.

Installation

Install from NPM:

npm install react-frau-events

Usage

Require the mixin provider:

var Emitter = require('react-frau-events');

The mixin will add an emitEventName function with your component, and all associated handlers (if defined) will be invoked when the event is emitted:

     var Component = React.createClass({
          mixins: [Emitter.ForEvent('customEvent')],
          onCustomEvent: function() {
               ...
          },
          render: function() {
               ...
          }
     });

The event is emitted simply by calling emitEventName on an instance of the component.

     var componentInstance = React.render(
          <Component />,
          node
     );
     componentInstance.emitCustomEvent();

Isolated Component Emitters

By default, the mixin will use a global/shared event emitter, meaning that all component instances using the mixin will share the same emitter, and emitting an event will call the respective handlers on all the components. It is possible to scope the emitter for components when the mixin specified for the component.

For example, the following would provide an EventEmitter for instances of Component, and when the custom event is emitted, only delegates on instances of Component would be called.

     var EventEmitter = require('events').EventEmitter;

     var Component = React.createClass({
          mixins: [Emitter.ForEvent('customEvent', new EventEmitter())],
          ...
     });

Promises

A promise is returned from emitEventName when all of the handlers have completed running. When the promise resolves, the results of the handlers are passed along. This enabled handlers themselves to be asynchronous.

     componentInstance
          .emitCustomEvent()
          .then(function(results) {
               ...
          });

Contributing

Code Style

This repository is configured with EditorConfig rules and contributions should make use of them.