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:
@@ -8,7 +8,7 @@ Transactional mail from plugin-owned Markdown templates and layouts, delivered t
|
||||
|
||||
## Overview
|
||||
|
||||
postcard is the mail layer of SummerCMS. Plugins that implement `pact.HasMailTemplates` ship WinterCMS-shaped mail files under `views/mail/`; at boot, `postcard.Activate` publishes one app-scoped `postcard.Mailer` built from the compass `mail.*` config, and `postcard.BootPlugin` registers each plugin's templates and layouts as the plugin boots. Callers then send a template by its dotted name with a map of variables. postcard also owns the mail tables that hold administrators' edits: when a template has a customized row, the mailer sends that override, and the plugin's file otherwise. It is the counterpart of WinterCMS's `Mail::send` with `views/mail/*.htm` templates and mail layouts.
|
||||
postcard is the mail layer of SummerCMS. Plugins that implement `pact.HasMailTemplates` ship WinterCMS-shaped mail files under `views/mail/`, and plugins that implement `pact.HasMailPartials` ship reusable blocks for them; at boot, `postcard.Activate` publishes one app-scoped `postcard.Mailer` built from the compass `mail.*` config, and `postcard.BootPlugin` registers each plugin's templates, layouts and partials as the plugin boots. Callers then send a template by its dotted name with a map of variables. postcard also owns the mail tables that hold administrators' edits: when a template, layout or partial has a customized row, the mailer uses that override, and the plugin's file otherwise. It is the counterpart of WinterCMS's `Mail::send` with `views/mail/*.htm` templates and mail layouts.
|
||||
|
||||
## Role in the framework
|
||||
|
||||
@@ -24,11 +24,12 @@ Use cases:
|
||||
|
||||
- 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.
|
||||
- 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). A neutral default layout is built in.
|
||||
- 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`.
|
||||
- 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. `mail.css` and `mail.brandCss` are inlined into the layout's style block.
|
||||
- Safety checks: rendered HTML with script, iframe, object or embed tags, inline event handlers or `javascript:`/`vbscript:`/`data:` URLs is rejected; CR/LF in the subject or address headers is rejected; addresses are parsed with `net/mail`.
|
||||
- Drivers behind the `postcard.Driver` interface: `postcard.MemoryDriver` (keeps messages for tests), `postcard.LogDriver` (logs headers and the text part through `log/slog`, never the HTML or credentials), `postcard.SMTPDriver` (go-mail with an explicit TLS policy) and `postcard.FailDriver` (a deterministic failure for tests).
|
||||
- Database overrides: a customized row of `system_mail_templates` replaces a template's subject, body and layout. The mailer reads it on every send, with no cache, in every process that publishes a `*gorm.DB`. A missing database, tables that are not migrated yet, or an override that does not render or fails the safety checks sends the file version.
|
||||
- Database overrides: a customized row of `system_mail_templates` replaces a template's subject, body and layout, a customized row of `system_mail_layouts` or `system_mail_partials` replaces a layout or a partial, and `system_mail_layouts` also holds layouts that exist only in the database. The mailer reads them on every send, with no cache, in every process that publishes a `*gorm.DB`. A missing database, tables that are not migrated yet, or an override that does not render or fails the safety checks sends the file version.
|
||||
- No locale selection: callers pass the full template name, including any locale suffix.
|
||||
|
||||
## Usage
|
||||
@@ -99,6 +100,83 @@ func TestWelcomeMail(t *testing.T) {
|
||||
}
|
||||
```
|
||||
|
||||
### Partials
|
||||
|
||||
A partial is a block of mail that several templates and layouts share, such as a button. Its file has the layout format: a header with a `name`, a `==` line, the text section, a `==` line, then the HTML section. A plugin ships `views/mail/partials/note.htm`:
|
||||
|
||||
```text
|
||||
name = "Note"
|
||||
==
|
||||
NOTE: {{ .text }}
|
||||
==
|
||||
<div class="note">{{ .text }}</div>
|
||||
```
|
||||
|
||||
and declares it next to its templates:
|
||||
|
||||
```go
|
||||
package blog
|
||||
|
||||
import (
|
||||
"embed"
|
||||
"io/fs"
|
||||
|
||||
"git.golem15.com/golem15/summercms/modules/pact"
|
||||
)
|
||||
|
||||
//go:embed views/mail
|
||||
var mailFS embed.FS
|
||||
|
||||
type Plugin struct{}
|
||||
|
||||
var _ pact.HasMailPartials = Plugin{}
|
||||
|
||||
func (Plugin) ID() string { return "acme.blog" }
|
||||
|
||||
func (Plugin) MailPartialsFS() fs.FS { return mailFS }
|
||||
|
||||
func (Plugin) MailPartials() []string {
|
||||
return []string{"acme.blog::mail.partials.note"}
|
||||
}
|
||||
```
|
||||
|
||||
A name must be in the plugin's own namespace and under `mail.partials.`; a name outside either, a missing file or a duplicate fails `postcard.BootPlugin` with the dotted name. A plugin may implement `pact.HasMailPartials` without `pact.HasMailTemplates`, and any plugin's templates may call its partials.
|
||||
|
||||
A template body or a layout calls a partial with its name followed by pairs of a key and a value, which become the partial's variables:
|
||||
|
||||
```text
|
||||
subject = "Your order {{ .code }}"
|
||||
==
|
||||
Thanks for your order.
|
||||
|
||||
{{ partial "button" "url" .link "body" "Track the order" "type" "positive" }}
|
||||
|
||||
{{ partial "acme.blog::mail.partials.note" "text" .note }}
|
||||
```
|
||||
|
||||
A bare name such as `button` is one of postcard's built-in partials; a plugin's partial is called by its full name. The HTML section goes into the HTML part and the text section into the plain-text part. An unknown name, an odd number of key and value arguments or a key that is not a string fails the render with the partial's name.
|
||||
|
||||
Inside a partial's HTML section, `{{ markdown .body }}` renders a value as Markdown, tables included; in the text section it returns the value unchanged. A partial cannot call `partial`.
|
||||
|
||||
Markdown drops raw HTML, so a call in a body does not insert the partial's HTML directly. It leaves a token of letters and digits, `MAILPARTIAL` followed by a random value drawn for that one render, and postcard swaps the token for the rendered partial after the body has been converted. A variable's value cannot contain that token, so text that only looks like one stays text. Put a call on its own line, with blank lines around it, to get the partial as a block of its own. Markdown rendering of bodies is unchanged: raw HTML in a body is still dropped.
|
||||
|
||||
### Built-in layouts and partials
|
||||
|
||||
| Layout alias | Full name | Renders |
|
||||
|--------------|-----------|---------|
|
||||
| `default` | `postcard::mail.layouts.default` | The message in a `content-body` block. 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. |
|
||||
|
||||
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.
|
||||
|
||||
| Partial | Arguments | Renders |
|
||||
|---------|-----------|---------|
|
||||
| `button` | `url`, `body`, `type` (`primary` by default, `positive` or `negative`) | A link styled as a button (`button button-<type>`); in text, the label and the address. |
|
||||
| `panel` | `body` (Markdown) | A highlighted block (`panel`). |
|
||||
| `table` | `body` (a Markdown table) | A table in a `table` block. |
|
||||
| `subcopy` | `body` (Markdown) | Small print under a rule (`subcopy`). |
|
||||
|
||||
### Overrides from the admin
|
||||
|
||||
postcard owns the tables `system_mail_templates`, `system_mail_layouts`, `system_mail_partials`, `system_mail_brand_settings` and `system_mail_image_library` (`postcard.Migrations`). A row of `system_mail_templates` with `is_custom` set is an override of the template named in its `code`: its `subject` and `body` replace the file's, and the row its `layout_id` points at names the layout. The body has the same format as in the file, Markdown with Go template variables.
|
||||
@@ -111,11 +189,13 @@ The subject is taken from the first of these that is set:
|
||||
2. the override's subject;
|
||||
3. the file's subject.
|
||||
|
||||
Layouts and partials are overridden the same way. A row of `system_mail_layouts` with `is_custom` set and a full layout name in `code` replaces that layout's HTML and text wrappers; a row with another `code` is a layout that exists only in the database, which a template override can select. A layout row's `content_css` is placed before `mail.css` in the layout's `{{ .css }}` slot. A row of `system_mail_partials` with `is_custom` set replaces the HTML and text sections of the partial named in its `code`.
|
||||
|
||||
An override never stops mail:
|
||||
|
||||
- With no `*gorm.DB` published, the file version is sent.
|
||||
- When the lookup fails (no connection, or the tables are not migrated yet), the file version is sent and a warning is logged, at most once a minute per distinct error.
|
||||
- When the override does not parse, fails while rendering (for example it uses a field of a variable the caller does not pass) or fails the safety checks, the error is logged as `postcard: override failed, sending the file version` with the template name, and the file version is sent.
|
||||
- When an override (of the template, its layout or a partial it calls) does not parse, fails while rendering (for example it uses a field of a variable the caller does not pass) or fails the safety checks, the error is logged as `postcard: override failed, sending the file version` with the template name, and the message is sent from the files alone.
|
||||
- When the override's layout no longer exists, the message is rendered in the default layout and a warning is logged.
|
||||
|
||||
`postcard.NewMailer` takes a source through `postcard.Options.Overrides`; any `postcard.OverrideSource` works, which is how a test supplies overrides without a database:
|
||||
@@ -152,14 +232,15 @@ func newTestMailer(cat *postcard.Catalog, driver postcard.Driver) postcard.Maile
|
||||
| Identifier | Description |
|
||||
|------------|-------------|
|
||||
| `postcard.Activate` | Builds the driver from config and publishes the app-scoped `postcard.Mailer` before plugins boot. The mailer reads overrides through `postcard.NewDBSource`. |
|
||||
| `postcard.BootPlugin` | Registers a booting plugin's declared templates and layouts with the published mailer. |
|
||||
| `postcard.BootPlugin` | Registers a booting plugin's declared partials (`pact.HasMailPartials`) and its templates and layouts (`pact.HasMailTemplates`) with the published mailer. |
|
||||
| `postcard.Mailer` | Sends a registered template through the configured driver. |
|
||||
| `postcard.NewMailer` | Builds a mailer from a catalog, a driver and `postcard.Options`. |
|
||||
| `postcard.Message` | What callers send: template name, recipients, reply-to, variables and an optional subject override. |
|
||||
| `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 and layouts, including the built-in default layout. |
|
||||
| `postcard.NewCatalog` | Returns a catalog holding only the default layout. |
|
||||
| `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.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. |
|
||||
| `postcard.NewMemoryDriver` | In-memory driver; `postcard.MemoryDriver.Messages` returns what was sent. |
|
||||
@@ -170,8 +251,8 @@ func newTestMailer(cat *postcard.Catalog, driver postcard.Driver) postcard.Maile
|
||||
| `postcard.OverrideSource` | Supplies the database overrides of one render. `postcard.OverrideSource.MailOverrides` takes the template name; an empty name asks for everything except a template override. |
|
||||
| `postcard.Overrides` | What a source returns: the template override in `postcard.Overrides.Template` (nil when there is none), layout content by code in `postcard.Overrides.Layouts` and partial content by name in `postcard.Overrides.Partials`. |
|
||||
| `postcard.TemplateOverride` | A template's customized subject, body and layout code. An empty `postcard.TemplateOverride.Layout` keeps the file's layout. |
|
||||
| `postcard.LayoutOverride` | A layout's name, HTML wrapper, text wrapper and CSS as stored in the database. |
|
||||
| `postcard.PartialOverride` | A partial's HTML and text sections as stored in the database. |
|
||||
| `postcard.LayoutOverride` | A layout's name, HTML wrapper, text wrapper and CSS from the database. In `postcard.Overrides.Layouts` under a file layout's full name it replaces that layout; under another code it is a database-only layout. |
|
||||
| `postcard.PartialOverride` | A partial's HTML and text sections from the database, in `postcard.Overrides.Partials` under the partial's full name. |
|
||||
| `postcard.NewDBSource` | The source over postcard's tables. It looks the `*gorm.DB` up on the app at every call and returns no overrides when none is published. |
|
||||
| `postcard.Migrations` | The gormigrate set that creates the mail tables; lagoon runs it under the `summercms.postcard` history. |
|
||||
| `postcard.TemplatesTable`, `postcard.LayoutsTable`, `postcard.PartialsTable`, `postcard.BrandTable`, `postcard.ImageLibraryTable` | The names of the mail tables, for code that defines models over them. |
|
||||
@@ -208,8 +289,8 @@ mail:
|
||||
## Dependencies
|
||||
|
||||
- SummerCMS modules: [backpack](../backpack/README.md), [compass](../compass/README.md), [diary](../diary/README.md) (component logger `postcard` when the app publishes no logger), [pact](../pact/README.md).
|
||||
- Third-party: `github.com/wneessen/go-mail` (SMTP), `github.com/yuin/goldmark` (Markdown), `gorm.io/gorm` (reading overrides), `github.com/go-gormigrate/gormigrate/v2` (the mail tables' migrations).
|
||||
- Standard library: `bytes`, `context`, `embed`, `fmt`, `html/template`, `io/fs`, `log/slog`, `net/mail`, `regexp`, `strings`, `sync`, `text/template`, `time`.
|
||||
- Third-party: `github.com/wneessen/go-mail` (SMTP), `github.com/yuin/goldmark` (Markdown, and its table extension inside partials), `gorm.io/gorm` (reading overrides), `github.com/go-gormigrate/gormigrate/v2` (the mail tables' migrations).
|
||||
- Standard library: `bytes`, `context`, `crypto/rand`, `database/sql`, `embed`, `encoding/hex`, `fmt`, `html/template`, `io/fs`, `log/slog`, `net/mail`, `regexp`, `strconv`, `strings`, `sync`, `text/template`, `time`.
|
||||
- Tests additionally use `github.com/testcontainers/testcontainers-go` (Mailpit and Postgres containers), `gorm.io/driver/postgres` and `github.com/jackc/pgx/v5`.
|
||||
|
||||
## Testing
|
||||
|
||||
14
modules/postcard/assets/minimal.htm
Normal file
14
modules/postcard/assets/minimal.htm
Normal file
@@ -0,0 +1,14 @@
|
||||
name = "Minimal"
|
||||
==
|
||||
{{ .Content }}
|
||||
==
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
|
||||
<style type="text/css">{{ .brandCss }}{{ .css }}</style>
|
||||
</head>
|
||||
<body>
|
||||
{{ .Content }}
|
||||
</body>
|
||||
</html>
|
||||
17
modules/postcard/assets/partials/button.htm
Normal file
17
modules/postcard/assets/partials/button.htm
Normal file
@@ -0,0 +1,17 @@
|
||||
name = "Button"
|
||||
==
|
||||
{{ .body }}{{ with .url }} <{{ . }}>{{ end }}
|
||||
==
|
||||
<table class="action" align="center" width="100%" cellpadding="0" cellspacing="0">
|
||||
<tr>
|
||||
<td align="center">
|
||||
<table border="0" cellpadding="0" cellspacing="0">
|
||||
<tr>
|
||||
<td>
|
||||
<a href="{{ .url }}" class="button button-{{ if .type }}{{ .type }}{{ else }}primary{{ end }}" target="_blank">{{ .body }}</a>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
17
modules/postcard/assets/partials/panel.htm
Normal file
17
modules/postcard/assets/partials/panel.htm
Normal file
@@ -0,0 +1,17 @@
|
||||
name = "Panel"
|
||||
==
|
||||
{{ .body }}
|
||||
==
|
||||
<table class="panel break-all" width="100%" cellpadding="0" cellspacing="0">
|
||||
<tr>
|
||||
<td class="panel-content">
|
||||
<table width="100%" cellpadding="0" cellspacing="0">
|
||||
<tr>
|
||||
<td class="panel-item">
|
||||
{{ markdown .body }}
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
12
modules/postcard/assets/partials/subcopy.htm
Normal file
12
modules/postcard/assets/partials/subcopy.htm
Normal file
@@ -0,0 +1,12 @@
|
||||
name = "Subcopy"
|
||||
==
|
||||
-----
|
||||
{{ .body }}
|
||||
==
|
||||
<table class="subcopy" width="100%" cellpadding="0" cellspacing="0">
|
||||
<tr>
|
||||
<td>
|
||||
{{ markdown .body }}
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
7
modules/postcard/assets/partials/table.htm
Normal file
7
modules/postcard/assets/partials/table.htm
Normal file
@@ -0,0 +1,7 @@
|
||||
name = "Table"
|
||||
==
|
||||
{{ .body }}
|
||||
==
|
||||
<div class="table">
|
||||
{{ markdown .body }}
|
||||
</div>
|
||||
38
modules/postcard/assets/system.htm
Normal file
38
modules/postcard/assets/system.htm
Normal file
@@ -0,0 +1,38 @@
|
||||
name = "System layout"
|
||||
==
|
||||
{{ .Content }}
|
||||
|
||||
|
||||
---
|
||||
This is an automatic message. Please do not reply to it.
|
||||
==
|
||||
<!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">
|
||||
<head>
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
|
||||
<style type="text/css">{{ .brandCss }}{{ .css }}</style>
|
||||
</head>
|
||||
<body>
|
||||
<table class="wrapper layout-system" width="100%" cellpadding="0" cellspacing="0">
|
||||
<tr>
|
||||
<td align="center">
|
||||
<table class="content" width="100%" cellpadding="0" cellspacing="0">
|
||||
<tr>
|
||||
<td class="body" width="100%" cellpadding="0" cellspacing="0">
|
||||
<table class="inner-body" align="center" width="570" cellpadding="0" cellspacing="0">
|
||||
<tr>
|
||||
<td class="content-cell">
|
||||
{{ .Content }}
|
||||
{{ partial "subcopy" "body" "**This is an automatic message. Please do not reply to it.**" }}
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
</body>
|
||||
</html>
|
||||
@@ -271,11 +271,14 @@ func loggerFromApp(app *backpack.App) *slog.Logger {
|
||||
return moduleLog
|
||||
}
|
||||
|
||||
// BootPlugin registers a plugin's declared mail templates and layouts.
|
||||
// Missing files and unknown layout aliases fail with the dotted name.
|
||||
// BootPlugin registers a plugin's declared mail partials (pact.HasMailPartials)
|
||||
// and its templates and layouts (pact.HasMailTemplates). Either capability is
|
||||
// optional. Missing files, duplicates, names outside the plugin's namespace
|
||||
// and unknown layout aliases fail with the dotted name.
|
||||
func BootPlugin[P interface{ ID() string }](app *backpack.App, p P) error {
|
||||
hm, ok := any(p).(pact.HasMailTemplates)
|
||||
if !ok {
|
||||
hm, hasTemplates := any(p).(pact.HasMailTemplates)
|
||||
hp, hasPartials := any(p).(pact.HasMailPartials)
|
||||
if !hasTemplates && !hasPartials {
|
||||
return nil
|
||||
}
|
||||
got, ok := app.Lookup[Mailer]()
|
||||
@@ -286,5 +289,13 @@ func BootPlugin[P interface{ ID() string }](app *backpack.App, p P) error {
|
||||
if !ok || m == nil || m.catalog == nil {
|
||||
return fmt.Errorf("postcard: mailer not published")
|
||||
}
|
||||
return m.catalog.Register(p.ID(), hm.MailTemplatesFS(), hm.MailTemplates(), hm.MailLayouts())
|
||||
if hasPartials {
|
||||
if err := m.catalog.RegisterPartials(p.ID(), hp.MailPartialsFS(), hp.MailPartials()); err != nil {
|
||||
return err
|
||||
}
|
||||
}
|
||||
if hasTemplates {
|
||||
return m.catalog.Register(p.ID(), hm.MailTemplatesFS(), hm.MailTemplates(), hm.MailLayouts())
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
@@ -165,6 +165,16 @@ func bootMailApp(t *testing.T, gdb *gorm.DB) (*mailer, *MemoryDriver, *bytes.Buf
|
||||
return m, drv, &logs
|
||||
}
|
||||
|
||||
// appWith returns an app that publishes gdb.
|
||||
func appWith(t *testing.T, gdb *gorm.DB) *backpack.App {
|
||||
t.Helper()
|
||||
app := backpack.New(nil)
|
||||
if err := app.Publish(gdb); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
return app
|
||||
}
|
||||
|
||||
// customizeWelcome turns the welcome template's index row into an override.
|
||||
// layoutCode names the layout row to point at; empty leaves layout_id NULL.
|
||||
func customizeWelcome(t *testing.T, gdb *gorm.DB, subject, body, layoutCode string) {
|
||||
@@ -173,7 +183,7 @@ func customizeWelcome(t *testing.T, gdb *gorm.DB, subject, body, layoutCode stri
|
||||
if layoutCode != "" {
|
||||
var id int64
|
||||
if err := gdb.Raw(`INSERT INTO `+LayoutsTable+` (code, source, name) VALUES (?, 'acme.blog', 'Blog')
|
||||
ON CONFLICT (code) DO UPDATE SET name = EXCLUDED.name RETURNING id`, layoutCode).Scan(&id).Error; err != nil {
|
||||
ON CONFLICT (code) DO UPDATE SET code = EXCLUDED.code RETURNING id`, layoutCode).Scan(&id).Error; err != nil {
|
||||
t.Fatalf("layout row: %v", err)
|
||||
}
|
||||
layoutID = id
|
||||
@@ -297,6 +307,62 @@ func TestMailOverrideSmoke(t *testing.T) {
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("layouts_and_partials", func(t *testing.T) {
|
||||
gdb := mailPostgres(t)
|
||||
m, drv, logs := bootMailApp(t, gdb)
|
||||
stmts := []string{
|
||||
// A customized file layout, a database-only layout and an index
|
||||
// row that is not customized.
|
||||
`INSERT INTO ` + LayoutsTable + ` (code, source, name, content_html, content_text, content_css, is_custom) VALUES
|
||||
('acme.blog::mail.layouts.blog', 'acme.blog', 'Blog', '<div class="custom-blog">{{ .Content }}</div><style>{{ .css }}</style>', '[custom] {{ .Content }}', '.custom{margin:0}', TRUE),
|
||||
('promo', NULL, 'Promo', '<div class="promo">{{ .Content }}{{ partial "button" "url" "https://example.com" "body" "Shop" }}</div>', 'PROMO {{ .Content }}', '', TRUE),
|
||||
('` + defaultLayoutName + `', 'postcard', 'Default', '<div class="mirror">{{ .Content }}</div>', 'MIRROR {{ .Content }}', '', FALSE)`,
|
||||
// A customized built-in partial.
|
||||
`INSERT INTO ` + PartialsTable + ` (code, source, name, content_html, content_text, is_custom) VALUES
|
||||
('postcard::mail.partials.button', 'postcard', 'Button', '<a class="btn" href="{{ .url }}">{{ .body }}</a>', '{{ .body }}: {{ .url }}', TRUE),
|
||||
('postcard::mail.partials.panel', 'postcard', 'Panel', 'mirror', 'mirror', FALSE)`,
|
||||
}
|
||||
for _, stmt := range stmts {
|
||||
if err := gdb.Exec(stmt).Error; err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
}
|
||||
// With no template row the file template is sent in its customized layout.
|
||||
sendWelcome(t, m, "")
|
||||
got := lastMessage(t, drv)
|
||||
if got.Subject != file.Subject || !strings.Contains(got.HTML, `<div class="custom-blog"><p>Hi <strong>Ada</strong>`) ||
|
||||
!strings.Contains(got.HTML, "<style>.custom{margin:0}</style>") || !strings.HasPrefix(got.Text, "[custom] Hi **Ada**") {
|
||||
t.Errorf("customized file layout: %+v", got)
|
||||
}
|
||||
|
||||
// A template override on the database-only layout, which calls the
|
||||
// customized partial.
|
||||
customizeWelcome(t, gdb, "Sale", "Now.", "promo")
|
||||
sendWelcome(t, m, "")
|
||||
got = lastMessage(t, drv)
|
||||
if got.Subject != "Sale" || !strings.Contains(got.HTML, `<div class="promo"><p>Now.</p>`+"\n"+`<a class="btn" href="https://example.com">Shop</a></div>`) {
|
||||
t.Errorf("database-only layout: %+v", got)
|
||||
}
|
||||
if got.Text != "PROMO Now." {
|
||||
t.Errorf("database-only layout: text = %q", got.Text)
|
||||
}
|
||||
|
||||
// An empty template name asks for everything except a template override.
|
||||
all, err := NewDBSource(appWith(t, gdb)).MailOverrides(context.Background(), "")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if all.Template != nil || len(all.Layouts) != 2 || len(all.Partials) != 1 {
|
||||
t.Errorf("overrides without a template name = %+v", all)
|
||||
}
|
||||
if l := all.Layouts["promo"]; l.Name != "Promo" || !strings.HasPrefix(l.Text, "PROMO") {
|
||||
t.Errorf("promo layout = %+v", l)
|
||||
}
|
||||
if logs.Len() != 0 {
|
||||
t.Errorf("unexpected log output:\n%s", logs)
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("file", func(t *testing.T) {
|
||||
gdb := mailPostgres(t)
|
||||
m, drv, logs := bootMailApp(t, gdb)
|
||||
|
||||
226
modules/postcard/partials.go
Normal file
226
modules/postcard/partials.go
Normal file
@@ -0,0 +1,226 @@
|
||||
package postcard
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"crypto/rand"
|
||||
"encoding/hex"
|
||||
"fmt"
|
||||
"html/template"
|
||||
"strconv"
|
||||
"strings"
|
||||
texttemplate "text/template"
|
||||
|
||||
"github.com/yuin/goldmark"
|
||||
"github.com/yuin/goldmark/extension"
|
||||
)
|
||||
|
||||
const (
|
||||
partialSegment = "mail.partials."
|
||||
// builtinPartialPrefix is what a bare partial name such as "button"
|
||||
// resolves under.
|
||||
builtinPartialPrefix = "postcard::" + partialSegment
|
||||
// partialTokenPrefix starts the placeholder a partial call leaves in a
|
||||
// Markdown body until the body has been converted to HTML.
|
||||
partialTokenPrefix = "MAILPARTIAL"
|
||||
)
|
||||
|
||||
// partialMarkdown renders the argument of the markdown func inside
|
||||
// partials: goldmark with tables, raw HTML still dropped.
|
||||
var partialMarkdown = goldmark.New(goldmark.WithExtensions(extension.Table))
|
||||
|
||||
// partialError is a failed partial call. name is the partial's full name.
|
||||
type partialError struct {
|
||||
name string
|
||||
msg string
|
||||
}
|
||||
|
||||
func (e *partialError) Error() string {
|
||||
return "postcard: " + e.msg + " " + e.name
|
||||
}
|
||||
|
||||
// partialRun renders the partial calls of one message. Partials come from
|
||||
// the catalog, with the run's overrides replacing their sections.
|
||||
//
|
||||
// goldmark drops raw HTML, so a call in a Markdown body cannot return its
|
||||
// HTML directly. It returns a token instead, made of letters and digits
|
||||
// only so that neither html/template nor goldmark changes it, and carrying
|
||||
// a nonce drawn for this run so that no variable value can contain it.
|
||||
// swapHTML and swapText put the rendered partial in its place afterwards.
|
||||
type partialRun struct {
|
||||
cat *Catalog
|
||||
overrides map[string]PartialOverride
|
||||
nonce string
|
||||
calls []partialCall
|
||||
}
|
||||
|
||||
// partialCall is one rendered call from a body.
|
||||
type partialCall struct {
|
||||
token string
|
||||
html string
|
||||
text string
|
||||
}
|
||||
|
||||
func newPartialRun(cat *Catalog, overrides map[string]PartialOverride) *partialRun {
|
||||
return &partialRun{cat: cat, overrides: overrides}
|
||||
}
|
||||
|
||||
// partialName returns the full name a call refers to: a bare name is one of
|
||||
// postcard's built-in partials.
|
||||
func partialName(name string) string {
|
||||
if strings.Contains(name, "::") {
|
||||
return name
|
||||
}
|
||||
return builtinPartialPrefix + name
|
||||
}
|
||||
|
||||
// sections returns the text and HTML sections of a partial, from its
|
||||
// override when the run has one.
|
||||
func (r *partialRun) sections(full string) (text, html string, err error) {
|
||||
p, ok := r.cat.lookupPartial(full)
|
||||
if !ok {
|
||||
return "", "", &partialError{name: full, msg: "unknown partial"}
|
||||
}
|
||||
if ov, ok := r.overrides[full]; ok {
|
||||
return ov.Text, ov.HTML, nil
|
||||
}
|
||||
return p.textWrap, p.htmlWrap, nil
|
||||
}
|
||||
|
||||
// partialArgs turns the key/value arguments of a call into the partial's
|
||||
// data.
|
||||
func partialArgs(full string, kv []any) (map[string]any, error) {
|
||||
if len(kv)%2 != 0 {
|
||||
return nil, &partialError{name: full, msg: "arguments must be pairs of a key and a value in a call of partial"}
|
||||
}
|
||||
data := make(map[string]any, len(kv)/2)
|
||||
for i := 0; i < len(kv); i += 2 {
|
||||
key, ok := kv[i].(string)
|
||||
if !ok {
|
||||
return nil, &partialError{name: full, msg: "argument " + strconv.Itoa(i+1) + " is not a string key in a call of partial"}
|
||||
}
|
||||
data[key] = kv[i+1]
|
||||
}
|
||||
return data, nil
|
||||
}
|
||||
|
||||
func (r *partialRun) renderHTML(name string, kv []any) (string, error) {
|
||||
full := partialName(name)
|
||||
_, src, err := r.sections(full)
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
data, err := partialArgs(full, kv)
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
out, err := execHTMLFuncs(full+".html", src, data, template.FuncMap{"markdown": partialMarkdownHTML})
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
if err := validateHTML(out); err != nil {
|
||||
return "", err
|
||||
}
|
||||
return out, nil
|
||||
}
|
||||
|
||||
func (r *partialRun) renderText(name string, kv []any) (string, error) {
|
||||
full := partialName(name)
|
||||
src, _, err := r.sections(full)
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
data, err := partialArgs(full, kv)
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
return execTextFuncs(full+".text", src, data, texttemplate.FuncMap{"markdown": partialMarkdownText})
|
||||
}
|
||||
|
||||
// bodyCall is the partial func of a Markdown body: it renders both sections
|
||||
// now and returns the token that stands for them.
|
||||
func (r *partialRun) bodyCall(name string, kv ...any) (string, error) {
|
||||
html, err := r.renderHTML(name, kv)
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
text, err := r.renderText(name, kv)
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
if r.nonce == "" {
|
||||
var raw [16]byte
|
||||
if _, err := rand.Read(raw[:]); err != nil {
|
||||
return "", fmt.Errorf("postcard: partial token: %w", err)
|
||||
}
|
||||
r.nonce = strings.ToUpper(hex.EncodeToString(raw[:]))
|
||||
}
|
||||
// X is not a hexadecimal digit: it ends the nonce and the counter, so
|
||||
// one token is never the prefix of another.
|
||||
token := partialTokenPrefix + r.nonce + "X" + strconv.Itoa(len(r.calls)+1) + "X"
|
||||
r.calls = append(r.calls, partialCall{token: token, html: html, text: text})
|
||||
return token, nil
|
||||
}
|
||||
|
||||
// htmlCall is the partial func of a layout's HTML wrapper.
|
||||
func (r *partialRun) htmlCall(name string, kv ...any) (template.HTML, error) {
|
||||
out, err := r.renderHTML(name, kv)
|
||||
return template.HTML(out), err
|
||||
}
|
||||
|
||||
// textCall is the partial func of a layout's text wrapper.
|
||||
func (r *partialRun) textCall(name string, kv ...any) (string, error) {
|
||||
return r.renderText(name, kv)
|
||||
}
|
||||
|
||||
// swapHTML replaces the tokens in a converted body with the partials' HTML.
|
||||
// A token alone in a paragraph takes the paragraph with it.
|
||||
func (r *partialRun) swapHTML(html string) string {
|
||||
if len(r.calls) == 0 {
|
||||
return html
|
||||
}
|
||||
pairs := make([]string, 0, len(r.calls)*4)
|
||||
for _, c := range r.calls {
|
||||
pairs = append(pairs, "<p>"+c.token+"</p>", c.html)
|
||||
}
|
||||
for _, c := range r.calls {
|
||||
pairs = append(pairs, c.token, c.html)
|
||||
}
|
||||
// One pass: text a partial rendered is never scanned again.
|
||||
return strings.NewReplacer(pairs...).Replace(html)
|
||||
}
|
||||
|
||||
// swapText replaces the tokens in a body with the partials' text.
|
||||
func (r *partialRun) swapText(text string) string {
|
||||
if len(r.calls) == 0 {
|
||||
return text
|
||||
}
|
||||
pairs := make([]string, 0, len(r.calls)*2)
|
||||
for _, c := range r.calls {
|
||||
pairs = append(pairs, c.token, c.text)
|
||||
}
|
||||
return strings.NewReplacer(pairs...).Replace(text)
|
||||
}
|
||||
|
||||
// partialMarkdownHTML is the markdown func of a partial's HTML section.
|
||||
func partialMarkdownHTML(v any) (template.HTML, error) {
|
||||
if v == nil {
|
||||
return "", nil
|
||||
}
|
||||
var buf bytes.Buffer
|
||||
if err := partialMarkdown.Convert([]byte(fmt.Sprint(v)), &buf); err != nil {
|
||||
return "", fmt.Errorf("postcard: markdown: %w", err)
|
||||
}
|
||||
if err := validateHTML(buf.String()); err != nil {
|
||||
return "", err
|
||||
}
|
||||
return template.HTML(buf.String()), nil
|
||||
}
|
||||
|
||||
// partialMarkdownText is the markdown func of a partial's text section: the
|
||||
// Markdown source is the text.
|
||||
func partialMarkdownText(v any) string {
|
||||
if v == nil {
|
||||
return ""
|
||||
}
|
||||
return fmt.Sprint(v)
|
||||
}
|
||||
448
modules/postcard/partials_smoke_test.go
Normal file
448
modules/postcard/partials_smoke_test.go
Normal file
@@ -0,0 +1,448 @@
|
||||
package postcard
|
||||
|
||||
import (
|
||||
"context"
|
||||
"io/fs"
|
||||
"strings"
|
||||
"testing"
|
||||
"testing/fstest"
|
||||
|
||||
"git.golem15.com/golem15/summercms/modules/backpack"
|
||||
"git.golem15.com/golem15/summercms/modules/pact"
|
||||
)
|
||||
|
||||
// partialsPlugin is a fixture plugin that ships only mail partials.
|
||||
type partialsPlugin struct {
|
||||
id string
|
||||
fsys fs.FS
|
||||
partials []string
|
||||
}
|
||||
|
||||
func (p partialsPlugin) ID() string { return p.id }
|
||||
func (p partialsPlugin) MailPartialsFS() fs.FS { return p.fsys }
|
||||
func (p partialsPlugin) MailPartials() []string { return p.partials }
|
||||
|
||||
// mailPlugin is a fixture plugin that ships templates and, optionally,
|
||||
// partials.
|
||||
type mailPlugin struct {
|
||||
partialsPlugin
|
||||
templates []string
|
||||
layouts map[string]string
|
||||
}
|
||||
|
||||
func (p mailPlugin) MailTemplatesFS() fs.FS { return p.fsys }
|
||||
func (p mailPlugin) MailTemplates() []string { return p.templates }
|
||||
func (p mailPlugin) MailLayouts() map[string]string { return p.layouts }
|
||||
|
||||
// templatesOnly hides the partial capability of a mailPlugin.
|
||||
type templatesOnly struct{ p mailPlugin }
|
||||
|
||||
func (t templatesOnly) ID() string { return t.p.id }
|
||||
func (t templatesOnly) MailTemplatesFS() fs.FS { return t.p.fsys }
|
||||
func (t templatesOnly) MailTemplates() []string { return t.p.templates }
|
||||
func (t templatesOnly) MailLayouts() map[string]string { return t.p.layouts }
|
||||
|
||||
var (
|
||||
_ pact.HasMailPartials = partialsPlugin{}
|
||||
_ pact.HasMailPartials = mailPlugin{}
|
||||
_ pact.HasMailTemplates = mailPlugin{}
|
||||
_ pact.HasMailTemplates = templatesOnly{}
|
||||
)
|
||||
|
||||
// fakeOverrides is an OverrideSource with a fixed answer.
|
||||
type fakeOverrides struct{ ov Overrides }
|
||||
|
||||
func (f fakeOverrides) MailOverrides(context.Context, string) (Overrides, error) { return f.ov, nil }
|
||||
|
||||
const noteHTM = `name = "Note"
|
||||
==
|
||||
NOTE: {{ .text }}
|
||||
==
|
||||
<div class="note">{{ .text }}</div>
|
||||
`
|
||||
|
||||
func partialsFS() fstest.MapFS {
|
||||
return fstest.MapFS{
|
||||
"views/mail/welcome.htm": {Data: []byte("subject = \"Welcome\"\n==\nHi {{ .Name }}\n\n{{ partial \"button\" \"url\" .Link \"body\" \"Go\" }}\n\nBye\n")},
|
||||
"views/mail/note.htm": {Data: []byte("subject = \"Note\"\nlayout = \"blog\"\n==\n{{ partial \"acme.blog::mail.partials.note\" \"text\" .Text }}\n")},
|
||||
"views/mail/auto.htm": {Data: []byte("subject = \"Auto\"\nlayout = \"system\"\n==\nDone.\n")},
|
||||
"views/mail/bare.htm": {Data: []byte("subject = \"Bare\"\nlayout = \"minimal\"\n==\nDone.\n")},
|
||||
"views/mail/layouts/blog.htm": {Data: []byte(`name = "Blog"
|
||||
==
|
||||
{{ .Content }}
|
||||
{{ partial "acme.blog::mail.partials.note" "text" "footer" }}
|
||||
==
|
||||
<div class="blog-mail">{{ .Content }}{{ partial "acme.blog::mail.partials.note" "text" "footer" }}</div>
|
||||
<style>{{ .brandCss }}{{ .css }}</style>
|
||||
`)},
|
||||
"views/mail/partials/note.htm": {Data: []byte(noteHTM)},
|
||||
}
|
||||
}
|
||||
|
||||
func blogPlugin() mailPlugin {
|
||||
return mailPlugin{
|
||||
partialsPlugin: partialsPlugin{id: "acme.blog", fsys: partialsFS(), partials: []string{"acme.blog::mail.partials.note"}},
|
||||
templates: []string{"acme.blog::mail.welcome", "acme.blog::mail.note", "acme.blog::mail.auto", "acme.blog::mail.bare"},
|
||||
layouts: map[string]string{"blog": "acme.blog::mail.layouts.blog"},
|
||||
}
|
||||
}
|
||||
|
||||
// partialsMailer registers the blog fixture in a fresh catalog and returns a
|
||||
// mailer over it with the given overrides.
|
||||
func partialsMailer(t *testing.T, opts Options, ov *Overrides) (Mailer, *MemoryDriver) {
|
||||
t.Helper()
|
||||
p := blogPlugin()
|
||||
cat := NewCatalog()
|
||||
if err := cat.RegisterPartials(p.id, p.fsys, p.partials); err != nil {
|
||||
t.Fatalf("RegisterPartials: %v", err)
|
||||
}
|
||||
if err := cat.Register(p.id, p.fsys, p.templates, p.layouts); err != nil {
|
||||
t.Fatalf("Register: %v", err)
|
||||
}
|
||||
if ov != nil {
|
||||
opts.Overrides = fakeOverrides{ov: *ov}
|
||||
}
|
||||
drv := NewMemoryDriver()
|
||||
return NewMailer(cat, drv, opts), drv
|
||||
}
|
||||
|
||||
func sendTemplate(t *testing.T, m Mailer, drv *MemoryDriver, name string, vars map[string]any) RenderedMessage {
|
||||
t.Helper()
|
||||
if err := m.Send(context.Background(), Message{Template: name, To: []string{"ada@example.com"}, Vars: vars}); err != nil {
|
||||
t.Fatalf("Send %s: %v", name, err)
|
||||
}
|
||||
return lastMessage(t, drv)
|
||||
}
|
||||
|
||||
func bootPartials[P interface{ ID() string }](t *testing.T, plugins ...P) (*backpack.App, error) {
|
||||
t.Helper()
|
||||
app := backpack.New(nil)
|
||||
if err := Activate(app, plugins); err != nil {
|
||||
t.Fatalf("Activate: %v", err)
|
||||
}
|
||||
for _, p := range plugins {
|
||||
if err := BootPlugin(app, p); err != nil {
|
||||
return app, err
|
||||
}
|
||||
}
|
||||
return app, nil
|
||||
}
|
||||
|
||||
// TestMailPartialsSmoke covers mail partials end to end without a database:
|
||||
// the pact capability and its boot errors, partial calls in Markdown bodies
|
||||
// and in layouts, the built-in layouts, and layout and partial overrides
|
||||
// from an OverrideSource.
|
||||
func TestMailPartialsSmoke(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
t.Run("capability", func(t *testing.T) {
|
||||
if _, err := bootPartials(t, blogPlugin()); err != nil {
|
||||
t.Fatalf("a plugin with templates and a partial does not boot: %v", err)
|
||||
}
|
||||
fsys := partialsFS()
|
||||
cases := []struct {
|
||||
name string
|
||||
partials []string
|
||||
want []string
|
||||
}{
|
||||
{"foreign namespace", []string{"acme.other::mail.partials.note"}, []string{"not owned", "acme.other::mail.partials.note"}},
|
||||
{"outside mail.partials", []string{"acme.blog::mail.note"}, []string{"acme.blog::mail.note", "mail.partials."}},
|
||||
{"missing file", []string{"acme.blog::mail.partials.gone"}, []string{"missing partial acme.blog::mail.partials.gone"}},
|
||||
{"duplicate", []string{"acme.blog::mail.partials.note", "acme.blog::mail.partials.note"}, []string{"duplicate partial acme.blog::mail.partials.note"}},
|
||||
{"path escape", []string{"acme.blog::mail.partials.a/../b"}, []string{"invalid mail name"}},
|
||||
}
|
||||
for _, tc := range cases {
|
||||
_, err := bootPartials(t, partialsPlugin{id: "acme.blog", fsys: fsys, partials: tc.partials})
|
||||
if err == nil {
|
||||
t.Errorf("%s: BootPlugin succeeded", tc.name)
|
||||
continue
|
||||
}
|
||||
for _, want := range tc.want {
|
||||
if !strings.Contains(err.Error(), want) {
|
||||
t.Errorf("%s: error %q lacks %q", tc.name, err, want)
|
||||
}
|
||||
}
|
||||
}
|
||||
// The built-in names cannot be taken by a plugin.
|
||||
if err := NewCatalog().RegisterPartials("postcard", fsys, []string{"postcard::mail.partials.button"}); err == nil || !strings.Contains(err.Error(), "duplicate partial") {
|
||||
t.Errorf("re-registering a built-in partial = %v", err)
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("partials_only_plugin", func(t *testing.T) {
|
||||
// acme.kit ships only a partial; acme.blog's template calls it.
|
||||
kit := partialsPlugin{id: "acme.kit", partials: []string{"acme.kit::mail.partials.badge"}, fsys: fstest.MapFS{
|
||||
"views/mail/partials/badge.htm": {Data: []byte("name = \"Badge\"\n==\n[{{ .label }}]\n==\n<span class=\"badge\">{{ .label }}</span>\n")},
|
||||
}}
|
||||
blog := mailPlugin{
|
||||
partialsPlugin: partialsPlugin{id: "acme.blog", fsys: fstest.MapFS{
|
||||
"views/mail/hello.htm": {Data: []byte("subject = \"Hello\"\n==\nNew: {{ partial \"acme.kit::mail.partials.badge\" \"label\" \"beta\" }}\n")},
|
||||
}},
|
||||
templates: []string{"acme.blog::mail.hello"},
|
||||
}
|
||||
app := backpack.New(nil)
|
||||
if err := Activate(app, []partialsPlugin{kit}); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := BootPlugin(app, kit); err != nil {
|
||||
t.Fatalf("a plugin with only partials does not boot: %v", err)
|
||||
}
|
||||
// blog implements both capabilities but declares no partial.
|
||||
if err := BootPlugin(app, blog); err != nil {
|
||||
t.Fatalf("BootPlugin blog: %v", err)
|
||||
}
|
||||
// A plugin with only templates still boots.
|
||||
if _, err := bootPartials(t, templatesOnly{p: blog}); err != nil {
|
||||
t.Fatalf("a plugin with only templates does not boot: %v", err)
|
||||
}
|
||||
got, _ := app.Lookup[Mailer]()
|
||||
m := got.(*mailer)
|
||||
msg := sendTemplate(t, m, m.driver.(*MemoryDriver), "acme.blog::mail.hello", nil)
|
||||
if !strings.Contains(msg.HTML, `<p>New: <span class="badge">beta</span></p>`) {
|
||||
t.Errorf("HTML = %q, want the other plugin's partial inline", msg.HTML)
|
||||
}
|
||||
if !strings.Contains(msg.Text, "New: [beta]") {
|
||||
t.Errorf("text = %q", msg.Text)
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("body", func(t *testing.T) {
|
||||
m, drv := partialsMailer(t, Options{}, nil)
|
||||
msg := sendTemplate(t, m, drv, "acme.blog::mail.welcome", map[string]any{"Name": "Ada", "Link": "https://example.com/go?a=1&b=2"})
|
||||
if strings.Contains(msg.HTML, "raw HTML omitted") {
|
||||
t.Errorf("the partial was dropped by Markdown:\n%s", msg.HTML)
|
||||
}
|
||||
for _, want := range []string{
|
||||
"<p>Hi Ada</p>\n<table class=\"action\"",
|
||||
`<a href="https://example.com/go?a=1&b=2" class="button button-primary" target="_blank">Go</a>`,
|
||||
"</table>\n<p>Bye</p>",
|
||||
} {
|
||||
if !strings.Contains(msg.HTML, want) {
|
||||
t.Errorf("HTML lacks %q:\n%s", want, msg.HTML)
|
||||
}
|
||||
}
|
||||
if strings.Contains(msg.HTML, "MAILPARTIAL") || strings.Contains(msg.Text, "MAILPARTIAL") {
|
||||
t.Errorf("a token was left in the message:\n%s\n%s", msg.HTML, msg.Text)
|
||||
}
|
||||
if msg.Text != "Hi Ada\n\nGo <https://example.com/go?a=1&b=2>\n\nBye" {
|
||||
t.Errorf("text = %q", msg.Text)
|
||||
}
|
||||
|
||||
// The type argument picks the button class.
|
||||
cat := NewCatalog()
|
||||
fsys := fstest.MapFS{"views/mail/b.htm": {Data: []byte("subject = \"B\"\n==\n{{ partial \"button\" \"url\" \"https://example.com\" \"body\" \"Pay\" \"type\" \"positive\" }}\n\n{{ partial \"panel\" \"body\" \"Keep **this**.\" }}\n\n{{ partial \"table\" \"body\" .Table }}\n\n{{ partial \"subcopy\" \"body\" \"Small print.\" }}\n")}}
|
||||
if err := cat.Register("acme.blog", fsys, []string{"acme.blog::mail.b"}, nil); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
drv2 := NewMemoryDriver()
|
||||
msg = sendTemplate(t, NewMailer(cat, drv2, Options{}), drv2, "acme.blog::mail.b", map[string]any{"Table": "| Item | Qty |\n|---|---|\n| Pen | 2 |"})
|
||||
for _, want := range []string{
|
||||
`class="button button-positive"`,
|
||||
`<table class="panel`, "<p>Keep <strong>this</strong>.</p>",
|
||||
`<div class="table">`, "<th>Item</th>", "<td>Pen</td>",
|
||||
`<table class="subcopy"`, "<p>Small print.</p>",
|
||||
} {
|
||||
if !strings.Contains(msg.HTML, want) {
|
||||
t.Errorf("built-in partials: HTML lacks %q:\n%s", want, msg.HTML)
|
||||
}
|
||||
}
|
||||
for _, want := range []string{"Pay <https://example.com>", "Keep **this**.", "| Pen | 2 |", "-----\nSmall print."} {
|
||||
if !strings.Contains(msg.Text, want) {
|
||||
t.Errorf("built-in partials: text lacks %q:\n%s", want, msg.Text)
|
||||
}
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("forged_token", func(t *testing.T) {
|
||||
m, drv := partialsMailer(t, Options{}, nil)
|
||||
forged := "MAILPARTIAL1 MAILPARTIAL" + strings.Repeat("0", 32) + "X1X"
|
||||
msg := sendTemplate(t, m, drv, "acme.blog::mail.welcome", map[string]any{"Name": forged, "Link": "https://example.com"})
|
||||
if !strings.Contains(msg.HTML, "<p>Hi "+forged+"</p>") {
|
||||
t.Errorf("a forged token in a variable was not left as text:\n%s", msg.HTML)
|
||||
}
|
||||
if n := strings.Count(msg.HTML, `class="button`); n != 1 {
|
||||
t.Errorf("%d buttons rendered, want 1:\n%s", n, msg.HTML)
|
||||
}
|
||||
if !strings.Contains(msg.Text, "Hi "+forged) {
|
||||
t.Errorf("text = %q", msg.Text)
|
||||
}
|
||||
|
||||
// Tokens carry a fresh random nonce per render.
|
||||
a, b := newPartialRun(NewCatalog(), nil), newPartialRun(NewCatalog(), nil)
|
||||
ta, err := a.bodyCall("button", "url", "https://example.com", "body", "Go")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
tb, err := b.bodyCall("button", "url", "https://example.com", "body", "Go")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if ta == tb {
|
||||
t.Errorf("two renders produced the same token %q", ta)
|
||||
}
|
||||
for _, tok := range []string{ta, tb} {
|
||||
if !strings.HasPrefix(tok, "MAILPARTIAL") || len(tok) < len("MAILPARTIAL")+32 || strings.Trim(tok, "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789") != "" {
|
||||
t.Errorf("token %q is not MAILPARTIAL plus an alphanumeric nonce", tok)
|
||||
}
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("errors", func(t *testing.T) {
|
||||
cases := map[string]struct {
|
||||
body string
|
||||
want []string
|
||||
}{
|
||||
"unknown": {`{{ partial "nope" "a" "b" }}`, []string{"unknown partial", "postcard::mail.partials.nope"}},
|
||||
"unknown_ns": {`{{ partial "acme.blog::mail.partials.nope" }}`, []string{"unknown partial", "acme.blog::mail.partials.nope"}},
|
||||
"odd": {`{{ partial "button" "url" }}`, []string{"postcard::mail.partials.button", "key and a value"}},
|
||||
"key_type": {`{{ partial "button" 1 "x" }}`, []string{"postcard::mail.partials.button", "not a string"}},
|
||||
"unsafe_html": {`{{ partial "panel" "body" "Type javascript: here" }}`, []string{"dangerous"}},
|
||||
}
|
||||
for name, tc := range cases {
|
||||
cat := NewCatalog()
|
||||
fsys := fstest.MapFS{"views/mail/x.htm": {Data: []byte("subject = \"X\"\n==\n" + tc.body + "\n")}}
|
||||
if err := cat.Register("acme.blog", fsys, []string{"acme.blog::mail.x"}, nil); err != nil {
|
||||
t.Fatalf("%s: Register: %v", name, err)
|
||||
}
|
||||
drv := NewMemoryDriver()
|
||||
err := NewMailer(cat, drv, Options{}).Send(context.Background(), Message{Template: "acme.blog::mail.x", To: []string{"ada@example.com"}})
|
||||
if err == nil {
|
||||
t.Errorf("%s: Send succeeded", name)
|
||||
continue
|
||||
}
|
||||
for _, want := range tc.want {
|
||||
if !strings.Contains(err.Error(), want) {
|
||||
t.Errorf("%s: error %q lacks %q", name, err, want)
|
||||
}
|
||||
}
|
||||
if len(drv.Messages()) != 0 {
|
||||
t.Errorf("%s: a message was sent", name)
|
||||
}
|
||||
}
|
||||
|
||||
// partial is not available inside a partial.
|
||||
nested := fstest.MapFS{"views/mail/partials/outer.htm": {Data: []byte("name = \"Outer\"\n==\nx\n==\n{{ partial \"button\" }}\n")}}
|
||||
cat := NewCatalog()
|
||||
if err := cat.RegisterPartials("acme.blog", nested, []string{"acme.blog::mail.partials.outer"}); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if _, err := newPartialRun(cat, nil).htmlCall("acme.blog::mail.partials.outer"); err == nil || !strings.Contains(err.Error(), `function "partial" not defined`) {
|
||||
t.Errorf("a partial calling partial = %v", err)
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("built_in_layouts", func(t *testing.T) {
|
||||
m, drv := partialsMailer(t, Options{CSS: "p{color:red}", BrandCSS: ".brand{color:blue}"}, nil)
|
||||
msg := sendTemplate(t, m, drv, "acme.blog::mail.auto", nil)
|
||||
for _, want := range []string{
|
||||
`class="wrapper layout-system"`, "<p>Done.</p>",
|
||||
`<table class="subcopy"`, "<strong>This is an automatic message. Please do not reply to it.</strong>",
|
||||
".brand{color:blue}", "p{color:red}",
|
||||
} {
|
||||
if !strings.Contains(msg.HTML, want) {
|
||||
t.Errorf("system layout: HTML lacks %q:\n%s", want, msg.HTML)
|
||||
}
|
||||
}
|
||||
if msg.Text != "Done.\n\n\n---\nThis is an automatic message. Please do not reply to it." {
|
||||
t.Errorf("system layout: text = %q", msg.Text)
|
||||
}
|
||||
|
||||
msg = sendTemplate(t, m, drv, "acme.blog::mail.bare", nil)
|
||||
if !strings.Contains(msg.HTML, "<body>\n<p>Done.</p>\n\n</body>") || strings.Contains(msg.HTML, "content-body") || strings.Contains(msg.HTML, "layout-system") {
|
||||
t.Errorf("minimal layout: HTML = %q", msg.HTML)
|
||||
}
|
||||
if !strings.Contains(msg.HTML, "<style type=\"text/css\">.brand{color:blue}p{color:red}</style>") {
|
||||
t.Errorf("minimal layout: style block = %q", msg.HTML)
|
||||
}
|
||||
if msg.Text != "Done." {
|
||||
t.Errorf("minimal layout: text = %q", msg.Text)
|
||||
}
|
||||
|
||||
// A plugin's own alias named system wins over the built-in one.
|
||||
fsys := fstest.MapFS{
|
||||
"views/mail/auto.htm": {Data: []byte("subject = \"Auto\"\nlayout = \"system\"\n==\nDone.\n")},
|
||||
"views/mail/layouts/system.htm": {Data: []byte("name = \"Mine\"\n==\n{{ .Content }}\n==\n<div class=\"mine\">{{ .Content }}</div>\n")},
|
||||
}
|
||||
cat := NewCatalog()
|
||||
if err := cat.Register("acme.shop", fsys, []string{"acme.shop::mail.auto"}, map[string]string{"system": "acme.shop::mail.layouts.system"}); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
drv2 := NewMemoryDriver()
|
||||
msg = sendTemplate(t, NewMailer(cat, drv2, Options{}), drv2, "acme.shop::mail.auto", nil)
|
||||
if !strings.Contains(msg.HTML, `<div class="mine">`) || strings.Contains(msg.HTML, "layout-system") {
|
||||
t.Errorf("a plugin alias named system did not win: %q", msg.HTML)
|
||||
}
|
||||
|
||||
// An alias that is neither the plugin's nor built in still fails at boot.
|
||||
bad := fstest.MapFS{"views/mail/x.htm": {Data: []byte("subject = \"X\"\nlayout = \"fancy\"\n==\nx\n")}}
|
||||
if err := NewCatalog().Register("acme.shop", bad, []string{"acme.shop::mail.x"}, nil); err == nil || !strings.Contains(err.Error(), "unknown layout fancy") {
|
||||
t.Errorf("unknown alias = %v", err)
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("layout_partials", func(t *testing.T) {
|
||||
m, drv := partialsMailer(t, Options{}, nil)
|
||||
msg := sendTemplate(t, m, drv, "acme.blog::mail.note", map[string]any{"Text": "<b>hi</b>"})
|
||||
want := `<div class="blog-mail"><div class="note"><b>hi</b></div>` + "\n" + `<div class="note">footer</div></div>`
|
||||
if !strings.Contains(msg.HTML, want) {
|
||||
t.Errorf("HTML = %q, want the body partial and the layout partial", msg.HTML)
|
||||
}
|
||||
if msg.Text != "NOTE: <b>hi</b>\nNOTE: footer" {
|
||||
t.Errorf("text = %q", msg.Text)
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("overrides", func(t *testing.T) {
|
||||
ov := Overrides{
|
||||
// A customized file layout, by its full name.
|
||||
Layouts: map[string]LayoutOverride{
|
||||
"acme.blog::mail.layouts.blog": {Name: "Blog", HTML: `<div class="custom-blog">{{ .Content }}</div><style>{{ .brandCss }}{{ .css }}</style>`, Text: "[custom] {{ .Content }}", CSS: ".custom{margin:0}"},
|
||||
// A database-only layout, by its code.
|
||||
"promo": {Name: "Promo", HTML: `<div class="promo">{{ .Content }}{{ partial "acme.blog::mail.partials.note" "text" "promo" }}</div><style>{{ .css }}</style>`, Text: "PROMO {{ .Content }}", CSS: ".promo{margin:0}"},
|
||||
},
|
||||
Partials: map[string]PartialOverride{
|
||||
"acme.blog::mail.partials.note": {HTML: `<aside>{{ .text }}</aside>`, Text: "* {{ .text }}"},
|
||||
// An override of a partial that no plugin ships is ignored.
|
||||
"acme.blog::mail.partials.gone": {HTML: "x", Text: "x"},
|
||||
},
|
||||
}
|
||||
m, drv := partialsMailer(t, Options{CSS: "p{color:red}", BrandCSS: ".brand{color:blue}"}, &ov)
|
||||
msg := sendTemplate(t, m, drv, "acme.blog::mail.note", map[string]any{"Text": "hi"})
|
||||
if !strings.Contains(msg.HTML, `<div class="custom-blog"><aside>hi</aside>`) {
|
||||
t.Errorf("HTML = %q, want the customized layout and partial", msg.HTML)
|
||||
}
|
||||
if !strings.Contains(msg.HTML, "<style>.brand{color:blue}.custom{margin:0}\np{color:red}</style>") {
|
||||
t.Errorf("style block = %q, want the layout CSS before mail.css", msg.HTML)
|
||||
}
|
||||
if msg.Text != "[custom] * hi" {
|
||||
t.Errorf("text = %q", msg.Text)
|
||||
}
|
||||
|
||||
// A template override moves the template to the database-only layout.
|
||||
ov.Template = &TemplateOverride{Subject: "Promo", Body: "Sale.", Layout: "promo"}
|
||||
m, drv = partialsMailer(t, Options{CSS: "p{color:red}"}, &ov)
|
||||
msg = sendTemplate(t, m, drv, "acme.blog::mail.welcome", nil)
|
||||
if msg.Subject != "Promo" || !strings.Contains(msg.HTML, `<div class="promo"><p>Sale.</p>`+"\n"+`<aside>promo</aside></div><style>.promo{margin:0}`+"\np{color:red}</style>") {
|
||||
t.Errorf("database-only layout: %q / %q", msg.Subject, msg.HTML)
|
||||
}
|
||||
if msg.Text != "PROMO Sale." {
|
||||
t.Errorf("database-only layout: text = %q", msg.Text)
|
||||
}
|
||||
|
||||
// A customized default layout applies to templates on the default layout.
|
||||
ov = Overrides{Layouts: map[string]LayoutOverride{defaultLayoutName: {HTML: `<main>{{ .Content }}</main>`, Text: "{{ .Content }} (sent by acme)"}}}
|
||||
m, drv = partialsMailer(t, Options{}, &ov)
|
||||
msg = sendTemplate(t, m, drv, "acme.blog::mail.welcome", map[string]any{"Name": "Ada", "Link": "https://example.com"})
|
||||
if !strings.HasPrefix(msg.HTML, "<main><p>Hi Ada</p>") || !strings.HasSuffix(msg.Text, "Bye (sent by acme)") {
|
||||
t.Errorf("customized default layout: %q / %q", msg.HTML, msg.Text)
|
||||
}
|
||||
|
||||
// A partial override that does not render falls back to the files.
|
||||
ov = Overrides{Partials: map[string]PartialOverride{"acme.blog::mail.partials.note": {HTML: `{{ .text.missing.field }}`, Text: "x"}}}
|
||||
m, drv = partialsMailer(t, Options{}, &ov)
|
||||
msg = sendTemplate(t, m, drv, "acme.blog::mail.note", map[string]any{"Text": "hi"})
|
||||
if !strings.Contains(msg.HTML, `<div class="note">hi</div>`) {
|
||||
t.Errorf("a failing partial override did not fall back to the file: %q", msg.HTML)
|
||||
}
|
||||
})
|
||||
}
|
||||
@@ -2,6 +2,7 @@ package postcard
|
||||
|
||||
import (
|
||||
"context"
|
||||
"database/sql"
|
||||
"fmt"
|
||||
|
||||
"git.golem15.com/golem15/summercms/modules/backpack"
|
||||
@@ -140,9 +141,11 @@ type Overrides struct {
|
||||
// Template is the customized subject, body and layout of the template
|
||||
// being sent, or nil.
|
||||
Template *TemplateOverride
|
||||
// Layouts holds layout content by layout code.
|
||||
// Layouts holds layout content by layout code: the full name of a
|
||||
// customized file layout, or the code of a database-only layout. The
|
||||
// layout a render uses is taken from here when its code is present.
|
||||
Layouts map[string]LayoutOverride
|
||||
// Partials holds partial content by partial name.
|
||||
// Partials holds the customized sections of partials by full name.
|
||||
Partials map[string]PartialOverride
|
||||
}
|
||||
|
||||
@@ -160,7 +163,8 @@ type TemplateOverride struct {
|
||||
Layout string
|
||||
}
|
||||
|
||||
// LayoutOverride replaces a layout's wrappers and adds its CSS.
|
||||
// LayoutOverride is a layout's content from the database: the HTML and text
|
||||
// wrappers, and CSS that is placed before mail.css in the layout's css slot.
|
||||
type LayoutOverride struct {
|
||||
Name string
|
||||
HTML string
|
||||
@@ -178,6 +182,10 @@ type PartialOverride struct {
|
||||
// looks the *gorm.DB up on app at every call and never caches a row, so an
|
||||
// edit is effective on the next send in every process that shares the
|
||||
// database. With no database published it returns no overrides and no error.
|
||||
//
|
||||
// One call reads, in one read-only transaction, the customized row of the
|
||||
// template, every customized file layout and every database-only layout, and
|
||||
// every customized partial.
|
||||
func NewDBSource(app *backpack.App) OverrideSource {
|
||||
return &dbSource{app: app}
|
||||
}
|
||||
@@ -199,23 +207,60 @@ func (s *dbSource) MailOverrides(ctx context.Context, name string) (Overrides, e
|
||||
// The mailer reports a failed lookup itself, rate-limited; GORM's own
|
||||
// error line per send would repeat it for every message.
|
||||
db := gdb.Session(&gorm.Session{Logger: gdb.Logger.LogMode(logger.Silent)}).WithContext(ctx)
|
||||
if name == "" {
|
||||
return out, nil
|
||||
}
|
||||
var rows []struct {
|
||||
Subject string
|
||||
Body string
|
||||
Layout string
|
||||
}
|
||||
err := db.Raw(`SELECT t.subject, t.body, COALESCE(l.code, '') AS layout
|
||||
err := db.Transaction(func(tx *gorm.DB) error {
|
||||
if name != "" {
|
||||
var rows []struct {
|
||||
Subject string
|
||||
Body string
|
||||
Layout string
|
||||
}
|
||||
err := tx.Raw(`SELECT t.subject, t.body, COALESCE(l.code, '') AS layout
|
||||
FROM `+TemplatesTable+` t
|
||||
LEFT JOIN `+LayoutsTable+` l ON l.id = t.layout_id
|
||||
WHERE t.code = ? AND t.is_custom`, name).Scan(&rows).Error
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
if len(rows) > 0 {
|
||||
out.Template = &TemplateOverride{Subject: rows[0].Subject, Body: rows[0].Body, Layout: rows[0].Layout}
|
||||
}
|
||||
}
|
||||
// is_custom is set on a customized file layout and on every
|
||||
// database-only layout.
|
||||
var layouts []struct {
|
||||
Code string
|
||||
Name string
|
||||
ContentHTML string `gorm:"column:content_html"`
|
||||
ContentText string `gorm:"column:content_text"`
|
||||
ContentCSS string `gorm:"column:content_css"`
|
||||
}
|
||||
if err := tx.Raw(`SELECT code, name, content_html, content_text, content_css FROM ` + LayoutsTable + ` WHERE is_custom`).Scan(&layouts).Error; err != nil {
|
||||
return err
|
||||
}
|
||||
for _, l := range layouts {
|
||||
if out.Layouts == nil {
|
||||
out.Layouts = make(map[string]LayoutOverride, len(layouts))
|
||||
}
|
||||
out.Layouts[l.Code] = LayoutOverride{Name: l.Name, HTML: l.ContentHTML, Text: l.ContentText, CSS: l.ContentCSS}
|
||||
}
|
||||
var partials []struct {
|
||||
Code string
|
||||
ContentHTML string `gorm:"column:content_html"`
|
||||
ContentText string `gorm:"column:content_text"`
|
||||
}
|
||||
if err := tx.Raw(`SELECT code, content_html, content_text FROM ` + PartialsTable + ` WHERE is_custom`).Scan(&partials).Error; err != nil {
|
||||
return err
|
||||
}
|
||||
for _, p := range partials {
|
||||
if out.Partials == nil {
|
||||
out.Partials = make(map[string]PartialOverride, len(partials))
|
||||
}
|
||||
out.Partials[p.Code] = PartialOverride{HTML: p.ContentHTML, Text: p.ContentText}
|
||||
}
|
||||
return nil
|
||||
}, &sql.TxOptions{ReadOnly: true, Isolation: sql.LevelRepeatableRead})
|
||||
if err != nil {
|
||||
return Overrides{}, fmt.Errorf("postcard: mail overrides: %w", err)
|
||||
}
|
||||
if len(rows) > 0 {
|
||||
out.Template = &TemplateOverride{Subject: rows[0].Subject, Body: rows[0].Body, Layout: rows[0].Layout}
|
||||
}
|
||||
return out, nil
|
||||
}
|
||||
|
||||
@@ -2,7 +2,7 @@ package postcard
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
_ "embed"
|
||||
"embed"
|
||||
"fmt"
|
||||
"html/template"
|
||||
"io/fs"
|
||||
@@ -15,12 +15,27 @@ import (
|
||||
)
|
||||
|
||||
const (
|
||||
builtinPluginID = "postcard"
|
||||
defaultLayoutAlias = "default"
|
||||
defaultLayoutName = "postcard::mail.layouts.default"
|
||||
systemLayoutName = "postcard::mail.layouts.system"
|
||||
minimalLayoutName = "postcard::mail.layouts.minimal"
|
||||
mailPrefix = "mail."
|
||||
assetRoot = "views/mail/"
|
||||
)
|
||||
|
||||
// builtinLayoutAliases are the layout aliases every plugin's templates can
|
||||
// use. A plugin's own alias of the same name wins, except default, which is
|
||||
// reserved.
|
||||
var builtinLayoutAliases = map[string]string{
|
||||
defaultLayoutAlias: defaultLayoutName,
|
||||
"system": systemLayoutName,
|
||||
"minimal": minimalLayoutName,
|
||||
}
|
||||
|
||||
// builtinPartials are the partials postcard ships, callable by bare name.
|
||||
var builtinPartials = []string{"button", "panel", "subcopy", "table"}
|
||||
|
||||
var (
|
||||
dangerousScheme = regexp.MustCompile(`(?i)(?:javascript|vbscript|data):`)
|
||||
eventHandler = regexp.MustCompile(`(?i)\son[a-z]+\s*=`)
|
||||
@@ -32,11 +47,17 @@ var (
|
||||
//go:embed assets/default.htm
|
||||
var defaultLayoutSource string
|
||||
|
||||
// Catalog holds registered mail templates and layouts.
|
||||
// builtinAssets holds postcard's own layouts and partials.
|
||||
//
|
||||
//go:embed assets
|
||||
var builtinAssets embed.FS
|
||||
|
||||
// Catalog holds registered mail templates, layouts and partials.
|
||||
type Catalog struct {
|
||||
mu sync.RWMutex
|
||||
templates map[string]*parsedTemplate
|
||||
layouts map[string]*parsedLayout
|
||||
partials map[string]*parsedPartial
|
||||
aliases map[string]map[string]string // pluginID -> short name -> full name
|
||||
}
|
||||
|
||||
@@ -57,19 +78,53 @@ type parsedLayout struct {
|
||||
htmlWrap string
|
||||
}
|
||||
|
||||
// NewCatalog returns an empty catalog that already contains postcard's
|
||||
// neutral default layout.
|
||||
// parsedPartial is a partial file: the layout file format, a header, a text
|
||||
// section and an HTML section.
|
||||
type parsedPartial struct {
|
||||
name string
|
||||
pluginID string
|
||||
headerName string
|
||||
textWrap string
|
||||
htmlWrap string
|
||||
}
|
||||
|
||||
// NewCatalog returns a catalog that already contains postcard's built-in
|
||||
// layouts (default, system and minimal) and partials (button, panel, table
|
||||
// and subcopy). It holds no template.
|
||||
func NewCatalog() *Catalog {
|
||||
c := &Catalog{
|
||||
templates: make(map[string]*parsedTemplate),
|
||||
layouts: make(map[string]*parsedLayout),
|
||||
partials: make(map[string]*parsedPartial),
|
||||
aliases: make(map[string]map[string]string),
|
||||
}
|
||||
layout, err := parseLayout(defaultLayoutName, "postcard", defaultLayoutSource)
|
||||
layout, err := parseLayout(defaultLayoutName, builtinPluginID, defaultLayoutSource)
|
||||
if err != nil {
|
||||
panic("postcard: default layout: " + err.Error())
|
||||
}
|
||||
c.layouts[defaultLayoutName] = layout
|
||||
for file, name := range map[string]string{"system": systemLayoutName, "minimal": minimalLayoutName} {
|
||||
raw, err := builtinAssets.ReadFile("assets/" + file + ".htm")
|
||||
if err != nil {
|
||||
panic("postcard: " + file + " layout: " + err.Error())
|
||||
}
|
||||
layout, err := parseLayout(name, builtinPluginID, string(raw))
|
||||
if err != nil {
|
||||
panic("postcard: " + file + " layout: " + err.Error())
|
||||
}
|
||||
c.layouts[name] = layout
|
||||
}
|
||||
for _, short := range builtinPartials {
|
||||
raw, err := builtinAssets.ReadFile("assets/partials/" + short + ".htm")
|
||||
if err != nil {
|
||||
panic("postcard: " + short + " partial: " + err.Error())
|
||||
}
|
||||
partial, err := parsePartial(builtinPartialPrefix+short, builtinPluginID, string(raw))
|
||||
if err != nil {
|
||||
panic("postcard: " + short + " partial: " + err.Error())
|
||||
}
|
||||
c.partials[partial.name] = partial
|
||||
}
|
||||
return c
|
||||
}
|
||||
|
||||
@@ -160,6 +215,10 @@ func (c *Catalog) resolveLayoutLocked(t *parsedTemplate) error {
|
||||
return nil
|
||||
}
|
||||
full, ok := c.aliases[t.pluginID][short]
|
||||
if !ok {
|
||||
// Not one of the plugin's own aliases: a built-in layout.
|
||||
full, ok = builtinLayoutAliases[short]
|
||||
}
|
||||
if !ok {
|
||||
return fmt.Errorf("postcard: unknown layout %s", short)
|
||||
}
|
||||
@@ -180,17 +239,50 @@ func (c *Catalog) lookupTemplate(name string) (*parsedTemplate, error) {
|
||||
return t, nil
|
||||
}
|
||||
|
||||
func (c *Catalog) lookupLayout(name string) (*parsedLayout, error) {
|
||||
// RegisterPartials loads declared partial names from fsys. Each name must
|
||||
// be owned by pluginID, have the form <plugin>::mail.partials.<name> and map
|
||||
// to views/mail/partials/<name>.htm.
|
||||
func (c *Catalog) RegisterPartials(pluginID string, fsys fs.FS, partials []string) error {
|
||||
if c == nil {
|
||||
return fmt.Errorf("postcard: catalog is nil")
|
||||
}
|
||||
if pluginID == "" {
|
||||
return fmt.Errorf("postcard: plugin id is empty")
|
||||
}
|
||||
c.mu.Lock()
|
||||
defer c.mu.Unlock()
|
||||
for _, name := range partials {
|
||||
if err := assertOwner(pluginID, name); err != nil {
|
||||
return err
|
||||
}
|
||||
if _, rest, _ := strings.Cut(name, "::"); !strings.HasPrefix(rest, partialSegment) || rest == partialSegment {
|
||||
return fmt.Errorf("postcard: invalid partial name %s (want %s::%s<name>)", name, pluginID, partialSegment)
|
||||
}
|
||||
if _, exists := c.partials[name]; exists {
|
||||
return fmt.Errorf("postcard: duplicate partial %s", name)
|
||||
}
|
||||
path, err := assetPath(name)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
raw, err := fs.ReadFile(fsys, path)
|
||||
if err != nil {
|
||||
return fmt.Errorf("postcard: missing partial %s", name)
|
||||
}
|
||||
parsed, err := parsePartial(name, pluginID, string(raw))
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
c.partials[name] = parsed
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func (c *Catalog) lookupPartial(name string) (*parsedPartial, bool) {
|
||||
c.mu.RLock()
|
||||
defer c.mu.RUnlock()
|
||||
if name == "" || name == defaultLayoutAlias {
|
||||
name = defaultLayoutName
|
||||
}
|
||||
l, ok := c.layouts[name]
|
||||
if !ok {
|
||||
return nil, fmt.Errorf("postcard: missing layout %s", name)
|
||||
}
|
||||
return l, nil
|
||||
p, ok := c.partials[name]
|
||||
return p, ok
|
||||
}
|
||||
|
||||
func assertOwner(pluginID, fullName string) error {
|
||||
@@ -253,6 +345,14 @@ func parseLayout(name, pluginID, src string) (*parsedLayout, error) {
|
||||
}, nil
|
||||
}
|
||||
|
||||
func parsePartial(name, pluginID, src string) (*parsedPartial, error) {
|
||||
l, err := parseLayout(name, pluginID, src)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return &parsedPartial{name: l.name, pluginID: l.pluginID, headerName: l.headerName, textWrap: l.textWrap, htmlWrap: l.htmlWrap}, nil
|
||||
}
|
||||
|
||||
func splitTwo(src string) (header, body string, err error) {
|
||||
parts, err := splitEQ(src, 2)
|
||||
if err != nil {
|
||||
@@ -373,7 +473,10 @@ func (c *Catalog) renderFrom(msg Message, src renderSource, opts renderOptions)
|
||||
if strings.ContainsAny(subject, "\r\n") {
|
||||
return out, fmt.Errorf("postcard: subject contains CR/LF")
|
||||
}
|
||||
markdownBody, err := execHTML(src.name+".body", src.body, vars)
|
||||
// Partial calls in the body leave tokens that are swapped for the
|
||||
// rendered partials once Markdown has run; see partialRun.
|
||||
partials := newPartialRun(c, opts.overrides.Partials)
|
||||
markdownBody, err := execHTMLFuncs(src.name+".body", src.body, vars, template.FuncMap{"partial": partials.bodyCall})
|
||||
if err != nil {
|
||||
return out, err
|
||||
}
|
||||
@@ -381,6 +484,8 @@ func (c *Catalog) renderFrom(msg Message, src renderSource, opts renderOptions)
|
||||
if err != nil {
|
||||
return out, err
|
||||
}
|
||||
htmlBody = partials.swapHTML(htmlBody)
|
||||
textBody := partials.swapText(markdownBody)
|
||||
if err := validateHTML(htmlBody); err != nil {
|
||||
return out, err
|
||||
}
|
||||
@@ -388,21 +493,29 @@ func (c *Catalog) renderFrom(msg Message, src renderSource, opts renderOptions)
|
||||
if err != nil {
|
||||
return out, err
|
||||
}
|
||||
text, err := execText(layout.name+".text", layout.textWrap, map[string]any{
|
||||
"Content": markdownBody,
|
||||
// A layout's own CSS goes before mail.css in the css slot.
|
||||
css := opts.css
|
||||
if layout.css != "" {
|
||||
css = layout.css
|
||||
if opts.css != "" {
|
||||
css += "\n" + opts.css
|
||||
}
|
||||
}
|
||||
text, err := execTextFuncs(layout.name+".text", layout.textWrap, map[string]any{
|
||||
"Content": textBody,
|
||||
"Subject": subject,
|
||||
"css": opts.css,
|
||||
"css": css,
|
||||
"brandCss": opts.brandCSS,
|
||||
})
|
||||
}, texttemplate.FuncMap{"partial": partials.textCall})
|
||||
if err != nil {
|
||||
return out, err
|
||||
}
|
||||
html, err := execHTML(layout.name+".html", layout.htmlWrap, map[string]any{
|
||||
html, err := execHTMLFuncs(layout.name+".html", layout.htmlWrap, map[string]any{
|
||||
"Content": template.HTML(htmlBody),
|
||||
"Subject": subject,
|
||||
"css": template.CSS(opts.css),
|
||||
"css": template.CSS(css),
|
||||
"brandCss": template.CSS(opts.brandCSS),
|
||||
})
|
||||
}, template.FuncMap{"partial": partials.htmlCall})
|
||||
if err != nil {
|
||||
return out, err
|
||||
}
|
||||
@@ -421,20 +534,54 @@ func (c *Catalog) renderFrom(msg Message, src renderSource, opts renderOptions)
|
||||
return out, nil
|
||||
}
|
||||
|
||||
// layoutFor returns the layout src renders in. A layout code from an
|
||||
// override that names no layout is reported through opts.warn and replaced
|
||||
// by the default layout.
|
||||
func (c *Catalog) layoutFor(src renderSource, opts renderOptions) (*parsedLayout, error) {
|
||||
layout, err := c.lookupLayout(src.layout)
|
||||
if err == nil || !src.layoutFromOverride {
|
||||
// renderLayout is the layout one render uses: a file layout, a file layout
|
||||
// with its override applied, or a database-only layout.
|
||||
type renderLayout struct {
|
||||
name string // layout code, used in parse and execute errors
|
||||
textWrap string
|
||||
htmlWrap string
|
||||
css string
|
||||
}
|
||||
|
||||
// layoutFor returns the layout src renders in. An override of that layout,
|
||||
// or a database-only layout of that code, wins over the file. A layout code
|
||||
// from a template override that names no layout is reported through
|
||||
// opts.warn and replaced by the default layout.
|
||||
func (c *Catalog) layoutFor(src renderSource, opts renderOptions) (renderLayout, error) {
|
||||
code := src.layout
|
||||
if code == "" || code == defaultLayoutAlias {
|
||||
code = defaultLayoutName
|
||||
}
|
||||
layout, ok, err := c.layoutByCode(code, opts.overrides.Layouts)
|
||||
if err != nil || ok {
|
||||
return layout, err
|
||||
}
|
||||
if opts.warn != nil {
|
||||
opts.warn("layout:"+src.name+":"+src.layout,
|
||||
"postcard: override names an unknown layout, using the default layout",
|
||||
"template", src.name, "layout", src.layout)
|
||||
if !src.layoutFromOverride {
|
||||
return renderLayout{}, fmt.Errorf("postcard: missing layout %s", code)
|
||||
}
|
||||
return c.lookupLayout(defaultLayoutAlias)
|
||||
if opts.warn != nil {
|
||||
opts.warn("layout:"+src.name+":"+code,
|
||||
"postcard: override names an unknown layout, using the default layout",
|
||||
"template", src.name, "layout", code)
|
||||
}
|
||||
layout, ok, err = c.layoutByCode(defaultLayoutName, opts.overrides.Layouts)
|
||||
if err == nil && !ok {
|
||||
err = fmt.Errorf("postcard: missing layout %s", defaultLayoutName)
|
||||
}
|
||||
return layout, err
|
||||
}
|
||||
|
||||
func (c *Catalog) layoutByCode(code string, overrides map[string]LayoutOverride) (renderLayout, bool, error) {
|
||||
if ov, ok := overrides[code]; ok {
|
||||
return renderLayout{name: code, textWrap: ov.Text, htmlWrap: ov.HTML, css: ov.CSS}, true, nil
|
||||
}
|
||||
c.mu.RLock()
|
||||
l, ok := c.layouts[code]
|
||||
c.mu.RUnlock()
|
||||
if !ok {
|
||||
return renderLayout{}, false, nil
|
||||
}
|
||||
return renderLayout{name: l.name, textWrap: l.textWrap, htmlWrap: l.htmlWrap}, true, nil
|
||||
}
|
||||
|
||||
func markdownHTML(src string) (string, error) {
|
||||
@@ -459,7 +606,17 @@ func validateHTML(html string) error {
|
||||
}
|
||||
|
||||
func execHTML(name, src string, data any) (string, error) {
|
||||
tmpl, err := template.New(name).Option("missingkey=zero").Parse(src)
|
||||
return execHTMLFuncs(name, src, data, nil)
|
||||
}
|
||||
|
||||
func execText(name, src string, data any) (string, error) {
|
||||
return execTextFuncs(name, src, data, nil)
|
||||
}
|
||||
|
||||
// execHTMLFuncs is execHTML with template funcs; they must be set before
|
||||
// the source is parsed.
|
||||
func execHTMLFuncs(name, src string, data any, funcs template.FuncMap) (string, error) {
|
||||
tmpl, err := template.New(name).Option("missingkey=zero").Funcs(funcs).Parse(src)
|
||||
if err != nil {
|
||||
return "", fmt.Errorf("postcard: parse %s: %w", name, err)
|
||||
}
|
||||
@@ -470,8 +627,8 @@ func execHTML(name, src string, data any) (string, error) {
|
||||
return buf.String(), nil
|
||||
}
|
||||
|
||||
func execText(name, src string, data any) (string, error) {
|
||||
tmpl, err := texttemplate.New(name).Option("missingkey=zero").Parse(src)
|
||||
func execTextFuncs(name, src string, data any, funcs texttemplate.FuncMap) (string, error) {
|
||||
tmpl, err := texttemplate.New(name).Option("missingkey=zero").Funcs(funcs).Parse(src)
|
||||
if err != nil {
|
||||
return "", fmt.Errorf("postcard: parse %s: %w", name, err)
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user