tesla-router

Tesla.js Router

About

An MVC style auto-router for Tesla.js.

How It Works

This router will attempt to auto-load a controller based on the current URL. If you are using Tesla.js it comes ready to go out of the box. If you want to use it as a stand-alone router, see the installation section below.

Following is a quick walkthrough of how URL's are mapped to controllers.

For example, Going to http://mysite.com/foo/bar will attempt to load:

File Structure

app/controllers/foo/barController.js

If it fails to find a file there, it will attempt to load:

app/controllers/foor/bar/indexController.js

If this also fails, the router will assume a more coplex controller and try this:

app/controllers/fooController.js

if that also fails, it will throw a 404 error.

Controller Structure

Generally, with a request like http://mysite.com/foo/bar, your controller file is expected to be formatted one of two ways:

module.exports = function(app, req, res) {
	// RENDER YOUR VIEWS HERE
	res.render('foo/bar');
}

or

exports.bar  = function(app, req, res) {
	// RENDER YOUR VIEWS HERE
	res.render('index');
}

Either of these methods are acceptable if you are loading a single view in your controller, and will work with either app/controllers/foo/barController.js or app/controllers/foo/bar/indexController.js.

If you are loading multiple views, or naming your controller like app/controllers/fooController.js (with a CRUD style controller for example), the module.exports format will not work. You will need to follow this format:

// responds to http://mysite.com/foo/bar
exports.bar  = function(app, req, res) {
	
	// RENDER YOUR VIEWS HERE
	res.render('foo/bar');
	
};

// responds to http://mysite.com/foo/baz
exports.baz  = function(app, req, res) {

	// RENDER YOUR VIEWS HERE
	res.render('foo/baz');
	
};

More Examples

A few more quick examples of how URL's will route to controller files:

http://mysite.com/ will only try:

• app/controllers/indexController.js

while http://mysite.com/login will try:

• app/controllers/loginController.js
• app/controllers/login/indexController.js

and lastly http://mysite.com/my/name/is/steve will try:

• app/controllers/my/name/is/steveController.js
• app/controllers/my/name/is/steve/indexController.js
• app/controllers/my/name/isController.js

Installation & Usage

This module is built to work with the Tesla.js framework, but will also work as a stand-alone router (though it does require Express 4 at a minimum).

Install

$ npm install tesla-router

Usage

All that's required is to require the router after your express app has been created, and pass it the app object:

require('tesla-router')(app);

Here's a super basic barebones example:

var express = require('express'), // GET EXPRESS
    app = module.exports = express(), // DEFINE THE APP
    server = require('http').createServer(app); // CREATE THE SERVER

// IF YOU HAVE ANY CUSTOM ROUTES YOU WANT TO OVERRIDE THE AUT ROUTER WITH
// THEY SHOULD COME FIRST (OPTIONAL)

// INCLUDE AUTO ROUTES
require('tesla-router')(app);

server.listen( 3000 );

// EXPOSE APP
exports = module.exports = app;

ERROR HANDLING

Tesla.js includes an error controller to handle any errors. But, if you are using this as a stand-alone, you will need to create the file app/controllers/errorController.js with the following methods:

// GENERIC ERROR HANDLER
exports.throw = function(app, req, res) {

	if (app.err.status) {

		res.status(app.err.status).render('errors/default', {
			title : app.err.message,
			status: app.err.status,
			site: app.site
		});

	} else {
		res.status(500).render('error', {
			title : app.err,
			status: '500',
			site: app.site
		});
	}

};


// 404 ERROR
exports.throw404 = function(app, req, res) {

	res.status(404).render('errors/404', {
		title : app.err,
		url: req.originalUrl,
		error: app.err,
		site: app.site
	});

};


// 500 ERROR
exports.throw500 = function(app, req, res) {

	res.status(500).render('errors/500', {
		title : app.err.title,
		url: req.originalUrl,
		error: app.err.stack,
		site: app.site
	});

};

The file doesn't need to be exactly this, but the router will look for the file app/controllers/errorController.js with the throw, throw404 & throw500 methods.