Content blocks — Reference
The Content blocks surface owns reusable section-level content that lives independently of any single page. A content block is authored once, stored under a stable id, and inserted into pages, posts, products, or any other surface that exposes a block-pick field. Updates to the block propagate to every surface that embeds it.
This page is a reference for platform engineers and integrators who need to understand the surface before extending it, scripting against it, or building a content-reuse workflow across many sites. Customer-facing how-tos live in the customer docs set; this page describes the shape of the surface, not the steps to drive it.
Overview
Content blocks live under the Content blocks module in SG-Admin. The module renders three primary views — the block list, the block create / edit form, and the version-history pane — and exposes write operations for create, edit, duplicate, version snapshot, promote snapshot, archive, and delete.
A content block is a complete section — typically the same size and shape as a single SG-Builder section on a page — that carries its own column tree, block tree, and per-breakpoint styles. The composition contract matches the SG-Builder editor exactly; a block authored in the editor is structurally identical to a section authored directly in a page, with the difference that the block has a stable id of its own and is editable from a central screen.
Inserting a content block into a page records a reference, not a copy. The page render fetches the block at render time. When the block is edited, every page that embeds it reflects the change on the next render. A page can optionally pin a block to a specific version snapshot, in which case the page render uses that snapshot until the pin is updated.
Where it lives in SG-Admin:
- Sidebar: SG-Admin → Content blocks
- URL prefix:
/sg-admin/content-blocks/ - View templates:
application/views/Admin/ContentBlocks/
┌──────────────────────────────────────────────────────────────────────┐│ SG-Admin → Content blocks [+ New block] │├──────────────────────────────────────────────────────────────────────┤│ Name Category Used on Updated ││ ────────────────────────── ────────────── ─────────── ────────── ││ Hero — feature launch Marketing 12 pages 2 hr ago ││ CTA — start free trial Marketing 37 pages 1 day ago ││ Pricing table — 3-tier Sales 4 pages 3 days ago ││ Trust strip — logos Brand 22 pages 1 week ago ││ Footer banner — promo Seasonal 0 pages 2 weeks ago││ ││ [⋯ Edit] [⋯ Duplicate] [⋯ Snapshot] [⋯ Where used] [⋯ Archive] │└──────────────────────────────────────────────────────────────────────┘Actions
The Content blocks surface exposes the following operations. Each is described by what it does to the data, not by its internal method name.
List and search
Returns the content block records on the site, with name, category, use count, and last-updated columns. Supports column sort and free-text filter. Driven by the standard SG-Admin data-table contract — responses arrive as a row collection plus a total count.
Create block
Opens an empty content block form. Required at minimum: name and category. The form lands the operator in the SG-Builder editor in a single-section canvas. Submit captures the column tree, the block tree, and the per-breakpoint style stack as a fresh content block record.
Edit block
Loads an existing record into the SG-Builder editor, pre-populated with its tree. Save replaces the stored tree with the posted tree. Edits propagate to every embedding surface on the next render; surfaces pinned to a prior snapshot continue to render that snapshot.
Duplicate block
Clones an existing record. The clone carries the suffix (copy) on its name, lands in draft status, and has its use count reset. The version history of the source block does not clone — the duplicate starts with a fresh snapshot lineage.
Version snapshot
Captures the current block as an immutable snapshot. Each snapshot carries the editor identity, a timestamp, an optional note, and a tag. Snapshots are listed in the Versions tab and serve as the targets for surface-level pins.
Promote snapshot
Reverses a snapshot back into the active record. The current shape is captured into a fresh snapshot before the promotion runs, so no edit history is ever lost.
Where used
Returns the list of surfaces that embed the block — pages, posts, product detail templates, footer slots, popup slots. The list reports the embedding record id, the surface type, and whether the embed is pinned to a specific snapshot.
Archive
Sets the block status to archived. Archived blocks remain available for read but cannot be embedded into new surfaces. Existing embeds continue to render. Useful for retiring seasonal content without breaking historic pages.
Delete
Hard-removes the block record. The surface refuses the action while the block has any active embed; the operator must remove or repoint the embedding surfaces before delete is allowed.
Data model
A content block record carries the following fields. Field names below are the conceptual shape — on-disk column names match closely but are not contractually stable across releases.
| Field | Type | Notes |
|---|---|---|
id | integer | Primary key. Stable across edits. |
slug | string | URL-safe handle. Unique within the site. |
name | string | Display name. Not unique. |
category | string | Taxonomy slug. Drives list filtering. |
tags | array | Optional free-form tags. |
status | enum | draft, active, archived. |
tree | object | The SG-Builder column tree, block tree, and style stack for the section. |
use_count | integer | Number of surfaces currently embedding the block. |
created_by | integer | User id of the original author. |
created_at | timestamp | Set on create, immutable. |
updated_at | timestamp | Touched on any edit. |
published_at | timestamp | Set when status first moves to active. |
Snapshots. Each snapshot is an immutable copy of the tree plus a tag. Snapshot ids are stable across promotions; the active record always carries a pointer to the most recent snapshot id.
CONTENT BLOCK RECORD├── id integer primary key├── slug string url-safe handle├── name string display├── category string taxonomy slug├── tags array optional├── status enum draft | active | archived├── tree object SG-Builder column + block + style stack├── use_count integer embeds across surfaces└── timestamps created_at, updated_at, published_at↓ on snapshotCONTENT BLOCK SNAPSHOT├── tree object immutable copy├── tag string optional label└── created_at timestampEMBEDDING SURFACE (page, post, product, etc.)└── block_ref├── block_id integer└── pin_to snapshot_id? optional version pinPermissions
Access to the Content blocks surface is gated at two layers.
Layer 1 — admin gate. Every action under SG-Admin passes through the platform's standard admin access check at request entry. An unauthenticated request never reaches the Content blocks surface.
Layer 2 — per-action capability. Each Content blocks action checks a capability associated with the calling operator's role. The default role configuration ships with three roles — Administrator, Editor, Viewer — and the capability map is:
| Capability | Administrator | Editor | Viewer |
|---|---|---|---|
| List blocks | ✔ | ✔ | ✔ |
| Create block | ✔ | ✔ | — |
| Edit block | ✔ | ✔ | — |
| Duplicate block | ✔ | ✔ | — |
| Snapshot | ✔ | ✔ | — |
| Promote snapshot | ✔ | — | — |
| Where used | ✔ | ✔ | ✔ |
| Archive | ✔ | ✔ | — |
| Delete | ✔ | — | — |
Embed guard. A block cannot be deleted while it has any active embed. The surface lists the blocking embeds in the rejection payload so the operator can resolve them.
Audit. Every write — create, edit, duplicate, snapshot, promote, archive, delete — emits an Activity Log entry naming the acting operator, the target record, and the change shape (tree-level diff for edits).
WHERE USED — "Hero — feature launch"──────────────────────────────────────────────────────────────────────Page: Home pinned to: latestPage: Product / SG-Builder pinned to: latestPage: Product / SG-Dashboard pinned to: snapshot #14Post: 2026-05-12 launch announcement pinned to: latestPost: 2026-04-30 dashboard release pinned to: snapshot #11Footer: Default footer (column 2) pinned to: latestTotal: 12 surfaces · 2 pinned to historic snapshotsRelated references
- Snippets — Reference. Smaller, inline-insertable reusable fragments. Content blocks are section-sized; snippets are text-sized.
- Pages — Reference. Pages embed content blocks as section references and can pin to specific snapshots.
- Posts — Reference. Posts embed content blocks the same way pages do.
- Products — Reference. Product detail templates embed content blocks for shared marketing sections (FAQ strip, trust row).
- Footer — Reference. Footer columns can carry a content-block reference for promo and announcement strips.
- Activity log — Reference. Every block write emits an audit entry — useful for tracing which surface broke after a block edit.
/docs/content/blocks.Embed resolution and propagation
When a surface that embeds a content block renders, the block reference is resolved through a three-step ladder. Understanding the order matters for any integration that uses snapshot pins to lock historic content.
- Snapshot pin. If the embedding surface declares
pin_to:, the renderer fetches that exact snapshot. The pin survives subsequent block edits. - Active record. If no pin is declared, the renderer fetches the current state of the block record. Edits to the block roll forward to every surface in this state on the next render.
- Fallback empty. If the referenced block has been deleted (and embed guard was bypassed by a force-delete capability), the renderer emits an empty section and logs a warning. The embedding surface continues to render.
Where-used drift. The use_count field is updated when surfaces add or remove a block reference. The count can drift if an embedding surface is force-deleted without removing its block references first; the Settings → Cache surface exposes a recount action that rebuilds the field from the surface store.
Snapshot retention. Snapshots are retained until manually deleted or until the block itself is deleted. The retention window is not capped by default; sites with high snapshot volumes can configure a cap under Settings → Content blocks.
Performance note. A page that embeds many large content blocks fetches each block at render time. The render cache amortizes the cost across requests, but the cold-cache render of a page with twenty embeds will measurably take longer than the same page with all sections authored inline.