Edit Page

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.

Parameters

#
Parameter Type Details
model String The identity of the containing model for the parent record.

e.g. 'employee' (in /employee/7/involvedinPurchases)
id String The desired parent record's primary key value.

e.g. '7' (in /employee/7/involvedInPurchases)
association String The name of the collection attribute.

e.g. 'involvedInPurchases'
fks Array The primary key values (usually ids) of the child records to use as the new members of this collection.

e.g. [47, 65]

The fks parameter 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]

Run in Postman

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 addedTo notification, since it was in Dolly's previous list of involvedInPurchases.

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 an addedTo or removedFrom notification will be sent. Otherwise, if the via points at a singular attribute (e.g. cashier) then the updated notification 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).

Is something missing?

If you notice something we've missed or could be improved on, please follow this link and submit a pull request to the sails repo. Once we merge it, the changes will be reflected on the website the next time it is deployed.

Reference

Reference