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:
@@ -10,9 +10,9 @@ WinterCMS plugins ship mail templates in `views/mail` and send them with `Mail::
|
||||
|
||||
## Templates and layouts
|
||||
|
||||
A plugin implements `pact.HasMailTemplates`: it returns its embedded `views/mail` files, the template names it ships and short aliases for its layouts. A template named `acme.blog::mail.welcome` lives in `views/mail/welcome.htm` (dots in the name become directories), and a plugin may only register names in its own namespace. A missing file, a duplicate name or an unknown layout alias fails the start-up.
|
||||
A plugin implements `pact.HasMailTemplates`: it returns its embedded `views/mail` files, the template names it ships and short aliases for its layouts. A template named `acme.blog::mail.welcome` lives in `views/mail/welcome.htm` (dots in the name become directories), and a plugin may only register names in its own namespace. A missing file, a duplicate name or a layout the template names that is not registered fails the start-up.
|
||||
|
||||
The file format is WinterCMS's: an INI header with the `subject`, the `layout` alias and a `description`, a `==` line, then a Markdown body with Go template variables such as `{{ .name }}`. A layout has a header, a text wrapper and an HTML wrapper, separated by `==` lines, each with `{{ .Content }}` where the message goes. A template without a `layout` uses the built-in `default` layout; see [Built-in layouts](#built-in-layouts).
|
||||
The file format is WinterCMS's: an INI header with the `subject`, the `layout` (an alias or a full layout name) and a `description`, a `==` line, then a Markdown body with Go template variables such as `{{ .name }}`. A layout has a header, a text wrapper and an HTML wrapper, separated by `==` lines, each with `{{ .Content }}` where the message goes. A template without a `layout` uses the built-in `default` layout; see [Built-in layouts](#built-in-layouts).
|
||||
|
||||
Each message gets an HTML part, rendered from the Markdown, and a plain-text part. `mail.css` and the brand CSS go into the layout's style block; see [Branding](#branding).
|
||||
|
||||
@@ -71,6 +71,19 @@ A plugin's own alias wins over `system` and `minimal`; `default` cannot be redef
|
||||
|
||||
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.
|
||||
|
||||
### Another plugin's layout
|
||||
|
||||
A template can use a layout another plugin ships by naming its full name. Here a template of `acme.shop` uses the layout of `acme.blog`:
|
||||
|
||||
```text
|
||||
subject = "Your order"
|
||||
layout = "acme.blog::mail.layouts.blog"
|
||||
==
|
||||
Thanks for your order.
|
||||
```
|
||||
|
||||
The plugin that owns the layout must be registered first: list it in the template plugin's `Requires()`, and it boots first. A full name that no registered plugin declares fails the start-up with `postcard: unknown layout`, naming the layout and the template. Another plugin's short alias does not work (`layout = "blog"` in `acme.shop` is an unknown layout); only its full name does. The layout picker in the admin already lists every layout, so a customized template can keep the borrowed layout or change it, and a customized version of the owner's layout applies to every template that uses it.
|
||||
|
||||
## Branding
|
||||
|
||||
A layout's style block has a brand slot, `{{ .brandCss }}`, before `{{ .css }}`. Until the branding settings are saved for the first time, the brand slot holds `mail.brandCss` from the configuration. From the first save on, it holds CSS that postcard compiles from the saved colours, and `mail.brandCss` is no longer used. `mail.css` is applied either way.
|
||||
|
||||
Reference in New Issue
Block a user