Snippets — Reference

The Snippets surface owns small, reusable text or HTML fragments that get inserted inline inside larger content. A snippet is authored once, stored under a stable slug, and referenced from anywhere the editor exposes a snippet token. Variable substitution lets a single snippet adapt its rendered output to the 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 wiring snippets into custom email or content workflows. 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

Snippets live under the Snippets module in SG-Admin. The module renders three primary views — the snippet list, the snippet create / edit form, and the usage report — and exposes write operations for create, edit, duplicate, archive, restore, and delete.

A snippet is a short fragment — typically a sentence, a paragraph, a small HTML fragment, or a localized phrase — that gets embedded into pages, posts, product descriptions, email templates, popup bodies, or any surface that supports the snippet-token format. Snippets differ from content blocks in three ways: smaller in size (text-level, not section-level), inline-insertable into prose, and capable of variable substitution at render time.

The token format is intentionally narrow. Embedding a snippet uses {{snippet:}} for a literal fetch, or {{snippet: var1="value" var2="value"}} to pass per-embed variables that the snippet body interpolates. Variables not provided at the embed fall back to the snippet's declared defaults; variables not declared on the snippet pass through unchanged.

Where it lives in SG-Admin:

• Sidebar: SG-Admin → Snippets
• URL prefix: /sg-admin/snippets/
• View templates: application/views/Admin/Snippets/

The module surface deliberately stays narrow. Rich-format authoring (full sections, multi-column layouts, per-breakpoint styles) is the content-blocks surface; the snippets surface is for short, inline-insertable fragments. Localization variants of the same snippet group under a shared slug with locale qualifiers.

┌──────────────────────────────────────────────────────────────────────┐│ SG-Admin → Snippets [+ New snippet]├──────────────────────────────────────────────────────────────────────┤│ Slug Type Variables Used Updated│ ───────────────────────── ─────── ────────────── ─────── ────────│ legal-fineprint text — 48 1 hr ago│ support-email text — 31 3 days ago│ pricing-tier-launch text price, period 17 1 week ago│ trust-badge-strip html — 12 2 weeks ago│ greeting-localized.en text name 8 3 days ago│ greeting-localized.fr text name 4 3 days ago│ ││ [⋯ Edit] [⋯ Duplicate] [⋯ Usage] [⋯ Archive] [⋯ Delete] │└──────────────────────────────────────────────────────────────────────┘

---

Actions

The Snippets 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 snippet records on the site, with slug, type, declared variables, use count, and last-updated columns. Supports column sort, free-text filter, and a type filter (text or HTML). Driven by the standard SG-Admin data-table contract — responses arrive as a row collection plus a total count.

Create snippet

Opens an empty snippet form. Required at minimum: slug, type, body. Optional: declared variables (each with a name, a default value, and an optional description), locale qualifier, expiry date. Slugs must be unique within their locale group. Submit validates that any variable referenced in the body is declared, then persists the record.

Edit snippet

Loads an existing record into the form, pre-populated. Submit replaces the stored body and variable declarations. Edits propagate to every embedding surface on the next render.

Duplicate snippet

Clones an existing record. The clone carries the suffix -copy on its slug, lands in draft status, and has its use count reset. Useful as a starting point for a locale variant or for an A/B variant under a parallel slug.

Usage report

Returns the list of surfaces that embed the snippet — page records, post records, email templates, popup records, content blocks. The report shows the embedding record id, the surface type, and the per-embed variable overrides if any.

Archive

Sets the snippet status to archived. Archived snippets render as their last published body when embedded by existing surfaces, but they are hidden from the picker for new embeds. Useful for retiring outdated legal copy without breaking historic pages.

Restore

Reverses an archive. The snippet returns to the active list with its body, variable declarations, and use count intact.

Delete

Hard-removes the snippet record. The surface refuses the action while the snippet has any active embed; the operator must remove or repoint the embedding surfaces before delete is allowed. Deleted snippet tokens render as an empty string on surfaces that still reference them (the renderer logs a warning).

---

Data model

A snippet 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 locale group.
locale	string	Optional locale qualifier (e.g. en, fr, de).
type	enum	text (plain) or html (markup-allowed).
body	string	The snippet content. Carries variable placeholders.
variables	array	Declared variables — each with name, default, optional description.
status	enum	draft, active, archived.
use_count	integer	Number of surfaces currently embedding the snippet.
expires_at	timestamp	Optional. Snippet hides from picker after this date; existing embeds continue to render.
created_at	timestamp	Set on create, immutable.
updated_at	timestamp	Touched on any edit.

