From 09a5338d9a6d318858174732ff97044afe8d104b Mon Sep 17 00:00:00 2001 From: Jakub Zych Date: Fri, 13 Nov 2026 21:17:02 +0100 Subject: [PATCH] feat(postcard): header, logo, footer and padding in the system and minimal layouts - system.htm: the header partial (logo or site name) above the card and the copyright footer below it; its text wrapper ends with the footer - brand CSS: the system layout's content cell keeps WinterCMS's 35px side padding (the 35px 0 override is gone) - minimal.htm: the logo above the message when logoUrl is set - TestMailPartialsSmoke/built_in_layouts covers the three layouts and the inlined brand colour on the button in each - 35-06 Task 3 (G-35-8) --- docs/services/mail.md | 6 +-- modules/postcard/README.md | 8 +-- modules/postcard/assets/brand.css.tmpl | 3 -- modules/postcard/assets/minimal.htm | 3 +- modules/postcard/assets/system.htm | 4 ++ modules/postcard/partials_smoke_test.go | 68 ++++++++++++++++++++++--- 6 files changed, 74 insertions(+), 18 deletions(-) diff --git a/docs/services/mail.md b/docs/services/mail.md index 0fd98e2b..5616b245 100644 --- a/docs/services/mail.md +++ b/docs/services/mail.md @@ -64,12 +64,12 @@ Three layouts are available to every plugin's templates without declaring an ali | `layout` | Renders | |----------|---------| | `default` | WinterCMS's default layout: a header with the Branding logo (or the site name when no logo is set), the message on a white card, and a footer with the copyright year and the site name. Used when the template names no layout. | -| `system` | WinterCMS's system layout: the message in a centred table, then a note that it was sent automatically. | -| `minimal` | The message directly in the page body, with the style block only. | +| `system` | WinterCMS's system layout: the same header and footer as `default`, the message on a padded white card, then a note that it was sent automatically. | +| `minimal` | The message directly in the page body, with the Branding logo above it when one is set. | 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 layout uses the `header` and `footer` partials with them; the footer reads `© `, or `© ` 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 `© `, or `© ` when there is no name, and the header row is left out when there is neither a logo nor a name. ## Branding diff --git a/modules/postcard/README.md b/modules/postcard/README.md index 322eae74..0d617abf 100644 --- a/modules/postcard/README.md +++ b/modules/postcard/README.md @@ -176,8 +176,8 @@ 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` | 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 `© `. 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. | +| `system` | `postcard::mail.layouts.system` | WinterCMS's system layout (`wrapper layout-system`): the same header and footer as `default`, the message in the padded card followed by a `subcopy` note that the message is automatic. Its text wrapper ends with that note and the footer's text section. | +| `minimal` | `postcard::mail.layouts.minimal` | The message directly in the page body, with the logo (`img.logo`, the site name as its alternative text) in a paragraph above it when `logoUrl` is set. | 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. @@ -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. When the inliner fails on a message, 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 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. +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. | Partial | Arguments | Renders | |---------|-----------|---------| @@ -263,7 +263,7 @@ Layouts have two CSS slots, `{{ .brandCss }}` and `{{ .css }}`, a logo slot, `{{ `mail.css` fills `{{ .css }}` in both cases, after the brand CSS, with a layout's own CSS before it. -The compiled CSS styles the page, links, headings, paragraphs and tables, and the classes of the built-in layouts and partials (`button button-primary`, `panel`, `table`, `subcopy`, `layout-system` and others), so the colours also apply in a plugin's layout that has the style block and no brand classes of its own. A colour must be a six-digit hexadecimal colour such as `#2da7c7`; `postcard.CompileBrandCSS` refuses anything else with an error naming the column. If a stored colour is invalid at send time, a warning is logged and `mail.brandCss` is used. +The compiled CSS styles the page, links, headings, paragraphs and tables, and the classes of the built-in layouts and partials (`button button-primary`, `panel`, `table`, `subcopy`, `header`, `footer`, the `logo` image and others), so the colours also apply in a plugin's layout that has the style block and no brand classes of its own. A colour must be a six-digit hexadecimal colour such as `#2da7c7`; `postcard.CompileBrandCSS` refuses anything else with an error naming the column. If a stored colour is invalid at send time, a warning is logged and `mail.brandCss` is used. | Column | `postcard.Brand` field | Default | |--------|------------------------|---------| diff --git a/modules/postcard/assets/brand.css.tmpl b/modules/postcard/assets/brand.css.tmpl index d37dd8c0..aa8926b2 100644 --- a/modules/postcard/assets/brand.css.tmpl +++ b/modules/postcard/assets/brand.css.tmpl @@ -116,9 +116,6 @@ img.logo { .content-cell { padding: 35px; } -.wrapper.layout-system .content-cell { - padding: 35px 0; -} /* Subcopy */ .subcopy { border-top: 1px solid {{ .TableBorderColor }}; diff --git a/modules/postcard/assets/minimal.htm b/modules/postcard/assets/minimal.htm index f6ad43b2..c29926d6 100644 --- a/modules/postcard/assets/minimal.htm +++ b/modules/postcard/assets/minimal.htm @@ -9,6 +9,7 @@ name = "Minimal" -{{ .Content }} +{{ if .logoUrl }}

