Collections

Model structured content with shared and embedded collections — reuse blocks across pages, or keep sections tied to a single widget version.

What are collections?

A collection is a reusable block of layout and content — rows of components, just like a widget, but designed to be dropped into pages and other collections. Use collections for anything you want to repeat: a product card, a testimonial strip, a footer, a pricing table, or a whole hero section.

Collections appear in the composer under the User Collections tab in the left palette. You can drag them onto any widget or collection you are editing, or open them in the composer to change their structure. See The Composer for palette basics.

Two ways to reuse: shared and embedded

RuleCMS gives you two distinct reuse models. Choosing the right one is the most important decision when you structure content for scale.

	Shared collection	Embedded collection
What it is	A standalone collection on your team. One source of truth, used in many places.	A copy that belongs to one parent widget or collection. Strongly tied to that parent's version.
Where you edit it	Open the collection from the palette or collections list — it has its own composer page.	From the parent widget or collection via Modify Embedded Collection in the Modify Display panel.
When you change it	Every draft widget or collection that references it sees the change immediately (unpublished work only).	Only this instance on this parent changes. Other parents are unaffected.
When you publish	Published once per environment. Widgets reference the live shared version — they do not duplicate its content.	Copied along with the parent widget each time you publish. Each published widget version keeps its own embedded copies.
Best for	Global content that should stay in sync everywhere: disclaimers, nav blocks, shared promos, legal text, design-system sections.	Layout that is part of a specific page: a unique sidebar on one landing page, a one-off form block, A/B variants tied to one widget.

Think of shared collections like a shared component library for structured content: update once, every consumer picks it up on the next publish. Embedded collections are like page-owned sections: they travel with that widget's history and can differ from version to version without affecting anything else.

Collection management pages

Collections for an environment are managed at these routes (replace path segments with your org, team, project, and environment ids):

List and search — …/e/[environmentId]/collections
Create — …/collections/new
Manage one collection — …/collections/[collectionId] (rename, copy, promote, publish, open in composer)
Edit in composer — …/composer/collections/[collectionId] (via the catch-all composer route)

Creating and using shared collections

Create a collection from your team's collections area (or save existing layout as a collection from the composer).
Build the collection in the composer — add rows, components, and nested collections as needed.
Drag it from the User Collections tab onto any widget or collection you are editing.
To change the shared source, click the collection on the canvas and choose Modify Shared Collection in the Modify Display panel.

Shared collections can be published on their own (from the collection's Publish tab) or automatically the first time a widget that uses them is published. After that, publishing a new version of the shared collection updates what every live widget sees — without republishing each widget.

What happens on the live site when a shared collection updates

Suppose a disclaimer collection is used in ten published widgets. You edit the disclaimer and publish a new version of the collection. All ten widgets immediately resolve to the updated disclaimer content on the next request (after cache refresh). You did not need to touch the ten widgets individually. That is the power of shared collections for operational content.

Creating and using embedded collections

Embedded collections start life in one of two ways:

You place a shared collection on a page and choose Make Embedded Copy And Modify in the Modify Display panel — RuleCMS creates a private copy attached to that parent only.
You build or nest a collection while editing inside a widget or another collection, and RuleCMS records it as embedded (it has a parent and shows an Embedded badge on its management page).

Embedded collections cannot be published on their own. They are always published as part of their parent widget (or parent collection tree). When you publish the widget, RuleCMS walks the tree, copies each embedded collection for that publish event, and wires the parent configuration to those copies.

Nested trees: embedded inside embedded, shared in the mix

Collections can nest freely. A typical pattern:

Widget root contains an embedded "page body" collection.
That body embeds a shared "product card" collection (same card everywhere in the product catalog widgets).
The body also embeds another embedded "sidebar" collection unique to this page.

On publish, shared nodes stay as references to the live shared published collection. Embedded nodes at every depth are copied so this widget version owns its full subtree. That is how you combine global consistency (shared) with page-specific structure (embedded) in one configuration.

Choosing the right model

Use this quick guide when you add a collection to a page:

Will this exact block need to differ on another page? → Prefer embedded (or make an embedded copy from a shared starting point).
Should a single edit propagate to many pages after publish? → Use a shared collection and reference it everywhere.
Need a reusable starting point you customize per page? → Start from a shared collection in the palette, then Make Embedded Copy And Modify on each page that needs its own variant.
Do you need independent version history per page? → Keep page-specific parts embedded so each widget publish snapshot includes its own copies. Shared parts inherit live shared content instead.

Editing without surprises

Shared collection edits

When you modify a shared collection, the UI warns you that unpublished widgets and collections referencing it will pick up the change. Already published pages stay on their last published snapshot until you publish again (widget and/or shared collection, depending on what changed).

Embedded collection edits

Editing an embedded collection only affects that parent's draft. Sibling pages that embedded a copy from the same shared collection are unaffected — each embedded copy is its own record.

Collections and publishing

Publishing behavior is where shared and embedded collections diverge most clearly:

Shared collections are published to staging or production independently. Their published key is stable per environment. Widgets store a reference, not a duplicate.
Embedded collections are included when you publish the parent widget. Each widget version in history carries its own embedded copies, so you can restore an old widget layout without disturbing other pages — see Republish a previous version in the Publishing guide.
The same rules apply when you restore a version to your draft: embedded collections from that version are copied into the draft as fresh editable collections, while shared collections are simply re-linked — the shared content itself is never changed.

For the full publish workflow, version history, compare tools, rollback-style republish, and restore to draft, read Publishing.

Good to know

Empty collections cannot be dragged from the palette — add at least one row before reusing.
Removing a collection from the palette list does not remove it from pages already using it or from published content.
The Collection Dependencies tab on a widget or published version shows every shared and embedded collection in the tree — useful for auditing what a publish will touch.
Multiple embedded collections can share the same display name; RuleCMS tracks each instance separately so they publish independently.