Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Misc #202

Merged
merged 2 commits into from
May 9, 2011
Merged

Misc #202

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3a5ab76
Updated the package.json, added more keywords. Added repo and fixed t…
3rd-Eden May 7, 2011
8f1d96a
Updated the readme, fixed typos, changed `socket.io` requires to `soc…
3rd-Eden May 7, 2011
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
268 changes: 148 additions & 120 deletions Readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,35 +7,41 @@ horizontal scalability, automatic JSON encoding/decoding, and more.

## How to Install

npm install socket.io
npm install socket.io-node

## How to use

First, require `socket.io`:
First, require `socket.io-node`:

var io = require('socket.io');
``` js
var io = require('socket.io-node');
```

Next, attach it to a HTTP/HTTPS server. If you're using the fantastic `express`
web framework:

var app = express.createServer();
, io = io.listen(app);
```js
var app = express.createServer();
, io = io.listen(app);

app.listen(80);
app.listen(80);

io.sockets.on('connection', function (socket) {
socket.send({ hello: 'world' });
});
io.sockets.on('connection', function (socket) {
socket.send({ hello: 'world' });
});
```

Finally, load it from the client side code:

<script src="/socket.io/socket.io.js"></script>
<script>
var socket = io.connect('http://localhost');
socket.on('news', function () {
socket.emit('myOtherEvent', { my: 'data' });
});
</script>
```html
<script src="/socket.io/socket.io.js"></script>
<script>
var socket = io.connect('http://localhost');
socket.on('news', function () {
socket.emit('myOtherEvent', { my: 'data' });
});
</script>
```

For more thorough examples, look at the `examples/` directory.

Expand All @@ -46,20 +52,22 @@ For more thorough examples, look at the `examples/` directory.
Socket.IO allows you to emit and receive custom events.
Besides `connect`, `message` and `disconnect`, you can emit custom events:

// note, io.listen(<port>) will create a http server for you
var io = require('socket.io').listen(80);
```js
// note, io.listen(<port>) will create a http server for you
var io = require('socket.io').listen(80);

