A framework for WebSocket application
JavaScript CSS
Switch branches/tags
Nothing to show
Clone or download
Pull request Compare This branch is 3 commits ahead of shunjikonishi:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
assets
dist
src
test
.gitignore
Gruntfile.js
Procfile
README.md
README_ja.md
bower.json
index.html
package.json

README.md

Roomframework

Roomframework is an application framework for SPA(Single Page Application).
The core feature is WebSocket wrapper.
It is easy to combine with other frameworks.

Features

  • WebSocket(room.connection.js)
    • WebSocket wrapper
    • Manage reconnection
    • Manage authenticate token
    • Request handling like ajax
    • Register message handlers
  • Cache(room.cache.js)
    • WebStorage wrapper
  • Logger(room.logger.js)
    • WebSocketLogger

To use WebSocket related features, you should use server side implementation for it. There is an implementation for Playframework.(roomframework-play)

Files

  • src/room.*.js
  • dist/room.*.min.js
  • dist/roomframework[.min].js

All features are included in roomframework[.min].js.
If you want to use WebSocket related features only, you can use room.connection[.min].js.

Getting started

Create room.Connection instance with ws(s) URL.
And send message by request method.

You can specify success and error callback like jQuery#ajax.
Also, you can register callback by on method.

var ws = new room.Connection("ws://room-sandbox.herokuapp.com/gettingstarted");
ws.on("chat", function(data) {
	console.log("EventHandler: " + data);
});
ws.request({
	command: "chat",
	data: "Hello world!",
	success: function(data) {
		console.log("Call and response: " + data);
	},
});
ws.request({
	command: "chat",
	data: "Hello world again!"
});

room-sandbox.herokuapp.com is an echo WebSocket server.
You will get following result by running above script.

Call and response: Hello world!
EventHandler: Hello world again!

The response of first request is processed by success callback.
The second response is processed by the event handler which was registered with 'on' method.
Because the second request didn't specify success callback.

Message structure

This framework defines send and receive message format.

You don't need to aware of send message format. Because it is automatically generated by request method.

If you shall implement server side message, you must implement with following format.

Request message format

{
  "id" : number,       //Message number. Added by request method.
  "command" : string,  //Command name
  "data" : any json    //Any data
}

Response message format

{
  "id" : number,       //Message number of the corresponding request.(Optional)
  "command" : string,  //Command name
  "type" : string,     //json, html, text, or error. errot type is processed as error.
  "data" : any json    //Any data
}

Constructor's option

The parameter of constructor is URL string of ws(s) protocol.
Or, you can speicify the hash with other options. Optional parameter name and its default values are follows.

Paramter Default Description
url Required URL of ws(s)
maxRetry 5 The number of retry, when disconnected.
retryInterval 1000 The interval of retry(ms). Retry interval is increased with this value.
logger null The object of output debug log. You can use console object.
authToken null If specified, this token is send by authCommand after connecting.
authCommand room.auth If authToken is specified, it is sent with this command name.
authError null The callback function for authCommand error.
Its parameter is response data.
onOpen null The callback function for WebSocket#onopen.
Its parameter is event object.
onClose null The callback function for WebSocket#onclose.
Its parameter is event object.
onMessage null The callback function for WebSocket#onmessage.
Its parameter is event object.
onSocketError null The callback function for WebSocket#onerror.
Its parameter is event object.
onRequest null The callback function for executing request method.
Its parameters are command name and data.
onServerError null The common callback function for error response.
Its parameter is response data.

Methods

request(params): void

  • params: object

Send a request. Params can include followings.

Key Type Description
command string Command name. Required.
data any Sending data. Any Json.
success function The callback for success response.Its parameter is response data.
error function The callback for error response. Its parameter is response data.

If you don't specify success or error, the response will be processed with an event handler that registered by on method.
If event handler isn't registered, the error response will be processed by common error handler that registered by onServerError method.

on(name, successFunc[, errorFunc]): this

  • name: Command name
  • successFunc: The callback for success message. Its parameter is response data.
  • errorFunc: The callback for error message. Its parameter is response data. (Optional)

Register the event handlers for server messages.

off(name): this

  • name: Command name

Unregister the event handler.

isConnected(): boolean

Return the WebSocket is connecting, or not.

close(): void

Close WebSocket.

sendNoop(interval[, sendIfHidden][, commandName]): int

  • interval: Interval(ms)
  • sendIfHidden: Send message when the browser is inactive. Default is false.
  • commandName: Command name. Default is 'noop'.

Send a noop message on regular basis.
You can cancel it by using clearInterval method with the return value of this method.

onOpen(func): this

  • func: Callback function. Its parameter is event object.

Specify the callback function for WebSocket#onopen.

onClose(func): this

  • func: Callback function. Its parameter is event object.

Specify the callback function for WebSocket#onclose.

onMessage(func): this

  • func: Callback function. Its parameter is event object.

Specify the callback function for WebSocket#onmessage.

onSocketError(func): this

  • func: Callback function. Its parameter is event object.

Specify the callback function for WebSocket#onerror.

onRequest(func): this

  • func: Callback function. Its parameters are command name and data.

Specify the callback function for invoking request method.

onServerError(func): this

  • func: Callback function. Its parameter is response data.

Specify the common callback function for the error response.
If the error response is handled by request#error or on#error, this handler doesn't run.

License

MIT

We have an commercial use version of this application officially supported.

Please contact us for details.

info@flect.co.jp