Header — Reference
The Header surface owns the top chrome that renders on every public page of an SGEN site. It carries logo placement, primary navigation anchor, sticky-vs-static behavior, transparent-vs-solid mode, breakpoint variants, and the conditional rules that swap variants per page type. Anything that appears above the main content region on the public site traces back to a template 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 building a multi-site rollout. 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
Headers live under the Appearance → Header area in SG-Admin. The module renders three primary views — the header list, the header create / edit form, and the breakpoint preview pane — and exposes write operations for create, duplicate, update, version snapshot, conditional rule assignment, and delete.
A site carries one active header for each page-type context. Defaults exist for the global fallback, the home page, the blog detail, the product detail, the checkout, and the maintenance page. Each site can override any of these with a custom variant. The active variant resolves at render time by walking the page-type ladder from the most specific match down to the global fallback.
A header record carries a logo block, a primary navigation anchor (resolved against the Menus surface), an optional secondary action region (call buttons, account links, cart summary), and a stack of behavioral flags — sticky on scroll, transparent on hero, shrink on scroll, hide on scroll-down. Per-breakpoint variants override layout and visibility at desktop, tablet, mobile-landscape, and mobile-portrait widths.
Where it lives in SG-Admin:
- Sidebar: SG-Admin → Appearance → Header
- URL prefix:
/sg-admin/header/ - View templates:
application/views/Admin/Appearance/Header/
┌──────────────────────────────────────────────────────────────────────┐│ SG-Admin → Appearance → Header [+ New header]│├──────────────────────────────────────────────────────────────────────┤│ Name Applies to Status Updated ││ ───────────────────── ──────────────────── ───────── ────────── ││ Default header Global fallback Active 2 days ago ││ Home hero header Home page only Active 5 days ago ││ Checkout header Cart, checkout Active 1 week ago ││ Campaign header (paused) Draft 3 weeks ago││ ││ [⋯ Edit] [⋯ Duplicate] [⋯ Assign] [⋯ Snapshot] [⋯ Delete] │└──────────────────────────────────────────────────────────────────────┘Actions
The Header 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 header records on the site, with name, page-type assignment, status, 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 header
Opens an empty header form. Required at minimum: name and logo block. The form ships with a three-region layout — logo on the left, primary nav in the center, action region on the right — and the author swaps region positions, sets behavioral flags, and configures per-breakpoint overrides. Submit validates the breakpoint stack (no orphan overrides at undefined breakpoints) and persists the record.
Edit header
Loads an existing record into the form, pre-populated with its layout and flag state. Submit replaces the stored shape with the posted shape. Edits do not roll forward to historic snapshots; the prior state is recoverable from the snapshot history.
Duplicate header
Clones an existing record. The clone carries the suffix (copy) on its name, lands in draft status, and has its assignment scope cleared. Useful for campaign variants and seasonal variants that share a logo block and nav anchor.
Conditional assignment
Maps a header record to one or more page-type contexts. The assignment matrix carries one row per context (global, home, blog index, post detail, product detail, cart, checkout, maintenance, custom collection) and one column per available header. Exactly one assignment per context is active at a time; setting a new assignment clears the prior one. The matrix exposes a preview link per assignment so the operator can verify the rendered shape before committing.
Breakpoint variant
Defines per-breakpoint overrides on a header record. Each breakpoint slot (desktop ≥1200, tablet 768–1199, mobile-landscape 480–767, mobile-portrait <480) carries optional overrides for region order, region visibility, logo size, and nav presentation (full, condensed, hamburger). Unset slots inherit from the next-larger defined slot.
Version snapshot
Captures the current header record as an immutable snapshot. Each snapshot carries the editor identity, a timestamp, and an optional note. Snapshots are listed in the Versions tab and can be promoted back into the active record at any time.
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.
Delete
Removes a header record. The surface refuses the action if the header holds any active page-type assignment; the operator must reassign the affected contexts before delete is allowed.
Data model
A header 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. |
name | string | Display name. Not unique. |
slug | string | URL-safe handle. Unique within the site. |
status | enum | active, draft, archived. |
assignments | array | List of page-type contexts the header renders on. |
logo_block | object | Image id, link target, alt text, optional retina variant. |
nav_menu_id | integer | Reference to a Menus record for the primary nav. |
action_region | array | Ordered list of action blocks (call-to-action, account, cart, search). |
flags | object | Sticky, transparent-on-hero, shrink-on-scroll, hide-on-scroll-down. |
breakpoints | object | Per-breakpoint override map. |
created_at | timestamp | Set on create, immutable. |
updated_at | timestamp | Touched on any edit. |
published_at | timestamp | Set when status moves to active. |
Breakpoint inheritance. A breakpoint slot left undefined inherits from the next-larger defined slot. The desktop slot is always defined; the rest cascade downward.
HEADER RECORD├── id integer primary key├── name string display├── status enum active | draft | archived├── assignments array page-type contexts├── logo_block object image id, link, alt├── nav_menu_id integer Menus reference├── action_region array call | account | cart | search├── flags object sticky | transparent | shrink | hide-on-down├── breakpoints│ ├── desktop object ≥1200px│ ├── tablet object 768–1199px (inherits)│ ├── mobile-l object 480–767px (inherits)│ └── mobile-p object <480px (inherits)└── timestamps created_at, updated_at, published_at↓ on snapshotHEADER VERSION RECORD(immutable; restorable via promote)Permissions
Access to the Header 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 Header surface.
Layer 2 — per-action capability. Each Header 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 headers | ✔ | ✔ | ✔ |
| Create header | ✔ | ✔ | — |
| Edit header | ✔ | ✔ | — |
| Duplicate header | ✔ | ✔ | — |
| Assign to page-type | ✔ | — | — |
| Configure breakpoints | ✔ | ✔ | — |
| Snapshot | ✔ | ✔ | — |
| Promote snapshot | ✔ | — | — |
| Delete header | ✔ | — | — |
Assignment guard. A header cannot be deleted while it holds an active assignment. The surface lists the blocking contexts in the rejection payload.
Audit. Every write — create, edit, duplicate, assignment change, breakpoint change, snapshot, promote, delete — emits an Activity Log entry naming the acting operator, the target record, and the change shape.
BREAKPOINT CASCADE desktop tablet mobile-L mobile-P─────────────────────────────────────────────────────────────────────────Region order L | N | A L | N | A L | A L | ALogo width 180px 150px 120px 100pxPrimary nav full full hamburger hamburgerAction region visible visible collapsed icon-onlySticky on scroll ● ● ● ●Transparent on hero ● ● ○ ○Shrink on scroll ● ● ○ ○(Undefined slots inherit from the next-larger slot.)Related references
- Footer — Reference. Owns the bottom chrome. Same model shape — columns, blocks, page-type assignment, snapshot history.
- Menus — Reference. The header's primary nav anchor and any secondary action menu reference menu records by id.
- Pages — Reference. Page records can override the resolved header with a per-page header slug, taking precedence over the assignment matrix.
- Media — Reference. Logo image assets resolve against the Media library; retina variants resolve as the next-resolution sibling.
- Settings — Reference. Default flag state for new headers, transparent-mode thresholds, and locale strings for account-state labels live under Settings.
- Content blocks — Reference. Action-region blocks that wrap a custom announcement bar or promo region pull from the content-blocks surface.
/docs/appearance/header.Render resolution order
When a public page renders, the active header is resolved through a five-step ladder. Understanding the order matters for any integration that swaps header variants by campaign, page-type, or per-page override.
- Per-page override. The page record's optional
header_slugfield, if set, wins outright. The Pages surface exposes this field on the page edit form. - Page-type assignment. The header assignment matrix is consulted for the page's resolved page-type. The most specific match wins (home beats global, product detail beats global).
- Custom collection match. Page collections (a curated set of pages grouped under a label) can carry a collection-level header assignment. The collection assignment beats page-type assignment when both apply.
- Locale fallback. If the site runs multiple locales and the resolved header has a locale-specific sibling, the sibling renders.
- Global fallback. The header marked as the global fallback in the assignment matrix renders if no other step resolved.
Flag composition. The active flag set is the merge of the header record's base flags and any per-breakpoint flag overrides. Conflicting flags (transparent-on-hero without sticky, shrink-on-scroll without sticky) are resolved by the validation rules at save time, so the renderer never sees a conflicting combination.
Cache invalidation. Header edits invalidate the render cache for every page whose resolution path passes through the edited record. The invalidation runs asynchronously; a forced flush is available from the Settings → Cache surface.