Who this is for. The integrations engineer adding, moving or removing sections across many records. Every key on this page goes inside patchRevision, beside originRevision and activeRevision (Choosing a write). The Collection operations reference has a real request and response for each.
Which key
| To | Send |
|---|---|
| Replace the whole collection | "areaContent(area)": [ …components ] |
| Replace one element with a new component | "areaCollectionElement(area, n)": { …component } (example) |
| Change some areas of one element | "patchAreaCollectionElement(area, n)": {"areaContent(name)": …} (example) |
| Insert an element so it becomes element n | "insertAreaCollectionElement(area, n)": { …component } (example) |
| Add one at the end | "appendAreaCollectionElement(area)": { …component } (example) |
| Add several at the end | "appendAreaCollectionElements(area)": [ …components ] (example) |
| Remove an element | "removeAreaCollectionElement(area, n)": true (example) |
A component is {"name": …, "layout": <component layout id>, "areas": {…}}, its layout areas in the write shape. In a list, an element can carry "published": false to be saved hidden. Use the key names above exactly: areaCollectionElement(area, n) is the one for a replace, not setAreaCollectionElement(area, n), which some clients send instead.
How positions count
- Positions start at 1.
- Within one request, every position refers to the collection as it was before the request. Removing 2 and 3 in one request removes the second and third elements, in whichever order the keys are written. Several operations, and other changes to the revision, can go in one request (example).
- Positions are not shown when you read. An element in
areasContenthas acomponentId, a name, a layout and its layout areas, but no position and no published flag. componentIdis not an address. Every new revision copies the components and gives them new ids. On the sandbox page, a section read ascomponentId17985 came back as 20771 after one unrelated patch.
Keeping positions correct after a removal
A removal does not renumber the elements after it. Each element keeps the position it was stored with, so a later request's position n addresses the element stored at n, not the n-th one. Measured on this site's sandbox page, one request at a time, each answering 200:
| Request | Before | After |
|---|---|---|
removeAreaCollectionElement(pageSections, 2) | A · B · C · D | A · C · D, stored at 1, 3, 4 |
insertAreaCollectionElement(pageSections, 3), with the position taken from a fresh read | A · C · D | A · C · X · D: right |
Inserts and appends land where you expect. Take every position from a fresh read taken after the last change, since the stored order is not renumbered for you, and the drift carries into every later revision.
Three rules keep a client safe:
- Make every change to one collection in one request, with positions taken from a fresh read. Within the request, positions refer to the collection before it, so they are right.
- After a removal, rewrite the collection before any later positional edit. Sending the whole list with
areaContent(area)stores the elements at 1, 2, 3 again. Map the read to the write shape first (Writing areas), or the rewrite loses content. - Check the result. Read the collection after a positional edit and compare the element names you expected with the ones you got; roll back with
activeRevisionif they differ (Going live).
On a collection you did not create, assume a removal has happened at some point.
Global components
A global component is one component shown on many records; editing it changes every one of them. To place it in a collection, refer to it by id with "global": true, and send nothing else: