summaryrefslogtreecommitdiffstats
path: root/README.md
diff options
context:
space:
mode:
authorLoïc Hoguin <[email protected]>2011-12-26 09:36:52 +0100
committerLoïc Hoguin <[email protected]>2011-12-26 09:36:52 +0100
commit76cae7b2268edec9a3c6cb5b0830d3fb5a1220f2 (patch)
tree991d4fe8590dfa014bc0a53bc34f5c89832e1f04 /README.md
parentaff844b94ae2cbf9ab9fc7cf662bc468a6c2f0ce (diff)
downloadbullet-76cae7b2268edec9a3c6cb5b0830d3fb5a1220f2.tar.gz
bullet-76cae7b2268edec9a3c6cb5b0830d3fb5a1220f2.tar.bz2
bullet-76cae7b2268edec9a3c6cb5b0830d3fb5a1220f2.zip
Explain Bullet usage thoroughly in the README
Diffstat (limited to 'README.md')
-rw-r--r--README.md98
1 files changed, 98 insertions, 0 deletions
diff --git a/README.md b/README.md
index 1060899..93e2070 100644
--- a/README.md
+++ b/README.md
@@ -9,3 +9,101 @@ Bullet defines a common interface both client and server-side to
facilitate the handling of such connections. Bullet also takes care
of reconnecting automatically when the connection is lost, and of
the optional heartbeat managed client-side.
+
+Today Bullet only supports websocket and long-polling transports.
+
+Cowboy handler
+--------------
+
+Similar to websocket handlers, you need to define 4 functions.
+A very simple bullet handler would look like the following:
+
+``` erlang
+-module(stream_handler).
+-export([init/4, stream/3, info/3, terminate/2]).
+
+init(_Transport, Req, _Opts, _Active) ->
+ {ok, Req, undefined_state}.
+
+stream(Data, Req, State) ->
+ {reply, Data, Req, State}.
+
+info(_Info, Req, State) ->
+ {ok, Req, State}.
+
+terminate(_Req, _State) ->
+ ok.
+```
+
+Of note is that the init/4 and terminate/2 functions are called
+everytime a connection is made or closed, respectively, which can
+happen many times over the course of a bullet connection's life,
+as Bullet will reconnect everytime it detects a disconnection.
+
+Note that you do not need to handle a heartbeat server-side, it
+is automatically done when needed by the Bullet client as explained
+later in this document.
+
+You might have noticed the odd Active argument to init/4. It
+indicates what type of connection we have. When Active == false,
+we have a temporary connection that only allows one reply before
+terminating. When Active == true, the connection allows any number
+of replies. You can use this information to inform your session
+process that it should send only 1 message, in the case of
+Active == false, or that it can send messages whenever in the
+case of Active == true.
+
+You would typically use init/4 to inform your session process
+that it can send you messages. In the same manner you can use
+terminate/2 to inform it that the connection is going down.
+
+Bullet handlers should only contain transport related code,
+logic should be done in your session process if any, or other
+parts of your application. Bullet processes should be considered
+temporary as you never know when a connection is going to close
+and therefore lose your State.
+
+Client-side javascript
+----------------------
+
+Bullet requires the jQuery library to be used. Initializing a
+bullet connection is quite simple and can be done directly from
+a document.ready function like this:
+
+``` js
+$(document).ready(function(){
+ var bullet = $.bullet(stream);
+ bullet.onopen = function(){
+ console.log('WebSocket: opened');
+ };
+ bullet.onclose = function(){
+ console.log('WebSocket: closed');
+ };
+ bullet.onmessage = function(e){
+ alert(e.data);
+ };
+ bullet.onheartbeat = function(){
+ bullet.send('ping');
+ }
+});
+```
+
+Bullet works especially well when it is used to send JSON data
+formatted with the jQuery JSON plugin.
+
+``` js
+bullet.send($.toJSON({type: 'event', data: 'hats!'}));
+```
+
+When receiving JSON you would typically receive a list of events,
+in which case your onmessage handler can look like this, assuming
+you previously defined a handlers function array for all your events:
+
+``` js
+ bullet.onmessage = function(e){
+ var obj = $.parseJSON(e.data);
+ for (i = 0; i < obj.length; i++){
+ handlers[obj[i].type](obj[i]);
+ }
+ };
+```