fix(postcard): print the site name literally in the built-in layouts' footer

- the footer partial gains a text argument, printed as a paragraph
  through html/template and verbatim in the text part; body stays
  Markdown for callers that pass Markdown on purpose
- the default and system layouts pass the copyright line as text, so
  *Acme*, Acme <Studio> and [x](url) appear as typed, as in the header
  (WR-01)
- README partial table, layouts and Branding paragraphs; docs partials
  table and built-in layouts paragraph
- TestMailSafetySmoke/literal_footer
This commit is contained in:
Jakub Zych
2026-11-14 15:29:57 +01:00
parent cd91cf2e64
commit 15d3e6fb8d
6 changed files with 58 additions and 11 deletions

View File

@@ -193,7 +193,7 @@ A layout opts out with WinterCMS's option name, `disable_auto_inline_css`:
An opted-out layout keeps its style block as rendered; it passed the same safety checks as an inlined one. When the inliner fails on a message, or its result fails the safety checks, the message is sent with its style block only and a warning keyed by the layout is logged at most once a minute.
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 and system layouts call 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.
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 and system layouts call 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, passed to the footer as its `text` argument, so the name is printed as typed and never read as Markdown. Its text wrapper is the message, a blank line and the footer's text section.
| Partial | Arguments | Renders |
|---------|-----------|---------|
@@ -202,7 +202,7 @@ Both wrappers of every layout get these keys: `Content`, `Subject`, `css`, `bran
| `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. |
| `footer` | `text` (plain, printed escaped in a paragraph) or `body` (Markdown) | A layout's footer row (`table.footer`). In text, a rule line and the text or the body. |
### Overrides from the admin
@@ -287,7 +287,7 @@ 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.
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, and printed literally in the header and the footer (`*Acme*` and `Acme <Studio>` appear as typed).
A name `postcard.UnsafeText` refuses (a `javascript:`, `vbscript:` or `data:` URL, or text that would read as markup such as `Shop onclick=x`) never reaches a layout and never stops a send: an unsafe Branding name is treated as empty, so the `mail.from` display name is used if that one is safe, and an unsafe `mail.from` display name gives no name. A warning naming the source (`branding` or `mail.from`), never the value, is logged at most once a minute per source. Prose such as `Big Data: Summit` is a name like any other. The Branding preview of an unsaved draft leaves such a name out the same way; the admin's Branding form refuses to save it.