Radiotower Client

The javascript client consists mainly of two parts:

  • Transistor.Control
  • Transistor.Radio

And optional Extensions:

  • Transistor.Backbone - Transparent Backbone.Collection using.

Using the library

Rails:

If you wan't to use only the Radio and the Array-Binder:

// dependencies are already included (faye-browser.js)
//= require transistor-radio

If you only wan't to use the control-interface:

// dependencies are already included (JSONP.js)
//= require transistor-control

If you are interested in using both, just require the base file:

// dependencies are already included (JSONP.js, faye-browser.js)
//= require transistor

For using the Backbone extensions, require the following file after transistor.js, backbone.js and underscore.js (they are obviously not included):

//= require transistor
//   or
//= require transistor-radio

//= require transistor-backbone

Control

The Control object is used for administrative work on a station. It is initialized as following:

var broadcaster_url = "http://broadcast.radiotower.io",
    station_uid = "5a665bf153c0437bdb14a3004dad52e1",
    push_token  = "e29c6c92143cfaa0d5026aebf87f1a0f";

var control = new Transistor.Control(broadcaster_url, station_uid, push_token);

The main purpose of the Control object is the administration of specific channels. It supports the following basic collection operations:

control.set("channel/path", [{value: 'collection'}, {value: 'of'}, {value: 'entries'}]);
control.insert("channel/path", {value: 'object that gets pushed'});
control.update("channel/path", 12, {value: 'i am the new object w/ id 12'});
control.remove("channel/path", 23); // object w/ id 23 gets removed

The actual ids of an specific entry are retrieved through the client, which usage gets explained in the following chapter.

Radio

The Radio object can be used --- as the name might suggest --- for listening to specific channels of a station of the Radiotower. It is initialized as following:

var aerial_url    = "http://aerial.radiotower.io",
    station_uid   = "5a665bf153c0437bdb14a3004dad52e1",
    test_token    = "d10cf06ecd08ff5bc0df1c8bb84d1107"
    // or use the live_token, if it's a production application

var radio = new Transistor.Radio(aerial_url, station_uid, test_token);

Now the basic Radio is initialized. No network connections or requests are done so far. On a second step, you have to tune your radio to all the channels, you want to listen to:

var listener = function (event, args) {
  console.log("Event '"+event+"' occured with args", arg);
};

radio.tune("news", listener);
radio.tune("sports", listener);

This will cause the listeners to fire an init event with the current collection as args. After that, your listener will fire, whenever an specific event occures.\ Below is a listing of the possible events and their respective arguments:

// These are the arguments of the called listener (event, args)

// "init",    [{id: 12, object: {..}}, {id: 13, object: {..}]
// "set",     {collection: [{id: 12, object: {..}}, {id: 13, object: {..}]}
// "insert",  {entry: {id: 24, object: {..}}}
// "update",  {id: 13, entry: {id: 13, object: {..}}}
// "remove",  {id: 13}

Binders

To simplify the binding between a remote Radiotower collection and your local array, Transistor gives you a nifty little tool called Binder.

Mainly, it implements a simple and thin listener which keeps track of changes and updates an array accordingly. Use it this way:

// radio is already initialized

var news        = [],
    news_binder = Transistor.Binder(news);

radio.tune("the/news", news_binder);

From now on, your local array news is an exact copy of the collection in the channel "the/news". Radio and Binder are there for you, they talk and sync and you have nothing to worry about at all while using your local array.

But keep in mind, that changes on the array itself will bring most likely inconsitencies in your data. All updates, inserts, a.s.o. MUST bew made through the Control object.

Transistor.Backbone

Readonly Collection (e.g. on some client)

Transistor.Backbone gives a simple constructor for an extended Backbone collection. For a general read-only-collection, you can use it as follow:

// radio is already initialized

var collection = new Transistor.Backbone.Collection({
  channel: 'the/news',
  radio: radio
});

The collection is a real Backbone.Collection instance that is auto-synced with the remote radiotower collection.

In contrast to the array-binder, all writing functions (add, set, reset, remove) of this collection are deactivated and throw an error in invocation.

Read-Write Collection (e.g. in the admin interface)

The Backbone.Collection has the ability, to sync writing calls with the radiotower collection. To enable this feature, a control instance must be passed to the Collection in creation:

// radio is already initialized
// control is also initialized

var collection = Transistor.Backbone.Collection({
  backbone: Backbone,
  channel: 'the/news',
  radio: radio,
  control: control
});

Now, the writing-functions of this collection aren't deactivated. Instead, they dispatch to the given control instance. So, if you add an entry into the collection, it is not immediatly updated. The add gets propagated to radiotower first. After this request hit the tower, it distributes the change, which triggers the add event on your local collection.

collection.add({my: 'entry'})

// after request roundtrip

collection.length == 1 //=> true