In 99% of use cases your tabs are on the same domain. Then tabex use is very
simple:
// Do it in every browser tab, and clients become magically connected// to common broadcast bus :)var live = window.tabex.client();live.on('channel.name', function handler(message) { // Do something});// Broadcast message to subscribed clients in all tabs, except self.live.emit('channel.name2', message);// Broadcast message to subscribed clients in all tabs, including self.live.emit('channel.name2', message, true);
Client
tabex.client(options)
Fabric to create messaging interface. For single domain you don't need any
options, and everything will be initialized automatically. For cross-domain
communication you will have to create html file with router for iframe, loaded
from shared domain.
Options:
iframe (String) - url of iframe source with router (on shared domain).
Optional.
namespace (String) - optional, for mad case when you need muiltiple
isolated tabex instances in parallel.
client.on(channel, handler)
Subscribe to channel. Chainable.
channel (String) - name of channel to subscribe.
handler (Function) - function (data, channel) { ... }.
client.off(channel [, handler])
Unsubscribe handler from channel. Chainable. If handler not specified -
unsubscribe all handlers from given channel.
client.emit(channel, message [, toSelf])
Send message to all tabs in specified channel. By default messages are
broadcasted to all clients except current one. To include existing client -
set toSelf to true.
client.lock(id, [timeout, ] fn):
id - lock identifier
timeout - optional, lock lifetime in ms, default 5000
fn(unlock) - handler will be executed if lock is acquired
unlock - function to release acquired lock
Note. Getting lock takes 30ms when localStorage used as events transport.
client.filterIn(fn), client.filterOut(fn)
Add transformers for incoming (handled) and outgoing (emitted) messages.
Chainable. This is a very powerful feature, allowing tabex customization. You
can morph data as you wish when it pass client pipeline from one end to another.
fn(channel, message, callback) - filter function.
channel - channel name.
message - wrapped event data (see below).
callback(channel, message) - function to return output data.
Filter message structure:
id - unique message id, <node_id>_<msg_counter>. Consists or unique
client instance id (random) and message ccounter (inremented for each
new message)
node_id - id message emitter source (client or router), random string.
data - message data, passed to client.emit().
Use case examples:
faye does not allow . in channel names. You can add filters
for transparent replace of . with !!.
you can drop and generate internal events to implement new features like locks
or remote function calls.
Router
Direct access to router is needed only for cross-domain communication (with
iframe). For single domain tabex client will create local router automatically.
tabex.router(options)
Fabric to create router in iframe. Options:
origin (Array|String) - list of valid origins, allowed to communicate with
this iframe. If nothing set, then iframe domain will be used.
namespace - the same as in tabex.client.
Example.
In your code:
var live = window.tabex.client({ iframe: 'https://shared.yourdomain.com/tabex_iframe.html'});
Warning! Never set * to allowed origins value. That's not secure.
Advanced use
System events
Channels !sys.* are reserved for internal needs and extensions. Also tabex
already has built-in events, emitted on some state changes:
!sys.channels.refresh - emitted when list of subscribed channels changed
(or in specific case, when master tab switched). Message data:
channels - array of all channels subscribed in all tabs
!sys.channels.add - emitted by tabex.client to notify router about new
subscribed channel. Message data:
channel - channel name
!sys.channels.remove - emitted by tabex.client to notify router that all
subscriptions to channel gone. Message data:
channel - channel name
!sys.lock.request - emitted by tabex.client to try acquire lock. Message data:
id - lock identifier
timeout - lock lifetime in ms
!sys.lock.acquired - emitted when router acquire lock for client
request_id - request message id
!sys.lock.release - emitted by tabex.client to release already acquired
lock. Message data:
id - lock identifier
!sys.error - emitted on internal errors, for debug.
!sys.master - sepecific for localStorage-based router. Message data:
node_id - id of "local" router node
master_id - id of node that become master
Note.!sys.master event is broadcasted only when localStorage router
used. You should NOT rely on it in your general application logic. Use locks
instead to filter single handler on broadcasts.
Sharing single server connection (faye)
Example below shows how to extend tabex to share single faye connection
between all open tab. We will create faye instances it all tabs, but activate
only one in "master" tab.
User can close tab with active server connection. When this happens, new master
will be elected and new faye instance will be activated.
We also do "transparent" subscribe to faye channels when user subscribes with
tabex client. Since user can wish to do local broadcasts too, strict separation
required for "local" and "remote". We do it with addind "remote.*" prefix for
channels which require server subscribtions.
Note. If you don't need cross-domain features - drop iframe-related options
and code.
// This one is for your application.//var live = window.tabex({ iframe: 'https://shared.yourdomain.com/tabex_iframe.html'});// Faye will work via separate interface. Second interface instance will// reuse the same router automatically. Always use separate interface for// different bus build blocks to properly track message sources in filters.//// Note, you can attach faye in iframe, but it's more convenient to keep// iframe source simple. `tabex` is isomorphic, and faye code location does// not make sense.//var flive = window.tabex({ iframe: 'https://shared.yourdomain.com/tabex_iframe.html'});var fayeClient = null;var trackedChannels = {};// Connect to messaging server when become master and