Widgets — Reference
The Widgets surface is the content-zone composition plane for SGEN. It owns the catalog of widget types the platform exposes, the per-zone placement records that map widgets onto sidebar, footer, and dashboard surfaces, the drag-place ordering inside each zone, and the conditional show rules that decide whether a placed widget renders for a given page, role, or audience. Anything that asks "what appears in this sidebar / footer / dashboard zone right now?" traces back to a record managed here.
This page is a reference for platform engineers and integrators who need to understand the surface before scripting against it, extending the widget type catalog, or scoping a conditional rendering model. Customer-facing widget walkthroughs live in the customer docs set; this page describes the shape of the surface, not the steps to drive it.
Overview
Widgets live under the Widgets module in SG-Admin. The module renders three primary views — the available widget catalog (every widget type the platform exposes, grouped by category), the per-zone placement editor (a drag-place surface that arranges widgets within a zone), and the per-widget configuration form (settings specific to a placed widget instance — title, content, count, filter, conditional show rules).
The module is paired by convention with the Pages and the SG-Dashboard surfaces. Pages defines the sidebar and footer zones that hold widgets on the front-of-site surface; SG-Dashboard defines the dashboard zones that hold widgets on the operator surface. The Widgets module is the single editor for all three zone families — the placement records carry a zone identifier that points at the consuming surface, but the form and the drag-place logic are shared.
A second surface — conditional rendering — extends the model. Each placed widget can carry a set of show rules — "render only on pages matching pattern X", "render only for visitors in role Y", "render only between dates D1 and D2". The rules resolve at render time, not at save time, so a widget can appear and disappear without the placement record changing.
Where it lives in SG-Admin:
- Sidebar: SG-Admin → Widgets
- URL prefix:
/sg-admin/widgets/ - View templates:
application/views/Admin/Widgets/
┌──────────────────────────────────────────────────────────────────────┐│ SG-Admin → Widgets → Zone: Sidebar (right) │├──────────────────────────────────────────────────────────────────────┤│ AVAILABLE PLACED ││ ─────────────── ─────────────── ││ □ Search 1. ▣ Recent Posts (5 items) ││ □ Recent Posts 2. ▣ Newsletter Signup ││ □ Categories 3. ▣ Tag Cloud ││ □ Tag Cloud 4. ▣ Custom HTML — "Featured" ││ □ Newsletter Signup ││ □ Custom HTML [drag to reorder] ││ □ Recent Comments ││ □ Calendar [⋯ Configure] [⋯ Remove] ││ □ Image ││ □ Embed Show rules: 4 active ││ ││ [+ Add custom widget type] [Save zone] │└──────────────────────────────────────────────────────────────────────┘Actions
The Widgets surface exposes the following operations. Each is described by what it does to the data, not by its internal method name.
List widget types
Returns every widget type the platform exposes, grouped by category (content listings, search, navigation, marketing, custom HTML, dashboard panels, integrations). Each entry carries the type slug, display name, supported zones (sidebar, footer, dashboard, or all), the configuration schema for instances of this type, and a preview thumbnail.
List zones
Returns every widget-bearing zone the platform exposes on the site. Default zones include left sidebar, right sidebar, footer column 1, footer column 2, footer column 3, dashboard top row, dashboard middle row. The list of zones is theme-driven — a theme can declare additional zones, and zones declared by retired themes are flagged as orphan in the surface.
View zone
Loads the placement editor for a single zone. The editor shows the available widget types on the left, the currently placed widget instances on the right (in display order), and the controls for adding, removing, reordering, and configuring placements.
Place widget
Adds a widget instance to a zone. The form prompts for the type, position (insert at start, end, or between two existing entries), and the initial configuration values for the type's schema. On submit, the placement record persists and the zone re-renders on the consuming surface.
Configure placement
Opens the configuration form for an already-placed widget instance. The form renders fields from the widget type's configuration schema — for a Recent Posts widget, the count and category filter; for a Custom HTML widget, the title and HTML body; for a Newsletter Signup widget, the form ID and the list pointer. Submit persists the configuration onto the placement record.
Reorder placement
Moves a placement up or down within its zone. The position field on the placement record updates and the zone re-renders. Drag-place in the editor calls this action repeatedly as the operator drags.
Remove placement
Deletes a placement record. The widget no longer appears in the zone. The widget type itself remains in the catalog — removal is at the placement layer, not the catalog layer.
Set show rules
Records the conditional show rules for a placement. The form accepts an array of rule clauses — each clause is a field selector (page pattern, role, audience tag, date range, device class), a comparison operator (equals, matches, in, between, not), and a value. Rules combine with AND by default, with OR available per group. The resolver runs the rules at render time against the request context.
Preview zone
A diagnostic action. Given a zone identifier and a sample request context (a page identifier, a visitor role, a device class, a date), returns the resolved widget list for that context — the same list the front-end render would produce. Useful for debugging conditional rules and for integration testing.
Duplicate placement
Copies an existing placement (including all configuration values) into the same zone or a different zone. Show rules can be carried forward or reset. Useful for setting up parallel sidebars across themes or for cloning a configured widget onto a different surface.
Export zone
Produces a snapshot of every placement in a zone (type, position, configuration, show rules). Used for cloning a zone composition across sites in a multi-site deployment, for version-controlled backup of a tuned sidebar, and for shipping a zone preset alongside a theme release.
Import zone
Loads a zone snapshot. The import validates against the current widget type catalog (a snapshot from an older platform version may carry retired widget types or miss new ones). Reports per-placement success and skips, with a per-skip reason. Existing placements in the target zone are preserved or replaced based on a per-import option.
Data model
A widget type carries the following fields. The catalog is owned by the platform and by installed extensions — new types ship with module updates or with custom-extension installations.
| Field | Type | Notes |
|---|---|---|
slug | string | Widget type identifier. Stable across releases. |
display_name | string | Display label rendered in the catalog. |
category | enum | content_listing, search, navigation, marketing, custom_html, dashboard_panel, integration. |
supported_zones | JSON | Array of zone identifiers this type can be placed in. Empty array means all zones. |
configuration_schema | JSON | Field schema for instances — field name, type, default, validation. |
render_template | string | Path to the view template that renders the widget on the consuming surface. |
is_archived | boolean | True for retired types. Existing placements continue to render; new placements cannot select an archived type. |
| Field | Type | Notes |
|---|---|---|
id | integer | Primary key. |
zone_id | string | Zone identifier. Join key against the zone catalog. |
widget_type_slug | string | Widget type identifier. Join key against the widget type catalog. |
position | integer | Display order within the zone. Lower values render first. |
configuration | JSON | Per-instance configuration values, conforming to the widget type's schema. |
show_rules | JSON | Optional. Array of rule clauses governing conditional rendering. |
is_enabled | boolean | Master switch. A disabled placement never renders, regardless of show rules. |
created_at | timestamp | Set on create, immutable. |
updated_at | timestamp | Touched on any edit. |
| Field | Type | Notes |
|---|---|---|
selector | enum | page_pattern, role, audience_tag, date_range, device_class, locale. |
operator | enum | equals, matches, in, between, not_in, before, after. |
value | JSON | Operator-specific value. A matches clause carries a regex; an in clause carries an array; a between clause carries two dates. |
group | string | Optional group identifier. Clauses in the same group combine with OR; clauses across groups combine with AND. |
Configuration validation: placement configuration is validated against the widget type's schema at save time. A configuration that fails validation (missing required field, value out of range, unknown field) rejects the save with a structured per-field error list. The validation also runs at import time — invalid placements from a zone import report per-placement skips rather than corrupting the zone.
Archival semantics: a widget type is retired by setting is_archived to true. Existing placements that reference an archived type continue to render — the platform never silently drops a placement because its type has been deprecated. The catalog view flags placements pointing at archived types so operators can plan a migration to a replacement type.
RENDER REQUEST│ zone: sidebar_right│ context: { page_id: 42, role: visitor, device: mobile }▼┌───────────────────────────────────────────┐│ Fetch enabled placements for zone ││ 1. Recent Posts (rules: 0) ││ 2. Newsletter Signup (rules: 2) ││ 3. Tag Cloud (rules: 0) ││ 4. Custom HTML "Featured" (rules: 3) │└──────────────────┬────────────────────────┘│▼ evaluate show rules per placement┌───────────────────────────────────────────┐│ Placement #2 — Newsletter Signup ││ rule 1: device_class not_in [mobile] ││ → device IS mobile → FAIL ││ placement DROPPED │├───────────────────────────────────────────┤│ Placement #4 — Custom HTML "Featured" ││ rule 1: page_pattern matches /blog/.* ││ → page_id=42 is /blog/foo → PASS ││ rule 2: role in [visitor, subscriber] ││ → role=visitor → PASS ││ rule 3: date_range between [05-01,06-30]││ → today=05-21 → PASS ││ placement KEPT │└───────────────────────────────────────────┘│▼RENDER LIST1. Recent Posts3. Tag Cloud4. Custom HTML "Featured"Permissions
Access to the Widgets 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 Widgets surface. The front-end render path (the consuming surface fetching the resolved widget list) bypasses the admin gate but is read-only and never returns configuration details for placements the visitor's context excludes.
Layer 2 — per-action capability. Within SG-Admin, each Widgets 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 widget types | ✔ | ✔ | ✔ |
| List zones | ✔ | ✔ | ✔ |
| View zone (placement list) | ✔ | ✔ | ✔ |
| Place widget | ✔ | ✔ | — |
| Configure placement | ✔ | ✔ | — |
| Reorder placement | ✔ | ✔ | — |
| Remove placement | ✔ | ✔ | — |
| Set show rules | ✔ | ✔ | — |
| Preview zone | ✔ | ✔ | ✔ |
| Duplicate placement | ✔ | ✔ | — |
| Export zone | ✔ | ✔ | — |
| Import zone | ✔ | — | — |
| Register custom widget type | ✔ | — | — |
widgets.custom_html.edit. Operators without this capability can place and configure other widget types but cannot edit the body of a Custom HTML widget. The gate exists because a Custom HTML widget can introduce arbitrary markup into the consuming surface; the platform treats it as elevated.Dashboard zone protection. Dashboard zones are operator-facing — the widgets placed there appear inside SG-Admin itself. A misconfigured dashboard widget can degrade the operator experience for every administrator on the site. Dashboard zones therefore require the broader widgets.dashboard.edit capability for placement and configuration changes, separate from the front-of-site zone capabilities.
Zone orphan handling. When a theme that declared a zone is retired, the placements for that zone become orphans. The platform never silently drops orphan placements. The zone list flags orphan zones with a recovery banner — the operator can reassign the placements to an existing zone, export them for later use, or explicitly delete them. Until handled, orphan placements do not render (the zone they target no longer exists on any active surface).
Audit. Every write — placement create, configure, reorder, remove, show rule edit, zone export, zone import, custom widget type register — emits an Activity Log entry. The log records the acting operator, the zone affected, the placement identifier, and the change shape (the configuration diff for configures, the rule diff for show rule edits). Custom HTML widget edits carry the rendered preview at the time of save in the audit record, so a malicious or accidental change can be reconstructed.
ZONE EXPORT BUNDLE│▼{zone_id: "sidebar_right",exported_at: "2026-05-21T14:32:00Z",exported_by: 4, // operator user_idplatform_version: "2026.5",placements: [{widget_type_slug: "recent_posts",position: 1,configuration: { count: 5, category_filter: null },show_rules: [],is_enabled: true},{widget_type_slug: "newsletter_signup",position: 2,configuration: { form_id: 12, list_pointer: "main" },show_rules: [{ selector: "device_class", operator: "not_in",value: ["mobile"], group: "default" }],is_enabled: true},//...]}Related references
- Pages — Reference. Sidebar and footer zones live on Pages-rendered surfaces. Page records carry the zone configuration for their layout; widgets compose into those zones.
- Posts — Reference. Post-listing widgets (Recent Posts, Tag Cloud, Categories) draw from the Posts surface for their data.
- SG-Dashboard — Reference. Dashboard zones live on SG-Admin's dashboard surface. The Widgets module is the editor; the dashboard surface is the renderer.
- Settings — Reference. Theme selection and the active zone catalog come from Settings. A theme change can introduce new zones and orphan placements in retired zones.
- Media — Reference. Image widgets and Custom HTML widgets reference Media library URLs; the Media surface owns the underlying records.
- Forms — Reference. Newsletter Signup widgets and Form Embed widgets reference Form records.
- Roles — Reference. The capability map above resolves through the Roles catalog.
- Permissions — Reference. Custom HTML and Dashboard widget capabilities are defined in the Permissions catalog.
/docs/widgets.