Layout & Design Templates

1. Executive Overview

What This Module Does

The Layout & Design — Page & Email Template System provides the complete visual management layer for the Hyphen Publishing Platform. It consists of two interconnected systems:

1. Page Template System — A visual drag-and-drop page builder that lets admins create, configure, and publish page layouts across 21 page categories (homepage, article, section, author, subscription, search, campaign, archive, shop, etc.). Published templates render on the Reader Portal as the public-facing magazine.

2. Email Template System — A template management system for all transactional, lifecycle, notification, and marketing emails. Admins can customize email content, branding, and behavior through a WYSIWYG editor with variable substitution, preview, and test-send capabilities.

Who Uses It

Business Problem Solved

• Eliminates the need for code changes to modify page layouts or email styling
• Provides consistent branding across all reader-facing pages and emails
• Enables non-technical staff to control magazine appearance and communication
• Supports 20+ page types with 80+ template variants and 176+ section components
• Centralizes email branding, variable management, and delivery tracking

2. Feature Scope

In Scope

Page Template System

Email Template System

Out of Scope

• A/B testing of page templates (not implemented)
• Drag-and-drop email editor (HTML-based editing only)
• Real-time collaborative editing (single editor at a time)
• Template marketplace or third-party template import

Related Modules / Dependencies

3. Roles Involved

Page Template System

Email Template System

RBAC Permissions Required

4. Architecture & Design Overview

System Architecture

Data Flow — Page Templates

1. Admin creates/edits template in Canvas Editor
2. API saves to PostgreSQL (PageTemplate + TemplateVersion) and writes versioned JSON file to /data/templates/
3. Admin publishes template → API syncs to Strapi CMS (page-configuration content type)
4. Reader Portal fetches page configuration from Strapi → resolves template → renders sections dynamically
5. Revalidation webhook triggers ISR cache refresh on Reader Portal

Data Flow — Email Templates

1. Admin creates/edits email template in Editor (Settings → Email → Templates)
2. API saves to PostgreSQL (EmailTemplate model). Each template carries a defaultPurposeKey that drives downstream routing.
3. System event triggers email (subscription welcome, OTP, campaign send, etc.)
4. Email Pipeline resolves the template's purpose → looks up the primary account for that purpose at EmailPurposeAccount → decrypts that account's credentials → replaces variables → wraps with branding → sends via the resolved provider → logs to EmailLog with purposeKey + emailAccountId
5. Admin views delivery status in Settings → Email → Logs and aggregate analytics in Settings → Email → Dashboard

Multi-account routing is the delivery model: each canonical purpose routes to its own provider account. See the Email System Guide for the admin-facing details.

Key Entities & Models

Page Template Models (PostgreSQL/Prisma)

Strapi Content Types

Email Models (PostgreSQL/Prisma)

Settings Precedence Model

The template system follows a 5-level precedence hierarchy:

Level 1: Global platform settings (DB)     — AUTHORITATIVE, NEVER overrideable
Level 2: Global site defaults (Strapi)     — AUTHORITATIVE with selective override
Level 3: Page template defaults            — OVERRIDE spacing/layout only
Level 4: Page-specific configuration       — Per-page overrides
Level 5: Content access rules              — OVERRIDE paywall per content

5. Prerequisites & Setup Requirements

Infrastructure Prerequisites

Environment Variables Required

Admin Console

Reader Portal

Module Dependencies (Must Be Set Up First)

Seed Data Initialization

Before the template system is usable, seed data must be initialized:

1. Page Categories — Seed 21 built-in categories:

   POST /api/page-categories/seed

2. Page Templates — Seed built-in templates:

   POST /api/templates/seed

3. Email Templates — Seed default email templates (subscription, campaign, notification, OTP, and operational):

   POST /api/settings/email-templates/seed

   Or click the "Seed Missing" button in Settings → Email → Templates.

Strapi Content Types Required

The following content types must exist in Strapi:

• page-configuration (collection, draft & publish enabled)
• page-template (collection)
• page-version (collection)
• site-navigation (single type)
• site-appearance (single type)
• homepage (single type)
• static-page (collection)

6. Configuration Guide — Page Template System

6.1 Accessing the Template System

Navigate to Layout & Design in the admin console sidebar:

6.2 Understanding Page Categories

There are 21 built-in page categories:

6.3 Working with the Template Canvas Editor

Opening the Editor

