Replace (blueprint)
Replace all of the foreign records in one of this record's collections (e.g. "comments").
PUT /:model/:id/:association
This action resets references to "foreign", or "child" records that are members of a particular collection of this record (the "primary", or "parent" record), replacing any existing references in the collection.
- If the specified
:iddoes not correspond with a primary record that exists in the database, this responds usingres.notFound(). - Note that, if the association is "2-way" (meaning it has
via), then the foreign key or collection on the foreign record(s) will also be updated.
Parameters
| Parameter | Type | Details |
|---|---|---|
| model | The identity of the containing model for the parent record. e.g. 'employee' (in /employee/7/involvedinPurchases) |
|
| id | The desired parent record's primary key value. e.g. '7' (in /employee/7/involvedInPurchases) |
|
| association | The name of the collection attribute. e.g. 'involvedInPurchases' |
|
| fks | The primary key values (usually ids) of the child records to use as the new members of this collection. e.g. [47, 65] |
The
fksparameter should be sent in the PUT request body, unless you are making this request using a development-only shortcut blueprint route, in which case you can simply include it in the query string as?fks=[47,65].
Example
Suppose you are in charge of keeping records for a large chain of grocery stores, and Dolly the cashier (employee #7) had been taking credit for being involved in a large number of purchases, when really she had only checked out two customers. Since the owner of the grocery store chain is very forgiving, Dolly gets to keep her job, but now you have to update Dolly's involvedInPurchases collection so that it only contains purchases #47 and #65:
PUT /employee/7/involvedInPurchases
[47, 65]
Expected response
This returns Dolly, the parent record. Notice that her record only shows her being involved in purchases #47 and #65:
{
"id": 7,
"name": "Dolly",
"createdAt": 1485462079725,
"updatedAt": 1485476060873,
"involvedInPurchases": [
{
"amount": 10000,
"createdAt": 1485551132315,
"updatedAt": 1486355134239,
"id": 47,
"cashier": 7
},
{
"amount": 5667,
"createdAt": 1483551158349,
"updatedAt": 1485355134284,
"id": 65,
"cashier": 7
}
]
}
Socket notifications
If you have WebSockets enabled for your app, then every client subscribed to the parent record will receive one addedTo notification for each child record in the new collection (if any).
For instance, continuing the example above, let's assume that Dolly's previous involvedInPurchases included purchases #65, #42, and #33. All clients subscribed to Dolly's employee record (except for the client making the request) would receive two kinds of notifications: addedTo for the purchase she was not previously involved in (#47), and removedFrom for the purchases she is no longer involved in (#42 and #33).
{
id: 7,
verb: 'addedTo',
attribute: 'involvedInPurchases',
addedIds: [ 47 ]
}
and
{
id: 7,
verb: 'removedFrom',
attribute: 'involvedInPurchases',
removedIds: [ 42, 33 ]
}
Note that purchase #65 is not included in the
addedTonotification, since it was in Dolly's previous list ofinvolvedInPurchases.
Clients subscribed to the child records receive additional notifications:
Assuming involvedInPurchases had a via, then either updated or addedTo/removedFrom notifications would also be sent to clients who were subscribed to any of the purchases we just linked or unlinked.
If the
via-linked attribute on the other side (Purchase) is also plural (e.g.cashiers), then anaddedToorremovedFromnotification will be sent. Otherwise, if theviapoints at a singular attribute (e.g.cashier) then theupdatednotification will be sent.
Finally, a third kind of notification might be sent:
If giving Dolly this new collection of Purchases would "steal" any of them from other employees' involvedInPurchases, then any clients subscribed to those other, stolen-from employee records (e.g. Motoki, employee #12 and Timothy, employee #4) would receive removedFrom notifications. (See Blueprints > remove from).
Notes
- Remember, this blueprint replaces the entire set of associated records for the given attribute. To add or remove a single associated record from the collection, leaving the rest of the collection unchanged, use the "add" or "remove" blueprint actions. (See Blueprints > add to and Blueprints > remove from).
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.