Gallery — Reference
The Gallery surface is the curated-image plane for every SGEN site. It owns the gallery record, the ordered image collection that backs it, lightbox and grid presentation configuration, and the embed handles used by pages, posts, and templates. Anything that surfaces as an operator-curated photo set on a published page traces back to a record managed here.
This page is a reference for platform engineers and integrators who need to understand the surface before extending it, scripting against it, or scoping a presentation tier. 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
Galleries live under the Gallery module in SG-Admin. The module renders three primary views — the gallery list, the gallery editor (image picker plus ordering plus per-image caption), and the gallery embed-handle index — and exposes a small set of write operations for create, edit, reorder, duplicate, soft delete, and restore.
The module is paired by convention with the Media library. Media holds the raw image record (file, dimensions, alt text, storage location); a gallery holds an ordered list of references to media records plus per-image gallery-scoped overrides (caption, link target, sort weight). Editing the underlying media record updates every gallery that references it; reordering or captioning inside a gallery does not touch the media record.
A second surface — gallery embed handles — lives adjacent to the Gallery module. Each gallery exposes a stable handle ({{gallery: and a numeric id) that pages, posts, and SG-Builder components resolve at render time. The handle index lets operators see every page that references a gallery before they edit or delete it.
Where it lives in SG-Admin:
- Sidebar: SG-Admin → Gallery
- URL prefix:
/sg-admin/gallery/ - View templates:
application/views/Admin/Gallery/
┌──────────────────────────────────────────────────────────────────────┐│ SG-Admin → Gallery [+ New gallery] │├──────────────────────────────────────────────────────────────────────┤│ Name Images Used on Updated ││ ───────────────────── ────── ──────────── ──────────────────────││ Homepage hero rotator 8 3 pages 2 hours ago ││ Product feature shots 24 12 pages yesterday ││ Team headshots 11 About page 4 days ago ││ Event recap — Q1 mixer 47 1 blog post 2 weeks ago ││ Press logos 6 Homepage a month ago ││ ││ Filter: [Used on ▼] [Recent ▼] Bulk: [Duplicate] [Soft delete] │└──────────────────────────────────────────────────────────────────────┘Actions
The Gallery 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 gallery records visible to the current operator, paginated, with name, image count, usage count, and updated-at columns. Supports column sort, free-text filter, and a usage-count filter that surfaces unused galleries. Driven by the data-table contract used across SG-Admin modules — responses arrive as a row collection plus a total count, suitable for direct binding to a paged grid.
Engineering note: the usage count column is computed by scanning page and post content for the gallery handle. The scan is cached and refreshed on any write to a page, post, or SG-Builder template.
Create gallery
Opens an empty gallery composer. Required at minimum: name. Optional fields at create time cover slug (auto-derived from name), display mode (grid / carousel / masonry / lightbox-only), thumbnail size preset, and per-row count. Images can be added immediately from the Media library picker or attached later. On submit, the surface validates slug uniqueness, persists the record, and returns the new identifier plus the embed handle.
Edit gallery
Loads an existing record into the gallery composer, pre-populated with the current image set and presentation config. Operators can add, remove, and reorder images; edit per-image captions, link targets, and visibility flags; and adjust display mode and thumbnail config. The form is partial-update by default — fields left blank do not clear server-side values.
Reorder images
A focused write path. Accepts an ordered list of image identifiers and rewrites the sort weights on the gallery's image collection. Reorder is a separate action from edit because it is the most common operation against an established gallery and benefits from a leaner payload. Drag-and-drop reordering in the composer calls this path.
Engineering note: image sort weights are sparse integers (10, 20, 30,...) rather than contiguous (0, 1, 2,...) so that inserts between two items do not force a rewrite of every following weight. The surface compacts the weight range on demand when sparse gaps grow large.
Duplicate
Creates a new gallery record carrying the same image set, per-image overrides, and presentation config as the source. The duplicate gets a new identifier, a new slug (source slug plus -copy suffix, made unique), and an empty usage list. Operators use this to fork a gallery for a variant page without affecting the original.
Set as featured
Marks the gallery as featured for a named scope (site-wide, per-category, per-section). Featured galleries are surfaced to the storefront and homepage templates via a dedicated handle ({{gallery:featured}} plus optional scope suffix). Only one gallery can hold the featured flag per scope; setting a new featured releases the prior one.
Soft delete
Marks the record inactive without removing it from the database. Soft-deleted galleries disappear from the default list view but remain queryable via the archive filter. References from pages, posts, and templates resolve to an empty render until the gallery is restored or replaced.
Restore
Reverses a soft delete. The record returns to the active list with its prior image set, presentation config, and usage list intact. Pages that previously referenced the gallery render its images again on next view.
Permanent delete
Hard-removes the record. Available only after a soft delete. Pages, posts, and templates that referenced the gallery handle render an empty block on next view; the surface returns a structured list of affected pages at delete time so operators can scope a replacement plan. This path is irreversible.
Data model
A gallery record carries the following fields. Field names below are the conceptual shape — the 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 | Unique. Used in the embed handle {{gallery:. |
name | string | Display name. Not unique. |
description | string | Optional. Surfaced to some templates as a caption block. |
display_mode | enum | grid, carousel, masonry, or lightbox-only. |
thumbnail_size | enum | small, medium, large, or custom (paired with width / height fields). |
per_row | integer | Used by grid and masonry modes. |
lightbox_enabled | boolean | Enables click-to-enlarge overlay across modes. |
images | array | Ordered list of gallery_image references — see below. |
usage | array | Computed at scan time — page / post / template handles that reference this gallery. |
status | enum | active, inactive (soft-deleted), or archived. |
featured_scope | string | Optional. Set when the gallery holds a featured flag. |
created_at | timestamp | Set on create, immutable. |
updated_at | timestamp | Touched on any edit. |
images carries:| Field | Type | Notes |
|---|---|---|
media_id | integer | References the Media library record. |
sort_weight | integer | Sparse weight (10, 20, 30,...) determines order. |
caption | string | Optional gallery-scoped caption. Overrides media-record default. |
link_target | string | Optional URL. Click target overrides lightbox when set. |
visible | boolean | Per-image hide flag. Hidden entries stay in the record but skip render. |
images[].media_id resolves at render time against the live Media library. Updating the media record (alt text, file replacement, crop) propagates to every gallery that references it. Per-image gallery-scoped overrides (caption, link target) are stored on the gallery record and do not change the media record.Soft-delete semantics: status = inactive is the soft-deleted state. Image references and per-image overrides are retained. Restore returns the gallery to active without re-fetching media records.
Featured scope: featured_scope is a string discriminator ("" for the default site-wide scope, or a section / category slug for narrower scopes). The uniqueness constraint is on featured_scope — at most one featured gallery per scope.
GALLERY RECORD├── id integer primary key├── slug string unique, drives {{gallery:<slug>}} handle├── name string display├── presentation display_mode + thumbnail_size + per_row + lightbox_enabled├── images array ordered list of references — sparse sort_weight│ └── per-image: media_id, sort_weight, caption, link_target, visible├── usage array computed scan — pages/posts/templates that reference├── featured_scope string optional uniqueness key for featured flag├── status enum active | inactive | archived└── timestamps created_at, updated_at↓ image render resolvesMEDIA LIBRARY RECORD (live — see Media — Reference)alt, dimensions, file, storage location, srcsetPermissions
Access to the Gallery 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 Gallery surface.
Layer 2 — per-action capability. Within SG-Admin, each Gallery action checks a capability associated with the calling operator's role. The default role configuration ships with three media-adjacent roles — Content Editor, Designer, Read-only Reviewer — layered on top of the platform's base roles. The capability map is:
| Capability | Administrator | Content Editor | Designer | Reviewer |
|---|---|---|---|---|
| List galleries | ✔ | ✔ | ✔ | ✔ |
| View gallery detail | ✔ | ✔ | ✔ | ✔ |
| Create gallery | ✔ | ✔ | ✔ | — |
| Edit gallery (images + captions) | ✔ | ✔ | ✔ | — |
| Reorder images | ✔ | ✔ | ✔ | — |
| Edit presentation config | ✔ | — | ✔ | — |
| Duplicate gallery | ✔ | ✔ | ✔ | — |
| Set featured | ✔ | — | ✔ | — |
| Soft delete | ✔ | — | ✔ | — |
| Restore | ✔ | — | ✔ | — |
| Permanent delete | ✔ | — | — | — |
Self-protection rules. A gallery that holds the featured flag cannot be soft-deleted without first releasing the flag or transferring it to another gallery in the same scope. A gallery currently referenced by published pages can be soft-deleted but produces a confirmation prompt listing the affected pages; permanent delete on the same record returns the affected-page list as a structured response rather than blocking.
Audit. Every write — create, edit, reorder, duplicate, featured-flag transfer, soft delete, restore, permanent delete — emits an Activity Log entry. The log records the acting operator, the target record, and the change shape (image-list diff for edits, weight diff for reorders). Activity Log retention is governed by the site's general settings.
REQUEST│▼┌───────────────────────────┐│ Admin gate │ unauth → reject└─────────────┬─────────────┘│ authed▼┌───────────────────────────┐│ Capability check │ role lacks cap → reject│ (per-action, per-role) │└─────────────┬─────────────┘│ allowed▼┌───────────────────────────┐│ Featured + usage guards │ delete-of-featured / delete-of-in-use│ │ → confirmation prompt or affected list└─────────────┬─────────────┘│ passes▼action executes│▼Sparse sort-weights rewrittenActivity Log entry writtenRelated references
- Media — Reference. Owns the underlying image records. Gallery image references resolve against Media at render time; edits to a media record propagate to every gallery using it.
- Videos — Reference. The video-asset analogue of this surface — curated video collections with their own presentation and embed-handle index.
- Pages — Reference. Page content references galleries via the
{{gallery:handle. The usage scan that backs the Gallery list view reads from page content.}} - Posts — Reference. Blog posts reference galleries the same way pages do. Permanent delete of an in-use gallery returns the affected post list.
- Custom Codes — Reference. Storefront and template surfaces can resolve gallery handles inside custom blocks. The handle format is stable across template surfaces.
- Settings — Reference. Owns the default presentation config (thumbnail size presets, default display mode, lightbox styling) inherited by new galleries.
/docs/gallery.