1. Go to Layout & Design > Pages
2. Select a page type (e.g., Homepage)
3. Click on the assigned template or click Edit Template
4. The Canvas Editor opens with three panels:
   • Left Panel: Section Palette (drag sections from here)
   • Center Panel: Canvas Area (your page layout)
   • Right Panel: Properties Panel (configure selected section)

Adding Sections

1. In the Section Palette (left panel), browse section variants by category
2. Drag a section variant onto the Canvas Area
3. Drop it in the desired position (drop zones appear between existing sections)
4. The section appears on the canvas with default configuration

Configuring Section Properties

When you select a section on the canvas, the Properties Panel shows configuration options based on the section's behavior type:

Curated editor filters vs. reader-facing filters

There are two distinct filter layers, and it helps to keep them apart:

1. Curated editor (scope) filters — In the Properties Panel, article-sourced Listing and Contextual sections expose multi-select Section / Tag / Language dropdowns. These narrow what the section pulls (its base scope) and are baked into the published configuration. Readers never see these controls; they only see the resulting content.
2. Reader-facing per-grid filters — Article grids can additionally expose live Language / Author / Section (Category) dropdowns above the grid on the Reader Portal. These let the reader re-filter within the section's base scope. They are opt-in per section (see §6.9) and default to off, so a grid shows no reader controls unless you enable them.

Section Variant Categories

Reordering Sections

• Drag sections up or down on the canvas to reorder
• Section order property updates automatically

Removing Sections

• Select the section on the canvas
• Click the Delete/Remove button in the Canvas Toolbar or section context menu

Live Preview

• The LiveTemplatePreview component renders a real-time preview of the current template configuration
• Preview updates as you modify section properties

6.4 Template Versioning

Every template edit creates a version record:

Viewing Version History:

1. Open a template in the editor
2. Click Version History to see all versions
3. Each version shows: version number, change note, author, timestamp

Rolling Back:

1. In the version history, find the desired version
2. Click Rollback to this version
3. A new version is created with the rolled-back content (non-destructive)

6.5 Publishing Templates

Publishing syncs the template configuration to Strapi CMS, making it available to the Reader Portal.

1. Open the template in the editor
2. Review the configuration
3. Click Publish
4. The API:
   • Sets template status to active
   • Syncs template data to Strapi page-configuration content type
   • Triggers Reader Portal ISR revalidation
5. Changes appear on the Reader Portal within seconds

6.6 Managing Static Pages

1. Go to Layout & Design > Static Pages
2. Click Create to add a new page (or select existing)
3. Fill in:
   • Title — Page heading
   • Slug — URL path (e.g., about, privacy-policy, terms)
   • Category — Default: static
   • Template ID — Optionally bind to a template
   • Content — Rich text content
   • Active — Toggle visibility
4. Click Save

6.7 Managing Navigation

Navigate to Settings > Navigation or Navigation page.

Header Links

• Add, edit, reorder, or remove main navigation links
• Each link has: label, URL, and optional icon
• Changes sync to Strapi site-navigation single type

Footer Configuration

• Configure footer columns (each with title and list of links)
• Add social media links (X/Twitter, Facebook, Instagram, LinkedIn, etc.)
• Set copyright text and company information

6.8 Theme & Appearance

Navigate to Settings > Appearance.

Available customizations:

These defaults mirror the Figma "The Hyphen" design system and are kept in sync across three places: the reader globals.css :root, the reader /api/appearance structural defaults, and the admin appearance route. Changing a token in the admin overrides the corresponding default.

Changes sync to Strapi site-appearance and are consumed by the Reader Portal's ThemeProvider, which applies them as CSS variables and prefixed Tailwind classes (theme-, font-theme-, spacing-, container-width-, header-style-, footer-style-, border-style-, section-nav-).

Live Preview: The appearance editor includes a live preview panel showing how changes will look on the Reader Portal.

6.9 Reader-Facing Per-Grid Filters (Language / Author / Section)

Article grids can optionally expose live filter dropdowns to readers, letting them re-filter a grid in place. This is opt-in per section and defaults to off, so a grid shows no reader controls unless you enable them.

Supported grid variants: Grid2Column, Grid3Column, Grid4Carousel, Grid2WithSidebar, and the section-page article grid (SectionArticleGrid).

Configuration (per section, in the Properties Panel): an articleFilters config with:

How it behaves on the Reader Portal:

