feat(quick-261115-cha): let a mail template use another plugin's layout by full code

- resolveLayoutLocked: after the plugin's own alias and the built-in
  aliases, a full layout name already in the catalog resolves to itself;
  an unregistered full name fails with a require-the-owner hint
- another plugin's short alias and the short-alias error are unchanged
- TestCrossPluginLayout covers register, send, errors and precedence
- postcard README and docs/services/mail.md describe the rule
This commit is contained in:
Jakub Zych
2026-11-15 09:08:21 +01:00
parent 42ab223e79
commit 1fb4254291
5 changed files with 214 additions and 7 deletions

View File

@@ -22,9 +22,9 @@ Use cases:
## Features
- Templates named `<plugin>::mail.<name>` and loaded from `views/mail/<name>.htm` (dots become directories). A plugin may only register names in its own namespace; missing files, duplicates and unknown layout aliases fail at boot.
- Templates named `<plugin>::mail.<name>` and loaded from `views/mail/<name>.htm` (dots become directories). A plugin may only register names in its own namespace; missing files, duplicates and unknown layouts fail at boot.
- WinterCMS file format: an INI header (`subject`, `layout`, `description`), a `==` separator, then a Markdown body rendered with Go `html/template` variables such as `{{ .name }}`.
- Layouts with a header, a text wrapper and an HTML wrapper, referenced from templates by a short alias (`pact.HasMailTemplates` maps aliases to full names). Three layouts are built in and usable from any plugin's templates: `default`, `system` and `minimal`.
- Layouts with a header, a text wrapper and an HTML wrapper, referenced from templates by a short alias (`pact.HasMailTemplates` maps aliases to full names). Three layouts are built in and usable from any plugin's templates: `default`, `system` and `minimal`. A template may also name a layout another plugin registered by its full name.
- Partials: reusable blocks named `<plugin>::mail.partials.<name>`, loaded from `views/mail/partials/<name>.htm` and declared through `pact.HasMailPartials`. Bodies and layouts call them with `{{ partial "<name>" "key" value }}`. The partials `button`, `panel`, `table` and `subcopy` are built in.
- Every message gets an HTML part (Markdown converted with goldmark) and a plain-text part. The brand CSS (`mail.brandCss`, or the saved Branding) and `mail.css` go into the layout's style block, and the rendered HTML is then inlined: each CSS rule is copied into the `style` attribute of the elements it matches (go-premailer), so mail clients that drop style blocks still show the design. A layout opts out with `disable_auto_inline_css`.
- Safety checks: rendered HTML with script, iframe, object or embed tags, inline event handlers (any attribute whose name starts with `on`) or `javascript:`/`vbscript:`/`data:` URLs is rejected. Schemes are looked for in URL-bearing attributes, `style` attributes, style elements, comments and `meta` content, after character references are decoded and whitespace and control characters removed (`javascript&#58;` and `java&#9;script:` are `javascript:`). The content of `noscript`, `title`, `textarea`, `style`, `xmp` and the other raw-text elements, and of comments, is checked as markup too, because a mail client may read it so (scripting off, `svg` content, Outlook conditional comments); such elements nested more than eight deep are refused. Every tag is also read with attribute quoting alone deciding where it ends, so an end tag or `-->` inside a quoted attribute (`<a title="</style>" href="javascript:...">`) does not hide the rest of the tag. Text is neither markup nor a URL: it is not checked for schemes, and text shaped like an event handler (`buy one = get one free`, `online = yes`) is sent. CR/LF in the subject or address headers is rejected; addresses are parsed with `net/mail`.
@@ -181,6 +181,15 @@ Markdown drops raw HTML, so a call in a body does not insert the partial's HTML
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.
A template's `layout` value is resolved in this order: empty or `default` is the default layout; then the plugin's own alias; then a built-in alias; then the full name of any layout already registered, another plugin's or a built-in one (`postcard::mail.layouts.minimal`). Another plugin's short alias is not visible. A full name must belong to a plugin that is already registered: list the owner in `Requires()`, and party boots it first. Otherwise start-up fails with `postcard: unknown layout`, naming the layout and the template. A template of `acme.shop`, which requires `acme.blog`, uses the blog's layout like this:
```text
subject = "Your order"
layout = "acme.blog::mail.layouts.blog"
==
Thanks for your order.
```
### CSS inlining
After a layout's HTML wrapper has rendered and passed the safety checks, postcard inlines it, as WinterCMS's `MailManager` does with CssToInlineStyles: `github.com/vanng822/go-premailer` with its default options reads the rules of every style element, writes them into the `style` attributes of the matching elements by specificity, mirrors CSS `width` and `height` to the attributes of the same name, keeps `class` attributes, and puts the rules it cannot inline (media queries, pseudo-classes such as `:hover`, selectors with `*`) back in one style element, marked `!important`. The safety checks run on the decoded markup before inlining, whether or not the layout opts out, so CSS in a style element with a `javascript:`, `vbscript:` or `data:` address is refused there. The inlined HTML is checked again, and an inlined result that fails the check is sent as its style-block version, with the same warning as an inliner error. HTML with no style element is left as it is. Preview, test send and sends run the same code; the text part is never changed.
@@ -396,7 +405,7 @@ A draft is rendered by the code that renders a send, with the mailer's CSS and t
| `postcard.Options` | Mailer settings: sender address, CSS, brand CSS and, in `postcard.Options.Overrides`, the source of database overrides (nil sends the file versions). |
| `postcard.Catalog` | Registered templates, layouts and partials, including the built-in ones. |
| `postcard.NewCatalog` | Returns a catalog holding the built-in layouts and partials and no template. |
| `postcard.Catalog.Register` | Loads a plugin's templates and layout aliases from an `fs.FS`. |
| `postcard.Catalog.Register` | Loads a plugin's templates and layout aliases from an `fs.FS`. A template's `layout` may be one of the plugin's aliases, a built-in alias, or the full name of a layout already in the catalog. |
| `postcard.Catalog.RegisterPartials` | Loads a plugin's partials from an `fs.FS`. |
| `postcard.Driver` | Delivers a `postcard.RenderedMessage`. |
| `postcard.RenderedMessage` | The validated payload a driver transmits: headers, HTML part and text part. |