Bogart

A blazing fast rapid application development web framework using JSGI for node.

Getting Started

Bogart can be installed via npm.

npm install bogart

Alternatively, clone the git repository.

git clone git://github.com/nrstott/bogart.git

Hello World in Bogart

Make a directory: mkdir hello-world

Create the following file:

app.js

var bogart = require('bogart');

var router = bogart.router();
router.get('/', function(req) { 
  return "hello world"; 
});

router.get('/:name', function(req) {
  return 'hello '+req.params.name;
});

var app = bogart.app();
app.use(bogart.batteries({secret: "my-super-secret"})); // A batteries included JSGI stack including streaming request body parsing, session, flash, and much more.
app.use(router); // Our router

app.start();

Start your app: node app.js

Visit it in a web browser at http://localhost:8080. Visit the route that says hello to you by name at http://localhost:8080/bob

Changing the port

If you can't run on 8080, change the app.start call e.g. app.start(9090, '127.0.0.1')

Routing

Routing in Bogart is simple and intuitive. A route is an HTTP method paired with an URL matching pattern and a handler function.

var router = bogart.router();
router.get('/', function(req) {
  return bogart.html('Hello World');
});

Routes are tested for matches in the order in which they are defined.

Route Patterns

Route patterns are matched against URLs. They may include named parameters that will be accessible via the params object of the req object passed to the route handler.

var router = bogart.router();
router.get('/hello/:name', function(req) {
  var greeting = 'Hello '+req.params.name;
  return bogart.html(greeting);
});

Route patterns support wildcards. Wildcards will match anything whereas regular named parameters will not match beyond a path separator ("/").

var router = bogart.router();
router.get('/hello/*', function(req, name) {
    return bogart.html('Hello '+req.params.splat[0]);
});

No Route Found

When no route pattern matches the request, a next jsgi application to be called may be specified either with the Router#notFound method or via a parameter to the function returned by bogart:router. If both techniques are used, then the parameter overrides the app specified by the Router#notFound method.

Specified by calling the Router#notFound method

var myRouter = bogart.myRouter();
router.get('/', index);
myRouter.notFound(function (req) {
  return bogart.html('Not Found', { status: 404 });
});

Specified as a parameter to the router

var myRouter = bogart.router();
myRouter.get('/', index);

var app = bogart.app();
app.use(myRouter(function (req) {
  return {
    status: 404,
    body: [ 'Not Found' ]
  };
}))

Regex Routes

When a route pattern is not powerful enough, regular expressions may be used to specify which URLs are to be matched.

var router = bogart.router();
router.get(/\/posts?/, function(req) {
  // Matches 'post' or 'posts'
  return bogart.html('Regex Route');
});

Parameters are via regular expression groups in regular expression routes. The parameter values are put in an Array in req.params.splat of the req object passed to the route handler.

var router = bogart.router();
router.get(/hello-(.*)/, function(req) {
  var name = req.params.splat[0];
  return bogart.html('Hello '+name);
});

Custom HTTP Verbs

To handle HTTP Verbs other than get, post, put, and delete, the route method of Router can be invoked.

var router = bogart.router();
router.route('options', '/', function (req) {
  // Logic for handling the request goes here.
});

Bogart Application

bogart.app makes it easy to setup a middleware chain and start coding. Combined with bogart.batteries (See Below), you can setup a full-stack JSGI application in two lines of code.

var app = bogart.app();
app.use(bogart.batteries({ secret: "my-super-secret" });

After adding bogart.batteries, you will normally want to add a Router. This is also done with app.use. To start the application, use the start method.

var app = bogart.app();
app.use(bogart.batteries({ secret: "my-super-secret" }));

var router = bogart.router();
// NOTE: Here you would normally add some routes.

app.use(router);
app.start();

Response Helpers

Bogart includes helpers for creating JSGI Responses. The helpers, by convention, take a final parameter of an options object that allows the caller to override defaults. The options object is merged with the default JSGI Response values of the helper before the JSGI Response is returned.