node package manager
Loosely couple your services. Use Orgs to version and reuse your code. Create a free org »

ampersand-controller-router

ampersand-controller-router

Allows you to map "controllers" to routes.

Usage

var AmpRouter = require('ampersand-controller-router');
 
var myRouter = new AmpRouter({
  // A map of controller constructors. Name is important. 
  controllers: {
    index: require('index-controller'),
    profile: require('profile-controller'),
  },
 
  // Passed to the controller constructor. I use this to pass a reference to 
  // my "app" object for example: 
  controllerOptions: {
    app: appInstance,
  },
 
  // Function passed to the route action. I use this to update the current view 
  // and stuff. 
  routeCallback: appInstance.routeHandler.bind(appInstance),
 
  // And finally your actual routes. Remember that leading `/` is not necessary 
  // and won't actually do what you think. 
  routes: {
    '': 'index.home', // On `/` execute the `home` method on the `index` controller 
    '/profile': 'profile.user',
  }
});
 
// Start the router. 
// Accepts the same arguments as the original `ampersand-router`. But has 
// slightly different defaults: 
// 
// pushState: true 
// hashChange: false 
// silent: false 
// root: '/' 
// 
// This means that `start()` will execute the _current_ URL and won't use # for 
// routing but rather "real" URLs. 
myRouter.start();

This router extends the original ampersand-router and all the same events etc should be emitted.

I usually make my "controllers" subclasses of ampersand-state. And the action method will call the callback with an error or an instance of an ampersand-view.

So something like this:

var AmpState = require('ampersand-state');
 
module.exports = AmpState.extend({
  app: null,
 
  // Constructor passed the `controllerOptions` given to the router. 
  initialize: function (controllerOptions) {
    this.app = controllerOptions.app;
  },
 
  // A route handler 
  // At the moment the controller action will _always_ be passed a query 
  // argument, this is the query string. Should the route accept any parameters, 
  // like: `user/:id` that parameter will come _before_ `query`. 
  home: function (query, callback) {
    // This is where I configure models etc. The controller is often the "owner" 
    // of those models. And the view's model will be the controller itself. 
    var view = new HomeView({model: this });
 
    // The `routeCallback` will take this view object and replace the current 
    // main view with this new view. 
    callback(null /* no error occured */, view);
  }
});

That's a sample of how I use this. For some history on it's origins check out my blog post building an app with Ampersand.

Notes

This is a very thin wrapper (~70 LOC including comments) around ampersand-router. It currently has no tests but have been working fine for me! :)

License

MIT