channel-manager | Documentation

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' });

Constructor options

Required?	Name	Type	Description
Yes	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`, uses long-polling if false
	ackEnabled	`boolean`	Whether the ACK extension is enabled. Defaults to `true`. See https://docs.cometd.org/current/reference/#extensionsacknowledge 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 (default) 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([options])

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

Parameters

Required?	Name	Type	Description
	options	`Object / String`	If string, assumed to be the base channel url. If object, assumed to be configuration options for the constructor.

Returns

Channel - Channel instance

Example

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

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

on(event)

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

Required?	Name	Type	Description
Yes	event	`string`	The event type. See more detail at jQuery Events: http://api.jquery.com/on/.

off(event)

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

Parameters

Required?	Name	Type	Description
Yes	event	`string`	The event type. See more detail at jQuery Events: http://api.jquery.com/off/.

trigger(event)

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

Parameters

Required?	Name	Type	Description
Yes	event	`string`	The event type. See more detail at jQuery Events: http://api.jquery.com/trigger/.

getChannel
on
off
trigger