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.
|
||||
|
||||
@@ -22,7 +22,7 @@ Use cases:
|
||||
|
||||
## Features
|
||||
|
||||
- Plugin capability interfaces: `pact.HasRoutes`, `pact.HasConfig`, `pact.HasMigrations`, `pact.HasCommands`, `pact.HasModels`, `pact.HasJobs`, `pact.HasSchedule`, `pact.HasLang`, `pact.HasLangOverrides` and `pact.HasMailTemplates`.
|
||||
- Plugin capability interfaces: `pact.HasRoutes`, `pact.HasConfig`, `pact.HasMigrations`, `pact.HasCommands`, `pact.HasModels`, `pact.HasJobs`, `pact.HasSchedule`, `pact.HasLang`, `pact.HasLangOverrides`, `pact.HasMailTemplates` and `pact.HasMailPartials`.
|
||||
- HTTP contracts: the `pact.Router` group builder (implemented by surf), the `pact.Middleware` type, and named, parameterized (`name:param`) and house-envelope middleware through `pact.HasMiddleware`, `pact.HasMiddlewareFactories` and `pact.HasHouseMiddleware`.
|
||||
- Backend registration data: `pact.Permission`, `pact.NavigationItem` and `pact.SettingsItem`, exposed through `pact.HasPermissions`, `pact.HasNavigation` and `pact.HasSettings`. A settings entry is either a singleton form or a link that opens an admin controller from the Settings page. A `pact.NavigationItem.Visible` func hides a navigation entry at request time (nil = always listed).
|
||||
- Personal API token scopes: `pact.TokenScope` and `pact.HasTokenScopes`, so a plugin declares named scopes (permissions and HTTP methods) that administrators can assign when creating a personal API token.
|
||||
@@ -121,6 +121,7 @@ func (p *Plugin) Schedule() []pact.ScheduledCommand {
|
||||
| `pact.HasLang` | Ships translation YAML under `lang/<locale>/<group>.yaml`. |
|
||||
| `pact.HasLangOverrides` | Replaces or adds translations of any loaded namespace, including the framework's own. |
|
||||
| `pact.HasMailTemplates` | Ships mail templates and layout aliases. |
|
||||
| `pact.HasMailPartials` | Ships mail partials, named `<plugin>::mail.partials.<name>` and loaded from `views/mail/partials/<name>.htm`. Independent of `pact.HasMailTemplates`. |
|
||||
| `pact.Permission` | One backend permission entry (code, tab, label, roles). |
|
||||
| `pact.HasPermissions` | Declares backend permissions. |
|
||||
| `pact.TokenScope` | One personal API token scope: name, label, description, permission patterns and HTTP methods. |
|
||||
|
||||
@@ -1274,6 +1274,19 @@ type HasMailTemplates interface {
|
||||
MailLayouts() map[string]string
|
||||
}
|
||||
|
||||
// HasMailPartials is implemented by plugins that ship mail partials: reusable
|
||||
// blocks that mail template bodies and layouts call with
|
||||
// {{ partial "<name>" "key" value ... }}. MailPartialsFS contains the
|
||||
// views/mail assets; MailPartials lists dotted names of the form
|
||||
// <plugin>::mail.partials.<name>, each loaded from
|
||||
// views/mail/partials/<name>.htm. A plugin may only declare names in its own
|
||||
// namespace. The capability is independent of HasMailTemplates: a plugin may
|
||||
// implement either or both.
|
||||
type HasMailPartials interface {
|
||||
MailPartialsFS() fs.FS
|
||||
MailPartials() []string
|
||||
}
|
||||
|
||||
// OptionalMessage is a service an optional plugin may publish so other
|
||||
// plugins can integrate without importing that plugin's package.
|
||||
type OptionalMessage interface {
|
||||
|
||||
@@ -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