Testimonials — Reference
The Testimonials surface is the social-proof plane for SGEN sites. It owns the operator-curated quotes that appear on landing pages, product pages, and trust sections — customer name, photo, rating, the quote itself, and the display rules that decide where each one shows up.
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 proof-program. 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
Testimonials lives under the Marketing module in SG-Admin. The module renders three primary views — the testimonial list, the create / edit form, and the display-rules editor that maps testimonials to pages or page collections — and exposes a small set of write operations for create, edit, publish, unpublish, reorder, and archive.
The module is paired by convention: one half renders the views and prepares the testimonial and display data, the other half handles writes and returns AJAX responses. Engineers reading the SG-Admin source will see this split across two controller files; the reference below describes the combined surface as it appears to a calling integration.
Testimonials are operator-curated. The surface does not collect testimonials from customers directly; submission flows live under the Forms surface. A submitted form entry is reviewed by an operator and converted into a testimonial record before it becomes eligible for display.
Where it lives in SG-Admin:
- Sidebar: SG-Admin → Marketing → Testimonials
- URL prefix:
/sg-admin/testimonials/ - View templates:
application/views/Admin/Marketing/Testimonials/
┌──────────────────────────────────────────────────────────────────────┐│ SG-Admin → Marketing → Testimonials [ + Add testimonial]│├──────────────────────────────────────────────────────────────────────┤│ Author Rating Quote (snippet) Status ││ ─────────────────── ────── ──────────────────────────── ──────────││ Maria — Founder ★★★★★ "Migrated three sites in…" published││ Ren — Agency lead ★★★★★ "We dropped our plugin…" published││ Jen — Designer ★★★★ "Onboarded the team in…" draft ││ Mark — Operator ★★★★★ "Recovered a Saturday…" published││ Sandbox account ★★★★★ "Test entry, do not display" archived ││ ││ Published: 14 · Drafts: 3 · Display rules: 22 ││ [ Edit ] [ Publish ] [ Reorder ] [ Archive ] │└──────────────────────────────────────────────────────────────────────┘Actions
The Testimonials surface exposes the following operations. Each is described by what it does to the data, not by its internal method name.
List testimonials
Returns the testimonial set paginated, with author name, rating, quote snippet, status (draft, published, archived), and a count of pages where each one is currently displayed. Supports filter by status, by rating, by author tag, and by display-target page or collection. The default view excludes archived testimonials — they remain queryable via the explicit filter.
View testimonial
Returns the full record for a single testimonial — author name, role, organization, photo URL, rating, full quote text, optional video reference, display rules, and a usage log of where the testimonial has appeared and for how long. The usage log correlates the testimonial with the pages that have rendered it.
Create testimonial
Opens an empty form. Required fields at minimum: author name, quote text, rating, status. Optional fields cover author role, organization, photo, video reference, source citation (URL or internal reference), and the initial display rule. On submit, the surface validates the photo asset if provided, persists the record at status draft, and returns the new identifier. The testimonial is not visible on the front-end until it is published.
Edit testimonial
Loads an existing record into the same form shape used for create, pre-populated. Submit replaces the stored testimonial with the posted values; fields left blank do not clear server-side values (the form is partial-update by default). Edits to a published testimonial take effect on the next page render — cached page output may serve the prior version until the cache expiry.
Publish testimonial
Transitions a draft testimonial to published. The surface validates that required fields are present, photo asset is resolvable, and at least one display rule is attached. Publish is reversible — unpublish returns the testimonial to draft state without losing the display rules.
Reorder display priority
Within a single display target (page or collection), testimonials are rendered in a priority order set by the operator. Reorder rewrites the priority slot for a given testimonial within a target, shifting the rest of the list to accommodate. Priority is per-target — a testimonial may rank first on the landing page and fifth on the pricing page.
Configure display rule
Display rules map testimonials to where they show up. A rule attaches a testimonial to one of: a specific page, a page collection (by tag, by template, by URL pattern), or a slot on the SG-Builder component palette for free placement. On submit, the surface persists the rule and refreshes the affected pages' testimonial pool.
Archive testimonial
Marks the testimonial inactive without removing it from the database. Archived testimonials disappear from the default list view and from all front-end displays. Their usage log remains attached for audit; the record itself is excluded from the display rules.
Restore from archive
Reverses an archive. The record returns to the active list at its prior status (draft if never published, published if published before archive). Display rules attached at archive time are restored alongside.
Import from form submission
A dedicated path. Reads a submitted form entry (typically a "leave us a review" form), maps the fields to the testimonial shape, presents a pre-filled draft for operator review, and persists on submit. The operator may edit any field before saving. The original form entry remains in the Forms surface for audit.
Engineering note. Form-to-testimonial conversion does not auto-publish. Operator review and explicit publish are always required before the quote becomes visible on the front-end.
Data model
A testimonial 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. |
author_name | string | Display name. Required. |
author_role | string | Optional. Title or relationship to product. |
author_organization | string | Optional. |
author_photo_url | string | Optional. Resolves against the Media library. |
quote | text | The testimonial body. Required. |
rating | integer | 1-5 stars. Optional — null hides the rating display. |
video_ref | string | Optional. Media-library or external video identifier. |
source_citation | string | Optional. Where the quote came from (URL, support ticket, form id). |
status | enum | draft, published, archived. |
tags | array | Optional. Used by display rules. |
submitted_via_form_id | integer | Optional. Set if imported from a form. |
created_at | timestamp | Set on create, immutable. |
updated_at | timestamp | Touched on any edit. |
published_at | timestamp | Set on first publish. |
testimonial_id, target_type (page, collection, slot), target_ref, priority, starts_at, ends_at. A single testimonial may carry multiple display rules; the front-end resolves them against the request URL at render time.Usage log entry: each render writes a row with testimonial_id, page_id, rendered_at, viewer_session. Used for proof-of-display reporting; retention follows the site's analytics window.
Source citation: the source_citation field is operator-only. It is not exposed on the front-end. Used for audit — proving where a quote originated, who approved it, and whether the customer consented to public use.
PAGE REQUEST│▼┌──────────────────────────────────────────┐│ Page renderer ││ ││ read testimonial slot count ││ query display rules: ││ ▶ match by page_id ││ ▶ match by collection (tags / tmpl) ││ ▶ match by URL pattern ││ filter by status = published ││ filter by schedule window ││ order by priority within target ││ apply slot count │└─────────────────┬────────────────────────┘│▼Rendered testimonials│▼Usage log entryPermissions
Access to the Testimonials 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 Testimonials surface.
Layer 2 — per-action capability. Within SG-Admin, each Testimonials 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 testimonials | ✔ | ✔ | ✔ |
| View testimonial | ✔ | ✔ | ✔ |
| View source citation | ✔ | ✔ | — |
| Create testimonial | ✔ | ✔ | — |
| Edit testimonial | ✔ | ✔ | — |
| Publish testimonial | ✔ | ✔ | — |
| Unpublish testimonial | ✔ | ✔ | — |
| Reorder priority | ✔ | ✔ | — |
| Configure display rule | ✔ | ✔ | — |
| Archive testimonial | ✔ | — | — |
| Restore from archive | ✔ | — | — |
| Import from form | ✔ | ✔ | — |
| Export usage log | ✔ | ✔ | ✔ |
Self-protection rules. A testimonial cannot be published without an attached display rule — the front-end has nowhere to render it. The surface returns a structured rejection naming the missing rule. An archived testimonial cannot be edited until restored; the archive state is read-only. The source citation may be hidden but cannot be permanently deleted while the testimonial remains queryable — audit trail must remain intact.
Audit. Every write — create, edit, publish, unpublish, reorder, rule change, archive, restore, import — emits an Activity Log entry. The log records the acting operator, the testimonial identifier, and the change shape (field-level diff for edits). Front-end renders write to the usage log; the two records are correlated by testimonial identifier.
REQUEST│▼┌───────────────────────────┐│ Admin gate │ unauth → reject└─────────────┬─────────────┘│ authed▼┌───────────────────────────┐│ Capability check │ role lacks cap → reject└─────────────┬─────────────┘│ allowed▼┌───────────────────────────┐│ Self-protection rules │ publish without rule /│ │ edit while archived → reject└─────────────┬─────────────┘│ passes▼action executes│▼Activity Log entry + usage log (on render)Related references
- Forms — Reference. Customer-submitted review entries land here. The Testimonials surface imports from a form entry; the original entry remains attached for audit via
submitted_via_form_id. - Media — Reference. Author photos and video references resolve against the Media library. Asset deletion is blocked while a published testimonial references the asset.
- Pages — Reference. Display rules target pages directly. The page record carries no testimonial fields; resolution happens at render time.
- SG-Builder Components — Reference. The Testimonials component reads from this surface. Component configuration may override the default display-rule resolution per-instance.
- Activity Log — Reference. Publish, unpublish, and archive events surface here for cross-surface auditing.
- Settings — Reference. Owns the photo asset constraints, the rating-display defaults, and the audit-log retention window.
/docs/testimonials.