• No filter selected — the grid uses its server-rendered (SSR) article pool and paginates client-side. No extra network calls.
• A filter selected — the grid re-fetches server-side via GET /api/articles, combining the reader's selection with the section's base scope (the section's own filters plus any page-level section/author scope, e.g. on a Section or Author page). Results re-paginate from page 1.
• Each enabled dropdown defaults to "All …". If its option list fails to load, the dropdown still renders at its default so the grid never breaks.
• A small feedback line handles loading ("Loading articles…"), empty ("No articles match these filters."), and error (with a "Try again" retry) states.
• Selections respect the same base scope, so a grid on /fiction filtered by Author still only shows that author's fiction.

The styling reuses the same shared FilterDropdown as the standalone utility-article-filter bar, so the two look identical. You can exercise all three dropdowns on the grid variants in /preview/sections.

7. Configuration Guide — Email Template System

7.1 Accessing Email Templates

Navigate to the Email sidebar group:

/settings/emails/config redirects to /settings/emails/accounts. The full guide is at Email System Guide.

7.2 Initial Setup — Seed Default Templates

Before email templates are usable, seed the defaults:

1. Go to Settings → Email → Templates
2. Click the "Seed Missing" button in the header
3. This creates 20 default templates (only creates missing ones, never overwrites existing):

7.3 Creating / Editing Email Templates

1. Go to Settings → Email → Templates
2. Click Create New or select an existing template
3. Fill in:

7.4 Using Template Variables

Variables are placeholders that get replaced with actual values at send time.

Syntax: {{variableName}} Matching: Case-insensitive (e.g., {{userName}} matches username)

System Variables (Auto-Injected)

These are always available in every template:

CRM Variables (Auto-Injected from CRM Settings)

Context-Specific Variables

7.5 Previewing Email Templates

1. In the template editor, click Preview
2. The preview renders the template with:
   • Branding wrapper (logo, header, footer from Email Preferences)
   • Sample variable values
   • Actual styling as it would appear in email clients

7.6 Sending Test Emails

1. In the template editor, click Send Test
2. Enter a recipient email address
3. The system sends the email with:
   • [TEST] prefix in subject line
   • Sample variable values
   • Full branding wrapper
4. Check the Email Logs page to verify delivery

7.7 Configuring Email Branding (Preferences)

Navigate to Settings → Email → Templates → Preferences:

Important: Custom footer HTML is sanitized server-side to prevent XSS (strips scripts, iframes, event handlers, javascript: URLs).

7.8 Provider Configuration (Email Accounts)

Navigate to Settings → Email → Accounts and click + New email account, or click an existing row to edit:

1. Pick a provider: Custom SMTP, SendGrid, Mailchimp Transactional, AWS SES, or Postmark (immutable after save).
2. Enter provider credentials. The form encrypts them at rest with AES-256-GCM.
3. Set the sender identity (from name, from email, optional reply-to and return-path).
4. Click Save & connect — saves AND runs a connection probe in one action. The result is shown inline (latency on success, the provider's actual error message on failure).
5. To re-verify later, use Verify connection in the Diagnostics card on the account detail page. To send an actual templated probe, use Send test email in the same card.

Multiple accounts coexist side by side. Map each canonical email purpose to a primary account at Settings → Email → Purposes. The pipeline reads this mapping at every send. After every save, the resolver cache and per-account transporter are invalidated automatically — no server restart required.

7.9 Viewing Email Logs

Navigate to Settings → Email → Logs:

Additional features:

• Unsubscribe Analytics — Collapsible section showing: total unsubscribes, by reason, by category, 30-day timeline

8. How the Page Template System Works End to End

8.1 Template Lifecycle

8.2 What Happens When You Publish

1. Template status set to active in PostgreSQL
2. Template data (sections, styles, banners) synced to Strapi page-configuration
3. Strapi stores as a published document (draft/publish workflow)
4. Reader Portal receives revalidation webhook
5. Next.js ISR regenerates affected pages
6. Readers see updated layout within seconds

8.3 Reader Portal Rendering Pipeline

1. Request arrives at Reader Portal (e.g., /fiction)
2. Next.js route resolves page type (e.g., "section")
3. Fetch page-configuration from Strapi for this page type
4. Extract templateId, sections[], banners[], styles
5. TemplateRenderer maps templateId → React component
6. DynamicTemplate iterates over sections[]:
   a. Resolve section variant → SectionRenderer → actual component
   b. Fetch section data based on contentSource (dynamic queries, manual IDs, mixed)
   c. Apply personalization boost if personalizationEnabled=true
   d. Render section component with data + properties
7. PageStyleOverrides applies page-level CSS overrides
8. BannerRenderer renders active banners (checks startsAt/endsAt)
9. ThemeProvider applies global appearance (colors, fonts, spacing)

8.4 Section Data Resolution

Each section can get content from different sources:

When a grid has reader-facing filters enabled (§6.9), the initial render uses the resolved dynamic/mixed pool, but a reader selection triggers a client-side server refetch (GET /api/articles) that re-applies the section's base scope plus the chosen Language / Author / Section value.

9. How the Email Template System Works End to End

9.1 Email Pipeline Flow

9.2 Email Classes and Compliance

9.3 Unsubscribe Flow

1. Reader clicks unsubscribe link in email
2. Link contains HMAC token (generated from email + secret)
3. Reader Portal /unsubscribe page loads
4. If requireConfirmation enabled: a. Shows confirmation message b. Optional reason picker (admin-configured options) c. Grace period notice if configured
5. Reader confirms → API processes unsubscribe: a. Update Reader.newsletterOptIn b. Set AudienceContact.unsubscribedAt c. Create audit log entry d. If grace period > 0: store as pending, process via daily cron
6. Reader sees confirmation with category-specific message

10. Business Logic & Rules

Page Template Rules

Email Template Rules

Style Precedence

Global Appearance (Strapi) → Template defaultStyles → Page-specific styles

Override scope:

• spacing, containerWidth, fontFamily can be overridden at template and page level
• Colors, global fonts, and navigation are authoritative from global settings

11. Use Cases & Operational Scenarios

Page Template Use Cases

Email Template Use Cases

12. End-to-End User Flows

Flow 1: Create and Publish a New Page Template

Step 1: Admin navigates to Layout & Design > Pages
Step 2: Selects a page type (e.g., "Section")
Step 3: Clicks "Edit Template" or creates a new template
Step 4: Canvas Editor opens with three panels
Step 5: Admin drags sections from the palette onto the canvas:
        - HeroFullWidth (hero section)
        - FeaturedAboveGrid (featured articles)
        - Grid3Column (article grid)
        - NewsletterInline (newsletter signup)
Step 6: For each section, admin configures properties:
        - Content source: dynamic
        - Category filter: current section's category
        - Max items: 9
        - Sort order: newest first
Step 7: Admin clicks "Preview" to verify layout
Step 8: Admin clicks "Publish"
Step 9: System syncs to Strapi + triggers revalidation
Step 10: Reader Portal shows updated section page layout

Flow 2: Customize and Test an Email Template

Step 1: Admin navigates to Settings → Email → Templates
Step 2: Locates "Subscription Welcome" template
Step 3: Opens the editor
Step 4: Modifies subject line: "Welcome to `{{site_name}}`, `{{userName}}`!"
Step 5: Edits HTML body with updated welcome message
Step 6: Clicks "Preview" — sees rendered email with branding
Step 7: Clicks "Send Test" → enters own email address
Step 8: Receives test email with [TEST] prefix
Step 9: Verifies styling, variables, branding in email client
Step 10: Clicks "Save" to persist changes
Step 11: Future welcome emails use the updated template

Flow 3: Configure Email Branding

Step 1: Admin navigates to Settings → Email → Templates → Preferences
Step 2: Updates Header section:
        - Upload logo image URL
        - Set header background color
Step 3: Updates Footer section:
        - Company name, address
        - Social media links (Twitter, Facebook, etc.)
        - Copyright text
Step 4: Updates Unsubscribe section:
        - Grace period: 7 days
        - Require confirmation: Yes
        - Reason options: "Too many emails", "Not relevant", "Other"
Step 5: Clicks "Save"
Step 6: All future emails use updated branding

Flow 4: Manage Site Appearance and Navigation

Step 1: Admin navigates to Settings > Appearance
Step 2: Adjusts color theme (primary color, accent color)
Step 3: Selects font family for headings and body
Step 4: Adjusts spacing (container width, section padding)
Step 5: Previews changes in live preview panel
Step 6: Clicks "Save" → Strapi updated → Reader Portal revalidated

Step 7: Admin navigates to Settings > Navigation
Step 8: Adds "Programs" link to header navigation
Step 9: Reorders footer columns
Step 10: Adds Instagram social link
Step 11: Clicks "Save" → Changes appear on Reader Portal

Known Limitations

Page Template System

Email Template System

FAQ