omega-wf
v0.9.14
Published
A web application framework based on socket.io and angularjs.
Downloads
4
Readme
Omega Web Framework
A web application framework that is designed to support realtime web applications simply and effectively. It takes a 'batteries included, but optional' approach; it comes with a template language, and an extensible authentication system, but you are not required to use any of that. It also provides a django-like admin section that, when coupled with the built in database support, alows you to inspect, modify, and create instances of your models. ( Note: this feature is very new, and very experimental; it is not recommended to use in production. )
Basic App
A basic omega application looks like this:
var path = require('path');
var app = require('omega-wf').app;
app.router.add({url: '/static/*', path: path.join(__dirname, 'static')});
// Start the omega app.
app.listen();
This tells omega to serve the ./static
folder statically at the url /static/*
, and then starts listening for incomming
connections. Admitedly, this isn't the most exciting application in the world, but it illustrates the basics of omega;
first and foremost: omega is simple. It tries to make whatever you're doing as straightforward as possible, and hide
any complexity from you.
Second, this demonstrates a core concept of working with omega: the app is king. omega plication object provides an api into omega's functionality. Really, this should be intuitive for most people, but it's worth repeating.
Static File Serving
The basic example also included a basic example of static file serving. Omega supports as many static files as you would like, and handled directories, as well as individual files. To exand on the first example, we can also pass a list of directories to serve:
var path = require('path');
var app = require('omega-wf').app;
app.router.add(
{
url: '/static/*',
path: path.join(__dirname, 'static')
},
{
url: '/images/*',
path: '/usr/share/images'
},
{
url: '/uploads/*',
path: '/tmp/uploads',
options: {
autoIndex: false
}
);
The big difference between serving a static file, and serving a normal url route, is that omega looks for the path
key
and assumes that anything with path
is a static file. As path
is not a HTTP verb, I feel this is safe.
Options
Currently, the only option supported is autoIndex
. If true, and the path requested is a directory, omega looks for an
index.html
file, and serves that, instead.
Security/Performance
Under the hood omega uses it's own custom static file router, which supports streaming. While the intention is for it to be usable in production, a dedicated static file server, like nginx will always be faster, and more secure.
URL Routing
Even though the focus of omega is on realtime web applications, there are reasons you may wish to do things a more
traditional way, with server-side processing. Or, perhaps, you need to write a simple REST
service. That's easily done
with omega:
var app = require('omega-wf').app;
var controllers = require('./controllers');
app.router.add({url: '/', get: controllers.index});
It also supports adding multiple paths, with multiple verbs at once:
var app = require('omega-wf').app;
var controllers = require('./controllers');
app.router.add(
{
url: '/',
get: controllers.index
},
{
path: '/blog',
get: controllers.blog_index,
post: controllers.blog_new
}
);
The url
parameter can be a regular expression, supporting capture groups:
app.router.add({url: '/blog/{slug}', get: controllers.blog});
In the controllers.blog
function, you can get the url parameter like this:
function(request, response) {
var slug = request.params.slug;
// Your code here
response.end();
}
This is all simply a wrapper around gett/router, with a bit of syntactic sugar. All HTTP verbs supported there are supported by omega.
Socket.io
One of the big things omega provides is socket.io
functionality. We expose this in a very straightforward way:
var app = require('omega-wf').app;
app.sockets.on('connection', function(socket) {
socket.emit('news', { hello: 'world' });
socket.on('my other event', function (data) {
console.log(data);
});
});
Since socket.io
has a great, easy to understand api, we don't even bother to wrap it; we just take care of starting
the server for you. (We don't expose the io
object directly, as there's hardly any need. Should you need to use it,
you can access it via app._io
.)
Namespaces
We also expose socket.io's namespaces as channels
:
var app = require('omega-wf').app;
app.channel('/news').on('connection', function (socket) {
socket.emit('item', { news: 'item' });
});
This makes is nice and straightforward to write socket.io
code however you wish.
Authentication
Omega has integration with Passport for authentication. This can be accessed through require('omega-wf').auth
.
( Note: This is one of the few pieces not wrapped in the omega app. This is because auth is considered optional. )
Example to come soon.
Initialization
Sometimes, you need to do some initialization that depends on the omega app having finished it's setup. For these cases,
omega provides app.init
:
var app = require('omega-wf').app;
app.init(function() {
// It is safe to work with app.config here.
});
// It is not safe to work with app.config here.
This is very useful if you want to split your app into several modules, some of which depend on configuration.
App Name
It's possible to set the name of your application:
var app = require('omega-wf').app;
app.setName("Some Really Cool App v2.0.1.adf23019w-pre7");
This is useful for logging, mostly. (But it might get used later. Suggestions welcome!)
Unit Tests
Tests can be run with:
$ npm tests
Installation
Simply install globally from npm:
$ npm install -g omega-wf
This will get you the omega-admin
script, with which you can start a new app:
$ omega-admin startapp my_app
(You can also install it locally, but then you won't get the omega admin script.)
Work in Progress
This is a massive work in progress. Currently, I'm gearing up for a 1.0 release. The API is mostly stable, and I'm using it to develop some projects. As I find issues, I am documenting them with github issues, and then fixing them, so the issues list is a good idea of what doesn't work.
At the moment, I would call it "beta quality", and wouldn't run it in production without doing some extensive testing. If, however, you are a brave soul, and are using it in production, let me know! The more feedback, the better.