Director
Overview
Director is a router. Routing is the process of determining what code to run when a URL is requested. Director works on the client and the server. Director is dependency free, on the client it does not require any other libraries (such as jQuery).
Client-side Routing
It simply watches the hash of the URL to determine what to do, for example:
http://foo.com/#/bar
Client-side routing (aka hash-routing) allows you to specify some information about the state of the application using the URL. So that when the user visits a specific URL, the application can be transformed accordingly.
Here is a simple example:
<!html>
<html>
<head>
<script src="/director.js"></script>
<script>
var author = function () { },
books = function () { },
viewBook = function(bookId) { };
var routes = {
'/author': author,
'/books': [books, function() { }],
'/books/view/:bookId': viewBook
};
var router = Router(routes);
router.init();
</script>
</head>
<body>
</body>
</html>
Director works great with your favorite DOM library, such as jQuery.
<!html>
<html>
<head>
<script src="/director.js"></script>
<script>
var author = function () { },
books = function () { },
allroutes = function(route) {
var sections = $('section');
sections.hide();
sections.find('data-route[' + route + ']').show();
};
var routes = {
'/author': showAuthorInfo,
'/books': [showAuthorInfo, listBooks]
};
var router = Router(routes);
router.configure({
on: allroutes
});
router.init();
</script>
</head>
<body>
<section data-route="author">Author Name</section>
<section data-route="books">Book1, Book2, Book3</section>
</body>
</html>
You can find a browser-specific build of director
here which has all of the server code stripped away.
Server-Side HTTP Routing
Director handles routing for HTTP requests similar to journey
or express
:
var http = require('http'),
director = require('director');
function helloWorld(route) {
this.res.writeHead(200, { 'Content-Type': 'text/plain' })
this.res.end('hello world from (' + route + ')');
}
var router = new director.http.Router({
'/hello': {
get: helloWorld
}
});
var server = http.createServer(function (req, res) {
router.dispatch(req, res, function (err) {
if (err) {
res.writeHead(404);
res.end();
}
});
});
router.get('/bonjour', helloWorld);
router.get(/hola/, helloWorld);
server.listen(8080);
CLI Routing
Director supports Command Line Interface routing. Routes for cli options are based on command line input (i.e. process.argv
) instead of a URL.
var director = require('director');
var router = new director.cli.Router();
router.on('create', function () {
console.log('create something');
});
router.on(/destroy/, function () {
console.log('destroy something');
});
router.dispatch('on', process.argv.slice(2).join(' '));
Using the cli router, you can dispatch commands by passing them as a string. For example, if this example is in a file called foo.js
:
$ node foo.js create
create something
$ node foo.js destroy
destroy something
API Documentation
Constructor
var router = Router(routes);
Routing Table
An object literal that contains nested route definitions. A potentially nested set of key/value pairs. The keys in the object literal represent each potential part of the URL. The values in the object literal contain references to the functions that should be associated with them. bark and meow are two functions that you have defined in your code.
var routes = {
'/dog': bark,
'/cat': [meow, scratch]
};
var router = Router(routes);
Adhoc Routing
When developing large client-side or server-side applications it is not always possible to define routes in one location. Usually individual decoupled components register their own routes with the application router. We refer to this as Adhoc Routing. Lets take a look at the API director
exposes for adhoc routing:
Client-side Routing
var router = new Router().init();
router.on('/some/resource', function () {
});
HTTP Routing
var router = new director.http.Router();
router.get(/\/some\/resource/, function () {
});
Scoped Routing
In large web appliations, both Client-side and Server-side, routes are often scoped within a few individual resources. Director exposes a simple way to do this for Adhoc Routing scenarios:
var router = new director.http.Router();
router.path(/\/users\/(\w+)/, function () {
this.post(function (id) {
});
this.get(function (id) {
});
this.get(/\/friends/, function (id) {
});
});
Routing Events
In director
, a "routing event" is a named property in the Routing Table which can be assigned to a function or an Array of functions to be called when a route is matched in a call to router.dispatch()
.
- on: A function or Array of functions to execute when the route is matched.
- before: A function or Array of functions to execute before calling the
on
method(s).
Client-side only
- after: A function or Array of functions to execute when leaving a particular route.
- once: A function or Array of functions to execute only once for a particular route.
Configuration
Given the flexible nature of director
there are several options available for both the Client-side and Server-side. These options can be set using the .configure()
method:
var router = new director.Router(routes).configure(options);
The options
are:
- recurse: Controls route recursion. Use
forward
, backward
, or false
. Default is false
Client-side, and backward
Server-side. - strict: If set to
false
, then trailing slashes (or other delimiters) are allowed in routes. Default is true
. - async: Controls async routing. Use
true
or false
. Default is false
. - delimiter: Character separator between route fragments. Default is
/
. - notfound: A function to call if no route is found on a call to
router.dispatch()
. - on: A function (or list of functions) to call on every call to
router.dispatch()
when a route is found. - before: A function (or list of functions) to call before every call to
router.dispatch()
when a route is found.
Client-side only
- resource: An object to which string-based routes will be bound. This can be especially useful for late-binding to route functions (such as async client-side requires).
- after: A function (or list of functions) to call when a given route is no longer the active route.
URL Matching
var router = Router({
'/dog': {
'/:color': {
on: function (color) { console.log(color) }
}
}
});
Routes can sometimes become very complex, simple/:tokens
don't always suffice. Director supports regular expressions inside the route names. The values captured from the regular expressions are passed to your listener function.
var router = Router({
'/hello': {
'/(\\w+)': {
on: function (who) { console.log(who) }
}
}
});
var router = Router({
'/hello': {
'/world/?([^\/]*)\/([^\/]*)/?': function (a, b) {
console.log(a, b);
}
}
});
URL Parameters
When you are using the same route fragments it is more descriptive to define these fragments by name and then use them in your Routing Table or Adhoc Routes. Consider a simple example where a userId
is used repeatedly.
var router = new director.Router();
router.on(/([\w-_]+)/, function (userId) { });
router.param('userId', /([\\w\\-]+)/);
router.on('/anything/:userId', function (userId) { });
router.on('/something-else/:userId', function (userId) { });
Route Recursion
Can be assigned the value of forward
or backward
. The recurse option will determine the order in which to fire the listeners that are associated with your routes. If this option is NOT specified or set to null, then only the listeners associated with an exact match will be fired.
No recursion, with the URL /dog/angry
var routes = {
'/dog': {
'/angry': {
on: growl
},
on: bark
}
};
var router = Router(routes);
Recursion set to backward
, with the URL /dog/angry
var routes = {
'/dog': {
'/angry': {
on: growl
},
on: bark
}
};
var router = Router(routes).configure({ recurse: 'backward' });
Recursion set to forward
, with the URL /dog/angry
var routes = {
'/dog': {
'/angry': {
on: growl
},
on: bark
}
};
var router = Router(routes).configure({ recurse: 'forward' });
Breaking out of recursion, with the URL /dog/angry
var routes = {
'/dog': {
'/angry': {
on: function() { return false; }
},
on: bark
}
};
var router = Router(routes).configure({ recurse: 'backward' });
Async Routing
Before diving into how Director exposes async routing, you should understand Route Recursion. At it's core route recursion is about evaluating a series of functions gathered when traversing the Routing Table.
Normally this series of functions is evaluated synchronously. In async routing, these functions are evaluated asynchronously. Async routing can be extremely useful both on the client-side and the server-side:
- Client-side: To ensure an animation or other async operations (such as HTTP requests for authentication) have completed before continuing evaluation of a route.
- Server-side: To ensure arbitrary async operations (such as performing authentication) have completed before continuing the evaluation of a route.
The method signatures for route functions in synchronous and asynchronous evaluation are different: async route functions take an additional next()
callback.
Synchronous route functions
var router = new director.Router();
router.on('/:foo/:bar/:bazz', function (foo, bar, bazz) {
});
Asynchronous route functions
var router = new director.http.Router().configure({ async: true });
router.on('/:foo/:bar/:bazz', function (foo, bar, bazz, next) {
next(false);
});
Resources
Available on the Client-side only. An object literal containing functions. If a host object is specified, your route definitions can provide string literals that represent the function names inside the host object. A host object can provide the means for better encapsulation and design.
var router = Router({
'/hello': {
'/usa': 'americas',
'/china': 'asia'
}
}).configure({ resource: container }).init();
var container = {
americas: function() { return true; },
china: function() { return true; }
};
Instance methods
configure(options)
options
{Object}: Options to configure this instance with.
Configures the Router instance with the specified options
. See Configuration for more documentation.
param(token, matcher)
- token {string}: Named parameter token to set to the specified
matcher
- matcher {string|Regexp}: Matcher for the specified
token
.
Adds a route fragment for the given string token
to the specified regex matcher
to this Router instance. See URL Parameters for more documentation.
on(method, path, route)
method
{string}: Method to insert within the Routing Table (e.g. on
, get
, etc.).path
{string}: Path within the Routing Table to set the route
to.route
{function|Array}: Route handler to invoke for the method
and path
.
Adds the route
handler for the specified method
and path
within the Routing Table.
path(path, routesFn)
path
{string|Regexp}: Scope within the Routing Table to invoke the routesFn
within.routesFn
{function}: Adhoc Routing function with calls to this.on()
, this.get()
etc.
Invokes the routesFn
within the scope of the specified path
for this Router instance.
dispatch(method, path[, callback])
- method {string}: Method to invoke handlers for within the Routing Table
- path {string}: Path within the Routing Table to match
- callback {function}: Invoked once all route handlers have been called.
Dispatches the route handlers matched within the Routing Table for this instance for the specified method
and path
.
mount(routes, path)
- routes {object}: Partial routing table to insert into this instance.
- path {string|Regexp}: Path within the Routing Table to insert the
routes
into.
Inserts the partial Routing Table, routes
, into the Routing Table for this Router instance at the specified path
.
Instance methods (Client-side only)
init()
Initialize the router, start listening for changes to the URL.
getState()
Returns the state object that is relative to the current route.
getRoute([index])
index
{Number}: The hash value is divided by forward slashes, each section then has an index, if this is provided, only that section of the route will be returned.
Returns the entire route or just a section of it.
setRoute(route)
route
{String}: Supply a route value, such as home/stats
.
Set the current route.
setRoute(start, length)
start
{Number} - The position at which to start removing items.length
{Number} - The number of items to remove from the route.
Remove a segment from the current route.
setRoute(index, value)
index
{Number} - The hash value is divided by forward slashes, each section then has an index.value
{String} - The new value to assign the the position indicated by the first parameter.
Set a segment of the current route.
Frequently Asked Questions
What About SEO?
Is using a Client-side router a problem for SEO? Yes. If advertising is a requirement, you are probably building a "Web Page" and not a "Web Application". Director on the client is meant for script-heavy Web Applications.
Is Director compatible with X?
Director is known to be Ender.js compatible. However, the project still needs solid cross-browser testing.
Licence
(The MIT License)
Copyright (c) 2010 Nodejitsu Inc. http://www.twitter.com/nodejitsu
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.