io.sockets.on('connection', function (socket) {
io.sockets.emit('this', { will: 'be received by everyone');
io.sockets.on('connection', function (socket) {
io.sockets.emit('this', { will: 'be received by everyone');

socket.on('private message', function (from, msg) {
console.log('I received a private message by ', from, ' saying ', msg);
});
socket.on('private message', function (from, msg) {
console.log('I received a private message by ', from, ' saying ', msg);
});

socket.on('disconnect', function () {
sockets.emit('user disconnected');
});
});
socket.on('disconnect', function () {
sockets.emit('user disconnected');
});
});
```

### Storing data associated to a client

Expand All @@ -68,33 +76,37 @@ necessary for the duration of the session.

#### Server side

var io = require('socket.io').listen(80);
```js
var io = require('socket.io-node').listen(80);

io.sockets.on('connection', function (socket) {
socket.on('set nickname', function (name) {
socket.set('nickname', name, function () { socket.emit('ready'); });
});
io.sockets.on('connection', function (socket) {
socket.on('set nickname', function (name) {
socket.set('nickname', name, function () { socket.emit('ready'); });
});

socket.on('msg', function () {
socket.get('nickname', function (name) {
console.log('Chat message by ', name);
});
});
socket.on('msg', function () {
socket.get('nickname', function (name) {
console.log('Chat message by ', name);
});
});
});
```

#### Client side

<script>
var socket = io.connect('http://localhost');
```html
<script>
var socket = io.connect('http://localhost');

socket.on('connect', function () {
socket.emit('set nickname', confirm('What is your nickname?'));
socket.on('ready', function () {
console.log('Connected !');
socket.emit('msg', confirm('What is your message?'));
});
});
</script>
socket.on('connect', function () {
socket.emit('set nickname', confirm('What is your nickname?'));
socket.on('ready', function () {
console.log('Connected !');
socket.emit('msg', confirm('What is your message?'));
});
});
</script>
```

### Restricting yourself to a namespace

Expand All @@ -112,36 +124,40 @@ The following example defines a socket that listens on '/chat' and one for

#### Server side

var io = require('socket.io').listen(80);
```js
var io = require('socket.io-node').listen(80);

var chat = io
.for('/chat');
.on('connection', function (socket) {
socket.emit('a message', { that: 'only', '/chat': 'will get' });
chat.emit('a message', { everyone: 'in', '/chat': 'will get' });
});
var chat = io
.for('/chat');
.on('connection', function (socket) {
socket.emit('a message', { that: 'only', '/chat': 'will get' });
chat.emit('a message', { everyone: 'in', '/chat': 'will get' });
});

var news = io
.for('/news');
.on('connection', function (socket) {
socket.emit('item', { news: 'item' });
});
var news = io
.for('/news');
.on('connection', function (socket) {
socket.emit('item', { news: 'item' });
});
```

#### Client side:

<script>
var socket = io.connect('http://localhost/')
, chat = socket.for('/chat')
, news = socket.for('/news');
```html
<script>
var socket = io.connect('http://localhost/')
, chat = socket.for('/chat')
, news = socket.for('/news');

chat.on('connect', function () {
chat.emit('hi!');
});
chat.on('connect', function () {
chat.emit('hi!');
});

news.on('news', function () {
news.emit('woot');
});
</script>
news.on('news', function () {
news.emit('woot');
});
</script>
```

### Sending volatile messages.

Expand All @@ -157,19 +173,21 @@ In that case, you might want to send those messages as volatile messages.

#### Server side

var io = require('socket.io').listen(80);
```js
var io = require('socket.io-node').listen(80);

io.sockets.on('connection', function (socket) {
var tweets = setInterval(function () {
getBieberTweet(function (tweet) {
socket.volatile.emit('bieber tweeet', tweet);
});
}, 100);

socket.on('disconnect', function () {
clearInterval(tweets);
});
io.sockets.on('connection', function (socket) {
var tweets = setInterval(function () {
getBieberTweet(function (tweet) {
socket.volatile.emit('bieber tweet', tweet);
});
}, 100);

socket.on('disconnect', function () {
clearInterval(tweets);
});
});
```

#### Client side

Expand All @@ -179,7 +197,7 @@ or not.
### Getting acknowledgements

Sometimes, you might want to get a callback when the client confirmed the message
receiption.
reception.

To do this, simply pass a function as the last parameter of `.send` or `.emit`.
What's more, you can also perform a manual acknowledgement, like in the example
Expand All @@ -188,26 +206,30 @@ function is `0` when you `emit` or `send`.

#### Server side

var io = require('socket.io').listen(80);
```js
var io = require('socket.io-node').listen(80);

io.sockets.on('connection', function (socket) {
socket.on('ferret', function (name, fn) {
fn('woot');
});
});
io.sockets.on('connection', function (socket) {
socket.on('ferret', function (name, fn) {
fn('woot');
});
});
```

#### Client side

<script>
var socket = io.connect(); // TIP: .connect with no args does auto-discovery
socket.on('connection', function () {
socket.emit('ferret', 'tobi', function (data) {
// if the funtion arity here was 0 (ie: if no parameters were defined),
// socket.io would handle the acknowledgement automatically.
console.log(data); // data will be 'woot'
});
});
</script>
```html
<script>
var socket = io.connect(); // TIP: .connect with no args does auto-discovery
socket.on('connection', function () {
socket.emit('ferret', 'tobi', function (data) {
// if the function arity here was 0 (ie: if no parameters were defined),
// socket.io would handle the acknowledgement automatically.
console.log(data); // data will be 'woot'
});
});
</script>
```

### Using it just as a cross-browser WebSocket

Expand All @@ -216,42 +238,48 @@ Simply leverage `send` and listen on the `message` event:

#### Server side

var io = require('socket.io').listen(80);
```js
var io = require('socket.io-node').listen(80);

io.sockets.on('connection', function (socket) {
socket.on('message', function () { });
socket.on('disconnect', function () { });
});
io.sockets.on('connection', function (socket) {
socket.on('message', function () { });
socket.on('disconnect', function () { });
});
```

#### Client side

<script>
var socket = io.connect('http://localhost/');
socket.on('connect', function () {
socket.send('hi');
```html
<script>
var socket = io.connect('http://localhost/');
socket.on('connect', function () {
socket.send('hi');

socket.on('message', function (msg) {
// my msg
});
});
</script>
socket.on('message', function (msg) {
// my msg
});
});
</script>
```

### Changing configuration

Configuration in socket.io is TJ-style:

#### Server side

var io = require('socket.io').listen(80);
```js
var io = require('socket.io-node').listen(80);

io.configure(function () {
io.set('transports', ['websocket', 'flashsocket', 'xhr-polling']);
});
io.configure(function () {
io.set('transports', ['websocket', 'flashsocket', 'xhr-polling']);
});

io.configure('development', function () {
io.set('transports', ['websocket', 'xhr-polling']);
io.enable('log');
});
io.configure('development', function () {
io.set('transports', ['websocket', 'xhr-polling']);
io.enable('log');
});
```

## [API docs](http://socket.io/api.html)

Expand Down
8 changes: 6 additions & 2 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,17 @@
"name": "socket.io-node"
, "version": "0.7.0"
, "description": "Realtime apps made cross-browser & easy with a WebSocket-like API"
, "keywords": ["websocket", "socket", "realtime"]
, "keywords": ["websocket", "socket", "realtime", "socket.io", "comet", "ajax"]
, "author": "Guillermo Rauch <[email protected]>"
, "contributors": [
{ "name": "Guillermo Rauch", "email": "[email protected]" }
, { "name": "Arnout Kazemier", "email": "[email protected]" }
]
, "repository":{
"type": "git"
, "url": "https://github.com/LearnBoost/Socket.IO-node.git"
}
, "dependencies": {}
, "main": "index"
, "engines": { "node": "0.4.x" }
, "engines": { "node": ">= 0.4.0" }
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

wouldn't do that, this bit me with many of my earlier modules

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Both situations are indeed less than ideal, but the previous version was to restrictive this allows 0.4 and >. So I guess there isn't perfect solution for this.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

were you wanting to use it with the 0.5.x stuff? maybe >= 0.4.0 < 0.6.0 would be ok

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I develop and test all code on 0.4 and 0.5 to ensure a flawless upgrade once a new stable node.js is available.
So I guess a >= 0.4.0 < 0.6.0 would be suitable for this.

Want me to update the commit?
On May 8, 2011, at 7:13 PM, visionmedia wrote:

, "dependencies": {}
, "main": "index"

  • , "engines": { "node": "0.4.x" }
  • , "engines": { "node": ">= 0.4.0" }

were you wanting to use it with the 0.5.x stuff? maybe >= 0.4.0 < 0.6.0 would be ok

Reply to this email directly or view it on GitHub:
https://github.com/LearnBoost/Socket.IO-node/pull/202/files#r27205

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

personally I dont think people should be targeting 0.5.x at all, it's just not really a concern right now but we'll see what @guille thinks. IMO we should leave it at 0.4.x

}