Add (blueprint)
Add a foreign record (e.g. a comment) to one of this record's collections (e.g. "comments").
PUT /:model/:id/:association/:fk
This action adds a reference to some other record (the "foreign", or "child" record) onto a particular collection of this record (the "primary", or "parent" record).
- If the specified
:iddoes not correspond with a primary record that exists in the database, this responds usingres.notFound(). - If the specified
:fkdoes not correspond with a foreign record that exists in the database, this responds usingres.notFound(). - If the primary record is already associated with this foreign record, this action will not modify any records. (Note that currently, in the case of a many-to-many association, it will add duplicate junction records! To resolve this, add a multi-column index at the database layer, if possible. We are currently working on a friendlier solution/default for users of MongoDB, sails-disk, and other NoSQL databases.)
- Note that if the association is "2-way" (meaning it has
via), then the foreign key or collection it points to with thatviawill also be updated on the foreign record.
Parameters
| Parameter | Type | Details |
|---|---|---|
| model | The identity of the containing model for the parent record. e.g. 'employee' (in /employee/7/involvedinPurchases/47) |
|
| id | The desired parent record's primary key value. e.g. '7' (in /employee/7/involvedInPurchases/47) |
|
| association | The name of the collection attribute. e.g. 'involvedInPurchases' |
|
| fk | The primary key value (usually id) of the child record to add to this collection. e.g. '47' |
Example
Add purchase #47 to the list of purchases that Dolly (employee #7) has been involved in:
PUT /employee/7/involvedInPurchases/47
Expected response
This returns "Dolly", the parent record. Notice she is now involved in purchase #47:
{
"id": 7,
"name": "Dolly",
"createdAt": 1485462079725,
"updatedAt": 1485476060873,
"involvedInPurchases": [
{
"amount": 10000,
"createdAt": 1485476060873,
"updatedAt": 1485476060873,
"id": 47,
"cashier": 7
}
]
}
Using jQuery
$.put('/employee/7/involvedInPurchases/47', function (purchases) {
console.log(purchases);
});
Using Angular
$http.put('/employee/7/involvedInPurchases/47')
.then(function (purchases) {
console.log(purchases);
});
Using sails.io.js
io.socket.put('/employee/7/involvedInPurchases/47', function (purchases) {
console.log(purchases);
});
Using cURL
curl http://localhost:1337/employee/7/involvedInPurchases/47 -X "PUT"
Socket notifications
If you have WebSockets enabled for your app, then every client subscribed to the primary record will receive a notification in which the notification event name is the primary model identity (e.g. 'employee'), and the message has the following format:
id: <the parent record primary key value>,
verb: 'addedTo',
attribute: <the parent record collection attribute name>,
addedIds: <the now-added child records' primary key values>
For instance, continuing the example above, all clients subscribed to Dolly, aka employee #7, (except for the client making the request) would receive the following message:
{
id: 7,
verb: 'addedTo',
attribute: 'involvedInPurchases',
addedIds: [ 47 ]
}
Clients subscribed to the child record receive an additional notification:
Assuming involvedInPurchases had a via, then either updated or addedTo notifications would also be sent to any clients who were subscribed to purchase #47, the child record we just added.
If the
via-linked attribute on the other side is also plural (e.g.cashiers), then anotheraddedTonotification will be sent. Otherwise, if theviapoints at a singular attribute (e.g.cashier) then theupdatednotification will be sent.
Finally, a third notification might be sent:
If adding this purchase to Dolly's collection would "steal" it from another employee's involvedInPurchases, then any clients subscribed to that other, stolen-from employee record (e.g. Motoki, employee #12) would receive a removedFrom notification (see Blueprints > remove from.
Notes
- If you'd like to spend some more time with Dolly, a more detailed walkthrough related to the example above is available here.
- This action is for dealing with plural ("collection") attributes. If you want to set or unset a singular ("model") attribute, just use update and set the foreign key to the id of the new foreign record (or
nullto clear the association). If you want to completely replace the set of records in the collection with another set, use the replace blueprint.The example above assumes "rest" blueprints are enabled, and that your project contains at least an 'Employee' model with attribute:
involvedInPurchases: {collection: 'Purchase', via: 'cashier'}as well as aPurchasemodel with attribute:cashier: {model: 'Employee'}. You can quickly achieve this by running:$ sails new foo $ cd foo $ sails generate model purchase $ sails generate model employee...then editing
api/models/Purchase.jsandapi/models/Employee.js.
For a better experience on sailsjs.com, update your browser.
Reference
- Application
- Blueprint API
- Command-line interface
-
Configuration
- sails.config.*
- sails.config.blueprints
- sails.config.bootstrap()
- sails.config.custom
- sails.config.datastores
- sails.config.globals
- sails.config.http
- sails.config.i18n
- sails.config.log
- sails.config.models
- sails.config.policies
- sails.config.routes
- sails.config.security
- sails.config.session
- sails.config.sockets
- sails.config.views
-
Request (`req`)
- req._startTime
- req.body
- req.cookies
- req.fresh
- req.headers
- req.hostname
- req.ip
- req.ips
- req.isSocket
- req.method
- req.options
- req.originalUrl
- req.params
- req.path
- req.protocol
- req.query
- req.secure
- req.signedCookies
- req.socket
- req.subdomains
- req.url
- req.wantsJSON
- req.xhr
- req.accepts()
- req.acceptsCharsets()
- req.acceptsLanguages()
- req.allParams()
- req.file()
- req.get()
- req.is()
- req.param()
- req.setLocale()
- req.setTimeout()
- req.host
- Response (`res`)
- Waterline (ORM)
- WebSockets
Reference
Built with Love
The Sails framework is built by a web & mobile shop in Austin, TX, with the help of our contributors. We created Sails in 2012 to assist us on Node.js projects. Naturally we open-sourced it. We hope it makes your life a little bit easier!
© 2012-2024 The Sails Company.
The Sails framework is free and open-source under the MIT License.
Illustrations by Edamame.