@opuscapita/react-signalr

OpusCapita react signalr

Stats

StarsIssuesVersionUpdatedCreatedSize
@opuscapita/react-signalr
1813.3.03 years ago3 years agoMinified + gzip package size for @opuscapita/react-signalr in KB

Readme

react-signalr

Description

Higher-Order Component that provides a connection to a SignalR hub. This component adds a hub proxy, that may be used to register and unregister event listeners, and also to invoke a hub controller and send data to it.

This component is built using the SignalR JavaScript client of the ASP.NET Core 2.1 Signalr product.

Installation

npm install @opuscapita/react-signalr --save

Builds

UMD

The default build with compiled styles in the .js file. Also minified version available in the lib/umd directory.

CommonJS/ES Module

You need to configure your module loader to use cjs or es fields of the package.json to use these module types. Also you need to configure sass loader, since all the styles are in sass format.

API

Options for injectSignalR

Option Type Default Description
hubName string required Name of the signalr hub
baseAddress string | func required Base address for signalr server
accessToken string | func Access token for authorization on the server
signalrPath string 'signalr' Path to signalr hubs
controller string <hubName> Name of the controller (if different from hubName)
retries integer 3 Number of retries to connect after a failure

Methods in hub proxy

Method Parameters Description
invoke(target, query) target: string, query: string Invokes hub controller with GET
send(target, payload) target: string, payload: object Invokes hub controller with POST
register(event, listener) event: string, listener: func Registers a listener for an event
unregister(event, listener) event: string, listener: func Unregisters a listener for an event
add(group) group: string Adds client to a named group1)
remove(group) group: string Removes client from a named group1)

1) To be able to use group messaging the SignalR hub must implement two methods, AddToGroup(string group) and RemoveFromGroup(string group), which respectively add and remove the client to and from the specified named group (cf. code example).

Code example

Injecting signalr HOC to a component

As a HOC
import React from 'react';
import { injectSignalR, hubShape } from '@opuscapita/react-signalr';

class MyComponent extends React.Component {
  // ... 
}

MyComponent.propTypes = {
  // PropType for the hub proxy.
  mynotifier: hubShape,
};

export default injectSignalR({
  // Defines both the last part of the route to the hub,
  // and also the key of the hub proxy in this.props.
  // In this case it hub proxy is found in this.props.mynotifier.
  hubName: 'mynotifier',
  // Either 1) a string containing the server url, or 
  // 2) a function getting the server url from the state (example).
  baseAddress: (state) => state.configuration.server,
  // 1) A string containing the access token, or 
  // 2) a function getting the access token from the state (example), or
  // 3) a function using the state to return a function that 
  // gets the access token.
  accessToken: (state) => state.configuration.accessToken,
})(MyComponent);
As a decorator
import React from 'react';
import { injectSignalR, hubShape } from '@opuscapita/react-signalr';

@injectSignalR({
  hubName: 'mynotifier',
  baseAddress: (state) => state.configuration.server,
  accessToken: (state) => state.configuration.accessToken,
})
export default class MyComponent extends React.Component {
  // ... 
}

MyComponent.propTypes = {
  // PropType for the hub proxy.
  mynotifier: hubShape,
};

Passing the hub proxy to child component(s)

class MyComponent extends React.Component {

  // ... 

  render() {
    // Passing the hub proxy from this.props to child component(s) allows
    // also the child component(s) to register its (their) own listeners.
    const { ...passThroughProps } = this.props;
    return (<ChildComponent
      {...passThroughProps} />);
  }
}

Registering and unregistering listeners

class MyComponent extends React.Component {

  // ...

  // Listeners may be registered in componentDidMount (recommended).
  componentDidMount() {
    // Hub proxy is found in this.props.
    const { mynotifier } = this.props;
    if (mynotifier) {
      // Register this.onInserted to listen 'inserted' event.
      mynotifier.register('inserted', this.onInserted);
      // Register this.onUpdated to listen 'updated' event.
      mynotifier.register('updated', this.onUpdated);
    }
  }

  // Listeners may be unregistered in componentWillUnmount (recommended).
  componentWillUnmount() {
    const { mynotifier } = this.props;
    if (mynotifier) {
      // Unregister this.onInserted from listening to 'inserted' event.
      mynotifier.unregister('inserted', this.onInserted);
      // Unregister this.onUpdated from listening to 'updated' event.
      mynotifier.unregister('updated', this.onUpdated);
    }
  }

  // Parameter list should match the response sent from the server.
  onInserted = (target, id) => {
    // Handle inserted event ...
  }

  onUpdated = (target, id) =>  {
    // Handle updated event ...
  }

  // ...
}

Invoking controller or sending data to it

class MyComponent extends React.Component {

  // ...

  invoke() {
    // Requests '<baseAddress>/<controller>/target/123' with GET
    this.props.mynotifier.invoke('target', 123);
  }

  send(data) {
    // Requests '<baseAddress>/<controller>/target' with POST 
    // and the JS object `data` as payload in JSON format
    this.props.mynotifier.send('target', data);
  }

  // ...
}

Adding/removing the client to/from a named group

The SignalR hub
public class MyNotifier : Hub
{
    // ...

    public Task AddToGroup(string group)
        => Groups.AddToGroupAsync(group);

    public Task RemoveFromGroup(string group)
        => Groups.RemoveFromGroupAsync(group);

    // ...
}
The client component
class MyComponent extends React.Component {

  // ...

  add(group) {
    this.props.mynotifier.add(group);
  }

  remove(group) {
    this.props.mynotifier.remove(group);
  }

  // ...
}

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.