forio Toggle navigation

Channel Manager

There are two main use cases for the channel: event notifications and chat messages.

If you are developing with Epicenter.js, you should use the Epicenter Channel Manager rather than this more generic Channel Manager. (The Epicenter Channel Manager is a wrapper that instantiates a Channel Manager with Epicenter-specific defaults.) The Epicenter Channel Manager documentation also has more background information on channels and their use.

However, you can work directly with the Channel Manager if you like. (This might be useful if you are working through Node.js, for example, require('manager/channel-manager').)

The Channel Manager is a wrapper around the default cometd JavaScript library, $.cometd. It provides a few nice features that $.cometd doesn't, including:

  • Automatic re-subscription to channels if you lose your connection
  • Online / Offline notifications
  • 'Events' for cometd notifications (instead of having to listen on specific meta channels)

You'll need to include the epicenter-multiplayer-dependencies.js library in addition to the epicenter.js library in your project to use the Channel Manager. (See Including Epicenter.js.)

To use the Channel Manager in client-side JavaScript, instantiate the Epicenter Channel Manager, get a particular channel -- that is, an instance of a Channel Service -- then use the channel's subscribe() and publish() methods to subscribe to topics or publish data to topics.

 var cm = new F.manager.ChannelManager();
 var gc = cm.getGroupChannel();
 // because we used an Epicenter Channel Manager to get the group channel,
 // subscribe() and publish() here default to the base topic for the group;
 gc.subscribe('', function(data) { console.log(data); });
 gc.publish('', { message: 'a new message to the group' });

The parameters for instantiating a Channel Manager include:

  • options The options object to configure the Channel Manager. Besides the common options listed here, see http://docs.cometd.org/reference/javascript.html for other supported options.
  • options.url The Cometd endpoint URL.
  • options.websocketEnabled Whether websocket support is active (boolean).
  • options.channel Other defaults to pass on to instances of the underlying Channel Service. See Channel Service for details.

Configuration Options

url

  • string

The Cometd endpoint URL.

logLevel

  • string

The log level for the channel (logs to console).

websocketEnabled

  • boolean

Whether websocket support is active. Defaults to true.

ackEnabled

  • boolean

Whether the ACK extension is enabled. Defaults to true. See https://docs.cometd.org/current/reference/#_extensions_acknowledge for more info.

shareConnection

  • boolean

If false each instance of Channel will have a separate cometd connection to server, which could be noisy. Set to true to re-use the same connection across instances.

channel

  • object

Other defaults to pass on to instances of the underlying Channel Service, which are created through getChannel().

handshake

  • object

Options to pass to the channel handshake.

For example, the Epicenter Channel Manager passes ext and authorization information. More information on possible options is in the details of the underlying Push Channel API.

Methods

getChannel

Creates and returns a channel, that is, an instance of a Channel Service.

Example

 var cm = new F.manager.ChannelManager();
 var channel = cm.getChannel();

 channel.subscribe('topic', callback);
 channel.publish('topic', { myData: 100 });

Parameters

  • options: Object|String (Optional) If string, assumed to be the base channel url. If object, assumed to be configuration options for the constructor.

on

Start listening for events on this instance. Signature is same as for jQuery Events: http://api.jquery.com/on/.

Supported events are: connect, disconnect, subscribe, unsubscribe, publish, error.

Parameters

off

Stop listening for events on this instance. Signature is same as for jQuery Events: http://api.jquery.com/off/.

Parameters

trigger

Trigger events and execute handlers. Signature is same as for jQuery Events: http://api.jquery.com/trigger/.

Parameters