From 12f7405781fb623e80af40c9e3a3e16965cab46f Mon Sep 17 00:00:00 2001 From: Sahat Yalkabov Date: Thu, 30 Jan 2014 04:15:18 -0500 Subject: [PATCH] Add socket.io guide --- README.md | 107 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 100 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index d078c96946..133b6e9659 100644 --- a/README.md +++ b/README.md @@ -272,8 +272,8 @@ for authentication with single page applications. If you insist on using a client-side framework, it's best if you use a boilerplate of choice for your particular client-side framework and just grab the pieces you need from the Hackathon Starter. -HOW IT WORKS (mini guide series) --------------------------------- +How it works (mini guide) +------------------------- This section is intended for giving you a detailed explanation about how a particular functionality works. Maybe you are just curious about how it works, or maybe you are lost and confused while reading the code, @@ -353,14 +353,107 @@ Todo
+### How do I use Socket.io with Hackathon Starter? +[Dan Stroot](https://github.com/dstroot) submitted an excellent [pull request](https://github.com/dstroot/hackathon-starter/commit/0a632def1ce8da446709d92812423d337c977d75) that adds a real-time dashboard with socket.io. +And as much as I'd like to add it to the project, I think it violates one of the main +principles of the Hackathon Starter: +> When I started this project, my primary focus was on simplicity and ease of use. +> I also tried to make it as generic and reusable as possible to cover most use cases of +> hackathon web apps, **without being too specific**. -TODO LIST ---------- +When I need to use socket.io, I **really** need it, but most of the time - I don't. But more +importantly, websockets support is still experimental on most hosting providers. As of October 2013, +Heroku supports websockets, but not until you opt-in by running this command: +``` +heroku labs:enable websockets -a myapp +``` +And what if you are deploying to OpenShift? They do support websockets, but it is currently in a +preview state. So, for OpenShift you would need to change the socket.io connect URI to the following: +``` +var socket = io.connect('http://yoursite-namespace.rhcloud.com:8000'); +``` +Wait, why is it on port 8000? And why is it you don't have to specify the port number when you are +deploying your app to Heroku? Who knows, and if I didn't run across this [blog post](http://velin-georgiev-blog.appspot.com/blog/set-up-nodejs-express-socketio-application-using-websockets-on-openshift-by-red-hat/) +I wouldn't even know I had to use port 8000. + +I am really glad that Heroku and OpenShift at least +have a websockets support, because many other PaaS providers still do not support it. +Due to the aforementioned issues with websockets, I cannot include socket.io as part of the Hackathon Starter. *For now*. +If you need to use socket.io in your app, then continue reading. + +First you need to install socket.io: +``` +npm install socket.io --save` +``` + +Replace `var app = express();` with the following code: + +``` +var app = express(); +var http = require('http'); +var server = http.createServer(app); +var io = require('socket.io').listen(server); + +``` + +I like to have the following code organization in `app.js` (from top to bottom): module dependencies, +import controllers, import configs, connect to database, express configuration, routes, +start the server, socket.io stuff. That way I always know where to look for things. + +Add the following code at the end of `app.js`: + +``` +io.configure(function() { + io.set('transports', ['websocket']); +}); + +io.sockets.on('connection', function(socket) { + socket.emit('greet', { hello: 'Hey, Mr.Client!' }); + socket.on('respond', function(data) { + console.log(data); + }); + socket.on('disconnect', function() { + console.log('Socket disconnected'); + }); +}); +``` + +We are done with the server-side business. + +You now have a choice - to include your JavaScript code in Jade templates or have all your client-side +JavaScript in a separate file - in `main.js`. I will admit, when I first started out with Node.js and JavaScript in general, +I placed all JavaScript code inside templates because I have access to template variables passed in from Express +right then and there. It's the easiest thing you can do, but also the least efficient and harder to maintain. + +But it's understandable if you take the easier road. Most of the time you don't care about performance during hackathons, you just +want to [*"get shit done"*](http://www.startupvitamins.com/media/products/13/aaron_levie_poster_black.jpg) before the time runs out. + +If you want to stick all your JavaScript inside templates, then in `layout.jade` - +your main template file, add this to `head` block. + +``` +script(src='/socket.io/socket.io.js?v=#{cacheBuster}') +script. + var socket = io.connect(window.location.href); + socket.on('greet', function (data) { + console.log(data); + socket.emit('respond', { message: 'Hello to you too, Mr.Server!' }); + }); +``` + +If you want to have JavaScript code separate from templates, move that inline script code into `main.js`, +inside the `$(document).ready()`. Oh, and notice the path of socket.io file, you don't actually +have to have `socket.io.js` file anywhere in your project, it will be generated automatically +at runtime. + +And that's it, we are done! + +
+ +TODO +---- - Concatenate and minify all assets via Express middleware if possible, otherwise Gulp.js. Because even with caching enabled, there is at least 50-80ms delay for each static file request (On Heroku). - Pages that require login, should automatically redirect to last attempted URL on successful sign-in. -- Add more API examples. -- Mocha tests. -- Once things are stabilized, create a CHANGELOG.md and follow a version format so people who already use Hackathon Starter could know what are the new changes. Contributing