Permalink
Fetching contributors…
Cannot retrieve contributors at this time
62 lines (33 sloc) 4.88 KB

Blueprint API

Overview

For a conceptual overview of blueprints, see Concepts > Blueprints.

Activating/deactivating blueprint routes in your app

The process for activating/deactivating blueprints varies slightly with the kind of blueprint route you are concerned with (RESTful routes, shortcut routes or action routes). See the Blueprint Routes documentation section for a discussion of the different blueprint types.

Overriding blueprints

The best way to change a blueprint route is just to explicitly configure a custom route instead. Similarly, the best way to override a blueprint action is just to write your own custom action. This is the recommended approach.

But if you really know what you're doing, then read on:

RESTful / shortcut routes and actions

To override a RESTful blueprint route for a single model, simply create an action in the relevant controller file (or a standalone action in the relevant folder) with the appropriate name: find, findOne, create, update, destroy, populate, add or remove.

If you’d like to override a particular blueprint for all models, check out the sails-hook-custom-blueprints plugin. It's important to realize that, even if you haven't defined these yourself, Sails will respond with built-in CRUD logic for each model in the form of a JSON API (including support for sort, pagination, and filtering) as long as action or shortcut blueprints are enabled in your blueprints configuration.

Blueprints and resourceful pubsub

The blueprint API (just like any of your custom actions and policies) is compatible with WebSockets, thanks to the virtual request interpreter. Check out the reference section on the browser SDK (Reference > WebSockets > sails.io.js) for example usage.

Blueprints and .subscribe()

By default, the Find and Find One blueprint actions will call .subscribe() automatically when a socket request is used. This subscribes the requesting socket to each of the returned records. However, if the same socket sends a request to the Update or Destroy actions with io.socket.put() (for example) this will not cause a message to be sent to the requesting socket by default--only to the other connected, subscribed sockets. This is intended to allow UI code to use the client-side SDK's callback to handle the server response separately; e.g. to replace a loading spinner.

Blueprints and "auto-watch"

By default, the find blueprint action (when triggered via a WebSocket request) will subscribe the requesting socket to notifications about new instances of that model being created. This behavior can be changed for all models by setting sails.config.blueprints.autoWatch to false.

Disabling blueprint routes on a per-controller basis

The following technique is only supported for compatibility reasons. Please just use custom routes, whether or not you are using blueprint actions!

If you are using controllers, rather than standalone action files, it is possible to disable certain settings from config/blueprints.js on a per-controller basis by defining a _config key in your controller definition:

// In /api/controllers/PetController.js
module.exports = {
  _config: {
    actions: false,
    shortcuts: false,
    rest: false
  }
}

Disabling shortcuts-style automatic routes on a per-controller basis is not supported. This is never necessary, because you should never use shortcuts: true in production.