angular-actioncable

An Angular 1.x service for seamlessly integrating Rails 5 (ActionCable) into frontend Angular code. This service opens and maintains a websocket connection between Angular and ActionCable, reconnecting & resubscribing when the connection has been lost, and desynchronising the clients from one another to ease server-side events like code deploys or server restarts.

  

Usage

How to add this to your project

• Use bower and run bower install angular-actioncable --save (preferred)
• Use npm and run npm install angular-actioncable --save
• Download it manually
• CDN for development https://rawgit.com/angular-actioncable/angular-actioncable/1.3.0/dist/angular-actioncable.js
• CDN for production https://cdn.rawgit.com/angular-actioncable/angular-actioncable/1.3.0/dist/angular-actioncable.min.js

The One-Liner. (not recommended, but possible)

  <%= action_cable_meta_tag %>
  <script src="http://ajax.googleapis.com/ajax/libs/angularjs/1.5.3/angular.min.js"></script> 
  <script src="bower_components/angular-websocket/dist/angular-websocket.min.js"></script> 
  <script src="bower_components/angular-actioncable/dist/angular-actioncable.js"></script> 
  <section ng-controller="SomeController">
    <ul>
      <li ng-repeat="datum in myData">
        {{ datum }}
      </li>
    </ul>
  </section>
  <script>
    angular.module('YOUR_APP', [
      'ngActionCable'
    ])
    .controller('SomeController', function ($scope, ActionCableChannel){
      $scope.myData = [];
 
      // connect to ActionCable
      (new ActionCableChannel("MyChannel")).subscribe(function(message){ $scope.myData.push(message) });
 
    });
  </script> 

A better way

  <meta name="action-cable-url" content="ws://localhost:3000/cable"/>
  <script src="http://ajax.googleapis.com/ajax/libs/angularjs/1.5.3/angular.min.js"></script> 
  <script src="bower_components/angular-websocket/dist/angular-websocket.min.js"></script> 
  <script src="bower_components/angular-actioncable/dist/angular-actioncable.js"></script> 
  <section ng-controller="SomeController">
    <ul>
      <li ng-repeat="datum in myData">
        {{ datum }}
      </li>
    </ul>
    <input ng-model="inputText" /><button ng-click="sendToMyChannel(inputText)">Send</button>
  </section>
  <script>
    angular.module('YOUR_APP', [
      'ngActionCable'
    ])
    .controller('SomeController', function ($scope, ActionCableChannel){
      $scope.inputText = "";
      $scope.myData = [];
 
      // connect to ActionCable
      var consumer = new ActionCableChannel("MyChannel", {user: 42, chat: 37});
      var callback = function(message){ $scope.myData.push(message); };
      consumer.subscribe(callback).then(function(){
        $scope.sendToMyChannel = function(message){ consumer.send(message, 'send_a_message'); };
        $scope.$on("$destroy", function(){
          consumer.unsubscribe().then(function(){ $scope.sendToMyChannel = undefined; });
        });
      });
 
    });
  </script> 

class MyChannel < ApplicationCable::Channel
  # ... 
  def send_a_message(message)
    # ... 
  end
end

Support

Supports:

• Rails 5.0

Examples

• Demo project with Rails 5 backend and Angular frontend from Neil-Ni
• Example frontend

API

Factory: ActionCableChannel

constructor function

Methods

name	arguments	description
new	channelName:String channelParams:Hash:optional returns instance	Creates and opens an ActionCableChannel instance. var consumer = new ActionCableChannel('MyChannel', {widget_id: 17});
subscribe	callback:Function returns promise	Subscribes a callback function to the channel. consumer.subscribe(function(message){ $scope.thing = message });
unsubscribe	returns promise	Unsubscribes the callback function from the channel. consumer.unsubscribe();
send	message:String action:String:optional returns promise	Send a message to an action in Rails. The action is the method name in Ruby. consumer.send('message');
onConfirmSubscription	callback:Function	Call each time server registers a subscription. consumer.onConfirmSubscription(function(){ console.log('subscribed'); });

Factory: ActionCableSocketWrangler

singleton

Methods

name	arguments	description
start		Starts ngActionCable services. ActionCableSocketWrangler.start(); This will start by default unless disabled.
stop		Stops ngActionCable services. ActionCableSocketWrangler.stop();

Properties

Exactly one will be true at all times.

name	type	description
connected	Property:Boolean	ngActionCable is started and connected live. ActionCableSocketWrangler.connected;
connecting	Property:Boolean	ngActionCable is started and trying to establish a connection. ActionCableSocketWrangler.connecting;
disconnected	Property:Boolean	ngActionCable is stopped and not connected. ActionCableSocketWrangler.disconnected;

Configuration: ActionCableConfig

value

Properties

You can override the defaults.

name	type	description
wsUri	String	URI to connect ngActionCable to ActionCable. If this is inside a Rails view, it will be read from the action_cable_meta_tag but can still be overridden.
protocols	Array	Specify protocol headers for the websocket connection. Empty by default.
autoStart	Boolean	Connect automatically? Default is true. ActionCableConfig.autoStart= false;
debug	Boolean	Show verbose logs. Default is false. ActionCableConfig.debug= true;

my_app.run(function (ActionCableConfig){
  ActionCableConfig.wsUri= "wss://example.com/cable";
  ActionCableConfig.protocols = ['soap', 'wamp'];
  ActionCableConfig.autoStart= false;
});

Frequently Asked Questions

• Q.: What if the browser doesn't support WebSockets?
• A.: This module depends on angular-websocket which will not help; it does not have a fallback story for browsers that do not support WebSockets. Please check your browser target support.

Is it any good?

Yes

License

MIT

Development

Setup development