+{{ end }}{{ .Content }} diff --git a/modules/postcard/assets/system.htm b/modules/postcard/assets/system.htm index b4b01fd0..0e209541 100644 --- a/modules/postcard/assets/system.htm +++ b/modules/postcard/assets/system.htm @@ -5,6 +5,8 @@ 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 }} == @@ -15,6 +17,7 @@ This is an automatic message. Please do not reply to it. +{{ if or .logoUrl .siteName }}{{ partial "header" "logo" .logoUrl "body" .siteName }}{{ end }} +{{ $copy := printf "© %v" .year }}{{ with .siteName }}{{ $copy = printf "%s %s" $copy . }}{{ end }}{{ partial "footer" "body" $copy }}
@@ -33,6 +36,7 @@ This is an automatic message. Please do not reply to it.
diff --git a/modules/postcard/partials_smoke_test.go b/modules/postcard/partials_smoke_test.go index 76df08ad..e9199a61 100644 --- a/modules/postcard/partials_smoke_test.go +++ b/modules/postcard/partials_smoke_test.go @@ -360,21 +360,55 @@ func TestMailPartialsSmoke(t *testing.T) { }) t.Run("built_in_layouts", func(t *testing.T) { - m, drv := partialsMailer(t, Options{CSS: "p{color:red}", BrandCSS: ".brand{color:blue}"}, nil) + const logo = "https://cdn.example.com/u/logo.png" + header := "\n\"Acme" + + // The system layout with a logo: the header above the card, the + // card with the subcopy, the footer below, and the content cell's + // side padding. + m, drv := partialsMailer(t, Options{CSS: "p{color:red}"}, &Overrides{Brand: &Brand{LogoURL: logo, SiteName: "Acme Mail"}}) msg := sendTemplate(t, m, drv, "acme.blog::mail.auto", nil) + html := unstyled(msg.HTML) for _, want := range []string{ - // mail.css is inlined onto the paragraph. - `class="wrapper layout-system"`, `

Done.

`, + `class="wrapper layout-system"`, header, "

Done.

", `This is an automatic message. Please do not reply to it.", + `
" + copyright() + " Acme Mail

", } { - if !strings.Contains(msg.HTML, want) { - t.Errorf("system layout: HTML lacks %q:\n%s", want, msg.HTML) + if !strings.Contains(html, want) { + t.Errorf("system layout: HTML lacks %q:\n%s", want, html) } } - if msg.Text != "Done.\n\n\n---\nThis is an automatic message. Please do not reply to it." { + if h, card, foot := strings.Index(html, `class="header"`), strings.Index(html, `class="inner-body"`), strings.Index(html, `class="footer"`); h > card || card > foot { + t.Errorf("system layout: header %d, card %d, footer %d are out of order", h, card, foot) + } + // mail.css is inlined onto the paragraph, after the brand CSS. + if !regexp.MustCompile(`

]*>Done\.

`).MatchString(msg.HTML) { + t.Errorf("system layout: mail.css is not inlined:\n%s", msg.HTML) + } + if !strings.Contains(msg.HTML, `