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:
@@ -53,7 +53,7 @@ A bare name is one of the built-in partials; a plugin's partial is called by its
|
||||
| `table` | `body` | A Markdown table. |
|
||||
| `subcopy` | `body` | Small print under a rule; the body is Markdown. |
|
||||
| `header` | `logo` (an image URL), `body` (a name), `url` (optional link) | A table row for a layout's header: the logo, with the name as its alternative text, or the name when there is no logo. |
|
||||
| `footer` | `body` | A table row for a layout's footer; the body is Markdown. |
|
||||
| `footer` | `text` or `body` | A table row for a layout's footer; `text` is printed as it is (escaped), `body` is Markdown. |
|
||||
|
||||
In a body, write the call on a line of its own with blank lines around it. Bodies are Markdown and raw HTML in them is still dropped; postcard inserts a partial's HTML after the Markdown conversion, through a random token that a variable's value cannot contain. Inside a partial's HTML section, `{{ markdown .body }}` renders a value as Markdown.
|
||||
|
||||
@@ -69,7 +69,7 @@ Three layouts are available to every plugin's templates without declaring an ali
|
||||
|
||||
A plugin's own alias wins over `system` and `minimal`; `default` cannot be redefined.
|
||||
|
||||
Every layout gets these values besides `{{ .Content }}`: `{{ .Subject }}`, the CSS slots `{{ .brandCss }}` and `{{ .css }}`, `{{ .logoUrl }}` (see [Branding](#branding)), `{{ .siteName }}`, the site name, and `{{ .year }}`, the current year. The default and system layouts use the `header` and `footer` partials with them; the footer reads `© <year> <site name>`, or `© <year>` when there is no name, and the header row is left out when there is neither a logo nor a name.
|
||||
Every layout gets these values besides `{{ .Content }}`: `{{ .Subject }}`, the CSS slots `{{ .brandCss }}` and `{{ .css }}`, `{{ .logoUrl }}` (see [Branding](#branding)), `{{ .siteName }}`, the site name, and `{{ .year }}`, the current year. The default and system layouts use the `header` and `footer` partials with them; the footer reads `© <year> <site name>`, or `© <year>` when there is no name, passed as the footer's `text`, so the site name is printed as typed, never as Markdown, and the header row is left out when there is neither a logo nor a name.
|
||||
|
||||
## Branding
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@ name = "Default"
|
||||
==
|
||||
{{ .Content }}
|
||||
|
||||
{{ $copy := printf "© %v" .year }}{{ with .siteName }}{{ $copy = printf "%s %s" $copy . }}{{ end }}{{ partial "footer" "body" $copy }}
|
||||
{{ $copy := printf "© %v" .year }}{{ with .siteName }}{{ $copy = printf "%s %s" $copy . }}{{ end }}{{ partial "footer" "text" $copy }}
|
||||
==
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
@@ -31,7 +31,7 @@ name = "Default"
|
||||
</table>
|
||||
</td>
|
||||
</tr>
|
||||
{{ $copy := printf "© %v" .year }}{{ with .siteName }}{{ $copy = printf "%s %s" $copy . }}{{ end }}{{ partial "footer" "body" $copy }}
|
||||
{{ $copy := printf "© %v" .year }}{{ with .siteName }}{{ $copy = printf "%s %s" $copy . }}{{ end }}{{ partial "footer" "text" $copy }}
|
||||
</table>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
@@ -1,14 +1,14 @@
|
||||
name = "Footer"
|
||||
==
|
||||
-------------------
|
||||
{{ .body }}
|
||||
{{ if .text }}{{ .text }}{{ else }}{{ .body }}{{ end }}
|
||||
==
|
||||
<tr>
|
||||
<td>
|
||||
<table class="footer" align="center" width="570" cellpadding="0" cellspacing="0">
|
||||
<tr>
|
||||
<td class="content-cell" align="center">
|
||||
{{ markdown .body }}
|
||||
{{ if .text }}<p>{{ .text }}</p>{{ else }}{{ markdown .body }}{{ end }}
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
@@ -6,7 +6,7 @@ name = "System layout"
|
||||
---
|
||||
This is an automatic message. Please do not reply to it.
|
||||
|
||||
{{ $copy := printf "© %v" .year }}{{ with .siteName }}{{ $copy = printf "%s %s" $copy . }}{{ end }}{{ partial "footer" "body" $copy }}
|
||||
{{ $copy := printf "© %v" .year }}{{ with .siteName }}{{ $copy = printf "%s %s" $copy . }}{{ end }}{{ partial "footer" "text" $copy }}
|
||||
==
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
@@ -36,7 +36,7 @@ This is an automatic message. Please do not reply to it.
|
||||
</table>
|
||||
</td>
|
||||
</tr>
|
||||
{{ $copy := printf "© %v" .year }}{{ with .siteName }}{{ $copy = printf "%s %s" $copy . }}{{ end }}{{ partial "footer" "body" $copy }}
|
||||
{{ $copy := printf "© %v" .year }}{{ with .siteName }}{{ $copy = printf "%s %s" $copy . }}{{ end }}{{ partial "footer" "text" $copy }}
|
||||
</table>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
@@ -3,6 +3,7 @@ package postcard
|
||||
import (
|
||||
"bytes"
|
||||
"context"
|
||||
"html"
|
||||
"log/slog"
|
||||
"strings"
|
||||
"testing"
|
||||
@@ -41,6 +42,17 @@ func assertSiteName(t *testing.T, msg RenderedMessage, name string) {
|
||||
}
|
||||
}
|
||||
|
||||
// footerTable returns the footer partial's table of html.
|
||||
func footerTable(t *testing.T, html string) string {
|
||||
t.Helper()
|
||||
tables := withClass(html, "table", "footer")
|
||||
if len(tables) != 1 {
|
||||
t.Fatalf("%d footer tables, want 1:\n%s", len(tables), html)
|
||||
}
|
||||
table, _, _ := strings.Cut(html[tables[0].start:], "</table>")
|
||||
return table
|
||||
}
|
||||
|
||||
// TestMailSafetySmoke covers the 35-08 gap closure: prose in a site name or
|
||||
// a body is not a URL, encoded script URLs are refused, unsafe site names
|
||||
// never stop a send, the inliner never stops mail and the footer prints the
|
||||
@@ -203,4 +215,39 @@ func TestMailSafetySmoke(t *testing.T) {
|
||||
t.Errorf("log = %q, want the layout", out)
|
||||
}
|
||||
})
|
||||
t.Run("literal_footer", func(t *testing.T) {
|
||||
for _, name := range []string{"*Acme*", "Acme <Studio>", "[x](https://example.com)"} {
|
||||
for _, l := range safetyLayouts {
|
||||
msg := brandedSend(t, &Brand{SiteName: name}, "", l.template)
|
||||
escaped := html.EscapeString(name)
|
||||
if got, want := footerText(t, msg.HTML), copyright()+" "+escaped; got != want {
|
||||
t.Errorf("%s %q: footer = %q, want %q", l.layout, name, got, want)
|
||||
}
|
||||
footer := footerTable(t, msg.HTML)
|
||||
for _, bad := range []string{"<em", "<a ", "raw HTML omitted", "<!--"} {
|
||||
if strings.Contains(footer, bad) {
|
||||
t.Errorf("%s %q: the footer holds %q:\n%s", l.layout, name, bad, footer)
|
||||
}
|
||||
}
|
||||
cell, _ := headerCell(msg.HTML)
|
||||
if m := logoSpan.FindStringSubmatch(cell); m == nil || m[1] != escaped {
|
||||
t.Errorf("%s %q: header = %q, want %q", l.layout, name, cell, escaped)
|
||||
}
|
||||
if want := "-------------------\n" + copyright() + " " + name; !strings.HasSuffix(strings.TrimRight(msg.Text, "\n"), want) {
|
||||
t.Errorf("%s %q: text part does not end with %q:\n%s", l.layout, name, want, msg.Text)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// The footer partial called with body only still renders Markdown.
|
||||
m, drv := partialsMailer(t, Options{}, &Overrides{Template: &TemplateOverride{Subject: "S", Body: `{{ partial "footer" "body" "**Bold** text" }}`}})
|
||||
msg := sendTemplate(t, m, drv, "acme.blog::mail.welcome", inlineVars)
|
||||
tables := withClass(msg.HTML, "table", "footer")
|
||||
if len(tables) != 2 {
|
||||
t.Fatalf("%d footer tables, want the body's and the layout's:\n%s", len(tables), msg.HTML)
|
||||
}
|
||||
if body, _, _ := strings.Cut(msg.HTML[tables[0].start:], "</table>"); !strings.Contains(body, "<strong>Bold</strong> text") {
|
||||
t.Errorf("a footer body is not rendered as Markdown:\n%s", msg.HTML)
|
||||
}
|
||||
})
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user