feat(postcard): mail partials, built-in layouts and layout and partial overrides
- pact.HasMailPartials: plugins declare <plugin>::mail.partials.<name>,
loaded from views/mail/partials/<name>.htm; HasMailTemplates is unchanged
- bodies and layouts call {{ partial "name" "key" value ... }}; a call in a
Markdown body leaves a per-render random token swapped after goldmark, so
raw HTML stays disabled for bodies
- built-in partials button, panel, table and subcopy, built-in layouts
system and minimal next to the unchanged default, reachable by alias
after a plugin's own aliases
- NewDBSource also reads customized and database-only layouts and
customized partials; a layout's CSS goes before mail.css
Plan 35-01, task 3.
This commit is contained in:
@@ -81,6 +81,7 @@ A WinterCMS plugin overrides `register*` methods of `PluginBase`. A SummerCMS pl
|
||||
| `pact.HasSchedule` | Console commands that run on a schedule; see [Scheduling](scheduling.md). |
|
||||
| `pact.HasLang`, `pact.HasLangOverrides` | Translations, and overrides of other namespaces. |
|
||||
| `pact.HasMailTemplates` | Mail templates and layouts. |
|
||||
| `pact.HasMailPartials` | Mail partials: blocks that mail templates and layouts call; see [Mail](../services/mail.md#partials). |
|
||||
| `pact.HasPermissions`, `pact.HasNavigation`, `pact.HasSettings` | Backend permissions, navigation and settings screens. |
|
||||
| `pact.HasTokenScopes` | Personal API token scopes (`pact.TokenScope`) compiled at admin boot. |
|
||||
| `pact.HasFrontendTokenScopes` | Member personal API token scopes (`pact.FrontendTokenScope`) a route's `user.scope:<name>` middleware checks, compiled by the user plugin; the admin token catalog never reads them. |
|
||||
@@ -98,6 +99,7 @@ Configuration defaults, translations and mail templates ship inside the binary t
|
||||
- `pact.HasConfig.ConfigFS` returns a tree with `config/config.yaml`. Its keys become `<plugin id>.<key>`, and any other `config/<name>.yaml` becomes `<plugin id>.<name>.<key>`. The application's own `config/` directory and `SUMMER_` variables override them.
|
||||
- `pact.HasLang.LangFS` returns `lang/<locale>/<group>.yaml` files.
|
||||
- `pact.HasMailTemplates.MailTemplatesFS` returns the `views/mail` templates, and `pact.HasMailTemplates.MailTemplates` lists their names.
|
||||
- `pact.HasMailPartials.MailPartialsFS` returns the same `views/mail` tree, and `pact.HasMailPartials.MailPartials` lists the names of the partials under `views/mail/partials`.
|
||||
|
||||
## The scaffolded layout
|
||||
|
||||
|
||||
@@ -12,10 +12,55 @@ WinterCMS plugins ship mail templates in `views/mail` and send them with `Mail::
|
||||
|
||||
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.
|
||||
|
||||
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 neutral `default` layout is built in.
|
||||
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).
|
||||
|
||||
Each message gets an HTML part, rendered from the Markdown, and a plain-text part. `mail.css` and `mail.brandCss` are inlined into the layout's style block.
|
||||
|
||||
## Partials
|
||||
|
||||
A partial is a block that several templates and layouts share, such as a button or a footer note. A plugin implements `pact.HasMailPartials`: it returns its embedded `views/mail` files and the partial names it ships. A partial named `acme.blog::mail.partials.note` lives in `views/mail/partials/note.htm`, and its file has the layout format, with a text section and an HTML section:
|
||||
|
||||
```text
|
||||
name = "Note"
|
||||
==
|
||||
NOTE: {{ .text }}
|
||||
==
|
||||
<div class="note">{{ .text }}</div>
|
||||
```
|
||||
|
||||
The name must be in the plugin's namespace and under `mail.partials.`; otherwise, or when the file is missing or the name is declared twice, the start-up fails. A plugin can ship partials without shipping templates.
|
||||
|
||||
A body or a layout calls a partial with its name and pairs of a key and a value:
|
||||
|
||||
```text
|
||||
{{ partial "button" "url" .link "body" "Track the order" "type" "positive" }}
|
||||
|
||||
{{ partial "acme.blog::mail.partials.note" "text" .note }}
|
||||
```
|
||||
|
||||
A bare name is one of the built-in partials; a plugin's partial is called by its full name, from any plugin's mail. The pairs become the partial's variables. The HTML section is used in the HTML part and the text section in the plain-text part.
|
||||
|
||||
| Built-in partial | Arguments | Renders |
|
||||
|------------------|-----------|---------|
|
||||
| `button` | `url`, `body`, `type` (`primary`, `positive` or `negative`) | A link styled as a button. |
|
||||
| `panel` | `body` | A highlighted block; the body is Markdown. |
|
||||
| `table` | `body` | A Markdown table. |
|
||||
| `subcopy` | `body` | Small print under a rule; the 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.
|
||||
|
||||
## Built-in layouts
|
||||
|
||||
Three layouts are available to every plugin's templates without declaring an alias:
|
||||
|
||||
| `layout` | Renders |
|
||||
|----------|---------|
|
||||
| `default` | The message in a plain page. 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. |
|
||||
|
||||
A plugin's own alias wins over `system` and `minimal`; `default` cannot be redefined.
|
||||
|
||||
## Sending
|
||||
|
||||
At boot, `postcard.Activate` publishes one `postcard.Mailer` on the application, and `postcard.BootPlugin` registers each plugin's templates as it boots. Look the mailer up with `app.Lookup[postcard.Mailer]()` and send a `postcard.Message` with the template name, the recipients and the variables. Tests build the catalog and a memory driver directly, and read back what was sent:
|
||||
@@ -80,10 +125,12 @@ A plugin's mail files are the default text. postcard also owns a set of mail tab
|
||||
2. the override's subject;
|
||||
3. the file's subject.
|
||||
|
||||
Layouts and partials have rows too, in `system_mail_layouts` and `system_mail_partials`. A customized row replaces the file's wrappers or sections, and a layout row whose `code` is not a file layout's name is a layout that exists only in the database, which a template override can select. A layout row's CSS goes before `mail.css` in the layout's style block.
|
||||
|
||||
An override cannot stop mail from going out:
|
||||
|
||||
- With no database, or before `migrate` has created the tables, the file version is sent. A failed lookup is logged as a warning, at most once a minute.
|
||||
- An override that does not parse, fails while rendering (it uses a field of a variable the caller does not pass, for example) or fails the safety checks is logged as an error with the template name, and the file version is sent.
|
||||
- An override of the template, its layout or a partial that does not parse, fails while rendering (it uses a field of a variable the caller does not pass, for example) or fails the safety checks is logged as an error with the template name, and the message is sent from the files alone.
|
||||
- An override whose layout no longer exists is rendered in the `default` layout, with a warning.
|
||||
|
||||
The log lines carry the component `postcard`. In a test, pass any `postcard.OverrideSource` in `postcard.Options.Overrides` to supply overrides without a database; `postcard.NewDBSource` is the one `postcard.Activate` installs.
|
||||
|
||||
Reference in New Issue
Block a user