Implements the Observer Pattern for use in Redux applications, enabling Event Dispatchers/Listeners between any classes connected to the store.
Note: While the name "React" is part of the name, React is not required to use this package and it will work with any Redux application.
npm install --save react-redux-events
React-Redux Events (RRE) allows parts of an application using Redux to subscribe/dispatch to events. This is useful when you want to pass messages between parts of the application in a decoupled one-to-many manner, but don't need to store the change in the state of the application.
Any situation where decoupled one-to-many event dispatching without storing it in state is useful. For example:
- Using a centralized tracking module, and dispatching tracking events from components.
- Using a centralized data fetching/sending module.
React-Redux Events (RRE) implements the Observer Pattern.
In this implementation, Listeners
subscribe to Events
, which can be Dispatched
from anywhere in the application.
Base Flow:
- A component signals interest in a specific
Event Type
, by registering aListener
method for that event. - React-Redux Events stores the interest for that Event type.
- Sometime later, somewhere else in the application, an Event of that type is
Dispatched
. - RRE looks up all the stored interested listeners for that event type, and calls the listener method with the event data.
- When the component unmounts or is no longer interested in the event type, it signals RRE to remove the listener.
- redux@>=3.1.0
- react@>=16.0.0 (if you want to use with React)
npm install --save react-redux-events
First, let's define some Event Types:
// Events.js
export const VIEWER_EVENT = 'VIEWER_EVENT';
export const TRACKING_EVENT = 'TRACKING_EVENT';
Then to enable React-Redux Events, register the RRE reducer along with your other reducers, and make sure the react-redux Provider wraps your app:
// Index.js
import React from 'react';
import ReactDOM from 'react-dom';
import { createStore, combineReducers } from 'redux';
import { Provider } from 'react-redux';
import { reduxEventReducer } from 'react-redux-events';
// Example: The Button Component dispatches events
import Button from './Button';
// Example: The EventViewer Component listens for events and prints them
import EventViewer from './EventViewer';
// Example: Initialize Analytics non-react class (see below)
import Analytics from './Analytics';
// Add the reactReduxEventReducer reducer
const store = createStore(
combineReducers({ reactReduxEvents: reduxEventReducer })
);
new Analytics(store);
ReactDOM.render(
<Provider store={store}>
<div>
<Button />
<EventViewer />
</div>
</Provider>,
document.body);
That's it. Now you can use the react-redux connect
method to tie add/remove listener actions to your components:
// EventViewer.js
import React, { Component } from 'react';
import { connect } from 'react-redux'
import { addEventListener } from 'react-redux-events';
import { TRACKING_EVENT, VIEWER_EVENT } from './Events';
const mapProps = state => ({});
const mapDispatch = dispatch => ({
addEventListener: (event, context, handler, priority) => dispatch(addEventListener(event, context, handler, priority))
});
class EventViewer extends Component {
constructor(props) {
super(props)
this.props.addEventListener(TRACKING_EVENT, this, this.onEvent);
this.props.addEventListener(VIEWER_EVENT, this, this.onEvent);
this.eventList = []
}
onEvent(event) {
this.eventList.push(event);
this.forceUpdate();
}
render() {
return (
<ul>
{this.eventList.map((event,i) => <li key={i}>{event.payload.date}: {event.type}</li>)}
</ul>
);
}
}
const connectedEventViewer = connect(mapProps, mapDispatch)(EventViewer)
export default connectedEventViewer;
Likewise, you use the react-redux connect
method to enable dispatching events:
// Button.js
import React, { Component } from 'react';
import { connect } from 'react-redux'
import { ReduxEvent, dispatchEvent } from 'react-redux-events';
import { TRACKING_EVENT, VIEWER_EVENT } from './Events';
const mapProps = state => ({});
const mapDispatch = dispatch => ({
dispatchEvent: (event) => dispatch(dispatchEvent(event))
});
class Button extends Component {
dispatchEvent1() {
// Create a new ReduxEvent and set the optional payload object
let event = new ReduxEvent(TRACKING_EVENT, { date: Date.now() });
// Dispatch the event to listeners around the app
this.props.dispatchEvent(event);
}
dispatchEvent2() {
let event = new ReduxEvent(VIEWER_EVENT, { date: Date.now() });
this.props.dispatchEvent(event);
}
render() {
return (
<div>
<button onClick={this.dispatchEvent1.bind(this)}>Dispatch Tracking Event!</button>
<button onClick={this.dispatchEvent2.bind(this)}>Dispatch Viewer Event!</button>
</div>
);
}
}
const connectedButton = connect(mapProps, mapDispatch)(Button)
export default connectedButton;
You can also add listeners / dispatchers to a non-react class:
// Analytics.js
import { addEventListener } from 'react-redux-events';
import { TRACKING_EVENT } from './Events';
export default class Analytics {
constructor(store) {
// We need a reference to the store to dispatch addEventListener methods
this.store = store;
this.registerListeners();
}
registerListeners() {
// Register the listener in the store
this.store.dispatch(addEventListener(TRACKING_EVENT, this, this.onEvent));
}
onEvent(event) {
console.log('Received event:', event.type, event.payload);
}
}
When a component is unmounted or in general no longer wishes to receive events it has added listeners to, remember to removeEventListener
each of those events. Otherwise you will have listeners firing on components that have already been removed from the app.
These are the dispatchable methods available:
This method registers an event listener for the specific event type
with the event handler
method.
The optional priority
value sets the priority level. Event listeners with higher priority levels get handled before listeners with lower levels.
type
(String) This is the type of the Eventcontext
(Object) This is the context where the handler will be called.handler
(Method) This is the handler that is called when the event is triggered. The handler is passed an object with the following structure:
{
type: 'EVENT_TYPE', // String
payload: {}, // Object
priority: 0 // Int
}
[Optional] priority
(Integer) The priority handling level of this listener. A higher number is handled before lower numbers on the same event. Default value = 0.
registerListeners() {
// Register the listener in the store
this.store.dispatch(addEventListener('EVENT_TYPE', this, this.onEvent.bind(this)));
this.store.dispatch(addEventListener('EVENT_TYPE', this, this.onPriorityEvent.bind(this), 2));
}
// Both of these listeners will be called when an event with the type 'EVENT_TYPE' is dispatched
onEvent(event) {
console.log('Received event:');
console.log('Event type:', event.type);
console.log('Event payload:', event.payload);
console.log('Event priority:', event.priority);
}
// Will be called first
onPriorityEvent(event) {
console.log('Received priority event:');
console.log('Priority Event type:', event.type);
console.log('Priority Event payload:', event.payload);
console.log('EPriority vent priority:', event.priority);
}
This method removes a event listener for the specific event type
and the specified handler
method.
type
(String) This is the type of the Event that was registeredcontext
(Object) This is the context where the handler was registered.handler
(Method) This is the handler that was registered
componentWillUnmount() {
// Unregister the listener from the store
this.store.dispatch(removeEventListener('EVENT_TYPE', this.onEvent.bind(this)));
}
This method dispatched an event.
The optional payload
value allows including a POJO (Plain Old Javascrip Object) payload that will be passed to the event handlers.
The optional priority
value sets the priority level. Note! See below for details.
type
(String) This is the type of the Event[Optional] payload
(Object) A Plain Old Javascript Object that is passed to the event listeners asevent.payload
. Default value ={}
.[Optional] priority
(Integer) The priority handling level of this event. Default = 0- Note! If this value is set, only listeners with priority level matching or higher are called.
onClick() {
// Register the listener in the store
this.store.dispatch(dispatchEvent('EVENT_TYPE'));
this.store.dispatch(dispatchEvent('EVENT_TYPE', { data: 'something' }));
this.store.dispatch(dispatchEvent('EVENT_TYPE', { data: 'something' }, 2));
}
This method removes all event listeners for the specified context
.
context
(object) This is the context you want to remove listeners from
componentWillUnmount() {
// Unregister the listener from the store
this.store.dispatch(removeAllListenersForContext(this));
}
This method removes all event listener for the specified event type
.
type
(String) This is the type of the Event that was registered
componentWillUnmount() {
// Unregister the listener from the store
this.store.dispatch(removeAllListenersForEvent('EVENT_TYPE'));
}
This method sets the console logging level for the event handling.
Level | Details |
---|---|
0 | No logging, except Errors. |
1 | Warnings and Errors |
2 | All |
level
(Integer) This is the desired logging level. Default 0.
componentDidMount() {
// Unregister the listener from the store
this.store.dispatch(setLogLevel(2));
}
MIT