react-event-observer
An event manager in ReactJs, to handle communication between components.
Using observers as a message-broker between components.
Or you can use it for a general purpose event system.
npm install --save react-event-observer
Features
- PubSub
- request-response
- namespacing
What is this:
- General javascript Event System.
- inter-component communication channel for ReactJs.
You can think of it as a network between components.
What This is not:
- client-server communication library
- client-client communication library
Why?
Because passing down methods to child components cluters your code.
and monolithic..
Initialize
;var observer = ;
Methods: PubSub
/* subscribe to event will return a 'Listener' Read about Listener below*/ var listener = observer; /* publish event */observer;// data is: 10 /* unsub */observer;
Listener
A Listener
is an object returned from subscribing to and event.
It will notify succeed
and error
of your function call. it alse has an unpublish
method, so you can unpublish your function from the observer.
listener listener // unsubscribe from event// for this particular functionlistener
Methods: request-response
/* prepare to respond to answer */observer; /* ask the question */observer;// Three is a number /* stop responding to questions */observer;
Usage Example
Include react-event-observer in your Parent Component
;
Initialize in parent
Initialize in Parent constructor, and pass down to child components
{ superprops; thisobserver = ; } ... { <div> <AppChild observer=thisobserver /> <AppChild observer=thisobserver /> <AppChildCounter observer=thisobserver /> </div> }
Subscribe / publish events
In Child Components, start listening to events on mount. Don't forget to unsubscribe on unmount.
AppChild
{ superprops; thisobserver = propsobserver; } { thisobserver; thisobserver; // you can return promise, for async calls // (everything with `.then` and `.catch`) thisobserver; // so, async is supported thisobserver; } { thisobserver; } ...
AppChildCounter
is where we will publish event or ask questions.
AppChildCounter
{ superprops; thisobserver = propsobserver; thisstate = attending : 0; } { thisobserver; thisobserver; } ...
Check the result in your console
Console
=======
hello event data: this is data
hello event data: this is data
...
attending: 1
attending: 2
attending: 3
attending: 4
...
Feature: event-namespace
The dot (.
) is used as a namespace separator.
observer;observer;observer; /* all child and grandchild will be called on parent invocation */observer;// main// main.child// main.child.child observer;// main.child// main.child.child /* the same goes for unsubscribe method */observer;observer;// main
Full Reference
Observer
Observer
is a multipurpose event system.
constructor
var observer = Observer()
Methods
observer.subscribe( String: event, Function: callback )
Alias: observer.on
Return: Listener
object
Subscribe to an event. The callback will receive data.
observer.unsubscribe( String: event, [Listener: listener] )
Alias: observer.off
Unsubscribe to an event. The absence of listener will delete all listener associated with the event.
observer.publish( String: event, [Mixed: data] )
Alias: observer.trigger
observer.emit
Publish data on an event. Data will be passed to all listener's function as a parameter.
observer.request( String: event, [Function: callback] )
Alias: observer.ask
Ask for data. This is a one time event, so it will be unregistered upon callback succession. When no responder available, callback will never be called.
observer.respond( String: event, [Function: callback] )
Alias: observer.answer
Respond to a request
. Unlike request
, respond
will always listen to event. You can think of it as a subscriber that gives data.
To respond to a request, you should return a value, or a promise.
observer observer
observer.silence( String: event )
Alias: observer.leave
Stop responding to requests.
observer.getEvents( String: event )
Get events. children will be included in the result
observer.getAllEvents( String: event )
Get All events.
observer.getListeners( String: event )
Get All listeners. Events will be evaluated with strict values. children will not be included.
Listener
Listener
is on object returned from subscribing on an event. It is used to catch errors and successions of the callback function. It also used to unsubscribe by calling unsubscribe
method, or passing it to the second parameter of observer.unsubscribe
.
Methods
listener.on( String: event, Function: callback )
This will register callback to events such ass error
and succeed
.
listener.unsubscribe()
Alias: listener.off
Unsubscribe this listener from it's event. Other way to unsubscribe is by passing this listener to observer.unsubscribe
var listener1 = observervar listener2 = observer // unsubscribelistener1; // also unsubscribeobserver
Events
Listener
have events. You can register callback to listen to those using listener.on
method.
Event | Description |
---|---|
error | Will be fired when the callback has errors. This is the only way we can catch errors, since the callback will be called asynchronously. The error object will be passed to function registered to this event |
succeed | Will be called upon sucessfull callback execution. It carries no data |
That's it.
cheers, him@jujiyangasli.com