# 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:

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

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

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

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

```javascript
// 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):

```javascript
//= 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:

```javascript
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:

```javascript
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:

```javascript
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:

```javascript
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:

```javascript
// 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:

```javascript
// 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:


```javascript
// 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:


```javascript
// radio is already initialized
// control is also initialized

var collection = Transistor.Backbone.Collection({
  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.


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

// after request roundtrip

collection.length == 1 //=> true
```