feat(postcard): finished default layout with logo header, footer and site name
- default.htm ports WinterCMS's default layout: wrapper, header row with the Branding logo (or the site name), the inner-body card and a copyright footer; its text wrapper ends with the footer - built-in header and footer partials (logo/body/url, body) - layouts get siteName (Branding site name, else the display name of mail.from) and year; Brand.SiteName and migration 202611130002_mail_brand_site_name - cabana Branding form gets site_name (trimmed, max 255), mapped into the Branding preview draft; en/pl copy; img.logo brand CSS - 35-06 Task 1 (G-35-8)
This commit is contained in:
@@ -30,7 +30,7 @@ Use cases:
|
||||
- Safety checks: rendered HTML with script, iframe, object or embed tags, inline event handlers or `javascript:`/`vbscript:`/`data:` URLs is rejected; CR/LF in the subject or address headers is rejected; addresses are parsed with `net/mail`.
|
||||
- Drivers behind the `postcard.Driver` interface: `postcard.MemoryDriver` (keeps messages for tests), `postcard.LogDriver` (logs headers and the text part through `log/slog`, never the HTML or credentials), `postcard.SMTPDriver` (go-mail with an explicit TLS policy) and `postcard.FailDriver` (a deterministic failure for tests).
|
||||
- Database overrides: a customized row of `system_mail_templates` replaces a template's subject, body and layout, a customized row of `system_mail_layouts` or `system_mail_partials` replaces a layout or a partial, and `system_mail_layouts` also holds layouts that exist only in the database. The mailer reads them on every send, with no cache, in every process that publishes a `*gorm.DB`. A missing database, tables that are not migrated yet, or an override that does not render or fails the safety checks sends the file version.
|
||||
- Branding: once the branding settings have been saved, the brand CSS is compiled from their colours (`postcard.CompileBrandCSS`) and replaces `mail.brandCss`, and layouts get the logo's absolute URL as `{{ .logoUrl }}`.
|
||||
- Branding: once the branding settings have been saved, the brand CSS is compiled from their colours (`postcard.CompileBrandCSS`) and replaces `mail.brandCss`, and layouts get the logo's absolute URL as `{{ .logoUrl }}` and the site name as `{{ .siteName }}` (else the display name of `mail.from`). The built-in default layout shows them in a header and a copyright footer.
|
||||
- Sample values: a template's header may give its variables sample values with `sample.<path>` keys. Previews and save checks use them, and show every other variable as a visible `[path]` placeholder.
|
||||
- An editor API for admin code (`postcard.Editor`): validate, preview and test-send an unsaved draft of a template, layout or partial through the same render path as a real send; one index row per file (`postcard.SyncIndex`) with a hash of the file for detecting that it changed under an override, and reset to the file version (`postcard.ResetOverride`).
|
||||
- No locale selection: callers pass the full template name, including any locale suffix. A `<template>-<locale>` name whose locale ships no file sends the default-locale version (see "Locale variants").
|
||||
@@ -175,18 +175,22 @@ Markdown drops raw HTML, so a call in a body does not insert the partial's HTML
|
||||
|
||||
| Layout alias | Full name | Renders |
|
||||
|--------------|-----------|---------|
|
||||
| `default` | `postcard::mail.layouts.default` | The message in a `content-body` block. Used when a template names no layout. |
|
||||
| `default` | `postcard::mail.layouts.default` | WinterCMS's default layout (`wrapper layout-default`): the `header` partial with the logo or the site name, the message in the `inner-body` card, and the `footer` partial with `© <year> <site name>`. Used when a template names no layout. |
|
||||
| `system` | `postcard::mail.layouts.system` | WinterCMS's system layout: the message in a centred table, followed by a note that the message is automatic. |
|
||||
| `minimal` | `postcard::mail.layouts.minimal` | The message directly in the page body. |
|
||||
|
||||
A template selects one with `layout = "system"`. A plugin's own alias of the same name wins, except `default`, which plugins cannot redefine. Every built-in layout has the `{{ .brandCss }}{{ .css }}` style block.
|
||||
|
||||
Both wrappers of every layout get these keys: `Content`, `Subject`, `css`, `brandCss`, `logoUrl` (see [Branding](#branding)), `siteName` (the Branding's site name, else the display name of `mail.from`, else empty) and `year` (the current year). The default layout calls the header only when `logoUrl` or `siteName` is set, and builds the footer line from `year` and `siteName`, `© 2026 Acme`, or `© 2026` without a name. Its text wrapper is the message, a blank line and the footer's text section.
|
||||
|
||||
| Partial | Arguments | Renders |
|
||||
|---------|-----------|---------|
|
||||
| `button` | `url`, `body`, `type` (`primary` by default, `positive` or `negative`) | A link styled as a button (`button button-<type>`); in text, the label and the address. |
|
||||
| `panel` | `body` (Markdown) | A highlighted block (`panel`). |
|
||||
| `table` | `body` (a Markdown table) | A table in a `table` block. |
|
||||
| `subcopy` | `body` (Markdown) | Small print under a rule (`subcopy`). |
|
||||
| `header` | `logo` (an image URL), `body` (a name), `url` (optional) | A layout's header row (`td.header`): `img.logo` with `body` as its alternative text when `logo` is set, else `body` in a `span`; wrapped in a link when `url` is set. In text, the name. |
|
||||
| `footer` | `body` (Markdown) | A layout's footer row (`table.footer`). In text, a rule line and the body. |
|
||||
|
||||
### Overrides from the admin
|
||||
|
||||
@@ -240,7 +244,7 @@ func newTestMailer(cat *postcard.Catalog, driver postcard.Driver) postcard.Maile
|
||||
|
||||
### Branding
|
||||
|
||||
Layouts have two CSS slots, `{{ .brandCss }}` and `{{ .css }}`, and a logo slot, `{{ .logoUrl }}`. What fills the brand slot depends on the row with `id` 1 of `system_mail_brand_settings`:
|
||||
Layouts have two CSS slots, `{{ .brandCss }}` and `{{ .css }}`, a logo slot, `{{ .logoUrl }}`, and a name slot, `{{ .siteName }}`. What fills the brand slot depends on the row with `id` 1 of `system_mail_brand_settings`:
|
||||
|
||||
- While the row does not exist, the slot holds `mail.brandCss` from the configuration and `{{ .logoUrl }}` is empty, so an application that never saves Branding is unchanged.
|
||||
- Once the row exists, the slot holds `postcard.CompileBrandCSS` of the row's colours, and `mail.brandCss` is no longer used. An empty colour column is that colour's default (`postcard.DefaultBrand`).
|
||||
@@ -271,6 +275,8 @@ The row's `logo_file_id` names a public `system_files` row. Its URL is not store
|
||||
{{ if .logoUrl }}<img src="{{ .logoUrl }}" alt="">{{ end }}
|
||||
```
|
||||
|
||||
The row's `site_name` column is `postcard.Brand.SiteName`. The built-in layouts show it in their header (as the logo's alternative text when there is a logo) and footer. While it is empty, and while no Branding row exists, `{{ .siteName }}` is the display name of `mail.from` parsed with `net/mail` (`Acme` for `Acme <no-reply@acme.test>`), or empty when the address has none. The name is HTML-escaped by `html/template` wherever a layout prints it.
|
||||
|
||||
A mail that falls back to its file version because an override failed still gets the Branding.
|
||||
|
||||
### Sample values
|
||||
@@ -391,7 +397,7 @@ A draft is rendered by the code that renders a send, with the mailer's CSS and t
|
||||
| `postcard.LayoutOverride` | A layout's name, HTML wrapper, text wrapper and CSS from the database. In `postcard.Overrides.Layouts` under a file layout's full name it replaces that layout; under another code it is a database-only layout. |
|
||||
| `postcard.PartialOverride` | A partial's HTML and text sections from the database, in `postcard.Overrides.Partials` under the partial's full name. |
|
||||
| `postcard.NewDBSource` | The source over postcard's tables. It looks the `*gorm.DB` up on the app at every call and returns no overrides when none is published. It builds the Branding logo's URL from the app's configuration. |
|
||||
| `postcard.Brand` | The Branding: thirteen colours and `postcard.Brand.LogoURL`, the logo's absolute URL. |
|
||||
| `postcard.Brand` | The Branding: thirteen colours, `postcard.Brand.LogoURL`, the logo's absolute URL, and `postcard.Brand.SiteName`, the name the built-in layouts show. |
|
||||
| `postcard.DefaultBrand` | WinterCMS's default mail colours. |
|
||||
| `postcard.CompileBrandCSS` | Checks a brand's colours and returns the brand CSS compiled from them. |
|
||||
| `postcard.Migrations` | The gormigrate set that creates the mail tables; lagoon runs it under the `summercms.postcard` history. |
|
||||
@@ -423,7 +429,7 @@ A draft is rendered by the code that renders a send, with the mailer's CSS and t
|
||||
| Key | Default | Controls |
|
||||
|-----|---------|----------|
|
||||
| `mail.driver` | `memory` | Delivery driver: `memory`, `log` or `smtp`. Any other value fails at boot. |
|
||||
| `mail.from` | empty | Sender address. Required by the SMTP driver. |
|
||||
| `mail.from` | empty | Sender address. Required by the SMTP driver. Its display name is the layouts' `{{ .siteName }}` while the Branding has no site name. |
|
||||
| `mail.css` | empty | CSS placed in the layout's style block, after the brand CSS. Always applied. |
|
||||
| `mail.brandCss` | empty | Brand CSS placed before `mail.css`. Used only until the branding settings are saved; from then on the CSS compiled from their colours replaces it (see [Branding](#branding)). |
|
||||
| `mail.smtp.host` | none | SMTP host. Required when `mail.driver` is `smtp`. |
|
||||
|
||||
Reference in New Issue
Block a user