Collections

A collection is a reusable block you drop into a widget — a product card, a footer, a testimonial strip. Maya puts one product card on the homepage hero and the catalog. When the card is shared, one edit updates every unpublished widget that uses it. When she needs a one-off price on the spring-sale hero, she makes an embedded copy so the everyday card stays put.

What you can do

You already opened Maya's homepage hero from Widgets and landed in the composer. The hero is a widget. The product card she wants on that hero — and on the catalog, and on the German hero — is a collection.

Two everyday jobs:

Reuse a product card on many pages. Build it once. Drop it on the homepage hero, the catalog widget, and the German hero. One source. When she changes the price on that shared card, every unpublished widget that uses it updates.
Freeze a one-off variant on the spring-sale hero. The sale page needs a crossed-out price that must not leak back onto the everyday card. She drops the same collection, then chooses Make Embedded Copy And Modify. That copy belongs to the sale widget only.

A collection is a reusable block. A widget is the page that holds it. Publishing is how the site gets a snapshot.

How a collection thinks

There are two reuse models. Choosing the wrong one is the surprise people remember.

A shared collection is one source. Every widget that drops it is looking at the same record. Edit the draft of Maya's product card and every unpublished widget that uses it changes — the homepage hero, the catalog, the German hero. An embedded copy on the spring-sale hero does not. That copy is tied to the sale widget's version.

Here is the case that surprises people. Maya edits the shared card and expects only the catalog to move. The unpublished homepage hero moves too, because it is still pointing at the same source. The sale hero stays put, because she made an embedded copy there. Already published pages stay on the last published snapshot of that shared collection until she publishes the collection again.

A Featured stamp on a shared card travels with that collection after you publish it. Every widget that embeds the card picks the stamp up — you do not republish each widget. Overlay authoring lives in the collection header, just left of the gear. See Overlay Layers.

When you reach for each model:

	Shared collection	Embedded collection
What it is	One source of truth on the team. Used in many widgets.	A copy that belongs to one parent widget or collection. Tied to that parent's version.
Where you edit it	Open it from the palette or the collections list. It has its own composer page. On a parent, Modify Shared Collection in the Modify drawer takes you there.	From the parent, Modify Embedded Collection in the Modify drawer.
When you change the draft	Every unpublished widget or collection that references it sees the change immediately.	Only this instance on this parent changes. Sibling pages are unaffected.
When you publish	Published once per environment, with its own published key. Widgets reference the live shared version — they do not duplicate its content.	Included in the parent widget's snapshot. Each published widget version keeps its own embedded copies. It cannot be published on its own.
When you reach for it	The product card, a disclaimer, a nav block — anything that should stay in sync everywhere.	A one-off sale price, a unique sidebar, an A/B variant tied to one widget. Start from the shared card, then Make Embedded Copy And Modify.

Collections nest. A typical page is an embedded body that still references the shared product card, plus another embedded sidebar unique to that page. On publish, shared nodes stay references. Embedded nodes at every depth are copied so that widget version owns its subtree.

Build your first collection

You do this on an environment page — the same place you open Widgets and Widget Selection Rulesets. You need a Collection Access group (View, Manage, or Admin) for that environment, or a RuleCMS admin account. Manage is enough to create and edit. Promoting and publishing use the same groups as a widget, under Utility Functions on the team's User Groups page: Post Promote To Staging, Post Promote To Production, Post Publish To Staging, and Post Publish To Production. No Collection Access group includes them, not even Admin. Staging and Production have their own Collection Access groups when you want to split who can edit there.

Open the organization → team → project → environment you want to work in.
Find the Collections card. It offers View Collections and Add. Add opens Create New Collection. The list page uses Add Collection for the same form. In the composer, the Create New Collection action at the bottom of the Collections tab — and in the Go To menu — opens that same page.
Collection Name is optional — leave it blank and RuleCMS assigns one. Submit Create Collection. You land in the composer.
Build the product card — rows, an image, a price. Empty collections cannot be dragged onto a page, so add at least one row before you reuse it.
Open the homepage hero widget. From the composer Collections tab, drop the card onto the hero. Dragging the move handle is the faster way. When that arrows icon is showing, the row highlights under the pointer, and clicking the row opens the same wizard as clicking a component. Edit and Remove stay their own buttons. Click to place walks through it.
Click the card on the canvas. The Modify drawer offers Modify Shared Collection if this should stay one source, or Make Embedded Copy And Modify if this hero needs a private variant. For the everyday card, leave it shared. For the spring-sale hero, make the embedded copy.
That is a safe stop. You are composing. Come back to the collection management page when you need a lever below.

