README.md in transistor-0.1.5 vs README.md in transistor-0.1.6
- old
+ new
@@ -3,20 +3,60 @@
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 = Transistor.Control(broadcaster_url, station_uid, push_token);
+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
@@ -31,16 +71,16 @@
## 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"
+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 = Transistor.Radio(station_finder_url, station_uid, test_token);
+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
@@ -50,26 +90,19 @@
radio.tune("news", listener);
radio.tune("sports", listener);
```
-Even at this point, no connections where made, the listener structure is 100% passive.
+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:
-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: {..}]}
+// "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}
```
@@ -79,18 +112,72 @@
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
+// radio is already initialized
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.
+
+## 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
+```