Events are a new feature of the Sails core as of 0.9.
Called when the Sails app is ready to start accepting requests.
Called before any of the app's configured static routes have been bound. i.e. a hook might listen to this event to bind some middleware.
Called after all of the app's configured static routes have been bound. i.e. a hook might listen to this event to bind a "shadow route" to a blueprint.
Called when all routes have been bound, including those originating from hooks.
Called when the router is flushed (i.e. all routes are unbound).
The http
hook (i.e. Express), and any other attached servers which maintain their own routes should listen for this event so they know to unbind their private routes.
Called when a request is received by the Sails router.
Should receive three arguments, req
, res
, and next
.
You know what that means.
Absolute last-resort handler for server errors.
Called when a request encounters an error and isn't handled by other means.
Should receive three arguments, err
, req
, and res
.
Absolute last-resort handler for requests which don't match any routes.
Called when a request doesn't match any routes (or shadow routes, including 404/slug handlers), and this case isn't handled by other means.
Should receive two arguments, req
, and res
.
Called when a route is bound.
Should receive a single argument, "routeObj", which looks like:
{
path: 'String',
target: function theFnBoundtoTheRoute (req, res, next) {},
verb: 'String'
}
hook:controllers:loaded
hook:controllers:error
hook:controllers:bound:crud
hook:controllers:bound:actions
hook:controllers:bound
hook:views:loaded
hook:views:error
hook:views:bound
hook:csrf:loaded
hook:csrf:error
hook:orm:loaded
hook:orm:error
hook:sockets:loaded
hook:sockets:error
hook:partials:loaded
hook:partials:error
hook:request:loaded
hook:request:error
hook:pubsub:loaded
hook:pubsub:error
- Developers need an easier way to modify the Sails core for their needs. Hooks and events make this possible! Events are really a necessary feature for hooks to talk to each other and load in the right order.
- Event-driven design makes for a more modular and extensible code base in general.
The instantiated sails
object is a Node EventEmitter. That's pretty much it!
Although it can be tempting, it's really best not to add new events to sails
in your app code. In general, consistent conventions, clarity, and simplicity are the best practice for developing apps, because it makes them easier to extend, and makes it easier for you to remember how everything works when you come back to it later (not to mention everyone else on your team!)
If you want to add/trigger events to monkeypatch your Sails core, it's best to do this by authoring a hook. More information will show up as we learn more about best practices around that process, but one thing we've definitely learned is that you're better off namespacing your events and firing them on a single object (sails
), then emitting and listening on different objects. Why? Sometimes objects get deleted or copied, and this can make a big mess.
If you need a special event in your hook, you will want to namespace it. For instance, if I'm adding a hook called enforceRestfulSesssions
that limits the actions that can be added to controllers to encourage code consistency, I might have a hook:enforceRestfulSesssions:checked
event that fires when all of the controllers have been checked. This is so that other hooks that know about enforceRestfulSesssions
can wait until it has finished its check before proceeding (whether it's just me, or other people on my team, or if I release my hook and it gets popular, other people in the Sails community).
In my hook's initialize method, I might have the following:
// Wait until all the middleware from this app's controllers have loaded
sails.on('hook:controllers:loaded', function () {
// Do stuff
// e.g. prevent any methods called `login`, `logout` or `signup`
// since we've opted organizationally for using CRUD on a SessionController instead
// .....code here........
// When you're done, fire an event in
sails.emit('hook:enforceRestfulSesssions:checked');
});
hook:orm:prepare
would be nice, allowing us to add raw models before the ORM Hook builds them.