Variable substitution. The body interpolates declared variables via {var_name} placeholders. Per-embed overrides come from the token call site ({{snippet:my-slug var_name="custom"}}). Undeclared variables in the body render as the literal placeholder string (the renderer logs a warning).

Locale resolution. When the renderer encounters a snippet token on a surface that carries a locale, it walks the locale ladder — exact-match locale, language fallback, default locale — and uses the first match.

SNIPPET RECORD├── id integer primary key├── slug string url-safe handle (unique per locale group)├── locale string optional qualifier├── type enum text | html├── body string content with {var} placeholders├── variables[]│ ├── name string placeholder name│ ├── default string fallback value│ └── description string? optional├── status enum draft | active | archived├── use_count integer embeds across surfaces├── expires_at timestamp? optional retirement date└── timestamps created_at, updated_atEMBEDDING SURFACE (page body, post body, email template, etc.)└── token reference {{snippet:<slug> var1="val" var2="val"}}↓ render timerenderer fetches snippet, applies per-embed overrides,substitutes variables, returns final string

---

Permissions

Access to the Snippets 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 Snippets surface.

Layer 2 — per-action capability. Each Snippets 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 snippets	✔	✔	✔
Create snippet	✔	✔	—
Edit snippet	✔	✔	—
Duplicate snippet	✔	✔	—
Usage report	✔	✔	✔
Archive	✔	✔	—
Restore	✔	✔	—
Delete	✔	—	—

Custom roles defined under Settings → Roles override the default map. The capability slugs are stable; the role slugs are configurable.

HTML-type snippets. Snippets declared as html pass through a sanitization layer before render — script tags and event handlers are stripped, style attributes are normalized. Operators who edit HTML snippets need the same capability as content-blocks edit; the surface refuses to upgrade a text snippet to HTML without that capability.

Audit. Every write — create, edit, duplicate, archive, restore, delete — emits an Activity Log entry naming the acting operator, the target record, and the change shape.

RENDER FLOW — snippet token in page body──────────────────────────────────────────────────────────────────────1. Page body contains {{snippet:pricing-tier-launch price="$29" period="month"}}2. Renderer parses token, extracts slug + per-embed variables3. Snippet store lookup: pricing-tier-launch (locale-resolved)4. Body fetched: "Launch tier — {price} per {period}. Cancel any time."5. Variables applied: price → "$29", period → "month"6. Final render: "Launch tier — $29 per month. Cancel any time."7. Use-count incremented; render audit logged.

---

Related references

• Content blocks — Reference. Larger, section-level reusable content. Snippets are inline-insertable text; content blocks are full sections.
• Email templates — Reference. Email bodies embed snippets via the same token format. Pricing strings, support contacts, and legal lines typically live as snippets.
• Pages — Reference. Page bodies and meta fields support snippet tokens.
• Posts — Reference. Same — post bodies and excerpts support snippet tokens.
• Popups — Reference. Popup bodies support snippet tokens for shared call-to-action copy.
• Translations — Reference. Snippet locale variants group under a shared slug; the translations surface lists missing locale variants and gaps in coverage.

For the corresponding customer-facing walkthrough — creating a reusable snippet, embedding it inline, swapping legal copy across the whole site at once — see the Content section of the customer docs at /docs/content/snippets.

---

Token resolution and locale handling

When a renderer encounters a snippet token, it walks a four-step resolution ladder. Understanding the order matters for any integration that maintains parallel locale variants of the same snippet group.

1. Exact-locale match. The renderer first looks for a snippet with the requested slug and an exact locale qualifier matching the embedding surface's locale.
2. Language-family fallback. If no exact-locale variant exists, the renderer falls back to the language family — fr-CA falls back to fr, en-GB falls back to en.
3. Default-locale fallback. If no language-family variant exists, the renderer falls back to the site's configured default locale.
4. Slug-only fallback. If the snippet has no locale qualifier at all, the renderer uses the slug-only record directly.

Missing-snippet handling. If no record matches the token, the renderer emits an empty string in place of the token and logs a warning. The embedding surface continues to render. The Settings → Snippets surface exposes a missing-references report that lists every surface with an unresolvable snippet token.

Variable interpolation. Per-embed variables (the key-value pairs on the token call site) override the snippet record's declared defaults. Undeclared variables in the body render as the literal placeholder string. The renderer is intentionally tolerant — a snippet with a missing variable does not break the page.

HTML safety. Snippets typed html pass through the platform's standard sanitizer before render. Script tags and event handlers are stripped, style attributes are normalized, and any markup outside the allowlist is escaped. The sanitizer report is available on the snippet edit form's Preview tab.

Cache behavior. Snippet edits invalidate the render cache for every surface that references the edited slug. Invalidation runs synchronously on save return; the next request rebuilds against the new body and variable declarations.