bogart

v0.7.3

Published

3 years ago

Fast JSGI web framework taking inspiration from Sinatra

Downloads

0High
0Medium
0Low

nathan

bogart framework sinatra REST

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: 'do-not-share' })); // 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 ("/"). Multiple wildcards may be used in a route pattern. The values for the wildcard matches are placed in an Array available from the request params at req.params.splat.

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

In the above example, everything after /hello/ will be in req.params.splat[0]. A request to /hello/how/are/you would have a splat of [ 'how/are/you' ].

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);
});

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' ]
  };
}))

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);

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);

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

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

View Engine

The Bogart view engine is a tempalting language agnostic tool to resolve and render templates. Bogart comes with a mustache renderer included. Other renderers can be added via the plugin infrastructure.

Example:

var viewEngine = bogart.viewEngine('mustache');

// Render `views/index.html` with values `{ name: 'Nathan Stott' }`
viewEngine.render('index.html', { locals: { name: 'Nathan Stott' } });

More information can be found in docs/view-engine.md.

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.