# Radiotower Client

The javascript client consists mainly of two parts:

* Transistor.Control
* Transistor.Radio

## 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 = 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 station_finder_url  = "http://station_finder.radiotower.io",
    station_uid         = "5a665bf153c0437bdb14a3004dad52e1",
    test_token          = "d10cf06ecd08ff5bc0df1c8bb84d1107"
    // or use the live_token, if it's a production application

var radio = Transistor.Radio(station_finder_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);
```

Even at this point, no connections where made, the listener structure is 100% passive.

To get things startet, you have to turn on the Radio (sounds pretty clear, eh?).

This will fire a request to the StationFinder like: "Hey, here I am, at which frequency can I get my channels, and what is their current state??"

```javascript
radio.turnOn();
```

From now on, 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",    {collection: [{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 but not turned on yet

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

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

radio.turnOn();
```

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.