The list for that environment shows every collection. Shared ones sit first. An embedded collection shows an Embedded badge on its management page and names its parent.

An agent can create that same collection after you connect MCP. The walkthrough is on collections from an agent.

When you reach for it

The first path above is create and drop. These are the other levers on the collection management page, named as jobs. Embedded collections hide Promote, Copy To, and Make a Copy — they belong to a parent, not the pipeline.

What you need	When you reach for it
Promote to Staging / Promote to Production	The shared draft is ready for the next environment. Promote copies the draft. It does not publish. On Development you see Promote to Staging. On Staging you see Promote to Production. Same buttons as a widget — see Widgets.
Copy To ▼	You named an extra environment and want a fork there. Copy To is only for extra environments you named yourself — not Staging or Production. Use promote for the pipeline. Make a Copy duplicates inside the same environment.
Publish	Staging and Production only, and only for a shared collection. Creates the snapshot widgets reference. Development shows Integrate instead — live drafts, no publish step. An embedded collection's Publish tab says it cannot be published in isolation. Without View Published Resource In Staging or View Published Resource In Production, the tab shows Permission Required. The snapshot workflow is Publishing.
CSS Settings	Tokens, classes, fonts, and the rest on this collection, when you have permission. The header button opens the hub. The CSS Settings tab is the read-only stack.
Collection Dependencies	Every shared and embedded collection in the tree — useful before a publish, and on a widget too.
Collection Config	Raw configuration for this collection.
Ask AI	Ask AI cannot create, embed, replace, or edit a collection. The button is hidden on a collection, not disabled. Use the palette and the Modify drawer.

Collection Settings

While you are editing a collection, a gear in the collection header opens Collection Settings — styles for the collection as a whole, the box every row sits inside. That is separate from the Modify drawer, which still edits one selected component, column, or row.

Use Collection Settings when you want the reused block itself to have a max width, padding, background, gap between rows, or to hide the whole collection on certain devices. Those values travel with the collection wherever it is used. Overlay layer controls sit just left of the same gear — a Featured stamp on this card, for example. How to add and stack layers is Overlay Layers.

Size, spacing, border, shadow, overflow, and hiding wait for Preview. The editing canvas stays full-size for drag and drop, so those settings are left out while you edit and apply in Preview and on the published page. Flex-friendly settings such as gap, colours, typography, and opacity apply while you edit. Every setting has an information icon; browse them under Collection Settings in the Attribute Reference. Widget Settings (the gear on a widget) style the outer embed. Both can apply when a collection sits inside a widget — each owns its own outermost box. See Widget Settings.

Shared versus embedded when you publish

Publishing is where the two models diverge most clearly. The catalog — history, compare, republish, restore — lives on History, compare, and restore.

Shared collections have their own published key in each environment. Widgets store a reference, not a duplicate. You can publish the collection from its Publish tab, or the first time a widget that uses an unpublished shared collection is published, RuleCMS publishes that collection too. After that, publishing a new version of the shared collection updates what every live widget sees — without republishing each widget.
Embedded collections are included when you publish the parent widget. Each widget version in history carries its own embedded copies, so you can republish a previous version of the sale hero without disturbing the everyday card.
When you restore a version to your draft, embedded collections from that version are copied into the draft as fresh editable collections. Shared collections are re-linked — the shared content itself is never changed.

Removing a collection from the palette list does not remove it from pages already using it or from published content. Two embedded collections can share a display name; RuleCMS tracks each instance separately.

How this fits

A collection is a reusable block. A widget is the page. Publishing is how the site gets a snapshot. Shared collections stay one source after that snapshot; embedded copies travel inside the widget version that owns them.

Drop Maya's product card on the homepage hero as shared. On the spring-sale hero, make an embedded copy. Publish the shared card when the Featured stamp should go live everywhere that card is used.