diff --git a/admin/tests/form/FormViewMail.test.ts b/admin/tests/form/FormViewMail.test.ts
index 61c5277f..0a6d3f9f 100644
--- a/admin/tests/form/FormViewMail.test.ts
+++ b/admin/tests/form/FormViewMail.test.ts
@@ -107,6 +107,26 @@ describe('FormView mail footer actions and meta.deletable', () => {
expect(absent.wrapper.find('[data-action="delete"]').exists()).toBe(true)
})
+ it('shows the locale switcher from meta.localeVariants when there are two or more', async () => {
+ const two = await mountApp(
+ '/summercms/cabana/mailtemplates/7',
+ routes({
+ [`GET ${RECORD}`]: mailRecord({
+ localeVariants: [
+ { id: 7, locale: '', label: 'Default', states: [], current: true },
+ { id: 9, locale: 'de', label: 'de', states: ['Customized'], current: false },
+ ],
+ }),
+ }),
+ )
+ const select = two.wrapper.find('header select[data-locale-variant]')
+ expect(select.exists()).toBe(true)
+ expect(select.findAll('option').map((option) => option.text())).toEqual(['Default', 'de — Customized'])
+
+ const none = await mountApp('/summercms/cabana/mailtemplates/7', routes())
+ expect(none.wrapper.find('[data-locale-variant]').exists()).toBe(false)
+ })
+
it('toasts 403 and 409 paths from record actions', async () => {
const forbidden = await mountApp(
'/summercms/cabana/mailtemplates/7',
diff --git a/admin/tests/form/LocaleVariantSwitcher.test.ts b/admin/tests/form/LocaleVariantSwitcher.test.ts
new file mode 100644
index 00000000..5937630c
--- /dev/null
+++ b/admin/tests/form/LocaleVariantSwitcher.test.ts
@@ -0,0 +1,75 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { enableAutoUnmount, flushPromises, mount } from '@vue/test-utils'
+import { defineComponent, h } from 'vue'
+import { createMemoryHistory, createRouter } from 'vue-router'
+import LocaleVariantSwitcher from '../../src/components/form/LocaleVariantSwitcher.vue'
+import { setBundle } from '../../src/app/i18n'
+import { resetState } from '../helpers'
+
+const variants = [
+ { id: 7, locale: '', label: 'Default', states: [], current: true },
+ { id: 9, locale: 'de', label: 'de', states: ['Customized', 'File changed'], current: false },
+ { id: 8, locale: 'en', label: 'en', states: [], current: false },
+]
+
+const Stub = defineComponent({ render: () => h('div') })
+
+async function mountSwitcher(allow: () => boolean) {
+ const router = createRouter({
+ history: createMemoryHistory(),
+ routes: [{ path: '/:vendor/:plugin/:controller/:id', name: 'update', component: Stub }],
+ })
+ router.beforeEach((_to, from) => (from.matched.length === 0 ? true : allow()))
+ await router.push('/summercms/cabana/mailtemplates/7')
+ const wrapper = mount(LocaleVariantSwitcher, {
+ props: { variants },
+ global: { plugins: [router] },
+ attachTo: document.body,
+ })
+ return { wrapper, router }
+}
+
+beforeEach(() => {
+ resetState()
+ setBundle({ 'backend::lang.form.locale_variant': { other: 'Language' } }, 'en')
+})
+
+afterEach(() => {
+ document.body.innerHTML = ''
+})
+
+enableAutoUnmount(afterEach)
+
+describe('LocaleVariantSwitcher', () => {
+ it('is a labelled select of the variants with their states, the current one selected', async () => {
+ const { wrapper } = await mountSwitcher(() => true)
+ const select = wrapper.find('select[data-locale-variant]')
+ expect(select.exists()).toBe(true)
+ const label = wrapper.find('label')
+ expect(label.text()).toBe('Language')
+ expect(label.attributes('for')).toBe(select.attributes('id'))
+ expect(wrapper.findAll('option').map((option) => option.text())).toEqual([
+ 'Default',
+ 'de — Customized, File changed',
+ 'en',
+ ])
+ expect(select.element.value).toBe('7')
+ })
+
+ it('opens the chosen version on the same route', async () => {
+ const { wrapper, router } = await mountSwitcher(() => true)
+ await wrapper.find('select').setValue('9')
+ await flushPromises()
+ expect(router.currentRoute.value.params.id).toBe('9')
+ expect(router.currentRoute.value.path).toBe('/summercms/cabana/mailtemplates/9')
+ })
+
+ it('puts the selection back when the navigation is refused', async () => {
+ const { wrapper, router } = await mountSwitcher(() => false)
+ const select = wrapper.find('select')
+ await select.setValue('8')
+ await flushPromises()
+ expect(router.currentRoute.value.params.id).toBe('7')
+ expect(select.element.value).toBe('7')
+ })
+})
diff --git a/docs/backend/forms.md b/docs/backend/forms.md
index 33b02856..038a11ba 100644
--- a/docs/backend/forms.md
+++ b/docs/backend/forms.md
@@ -31,7 +31,7 @@ On a create form Save follows `redirect` and Save and close follows `redirectClo
An optional `recordActions` key lists the record actions the form offers, by the names the controller registers through `pact.HasAdminRecordActions`. When the form has a `preview` block, those actions appear on the [preview screen](#preview-screen). When it has no preview, the update form footer shows them after Delete (outline buttons; a `danger` action uses the danger confirm). The show response of a record carries `meta.actions`: the declared actions the administrator may run and that apply to the record in its current state. See [Record actions](admin-controllers.md#record-actions).
-`meta.deletable` on the show response hides Delete when it is `false`. When the key is absent, Delete behaves as before (`true`), so existing controllers are unchanged. After every successful save and record action, `type: partial` fields reload so status hints and diffs stay current.
+`meta.deletable` on the show response hides Delete when it is `false`. When the key is absent, Delete behaves as before (`true`), so existing controllers are unchanged. `meta.localeVariants` on the show and update responses lists the locale versions of a record whose versions are separate rows (the mail templates screen, `cabana.RecordMeta.LocaleVariants`): each with its row `id`, `locale`, translated `label` and `states`, and `current` for the open record. With two or more, the update form shows a Language select under the title; choosing a version opens that record on the same route, behind the unsaved-changes confirm. Other controllers send no key. After every successful save and record action, `type: partial` fields reload so status hints and diffs stay current.
## fields.yaml
diff --git a/docs/services/mail.md b/docs/services/mail.md
index 5480a12b..02ab836a 100644
--- a/docs/services/mail.md
+++ b/docs/services/mail.md
@@ -139,7 +139,7 @@ fmt.Println(err != nil, len(driver.Messages()))
// true 1
```
-postcard does not pick a locale. For a per-language template, register one name per language (`acme.blog::mail.welcome_pl`) and pass the full name.
+postcard does not pick a locale: the caller passes the full name. A per-language version of a template is a file named after the template, a dash and the locale (`welcome-en.htm`, sent as `acme.blog::mail.welcome-en`). A name with its own file always renders that file. A name the catalog does not hold, of the form `-` where `` is registered and `` is a locale tag (two letters, optionally followed by `-` or `_` and a 2 to 8 character subtag, such as `de` or `pt-BR`), sends the default-locale version: the locale's own version when an administrator customized it, else the customized template, else the template's file. Any other unknown name fails with `postcard: unknown template `. So a plugin can pass `-` for every locale it serves, and a locale without a file still sends mail, in the default language until someone writes that locale's version in the admin.
Before a driver sees a message, postcard refuses a subject or address with a line break, parses every address with `net/mail`, and rejects rendered HTML that contains script, iframe, object or embed tags, inline event handlers, or `javascript:`, `vbscript:` or `data:` URLs. Variables are escaped by Go's `html/template`.
diff --git a/modules/cabana/README.md b/modules/cabana/README.md
index 0b5a1baf..0bb2e22b 100644
--- a/modules/cabana/README.md
+++ b/modules/cabana/README.md
@@ -59,7 +59,7 @@ Use cases:
- Form fields on another plugin's controller: a `pact.AdminActionExtension` with `Form` set to a `pact.AdminFormExtension` places fields and tabs in any admin controller's form by its ID. Its fields document is the `fields.yaml` format plus `before:`/`after:` anchors, `zone:` (only the tab zone for now) and a `tabs:` list, compiled at boot with every `fields.yaml` check; extensions apply in plugin activation order and the form is sent in the compiled order, so the SPA adds no ordering. `Hide` removes owner fields, `Permissions` and `Visible` decide per request who sees the fields (schema, show and save alike), widget fields run the extension's `Actions` and partial fields render from its `Dir` through `PartialData`. Extension values leave the save body before any owner path reads them; `Save` runs in the record's save transaction after the owner row is written (`pact.AdminFormErrors` answers 422, its notices join `meta.notices`) and `Load` serves the values on show. A form no extension lays out compiles unchanged. Unknown anchors, duplicate names, anchor cycles, anchors outside `Requires()`, other zones, `fileupload` fields and clashing widget action or partial names stop the boot naming the plugin, the controller and the name.
- Plugins screen: Settings → System → Plugins opens the admin SPA route `/system/plugins` (the settings entry carries `path` instead of a controller) for administrators holding `cabana.PermissionViewPlugins` (`backend.view_plugins`, granted to no role in code; superusers always pass). GET `/plugins` lists the plugins the application was built with from the `party.Installed` metadata `summer build` bakes (name, description, version, source, module and package), or only the IDs of `party.Activated` for an application built before that metadata existed, with the framework version and the state of the plugin registry (`plugins.registry_url`, read through `kiosk.RegistryURL`). With the registry configured, cabana (never the SPA) looks up each versioned plugin's releases through `kiosk.Client` and marks an update when `kiosk.NewestCompatible` finds a release newer than the installed version by `kiosk.Newer` (a `git describe` string or a pseudo-version compares by the tag it builds on), with the `summer plugin:update ` command; GET `/plugins/marketplace` searches the registry and adds installed and compatibility markers (compatible when `summer plugin:install` can install some release with the built framework, looking up the releases of a plugin whose newest one needs a newer framework; always compatible when the built framework version is not a release) and the `summer plugin:install ` command. Registry calls have a 4 second timeout, at most four run at once, and answers are cached in process (searches 5 minutes, at most 256 distinct searches with expired and then the oldest dropped first, releases 15 minutes, failures 1 minute); a failing registry gives `status` unavailable and never a non-200 answer.
- Administrators screen: when some plugin registers admin controllers, `cabana.Activate` also compiles the admin's own screens, an internal plugin with ID `summercms.cabana`. Settings → System → Administrators (controller `cabana.AdministratorsControllerID`, permission `cabana.PermissionManageUsers`) lists backend administrators with their role and last sign-in, opens a preview of each, where record actions (the admin's own and contributed ones) are offered, and creates and edits administrators: login, email, names, a password (hashed at `admin.password.bcrypt_cost`, at least 4 characters and at most 72 bytes), the role and per-administrator permission overrides. The server enforces the privilege rules in the save transaction: only a superuser sees superusers or sends the superuser switch, an administrator can neither grant permissions or roles above their own grants nor change an administrator who holds more than they do, their own role, superuser flag, permissions and password are not changed here, and the last active superuser cannot be demoted. A password set for another administrator ends their sessions (personal API tokens stay valid, as with `admin:reset-password`). Administrators are activated, deactivated and restored by record and bulk actions and deleted softly through `deleted_at` (never hard-deleted); the list shows deleted and deactivated rows with their row states and filters deleted ones, and the preview shows a status hint. Deactivating or deleting an administrator ends their sessions and stops their personal API tokens; the last active superuser cannot be demoted, deactivated or deleted on any of these paths (a transaction-scoped advisory lock serializes the check). The permission codes `cabana.PermissionManageUsers` and `cabana.PermissionManageRoles` are registered with no role grant, so after an upgrade only superusers see the screens until an administrator grants them. An application without admin controllers still activates no admin.
-- Mail screens (Settings → Mail): when the application publishes postcard's Mailer (`postcard.EditorFrom` succeeds; `party.Activate` runs `postcard.Activate`), the internal plugin also registers the mail screens over postcard's tables, the permission codes `cabana.PermissionManageMailTemplates` (`system.manage_mail_templates`) and `cabana.PermissionManageMailLayouts` (`system.manage_mail_layouts`), both granted to no role in code, and their Settings entries in category `backend::lang.settings.category_mail`. Mail templates (controller `cabana.MailTemplatesControllerID`, model `cabana.MailTemplate`) lists the templates of this process's catalog (rows of uninstalled plugins are hidden) with code, subject, description, locale (Default for a name without a locale suffix) and layout, and edits the subject, the Markdown body and the layout (a `relation` over `cabana.MailLayout` rows: every database-only layout and the catalog's file layouts). There is no create and no delete. A save marks the row customized, stamps `base_hash` with the file's current hash and `customized_at`, and validates the result through `postcard.Editor.Validate` inside the save's transaction; a `postcard.DraftError` is a 422 on its field with `backend::lang.mail.invalid_` (`:message`, `:name`). The index rows are written by `postcard.SyncIndex` through `lagoon.OnDatabase` at activation; a failed sync is logged and retried on the first mail list request of the process. Mail layouts (`cabana.MailLayoutsControllerID`, model `cabana.MailLayout`) lists postcard's default layout first, then the file layouts and the custom (database-only, `source` NULL, shown as Custom) layouts by name; it creates custom layouts (code `^[a-z0-9-]+$`, free, create-only) and deletes them, refusing one that template rows still reference with a `cabana.ForbiddenError` whose message names the layout and the count (CLDR plural). Mail partials (`cabana.MailPartialsControllerID`, model `cabana.MailPartial`) edits the partials' HTML and text sections. Both need `cabana.PermissionManageMailLayouts`; saves are stamped and validated as templates are. On all three, the record action `reset` (danger, offered on a customized file-backed row) calls `postcard.ResetOverride` in the action's transaction; rows from files are never deleted. The list row states are `customized` (an override) and `outdated` (an override whose `base_hash` differs from the file's `file_hash`), the lists have a status filter (customized, not customized, outdated) and templates a locale filter, and the forms carry the `info` and `file_version` partials: the file, the status, the sample variables or the partial's call, the drift callout, and a 3-line-context LCS line diff of the serialized override (`postcard.FormatTemplate`, `FormatLayout`, `FormatPartial`) against the file, skipped above 2000 lines per side. The mail controllers declare `recordActions` without a preview block: the admin offers them in the update form's footer, a boot rule only these internal controllers are exempt from. Layout and partial content fields use the built-in `codeeditor` type (`language: html|css|text`, optional `mailImages`); Branding is the settings form `mail_brand` on `cabana.MailBrandSetting` (postcard's brand row, 13 `colorpicker` colours and a `mailimage` logo; the first save switches mail from `mail.brandCss` to the compiled colours). Mail images is the singleton controller `cabana.MailImagesControllerID` (`cabana.MailImageLibrary`) with a public attachMany `images` fileupload; GET/POST `/mail/images` and GET `/mail/images/{id}` return absolute public URLs (`attach.AbsolutePublicURL`) and refuse with `mail.images.no_public_url` when neither `storage.uploads.public_url` nor `app.url` is set. Listing answers either mail permission; upload and the singleton form need `system.manage_mail_layouts`. POST `/mail/preview` renders an unsaved draft (`cabana.AdminMailPreviewRequest`: `mode`, `id`, `values`) through `postcard.Editor.Preview` and answers `cabana.AdminMailPreviewResult` (subject, html, text); mode `template` needs `system.manage_mail_templates`, modes `layout`, `partial` and `branding` need `system.manage_mail_layouts`. POST `/mail/test-send` (interactive sessions only) sends a template, layout or partial draft to the signed-in administrator's own email (`cabana.AdminMailTestSendResult`), refuses recipient keys in the body, and is limited to five sends per administrator per ten minutes through a published `cooler.Attempter` when `serve` has one, otherwise an in-process fixed window (429 with `Retry-After`). Forms carry `mailpreview` fields (`mode` matching the screen).
+- Mail screens (Settings → Mail): when the application publishes postcard's Mailer (`postcard.EditorFrom` succeeds; `party.Activate` runs `postcard.Activate`), the internal plugin also registers the mail screens over postcard's tables, the permission codes `cabana.PermissionManageMailTemplates` (`system.manage_mail_templates`) and `cabana.PermissionManageMailLayouts` (`system.manage_mail_layouts`), both granted to no role in code, and their Settings entries in category `backend::lang.settings.category_mail`. Mail templates (controller `cabana.MailTemplatesControllerID`, model `cabana.MailTemplate`) lists the templates of this process's catalog (rows of uninstalled plugins are hidden) with code, subject, description, locale (Default for a name without a locale suffix) and layout, and edits the subject, the Markdown body and the layout (a `relation` over `cabana.MailLayout` rows: every database-only layout and the catalog's file layouts). There is no create and no delete. A save marks the row customized, stamps `base_hash` with the file's current hash and `customized_at`, and validates the result through `postcard.Editor.Validate` inside the save's transaction; a `postcard.DraftError` is a 422 on its field with `backend::lang.mail.invalid_` (`:message`, `:name`). The index rows are written by `postcard.SyncIndex` and `postcard.EnsureLocaleRows` through `lagoon.OnDatabase` at activation; a failed sync is logged and retried on the first mail list request of the process, and a list request syncs again when the mail locales changed. The mail locales are the locales the translator's catalog holds plus, when a `cabana.TranslationWriter` is published, its enabled locales; the default locale is the writer's default locale, else the translator's. A template is one record per locale version: its own row (Default), a row per locale variant file (`welcome-en`) and a row per other mail locale that ships no file (`welcome-de`, created by `postcard.EnsureLocaleRows`, showing and sending the default version until it is customized). The update form's locale switcher lists them (`meta.localeVariants`); the record title is the template's base code, and the show response first ensures the template's missing locale rows, so a newly enabled locale can be opened without a restart. A save of a locale without a file stamps `base_hash` with the base file's hash. Mail layouts (`cabana.MailLayoutsControllerID`, model `cabana.MailLayout`) lists postcard's default layout first, then the file layouts and the custom (database-only, `source` NULL, shown as Custom) layouts by name; it creates custom layouts (code `^[a-z0-9-]+$`, free, create-only) and deletes them, refusing one that template rows still reference with a `cabana.ForbiddenError` whose message names the layout and the count (CLDR plural). Mail partials (`cabana.MailPartialsControllerID`, model `cabana.MailPartial`) edits the partials' HTML and text sections. Both need `cabana.PermissionManageMailLayouts`; saves are stamped and validated as templates are. On all three, the record action `reset` (danger, offered on a customized file-backed row) calls `postcard.ResetOverride` in the action's transaction; rows from files are never deleted. The list row states are `customized` (an override) and `outdated` (an override whose `base_hash` differs from the file's `file_hash`), the lists have a status filter (customized, not customized, outdated) and templates a locale filter, and the forms carry the `info` and `file_version` partials: the file, the status, the sample variables or the partial's call, the drift callout, and a 3-line-context LCS line diff of the serialized override (`postcard.FormatTemplate`, `FormatLayout`, `FormatPartial`) against the file, skipped above 2000 lines per side. The mail controllers declare `recordActions` without a preview block: the admin offers them in the update form's footer, a boot rule only these internal controllers are exempt from. Layout and partial content fields use the built-in `codeeditor` type (`language: html|css|text`, optional `mailImages`); Branding is the settings form `mail_brand` on `cabana.MailBrandSetting` (postcard's brand row, 13 `colorpicker` colours and a `mailimage` logo; the first save switches mail from `mail.brandCss` to the compiled colours). Mail images is the singleton controller `cabana.MailImagesControllerID` (`cabana.MailImageLibrary`) with a public attachMany `images` fileupload; GET/POST `/mail/images` and GET `/mail/images/{id}` return absolute public URLs (`attach.AbsolutePublicURL`) and refuse with `mail.images.no_public_url` when neither `storage.uploads.public_url` nor `app.url` is set. Listing answers either mail permission; upload and the singleton form need `system.manage_mail_layouts`. POST `/mail/preview` renders an unsaved draft (`cabana.AdminMailPreviewRequest`: `mode`, `id`, `values`) through `postcard.Editor.Preview` and answers `cabana.AdminMailPreviewResult` (subject, html, text); mode `template` needs `system.manage_mail_templates`, modes `layout`, `partial` and `branding` need `system.manage_mail_layouts`. POST `/mail/test-send` (interactive sessions only) sends a template, layout or partial draft to the signed-in administrator's own email (`cabana.AdminMailTestSendResult`), refuses recipient keys in the body, and is limited to five sends per administrator per ten minutes through a published `cooler.Attempter` when `serve` has one, otherwise an in-process fixed window (429 with `Retry-After`). Forms carry `mailpreview` fields (`mode` matching the screen).
- Danger record actions: `pact.AdminRecordAction.Danger` is served as `danger` on the record response's `cabana.RecordAction` (absent when false, so existing payloads are unchanged); the admin's confirm dialog then uses its danger variant.
- Prompted record actions: a `pact.AdminRecordAction` with a `Prompt` (`pact.AdminActionPrompt`) asks the administrator for one text value in its confirm dialog. The record response serves it as `prompt` on the action's `cabana.RecordAction` (absent for every other action, so existing payloads are unchanged), and the action route accepts the body key `payload`, a JSON string, only for such an action: trimmed, not empty and at most `max_length` runes (422 on `payload` with `backend::lang.form.action_prompt_required` or `action_prompt_too_long`, `backend::lang.form.action_prompt_invalid` for another JSON type), then handed to `Run` as `pact.AdminRecordActionInput.Value`. Every other record action keeps refusing `record_id`, `values` and `payload`. A prompt without a label fails boot, owned or contributed.
- My account contributions: a plugin implementing `pact.HasAccountContributions` adds sections (`pact.AccountContribution`) to the administrator's own account page, each with a status line and buttons (`pact.AccountAction`). GET `/account/contributions` lists them for the signed-in administrator and POST `/account/contributions/{name}/actions/{action}` runs one for that administrator only, behind the interactive-only guard, the action's permissions and its `Applies` rule, inside a transaction; the answer may carry a URL the admin opens in a new tab. That URL is kept only when it is an absolute `http`/`https` URL with a host or a same-origin path (one leading `/`); anything else, `javascript:` and `data:` included, is dropped and logged without the URL. A section whose `Status` fails is listed with an empty status and `error: true`, and an action whose `Applies` fails is left out and marks its section `error: true` as well; both are logged and the other sections are answered as usual. A status is translated only when it is a phrase key. Names are generic: cabana never names the contributing plugin. The existing `/account*` and `/auth/me` payloads are unchanged. A non-identifier or duplicate section name, an empty label, a duplicate or non-identifier action name, a nil `Run` or an empty action label stops the boot.
@@ -308,6 +308,8 @@ func (p *Plugin) AdminFS() fs.FS { return adminFS }
| `cabana.PermissionManageMailTemplates` / `cabana.PermissionManageMailLayouts` | The permission codes of the mail screens (`system.manage_mail_templates`: Mail templates, template preview and test send; `system.manage_mail_layouts`: layouts, partials, branding and the image library), granted to no role in code and registered only with the mail screens. |
| `cabana.MailTemplatesControllerID` / `cabana.MailLayoutsControllerID` / `cabana.MailPartialsControllerID` / `cabana.MailImagesControllerID` | The admin controller IDs of the mail screens (`summercms.cabana.mailtemplates`, `summercms.cabana.maillayouts`, `summercms.cabana.mailpartials`, `summercms.cabana.mailimages`). |
| `cabana.MailTemplate` / `cabana.MailLayout` / `cabana.MailPartial` | GORM models of postcard's `system_mail_templates`, `system_mail_layouts` and `system_mail_partials` rows, as the mail screens read and write them, with their filter scopes. |
+| `cabana.RecordMeta.LocaleVariants` | The locale versions of the record for the update form's locale switcher (`meta.localeVariants`), as `cabana.RecordLocaleVariant` values in display order: sent in the show and update responses of the mail templates screen only (Default, then by locale code), omitted for every other controller. |
+| `cabana.RecordLocaleVariant` | One locale version: the row `ID` to open, its `Locale` (empty for Default), the translated `Label` and `States` (customized, file changed) and `Current` for the record being shown. |
| `cabana.RecordMeta.Deletable` | Whether the record's form offers Delete (`meta.deletable`): sent only by controllers that decide it per record, the mail screens (false for templates, partials and file layouts, true for custom layouts), and omitted for every other controller. |
| `cabana.AdministratorsControllerID` / `cabana.RolesControllerID` | The admin controller IDs of the Administrators (`summercms.cabana.users`) and Roles (`summercms.cabana.roles`) screens; a plugin names the first in `pact.AdminActionExtension.Controller` to add record actions to it. |
| `cabana.BackendUser.Fillable` / `cabana.BackendUser.Rules` | The columns the Administrators screen fills from a form (login, email, first and last name) and their base rules. |
@@ -438,4 +440,4 @@ The Roles form's holders list is covered by the Docker-free TestRolesHoldersPart
The Plugins screen is covered by the Docker-free TestPluginsScreenSmoke in `plugins_smoke_test.go`: the installed list from `party.Installed` and the `party.Activated` fallback, 401 and 403 without `cabana.PermissionViewPlugins`, the settings entry with its `path` only for allowed administrators, and against a fake registry the update rule (a git describe version compares by its base tag), unlisted and local plugins, a failing or slow registry, a disabled one (no request), the marketplace search with its validation and the cache windows.
-The mail screens are covered by the Postgres test TestMailScreensSmoke in `mail_screens_smoke_test.go`, on a fixture plugin with two templates, a layout and a partial: the templates list and form, an override that the next send uses, a refused unsafe body that leaves the row unchanged, the permission split and the Settings → Mail tiles per permission; layouts (order, custom layout create, code format and uniqueness, the `{{ .Content }}` check, a customized layout in the next send), partials (parse error, usage line), reset, the in-use delete refusal, `meta.deletable`, drift (a second process booted over a changed file: row states, the status and locale filters, the info and file version partials, a save that clears the drift) and the line diff.
+The mail screens are covered by the Postgres test TestMailScreensSmoke in `mail_screens_smoke_test.go`, on a fixture plugin with two templates, a layout and a partial: the templates list and form, an override that the next send uses, a refused unsafe body that leaves the row unchanged, the permission split and the Settings → Mail tiles per permission; layouts (order, custom layout create, code format and uniqueness, the `{{ .Content }}` check, a customized layout in the next send), partials (parse error, usage line), reset, the in-use delete refusal, `meta.deletable`, drift (a second process booted over a changed file: row states, the status and locale filters, the info and file version partials, a save that clears the drift), the line diff, and locales (with a published `cabana.TranslationWriter` enabling pl, en and de: the template's `meta.localeVariants`, the base-code title, a save of the de version that the next send of `-de` uses, its preview, and a 404 for a row outside the catalog).
diff --git a/modules/cabana/crud.go b/modules/cabana/crud.go
index a40a11fa..57da4980 100644
--- a/modules/cabana/crud.go
+++ b/modules/cabana/crud.go
@@ -554,6 +554,12 @@ func (s CRUDService) ShowRecord(ctx context.Context, cc *CompiledController, id
deletable := decider.recordDeletable(target)
result.Meta.Deletable = &deletable
}
+ if lister, ok := cc.Controller.(recordLocaleVariants); ok && lister != nil {
+ result.Meta.LocaleVariants, err = lister.recordLocaleVariants(withTx(ctx, tx), tx, target)
+ if err != nil {
+ return err
+ }
+ }
result.Meta.Actions, err = s.offeredRecordActions(withTx(ctx, tx), cc, target)
return err
})
@@ -983,7 +989,14 @@ func (s CRUDService) save(ctx context.Context, cc *CompiledController, id any, i
if err := hydratePluginFields(ctx, tx, cc, s.writer, target, result.Data, op); err != nil {
return err
}
- return hydrateFormExtensions(ctx, extensionHydrate{Tx: tx, Tr: s.tr, Writer: s.writer, CC: cc, Target: target, Op: op, Visible: visible}, result.Data)
+ if err := hydrateFormExtensions(ctx, extensionHydrate{Tx: tx, Tr: s.tr, Writer: s.writer, CC: cc, Target: target, Op: op, Visible: visible}, result.Data); err != nil {
+ return err
+ }
+ // The saved version's states changed: the switcher shows them.
+ if lister, ok := cc.Controller.(recordLocaleVariants); ok && lister != nil && update {
+ result.Meta.LocaleVariants, err = lister.recordLocaleVariants(withTx(ctx, tx), tx, target)
+ }
+ return err
})
if err != nil {
return RecordResult{}, err
diff --git a/modules/cabana/mail_admin.go b/modules/cabana/mail_admin.go
index 02a980d8..0a49dd11 100644
--- a/modules/cabana/mail_admin.go
+++ b/modules/cabana/mail_admin.go
@@ -35,6 +35,9 @@ type mailScreens struct {
syncMu sync.Mutex
synced atomic.Bool
+ // syncedLocales is the mail locale set of the last successful sync
+ // (mailLocaleKey); a different set syncs again. Guarded by syncMu.
+ syncedLocales string
}
// mailPermissions are the two mail codes, with no role grants (D-03).
@@ -161,20 +164,63 @@ func (m *mailScreens) translator() *phrasebook.Translator {
return tr
}
-// locales are the application's locales, for postcard.TemplateLocale: the
-// locales the translator's catalog holds, none without a translator.
-func (m *mailScreens) locales() []string {
- return m.translator().Locales("")
+// mailLocales are the application's mail locales and its default locale:
+// the locales the translator's catalog holds plus, when a TranslationWriter
+// is published and answers, its enabled locales. The default is the
+// writer's default locale, else the translator's locale. locales is sorted
+// and includes the default. db is the handle the writer reads with; nil
+// leaves the writer out.
+func (m *mailScreens) mailLocales(ctx context.Context, db *gorm.DB) (def string, locales []string) {
+ tr := m.translator()
+ def = tr.Locale()
+ seen := map[string]bool{}
+ add := func(codes ...string) {
+ for _, code := range codes {
+ if code = strings.TrimSpace(code); code != "" && !seen[code] {
+ seen[code] = true
+ locales = append(locales, code)
+ }
+ }
+ }
+ add(tr.Locales("")...)
+ if app := m.application(); app != nil && db != nil {
+ if w, ok := app.Lookup[TranslationWriter](); ok && w != nil {
+ if codes, err := w.EnabledLocales(ctx, db); err == nil {
+ add(codes...)
+ } else {
+ moduleLog.WarnContext(ctx, "cabana: mail locales: enabled locales", "error", err)
+ }
+ if code, err := w.DefaultLocale(ctx, db); err == nil && strings.TrimSpace(code) != "" {
+ def = strings.TrimSpace(code)
+ }
+ }
+ }
+ add(def)
+ sort.Strings(locales)
+ return def, locales
+}
+
+// mailLocaleKey identifies a mail locale set, to tell whether the index was
+// synced with the current one.
+func mailLocaleKey(def string, locales []string) string {
+ return def + "|" + strings.Join(locales, ",")
}
// sync writes the index rows of every file template, layout and partial
-// (postcard.SyncIndex) and remembers that it succeeded.
+// (postcard.SyncIndex), then the rows of the locales a template ships no
+// file for (postcard.EnsureLocaleRows), and remembers the locale set it
+// succeeded with.
func (m *mailScreens) sync(ctx context.Context, gdb *gorm.DB) error {
m.syncMu.Lock()
defer m.syncMu.Unlock()
- if err := postcard.SyncIndex(ctx, gdb, m.catalog(), m.locales()); err != nil {
+ def, locales := m.mailLocales(ctx, gdb)
+ if err := postcard.SyncIndex(ctx, gdb, m.catalog(), locales); err != nil {
return err
}
+ if err := postcard.EnsureLocaleRows(ctx, gdb, m.catalog(), def, locales); err != nil {
+ return err
+ }
+ m.syncedLocales = mailLocaleKey(def, locales)
m.synced.Store(true)
return nil
}
@@ -190,16 +236,25 @@ func (m *mailScreens) syncOnDatabase(gdb *gorm.DB) {
}
// ensureSynced retries the index sync until it has succeeded once in this
-// process. It is called before a mail list is read.
+// process, and syncs again when the mail locales changed since (a locale
+// enabled through a translate plugin, for example). It is called before a
+// mail list is read.
func (m *mailScreens) ensureSynced(ctx context.Context) {
- if m.synced.Load() {
- return
- }
gdb := m.db()
if gdb == nil {
return
}
- if err := m.sync(ctx, gdb.Session(&gorm.Session{NewDB: true}).WithContext(ctx)); err != nil {
+ db := gdb.Session(&gorm.Session{NewDB: true}).WithContext(ctx)
+ if m.synced.Load() {
+ def, locales := m.mailLocales(ctx, db)
+ m.syncMu.Lock()
+ current := m.syncedLocales == mailLocaleKey(def, locales)
+ m.syncMu.Unlock()
+ if current {
+ return
+ }
+ }
+ if err := m.sync(ctx, db); err != nil {
moduleLog.WarnContext(ctx, "cabana: mail index sync failed", "error", err)
}
}
@@ -279,10 +334,13 @@ func nonEmpty(codes []string) []string {
}
// MailTemplate is a row of postcard's templates table: one per file
-// template, its override columns set while the template is customized.
+// template and one per locale a template ships no file for (a fallback-locale
+// row), its override columns set while that version is customized. BaseCode
+// groups the locale versions of one template.
type MailTemplate struct {
ID uint `gorm:"column:id;primaryKey"`
Code string `gorm:"column:code"`
+ BaseCode *string `gorm:"column:base_code"`
Source string `gorm:"column:source"`
Locale *string `gorm:"column:locale"`
Description string `gorm:"column:description"`
@@ -376,6 +434,7 @@ var (
_ pact.HasAdminRecordActions = mailTemplatesAdmin{}
_ pact.AdminPartialData = mailTemplatesAdmin{}
_ recordDeletable = mailTemplatesAdmin{}
+ _ recordLocaleVariants = mailTemplatesAdmin{}
_ formFooterActions = mailTemplatesAdmin{}
)
@@ -400,12 +459,16 @@ func asMailTemplate(model any) (*MailTemplate, error) {
return t, nil
}
-// FormRecordTitle names a template by its code.
+// FormRecordTitle names a template by its base code: every locale version
+// of a template carries the same title, the switcher tells them apart.
func (mailTemplatesAdmin) FormRecordTitle(_ context.Context, _ *gorm.DB, record any) (string, error) {
t, err := asMailTemplate(record)
if err != nil {
return "", err
}
+ if t.BaseCode != nil && *t.BaseCode != "" {
+ return *t.BaseCode, nil
+ }
return t.Code, nil
}
@@ -449,9 +512,21 @@ func (c mailTemplatesAdmin) ListExtendQuery(ctx context.Context, db *gorm.DB) *g
return c.scopeTemplates(db)
}
-// FormExtendQuery applies the catalog scope to every record lookup.
+// FormExtendQuery scopes every record lookup to the catalog's templates and
+// their fallback-locale rows (base_code a catalog template).
func (c mailTemplatesAdmin) FormExtendQuery(_ context.Context, db *gorm.DB) *gorm.DB {
- return c.scopeTemplates(db)
+ return c.mail.scopeTemplateVersions(db)
+}
+
+// scopeTemplateVersions limits a templates query to the rows a record lookup
+// may open: a catalog template's own row, or a row whose base_code is a
+// catalog template (a locale that ships no file).
+func (m *mailScreens) scopeTemplateVersions(db *gorm.DB) *gorm.DB {
+ if db == nil {
+ return db
+ }
+ codes := nonEmpty(m.templateCodes())
+ return db.Where("("+postcard.TemplatesTable+".code IN ? OR "+postcard.TemplatesTable+".base_code IN ?)", codes, codes)
}
// ListExtendRecords shows a template without a locale suffix as Default in
@@ -509,7 +584,7 @@ func (c mailTemplatesAdmin) FilterOptions(scope string) []pact.Option {
case mailFilterLocale:
out := []pact.Option{{Value: mailLocaleDefault, Label: mailLang + "template.locale_default"}}
seen := map[string]bool{}
- locales := c.mail.locales()
+ _, locales := c.mail.mailLocales(context.Background(), c.mail.db())
for _, f := range c.mail.catalog().Templates() {
if locale := postcard.TemplateLocale(f.Name, locales); locale != "" && !seen[locale] {
seen[locale] = true
@@ -575,7 +650,8 @@ func (c mailTemplatesAdmin) FormBeforeUpdate(_ context.Context, model any) error
if err != nil {
return err
}
- file, ok := c.mail.catalog().Template(t.Code)
+ // A fallback-locale row is based on the base template's file.
+ file, ok := c.mail.catalog().TemplateFor(t.Code)
if !ok {
return &ForbiddenError{Message: mailLang + "file_missing"}
}
@@ -644,6 +720,15 @@ type recordDeletable interface {
recordDeletable(record any) bool
}
+// recordLocaleVariants is implemented by the mail templates controller,
+// whose records are the locale versions of a template: the show response
+// then carries meta.localeVariants, the versions of the record's template
+// for the form's locale switcher. Unexported: no other controller's payload
+// changes.
+type recordLocaleVariants interface {
+ recordLocaleVariants(ctx context.Context, tx *gorm.DB, record any) ([]RecordLocaleVariant, error)
+}
+
// formFooterActions marks a controller whose config_form.yaml declares
// recordActions without a preview block: the admin offers them in the
// update form's footer instead. Only the mail controllers implement it.
@@ -1665,3 +1750,87 @@ func injectLayoutCreateDefaults(reg *Registry, editor *postcard.Editor) {
}
}
}
+
+// templateVersion is one row of a template's locale group.
+type templateVersion struct {
+ ID uint
+ Code string
+ Locale *string
+ IsCustom bool
+ BaseHash *string
+ FileHash *string
+}
+
+// recordLocaleVariants lists the locale versions of the record's template
+// for the switcher. It first gives the template's missing locales their rows
+// (postcard.EnsureLocaleRows, idempotent), so a locale enabled since the last
+// sync can be opened without a restart. The order is Default (the base
+// file), then by locale code every locale with its own file, every other
+// mail locale except the default, and any customized version of a locale
+// that is no longer enabled.
+func (c mailTemplatesAdmin) recordLocaleVariants(ctx context.Context, tx *gorm.DB, record any) ([]RecordLocaleVariant, error) {
+ t, err := asMailTemplate(record)
+ if err != nil {
+ return nil, err
+ }
+ def, locales := c.mail.mailLocales(ctx, tx)
+ base := postcard.TemplateBase(t.Code, locales)
+ if t.BaseCode != nil && *t.BaseCode != "" {
+ base = *t.BaseCode
+ }
+ cat := c.mail.catalog()
+ if _, ok := cat.Template(base); ok {
+ // Under a savepoint: a failure leaves the show working.
+ if err := tx.Transaction(func(sp *gorm.DB) error {
+ return postcard.EnsureLocaleRows(ctx, sp, cat, def, locales, base)
+ }); err != nil {
+ moduleLog.WarnContext(ctx, "cabana: mail locale rows", "template", base, "error", err)
+ }
+ }
+ var rows []templateVersion
+ q := tx.Session(&gorm.Session{NewDB: true}).Table(postcard.TemplatesTable).
+ Select("id, code, locale, is_custom, base_hash, file_hash").
+ Where(postcard.TemplatesTable+".base_code = ? OR "+postcard.TemplatesTable+".code = ?", base, base)
+ if err := c.mail.scopeTemplateVersions(q).Order("code").Scan(&rows).Error; err != nil {
+ return nil, err
+ }
+ enabled := map[string]bool{}
+ for _, l := range locales {
+ enabled[strings.ToLower(l)] = true
+ }
+ var head *RecordLocaleVariant
+ var rest []RecordLocaleVariant
+ for _, r := range rows {
+ _, fileBacked := cat.Template(r.Code)
+ v := RecordLocaleVariant{ID: r.ID, States: []string{}, Current: r.ID == t.ID}
+ if r.IsCustom {
+ v.States = append(v.States, c.mail.message(ctx, mailLang+"state_customized", nil))
+ if mailOutdated(true, r.BaseHash, r.FileHash) {
+ v.States = append(v.States, c.mail.message(ctx, mailLang+"state_outdated", nil))
+ }
+ }
+ if r.Code == base {
+ v.Label = c.mail.message(ctx, mailLang+"template.locale_default", nil)
+ head = &v
+ continue
+ }
+ if r.Locale != nil {
+ v.Locale = *r.Locale
+ }
+ v.Label = v.Locale
+ if v.Label == "" {
+ v.Label = r.Code
+ }
+ if !fileBacked && !r.IsCustom && (!enabled[strings.ToLower(v.Locale)] || strings.EqualFold(v.Locale, def)) {
+ // A fallback row of a locale no longer enabled, not customized.
+ continue
+ }
+ rest = append(rest, v)
+ }
+ sort.SliceStable(rest, func(i, j int) bool { return rest[i].Locale < rest[j].Locale })
+ out := make([]RecordLocaleVariant, 0, len(rest)+1)
+ if head != nil {
+ out = append(out, *head)
+ }
+ return append(out, rest...), nil
+}
diff --git a/modules/cabana/mail_routes.go b/modules/cabana/mail_routes.go
index d1af4455..481d4913 100644
--- a/modules/cabana/mail_routes.go
+++ b/modules/cabana/mail_routes.go
@@ -510,7 +510,8 @@ func (s *service) mailTemplateDraft(ctx context.Context, id uint64, values map[s
return postcard.Draft{}, err
}
if editor, ok := postcard.EditorFrom(s.app); ok && editor != nil {
- if _, ok := editor.Catalog().Template(name); !ok {
+ // A fallback-locale row previews and sends with its base file.
+ if _, ok := editor.Catalog().TemplateFor(name); !ok {
return postcard.Draft{}, recordNotFound{}
}
}
diff --git a/modules/cabana/mail_screens_smoke_test.go b/modules/cabana/mail_screens_smoke_test.go
index 66a5c6af..91c7a81b 100644
--- a/modules/cabana/mail_screens_smoke_test.go
+++ b/modules/cabana/mail_screens_smoke_test.go
@@ -30,6 +30,7 @@ import (
"git.golem15.com/golem15/summercms/modules/postcard"
"git.golem15.com/golem15/summercms/modules/surf"
"gocloud.dev/blob/memblob"
+ "gorm.io/gorm"
)
// The mail screens' paths under the admin API.
@@ -147,6 +148,31 @@ type mailEnvOptions struct {
files fstest.MapFS
keep bool
mutate func(*compass.Config)
+ // writer, when set, is published as the cabana.TranslationWriter: the
+ // application's content locales, which the mail locales include.
+ writer cabana.TranslationWriter
+}
+
+// mailLocaleWriter is a TranslationWriter that only answers the locales.
+type mailLocaleWriter struct {
+ def string
+ enabled []string
+}
+
+func (w mailLocaleWriter) DefaultLocale(context.Context, *gorm.DB) (string, error) {
+ return w.def, nil
+}
+
+func (w mailLocaleWriter) EnabledLocales(context.Context, *gorm.DB) ([]string, error) {
+ return w.enabled, nil
+}
+
+func (mailLocaleWriter) WriteTranslated(context.Context, *gorm.DB, any, string, string, string) error {
+ return nil
+}
+
+func (mailLocaleWriter) TranslatedExact(context.Context, *gorm.DB, any, string, string) (string, bool, error) {
+ return "", false, nil
}
func newMailScreensEnvWith(t *testing.T, opts mailEnvOptions) *mailEnv {
@@ -202,6 +228,11 @@ func newMailScreensEnvWith(t *testing.T, opts mailEnvOptions) *mailEnv {
if err := postcard.BootPlugin(app, blog); err != nil {
t.Fatal(err)
}
+ if opts.writer != nil {
+ if err := app.Publish[cabana.TranslationWriter](opts.writer); err != nil {
+ t.Fatal(err)
+ }
+ }
spy := &pingSpy{}
plugins := []party.Plugin{demoPlugin{fsys: demoFS()}, pingPlugin{spy: spy}, blog}
if err := phrasebook.Activate(app, plugins); err != nil {
@@ -346,6 +377,115 @@ func TestMailScreensSmoke(t *testing.T) {
})
mailLayoutsAndPartials(t, env, rootToken)
+
+ // Runs last: its env empties the mail tables.
+ t.Run("locales", func(t *testing.T) {
+ mailLocalesSmoke(t, rootToken)
+ })
+}
+
+// localeVariants returns a show response's meta.localeVariants.
+func localeVariants(t *testing.T, show map[string]any) []map[string]any {
+ t.Helper()
+ meta, _ := show["meta"].(map[string]any)
+ items, _ := meta["localeVariants"].([]any)
+ out := make([]map[string]any, 0, len(items))
+ for _, item := range items {
+ v, _ := item.(map[string]any)
+ out = append(out, v)
+ }
+ return out
+}
+
+// variantSummary is "label[states]*" per variant, * marking the current one.
+func variantSummary(variants []map[string]any) string {
+ parts := make([]string, 0, len(variants))
+ for _, v := range variants {
+ part := fmt.Sprintf("%v%v", v["label"], v["states"])
+ if v["current"] == true {
+ part += "*"
+ }
+ parts = append(parts, part)
+ }
+ return strings.Join(parts, " ")
+}
+
+// mailLocalesSmoke is G-35-1 end to end: on an application whose content
+// locales are pl (default), en and de, the welcome template's form lists
+// Default, de (no file) and en (its own file); the de version is opened,
+// saved and sent for acme.blog::mail.welcome-de.
+func mailLocalesSmoke(t *testing.T, rootToken string) {
+ env := newMailScreensEnvWith(t, mailEnvOptions{writer: mailLocaleWriter{def: "pl", enabled: []string{"pl", "en", "de"}}})
+ ctx := context.Background()
+
+ baseID := env.mailRowID(t, postcard.TemplatesTable, blogWelcome)
+ show := env.expect(t, http.StatusOK, http.MethodGet, fmt.Sprintf("%s/%d", mailTemplatesPath, baseID), rootToken, nil)
+ variants := localeVariants(t, show)
+ if got := variantSummary(variants); got != "Default[]* de[] en[]" {
+ t.Fatalf("welcome variants = %s", got)
+ }
+ deID := uint(variants[1]["id"].(float64))
+ if deID != env.mailRowID(t, postcard.TemplatesTable, blogWelcome+"-de") || variants[1]["locale"] != "de" || variants[0]["locale"] != "" {
+ t.Fatalf("de variant = %v", variants[1])
+ }
+
+ dePath := fmt.Sprintf("%s/%d", mailTemplatesPath, deID)
+ deShow := env.expect(t, http.StatusOK, http.MethodGet, dePath, rootToken, nil)
+ if meta, _ := deShow["meta"].(map[string]any); meta["title"] != blogWelcome {
+ t.Fatalf("de title = %v, want the base code", meta["title"])
+ }
+ if got := variantSummary(localeVariants(t, deShow)); got != "Default[] de[]* en[]" {
+ t.Fatalf("de variants = %s", got)
+ }
+
+ layoutID := env.mailRowID(t, postcard.LayoutsTable, blogLayout)
+ env.expect(t, http.StatusOK, http.MethodPut, dePath, rootToken, templateBody("Willkommen, {{ .name }}", "Hallo **{{ .name }}**.", layoutID))
+ var stored cabana.MailTemplate
+ if err := env.gdb.First(&stored, deID).Error; err != nil {
+ t.Fatal(err)
+ }
+ baseHash, _ := mailFileHash(t, env, blogWelcome)
+ if !stored.IsCustom || stored.BaseHash == nil || *stored.BaseHash != baseHash {
+ t.Fatalf("stored de row = %+v, want customized against the base file", stored)
+ }
+ after := localeVariants(t, env.expect(t, http.StatusOK, http.MethodGet, dePath, rootToken, nil))
+ if got := variantSummary(after); got != "Default[] de[Customized]* en[]" {
+ t.Fatalf("variants after the de save = %s", got)
+ }
+
+ send := func(name string) postcard.RenderedMessage {
+ t.Helper()
+ if err := env.mailer.Send(ctx, postcard.Message{Template: name, To: []string{"reader@example.test"}, Vars: map[string]any{"name": "Grace"}}); err != nil {
+ t.Fatalf("Send %s: %v", name, err)
+ }
+ msgs := env.driver.messages()
+ return msgs[len(msgs)-1]
+ }
+ if got := send(blogWelcome + "-de"); got.Subject != "Willkommen, Grace" || !strings.Contains(got.HTML, "blog-mail") {
+ t.Fatalf("welcome-de sent %q / %q", got.Subject, got.HTML)
+ }
+ if got := send(blogWelcome); got.Subject != "Witaj, Grace" {
+ t.Fatalf("welcome sent %q, want the base file", got.Subject)
+ }
+
+ env.expect(t, http.StatusOK, http.MethodPost, "/mail/preview", rootToken, map[string]any{
+ "mode": "template",
+ "id": deID,
+ "values": map[string]any{
+ "subject": "Vorschau",
+ "body": "Hallo **{{ .name }}**",
+ "layout": layoutID,
+ },
+ })
+
+ // An id outside the catalog's templates and their locale rows is a 404.
+ var orphan uint
+ if err := env.gdb.Raw(`INSERT INTO ` + postcard.TemplatesTable + ` (code, source, base_code) VALUES ('acme.gone::mail.x-de', 'acme.gone', 'acme.gone::mail.x') RETURNING id`).Scan(&orphan).Error; err != nil {
+ t.Fatal(err)
+ }
+ if rec := env.call(t, http.MethodGet, fmt.Sprintf("%s/%d", mailTemplatesPath, orphan), rootToken, nil); rec.Code != http.StatusNotFound {
+ t.Fatalf("orphan row status = %d", rec.Code)
+ }
}
// mailEditor is the env's postcard editor.
diff --git a/modules/cabana/relation_field.go b/modules/cabana/relation_field.go
index c0142a90..47a667d0 100644
--- a/modules/cabana/relation_field.go
+++ b/modules/cabana/relation_field.go
@@ -119,6 +119,23 @@ type RecordMeta struct {
// screens: a custom layout can be deleted, a file-backed row cannot)
// carries it; it is omitted otherwise, and Delete then shows as before.
Deletable *bool `json:"deletable,omitempty"`
+ // LocaleVariants are the locale versions of the record for the update
+ // form's locale switcher, in display order. Only the show and update
+ // responses of a controller whose records have locale versions (the mail
+ // templates screen) carry it; it is omitted otherwise.
+ LocaleVariants []RecordLocaleVariant `json:"localeVariants,omitempty"`
+}
+
+// RecordLocaleVariant is one locale version of a record: the row id to open,
+// its locale code (empty for the default version), the label to show and the
+// state words (customized, file changed), both translated in the request
+// locale, and whether it is the record being shown.
+type RecordLocaleVariant struct {
+ ID uint `json:"id"`
+ Locale string `json:"locale"`
+ Label string `json:"label"`
+ States []string `json:"states"`
+ Current bool `json:"current"`
}
// FieldNotice is one save notice: the field it is about, the content locale
diff --git a/modules/phrasebook/backend/lang/en/lang.yaml b/modules/phrasebook/backend/lang/en/lang.yaml
index 9c259cde..9d53794b 100644
--- a/modules/phrasebook/backend/lang/en/lang.yaml
+++ b/modules/phrasebook/backend/lang/en/lang.yaml
@@ -66,6 +66,7 @@ list:
bulk_stale: Some of the selected records are no longer available. The list has been refreshed; select the records again.
action_forbidden: You do not have permission to run this action.
form:
+ locale_variant: Language
save: Save
save_and_close: Save and close
create_and_new: Create and new
diff --git a/modules/phrasebook/backend/lang/pl/lang.yaml b/modules/phrasebook/backend/lang/pl/lang.yaml
index 93f86795..cf7628ee 100644
--- a/modules/phrasebook/backend/lang/pl/lang.yaml
+++ b/modules/phrasebook/backend/lang/pl/lang.yaml
@@ -72,6 +72,7 @@ list:
bulk_stale: Część zaznaczonych rekordów nie jest już dostępna. Lista została odświeżona; zaznacz rekordy ponownie.
action_forbidden: Nie masz uprawnień do wykonania tej akcji.
form:
+ locale_variant: Język
save: Zapisz
save_and_close: Zapisz i zamknij
create_and_new: Utwórz i nowy
diff --git a/modules/postcard/README.md b/modules/postcard/README.md
index a81e25a4..d7b59e3f 100644
--- a/modules/postcard/README.md
+++ b/modules/postcard/README.md
@@ -33,7 +33,7 @@ Use cases:
- Branding: once the branding settings have been saved, the brand CSS is compiled from their colours (`postcard.CompileBrandCSS`) and replaces `mail.brandCss`, and layouts get the logo's absolute URL as `{{ .logoUrl }}`.
- Sample values: a template's header may give its variables sample values with `sample.` keys. Previews and save checks use them, and show every other variable as a visible `[path]` placeholder.
- An editor API for admin code (`postcard.Editor`): validate, preview and test-send an unsaved draft of a template, layout or partial through the same render path as a real send; one index row per file (`postcard.SyncIndex`) with a hash of the file for detecting that it changed under an override, and reset to the file version (`postcard.ResetOverride`).
-- No locale selection: callers pass the full template name, including any locale suffix.
+- No locale selection: callers pass the full template name, including any locale suffix. A `-` name whose locale ships no file sends the default-locale version (see "Locale variants").
## Usage
@@ -103,6 +103,14 @@ func TestWelcomeMail(t *testing.T) {
}
```
+### Locale variants
+
+postcard picks no locale: the caller passes the full name, such as `acme.blog::mail.welcome-en` for English. A locale variant is a file whose name is the template's name, a dash and the locale (`welcome-en.htm`). A name with its own file always renders that file, as it always did.
+
+A name the catalog does not hold, of the form `-` where `` is a registered template and `` is a locale tag (two letters, optionally followed by `-` or `_` and a 2 to 8 character alphanumeric subtag: `de`, `pt-BR`; case does not matter), renders the template's file, the default-locale version. Its subject, body and layout come from, in this order: the customized row of the name itself (an administrator wrote that locale's version), the customized row of the template, the template's file. When several registered templates match, the longest name wins. Any other unknown name fails with `postcard: unknown template `. The rule needs no list of locales, so a worker that only runs postcard sends the same mail as the admin previews. `postcard.Catalog.TemplateFor` returns the file a name renders from; its `Name` is the base template's for a name without a file of its own.
+
+`postcard.EnsureLocaleRows` gives such locales their index rows, so an administrator can open and customize them (see "Index rows, drift and reset").
+
### 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`:
@@ -348,7 +356,9 @@ A draft is rendered by the code that renders a send, with the mailer's CSS and t
`postcard.Catalog.Templates`, `postcard.Catalog.Layouts` and `postcard.Catalog.Partials` list the files as `postcard.TemplateFile`, `postcard.LayoutFile` and `postcard.PartialFile` values; each carries its `Source` and a `Hash`, the SHA-256 of the file's text with CRLF line endings normalized, so the same file hashes the same on every platform.
-`postcard.SyncIndex` gives every file a row in its table, keyed by `code`. A row that is not customized mirrors the file, so lists and forms show the file version. A customized row keeps its content; only `source`, `description`, `locale`, `name` and `file_hash` follow the file. An override stores the hash of the file it was written against in `base_hash`, so it is outdated when `base_hash` and `file_hash` differ. `postcard.SyncIndex` never deletes a row, leaves database-only layouts alone, writes nothing when a row already matches, and may run in several processes at once. It needs the tables: when they are not migrated yet it returns the error.
+`postcard.SyncIndex` gives every file a row in its table, keyed by `code`. A row that is not customized mirrors the file, so lists and forms show the file version. A customized row keeps its content; only `source`, `description`, `locale`, `base_code`, `name` and `file_hash` follow the file. `base_code` groups the locale variants of one template: it is the code with its locale suffix stripped (`postcard.TemplateBase`), so `acme.blog::mail.welcome` and `acme.blog::mail.welcome-en` share the base `acme.blog::mail.welcome`. An override stores the hash of the file it was written against in `base_hash`, so it is outdated when `base_hash` and `file_hash` differ. `postcard.SyncIndex` never deletes a row, leaves database-only layouts alone, writes nothing when a row already matches, and may run in several processes at once. It needs the tables: when they are not migrated yet it returns the error.
+
+`postcard.EnsureLocaleRows` adds the rows of the locales a template ships no file for: for every base template and every given locale except the default one, the row `-` with that locale, the template as `base_code`, and the template file's subject, body, layout and hash. Such a row sends the default-locale version until it is customized (see "Locale variants"); its `file_hash` follows the template's file, so a customized one shows as outdated when that file changes. The default locale gets no row: the template's own file is its version. Like `postcard.SyncIndex` it writes nothing for a matching row, deletes nothing and is safe to run in several processes at once; it can be limited to some templates.
`postcard.ResetOverride` returns one row to its file version and clears `is_custom`, `base_hash` and `customized_at`. A database-only layout has no file version and is refused.
@@ -386,7 +396,8 @@ A draft is rendered by the code that renders a send, with the mailer's CSS and t
| `postcard.CompileBrandCSS` | Checks a brand's colours and returns the brand CSS compiled from them. |
| `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. |
-| `postcard.SyncIndex` | Upserts one index row per file template, layout and partial of a catalog; mirrors the file into rows that are not customized and refreshes `file_hash` on all. |
+| `postcard.SyncIndex` | Upserts one index row per file template, layout and partial of a catalog; mirrors the file into rows that are not customized and refreshes `file_hash` and the template's `base_code` on all. |
+| `postcard.EnsureLocaleRows` | Upserts the row `-` of every locale (except the default) a base template ships no file for, from the template's file; optionally limited to some templates. |
| `postcard.ResetOverride` | Returns one file-backed row to its file version. Takes the row's `postcard.Kind` and code. |
| `postcard.Kind` | What a draft or a row is: `postcard.KindTemplate`, `postcard.KindLayout`, `postcard.KindPartial` or `postcard.KindBrand` (a Branding draft; it has no index row). |
| `postcard.Editor` | Validates, previews and test-sends drafts with the mailer's catalog, configuration, override source and driver. |
@@ -400,8 +411,10 @@ A draft is rendered by the code that renders a send, with the mailer's CSS and t
| `postcard.TemplateFile`, `postcard.LayoutFile`, `postcard.PartialFile` | A registered file with its parts, its normalized `Source` and its `Hash`. `postcard.TemplateFile.Samples` holds the sample values and `postcard.TemplateFile.Layout` the full name of the file's layout. |
| `postcard.Catalog.Templates`, `postcard.Catalog.Layouts`, `postcard.Catalog.Partials` | The registered files, sorted by name. |
| `postcard.Catalog.Template`, `postcard.Catalog.Layout`, `postcard.Catalog.Partial` | One registered file by full name. |
+| `postcard.Catalog.TemplateFor` | The file a template name renders from: its own file, or the base template's file for a `-` name whose locale ships none. |
| `postcard.FormatTemplate`, `postcard.FormatLayout`, `postcard.FormatPartial` | Content written in the file format, for display and comparison. |
| `postcard.TemplateLocale` | The locale suffix of a template name, when it is one of the given locales. |
+| `postcard.TemplateBase` | A template name without the locale suffix `postcard.TemplateLocale` finds: the `base_code` its locale variants share. |
## Configuration
diff --git a/modules/postcard/editor.go b/modules/postcard/editor.go
index a303683e..71fd4603 100644
--- a/modules/postcard/editor.go
+++ b/modules/postcard/editor.go
@@ -208,7 +208,8 @@ func (e *Editor) render(ctx context.Context, d Draft) (RenderedMessage, error) {
func (e *Editor) renderTemplate(d Draft, ov Overrides, opts renderOptions) (RenderedMessage, error) {
cat := e.m.catalog
- t, err := cat.lookupTemplate(d.Name)
+ // A fallback-locale name renders the base file with its samples.
+ t, err := cat.resolveTemplate(d.Name)
if err != nil {
return RenderedMessage{}, err
}
diff --git a/modules/postcard/mailer.go b/modules/postcard/mailer.go
index c8371008..5eeaa8b8 100644
--- a/modules/postcard/mailer.go
+++ b/modules/postcard/mailer.go
@@ -64,11 +64,14 @@ func NewMailer(cat *Catalog, driver Driver, opts Options) Mailer {
return &mailer{catalog: cat, driver: driver, opts: opts, source: opts.Overrides}
}
-// Send renders msg.Template and delivers it. It performs no locale selection;
-// the caller must pass the full dotted name, including any -en suffix. A
-// database override of the template is applied when the mailer has an
-// OverrideSource; an override that cannot be read or does not render is
-// logged and the file version is sent instead.
+// Send renders msg.Template and delivers it. It picks no locale: the caller
+// passes the full dotted name, including any -en suffix. A -
+// name whose locale ships no file resolves to the default-locale version:
+// that name's customized row when there is one, else the base template's
+// customized row, else the base template's file. A database override of the
+// template is applied when the mailer has an OverrideSource; an override
+// that cannot be read or does not render is logged and the file version is
+// sent instead.
func (m *mailer) Send(ctx context.Context, msg Message) error {
if m == nil {
return fmt.Errorf("postcard: mailer is nil")
@@ -101,10 +104,17 @@ func (m *mailer) Send(ctx context.Context, msg Message) error {
// overrides, or overrides that fail to render or to pass the safety checks,
// it renders the file version.
func (m *mailer) render(ctx context.Context, msg Message) (RenderedMessage, error) {
- if _, err := m.catalog.lookupTemplate(msg.Template); err != nil {
+ t, err := m.catalog.resolveTemplate(msg.Template)
+ if err != nil {
return RenderedMessage{}, err
}
ov := m.overrides(ctx, msg.Template)
+ if t.name != msg.Template && ov.Template == nil {
+ // A fallback-locale name with no customization of its own sends the
+ // base's. Layouts, partials and Branding are the same in both
+ // answers; only the template override is taken.
+ ov.Template = m.overrides(ctx, t.name).Template
+ }
// The file version carries the Branding too: it is not an override of a
// file, and a failing override must not change how the mail looks.
file := m.options(ov.Brand)
diff --git a/modules/postcard/override_smoke_test.go b/modules/postcard/override_smoke_test.go
index 999f79c8..451963de 100644
--- a/modules/postcard/override_smoke_test.go
+++ b/modules/postcard/override_smoke_test.go
@@ -528,11 +528,99 @@ func TestMailOverrideSmoke(t *testing.T) {
}
})
+ t.Run("locale_fallback", func(t *testing.T) {
+ gdb := mailPostgres(t)
+ m, drv, logs := bootMailApp(t, gdb)
+ // welcome-en ships its own file; de and fr do not.
+ enFS := fstest.MapFS{"views/mail/welcome-en.htm": {Data: []byte("subject = \"English {{ .name }}\"\nlayout = \"blog\"\n==\nHello {{ .name }}.\n")}}
+ if err := m.catalog.Register("acme.blog", enFS, []string{acmeWelcome + "-en"}, nil); err != nil {
+ t.Fatal(err)
+ }
+ ctx := context.Background()
+ locales := []string{"pl", "en", "de"}
+ if err := SyncIndex(ctx, gdb, m.catalog, locales); err != nil {
+ t.Fatal(err)
+ }
+ if err := EnsureLocaleRows(ctx, gdb, m.catalog, "pl", locales); err != nil {
+ t.Fatal(err)
+ }
+ var rows []struct {
+ Code string
+ Locale *string
+ BaseCode *string
+ Subject string
+ FileHash string
+ }
+ if err := gdb.Raw(`SELECT code, locale, base_code, subject, file_hash FROM `+TemplatesTable+` WHERE base_code = ? ORDER BY code`, acmeWelcome).Scan(&rows).Error; err != nil {
+ t.Fatal(err)
+ }
+ base, _ := m.catalog.Template(acmeWelcome)
+ if len(rows) != 3 || rows[0].Code != acmeWelcome || rows[1].Code != acmeWelcome+"-de" || rows[2].Code != acmeWelcome+"-en" {
+ t.Fatalf("welcome group rows = %+v, want welcome, welcome-de, welcome-en", rows)
+ }
+ if de := rows[1]; de.Locale == nil || *de.Locale != "de" || de.Subject != base.Subject || de.FileHash != base.Hash {
+ t.Errorf("fallback row = %+v, want locale de with the base file's subject and hash", de)
+ }
+ // Idempotent: a second run writes nothing new.
+ if err := EnsureLocaleRows(ctx, gdb, m.catalog, "pl", locales, acmeWelcome); err != nil {
+ t.Fatal(err)
+ }
+ var n int64
+ gdb.Raw(`SELECT COUNT(*) FROM ` + TemplatesTable).Scan(&n)
+ if n != 6 { // welcome, welcome-de, welcome-en, notice, notice-de, notice-en
+ t.Errorf("%d template rows after a second ensure, want 6", n)
+ }
+
+ // fr has no row: the base file.
+ sendFixture(t, m, acmeWelcome+"-fr", "")
+ if got := lastMessage(t, drv); got.Subject != "Welcome, Ada" {
+ t.Errorf("welcome-fr subject = %q, want the base file's", got.Subject)
+ }
+ // de customized: its own row.
+ if err := gdb.Exec(`UPDATE `+TemplatesTable+` SET subject = 'Willkommen {{ .name }}', is_custom = TRUE, base_hash = file_hash WHERE code = ?`, acmeWelcome+"-de").Error; err != nil {
+ t.Fatal(err)
+ }
+ sendFixture(t, m, acmeWelcome+"-de", "")
+ if got := lastMessage(t, drv); got.Subject != "Willkommen Ada" || !strings.Contains(got.HTML, "blog-mail") {
+ t.Errorf("welcome-de = %q / %q, want its customization in the blog layout", got.Subject, got.HTML)
+ }
+ // The base customized: fr now sends it, de keeps its own.
+ customizeWelcome(t, gdb, "Base {{ .name }}", "Base body.", "acme.blog::mail.layouts.blog")
+ sendFixture(t, m, acmeWelcome+"-fr", "")
+ if got := lastMessage(t, drv); got.Subject != "Base Ada" {
+ t.Errorf("welcome-fr after the base was customized = %q", got.Subject)
+ }
+ sendFixture(t, m, acmeWelcome+"-de", "")
+ if got := lastMessage(t, drv); got.Subject != "Willkommen Ada" {
+ t.Errorf("welcome-de after the base was customized = %q", got.Subject)
+ }
+ // A name with its own file is unchanged.
+ sendFixture(t, m, acmeWelcome+"-en", "")
+ if got := lastMessage(t, drv); got.Subject != "English Ada" {
+ t.Errorf("welcome-en = %q, want its own file", got.Subject)
+ }
+ // Neither a base nor a locale tag: unknown, with today's text.
+ for _, name := range []string{"acme.blog::mail.missing-de", acmeWelcome + "-deutsch", acmeWelcome + "x"} {
+ err := m.Send(ctx, Message{Template: name, To: []string{"ada@example.com"}})
+ if err == nil || !strings.Contains(err.Error(), "unknown template "+name) {
+ t.Errorf("Send of %s = %v", name, err)
+ }
+ }
+ if f, ok := m.catalog.TemplateFor(acmeWelcome + "-pt-BR"); !ok || f.Name != acmeWelcome {
+ t.Errorf("TemplateFor(welcome-pt-BR) = %q, %v", f.Name, ok)
+ }
+ if logs.Len() != 0 {
+ t.Errorf("unexpected log output:\n%s", logs)
+ }
+ })
+
t.Run("migrations_roll_back", func(t *testing.T) {
gdb := mailPostgres(t)
mig := gormigrate.New(gdb, gormigrate.DefaultOptions, Migrations)
- if err := mig.RollbackLast(); err != nil {
- t.Fatalf("rollback: %v", err)
+ for range Migrations {
+ if err := mig.RollbackLast(); err != nil {
+ t.Fatalf("rollback: %v", err)
+ }
}
var n int64
if err := gdb.Raw(`SELECT COUNT(*) FROM information_schema.tables WHERE table_name LIKE 'system_mail_%'`).Scan(&n).Error; err != nil {
diff --git a/modules/postcard/store.go b/modules/postcard/store.go
index 51eb6a82..42f1ecfd 100644
--- a/modules/postcard/store.go
+++ b/modules/postcard/store.go
@@ -4,6 +4,7 @@ import (
"context"
"database/sql"
"fmt"
+ "strings"
"git.golem15.com/golem15/summercms/modules/backpack"
"git.golem15.com/golem15/summercms/modules/lagoon/attach"
@@ -127,6 +128,33 @@ var Migrations = []*gormigrate.Migration{
return nil
},
},
+ {
+ // base_code groups the locale variants of one template: the code
+ // with its locale suffix stripped (TemplateBase).
+ ID: "202611130001_mail_template_base_code",
+ Migrate: func(tx *gorm.DB) error {
+ for _, stmt := range []string{
+ `ALTER TABLE ` + TemplatesTable + ` ADD COLUMN base_code TEXT`,
+ `CREATE INDEX ` + TemplatesTable + `_base_code_index ON ` + TemplatesTable + ` (base_code)`,
+ } {
+ if err := tx.Exec(stmt).Error; err != nil {
+ return err
+ }
+ }
+ return nil
+ },
+ Rollback: func(tx *gorm.DB) error {
+ for _, stmt := range []string{
+ `DROP INDEX IF EXISTS ` + TemplatesTable + `_base_code_index`,
+ `ALTER TABLE ` + TemplatesTable + ` DROP COLUMN IF EXISTS base_code`,
+ } {
+ if err := tx.Exec(stmt).Error; err != nil {
+ return err
+ }
+ }
+ return nil
+ },
+ },
}
// OverrideSource supplies the database overrides one render needs.
@@ -347,10 +375,11 @@ const syncLockKey = "summercms.postcard.sync"
//
// For a row that is not customized the content columns mirror the file. For
// a customized row they are left alone: only source, description, locale,
-// name and file_hash follow the file, which is what makes a changed file
-// show as a difference between base_hash and file_hash. No row is deleted,
-// database-only layouts are not touched, and a row that already matches is
-// not written. locales are the application's locales, for TemplateLocale.
+// base_code, name and file_hash follow the file, which is what makes a
+// changed file show as a difference between base_hash and file_hash. No row
+// is deleted, database-only layouts are not touched, and a row that already
+// matches is not written. locales are the application's locales, for
+// TemplateLocale and TemplateBase.
//
// It is safe to call from several processes at once. It fails when the
// tables are not migrated yet; the caller decides when to try again.
@@ -387,24 +416,7 @@ WHERE t.source IS DISTINCT FROM EXCLUDED.source
}
}
for _, f := range templates {
- if err := tx.Exec(`INSERT INTO `+TemplatesTable+` AS t (code, source, locale, description, subject, body, layout_id, file_hash)
-VALUES (?, ?, NULLIF(?, ''), ?, ?, ?, (SELECT id FROM `+LayoutsTable+` WHERE code = ?), ?)
-ON CONFLICT (code) DO UPDATE SET
- source = EXCLUDED.source,
- locale = EXCLUDED.locale,
- description = EXCLUDED.description,
- file_hash = EXCLUDED.file_hash,
- subject = CASE WHEN t.is_custom THEN t.subject ELSE EXCLUDED.subject END,
- body = CASE WHEN t.is_custom THEN t.body ELSE EXCLUDED.body END,
- layout_id = CASE WHEN t.is_custom THEN t.layout_id ELSE EXCLUDED.layout_id END,
- updated_at = NOW()
-WHERE t.source IS DISTINCT FROM EXCLUDED.source
- OR t.locale IS DISTINCT FROM EXCLUDED.locale
- OR t.description IS DISTINCT FROM EXCLUDED.description
- OR t.file_hash IS DISTINCT FROM EXCLUDED.file_hash
- OR (NOT t.is_custom AND (t.subject, t.body, t.layout_id)
- IS DISTINCT FROM (EXCLUDED.subject, EXCLUDED.body, EXCLUDED.layout_id))`,
- f.Name, f.PluginID, TemplateLocale(f.Name, locales), f.Description, f.Subject, f.Body, f.Layout, f.Hash).Error; err != nil {
+ if err := upsertTemplateRow(tx, f.Name, f.PluginID, TemplateLocale(f.Name, locales), TemplateBase(f.Name, locales), f); err != nil {
return err
}
}
@@ -435,6 +447,111 @@ WHERE t.source IS DISTINCT FROM EXCLUDED.source
return nil
}
+// upsertTemplateRow writes the index row code of a template whose file
+// version is f: the template's own file, or the base's for a
+// fallback-locale row. A customized row keeps its content columns.
+func upsertTemplateRow(tx *gorm.DB, code, source, locale, base string, f TemplateFile) error {
+ return tx.Exec(`INSERT INTO `+TemplatesTable+` AS t (code, source, locale, base_code, description, subject, body, layout_id, file_hash)
+VALUES (?, ?, NULLIF(?, ''), ?, ?, ?, ?, (SELECT id FROM `+LayoutsTable+` WHERE code = ?), ?)
+ON CONFLICT (code) DO UPDATE SET
+ source = EXCLUDED.source,
+ locale = EXCLUDED.locale,
+ base_code = EXCLUDED.base_code,
+ description = EXCLUDED.description,
+ file_hash = EXCLUDED.file_hash,
+ subject = CASE WHEN t.is_custom THEN t.subject ELSE EXCLUDED.subject END,
+ body = CASE WHEN t.is_custom THEN t.body ELSE EXCLUDED.body END,
+ layout_id = CASE WHEN t.is_custom THEN t.layout_id ELSE EXCLUDED.layout_id END,
+ updated_at = NOW()
+WHERE t.source IS DISTINCT FROM EXCLUDED.source
+ OR t.locale IS DISTINCT FROM EXCLUDED.locale
+ OR t.base_code IS DISTINCT FROM EXCLUDED.base_code
+ OR t.description IS DISTINCT FROM EXCLUDED.description
+ OR t.file_hash IS DISTINCT FROM EXCLUDED.file_hash
+ OR (NOT t.is_custom AND (t.subject, t.body, t.layout_id)
+ IS DISTINCT FROM (EXCLUDED.subject, EXCLUDED.body, EXCLUDED.layout_id))`,
+ code, source, locale, base, f.Description, f.Subject, f.Body, f.Layout, f.Hash).Error
+}
+
+// EnsureLocaleRows gives every locale of a template that ships no file of
+// its own an index row, so that the locale can be opened and customized in
+// the admin. For every base template of cat (a template whose TemplateBase
+// is itself; all of them when bases is empty, else only those listed) and
+// every locale in locales other than defaultLocale for which cat holds no
+// - file, it upserts the row -: source, locale,
+// base_code, description, subject, body and layout from the base file, and
+// file_hash the base file's hash. A customized row keeps its content
+// columns while file_hash, description and base_code follow the base, so a
+// changed base file shows as drift. A matching row is not written and no row
+// is deleted. defaultLocale gets no row: the base file is its version.
+//
+// It takes the same advisory lock as SyncIndex and fails, like it, when the
+// tables are not migrated yet.
+func EnsureLocaleRows(ctx context.Context, db *gorm.DB, cat *Catalog, defaultLocale string, locales []string, bases ...string) error {
+ if db == nil {
+ return fmt.Errorf("postcard: ensure locale rows: database is nil")
+ }
+ if cat == nil {
+ return fmt.Errorf("postcard: ensure locale rows: catalog is nil")
+ }
+ all := locales
+ if defaultLocale != "" {
+ all = append([]string{defaultLocale}, locales...)
+ }
+ templates := cat.Templates()
+ have := make(map[string]bool, len(templates))
+ for _, f := range templates {
+ have[strings.ToLower(f.Name)] = true
+ }
+ only := make(map[string]bool, len(bases))
+ for _, b := range bases {
+ only[b] = true
+ }
+ type row struct {
+ code, locale string
+ base TemplateFile
+ }
+ var rows []row
+ for _, f := range templates {
+ if TemplateBase(f.Name, all) != f.Name || (len(only) > 0 && !only[f.Name]) {
+ continue
+ }
+ for _, locale := range locales {
+ if locale == "" || strings.EqualFold(locale, defaultLocale) {
+ continue
+ }
+ code := f.Name + "-" + locale
+ if have[strings.ToLower(code)] {
+ continue
+ }
+ // Only a code a send resolves to this base gets a row: a
+ // locale tag the send rule does not accept would never be used.
+ if to, ok := cat.TemplateFor(code); !ok || to.Name != f.Name {
+ continue
+ }
+ rows = append(rows, row{code: code, locale: locale, base: f})
+ }
+ }
+ if len(rows) == 0 {
+ return nil
+ }
+ err := db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+ if err := tx.Exec(`SELECT pg_advisory_xact_lock(hashtext(?))`, syncLockKey).Error; err != nil {
+ return err
+ }
+ for _, r := range rows {
+ if err := upsertTemplateRow(tx, r.code, r.base.PluginID, r.locale, r.base.Name, r.base); err != nil {
+ return err
+ }
+ }
+ return nil
+ })
+ if err != nil {
+ return fmt.Errorf("postcard: ensure locale rows: %w", err)
+ }
+ return nil
+}
+
// rowName is the name column of a layout or partial row: the name in the
// file's header, or the full name when the header has none.
func rowName(title, full string) string {
diff --git a/modules/postcard/templates.go b/modules/postcard/templates.go
index 39b996a7..88d98f30 100644
--- a/modules/postcard/templates.go
+++ b/modules/postcard/templates.go
@@ -240,14 +240,47 @@ func (c *Catalog) resolveLayoutLocked(t *parsedTemplate) error {
return nil
}
-func (c *Catalog) lookupTemplate(name string) (*parsedTemplate, error) {
+// localeTag matches the locale tag a fallback-locale name ends in: a
+// two-letter language, optionally followed by a dash or an underscore and
+// a 2-8 character alphanumeric subtag (de, pt-BR, zh_Hant).
+var localeTag = regexp.MustCompile(`^[A-Za-z]{2}(?:[-_][A-Za-z0-9]{2,8})?$`)
+
+// resolveTemplate is the lookup every send, preview and validation goes
+// through. A name with its own file is that file. A name the catalog does
+// not hold of the form -, where is a registered template
+// and a locale tag, is the base's file: a locale that ships no file
+// of its own sends the default-locale version. When several bases match,
+// the longest one wins. Any other name is an unknown template.
+func (c *Catalog) resolveTemplate(name string) (*parsedTemplate, error) {
c.mu.RLock()
defer c.mu.RUnlock()
- t, ok := c.templates[name]
- if !ok {
- return nil, fmt.Errorf("postcard: unknown template %s", name)
+ if t, ok := c.templates[name]; ok {
+ return t, nil
}
- return t, nil
+ if t := c.fallbackLocked(name); t != nil {
+ return t, nil
+ }
+ return nil, fmt.Errorf("postcard: unknown template %s", name)
+}
+
+// fallbackLocked returns the base template a fallback-locale name resolves
+// to, or nil. The caller holds c.mu.
+func (c *Catalog) fallbackLocked(name string) *parsedTemplate {
+ _, rest, ok := strings.Cut(name, "::")
+ if !ok {
+ return nil
+ }
+ // The tag holds no dot, so the dash is in the last dotted segment.
+ start := len(name) - len(rest) + strings.LastIndex(rest, ".") + 1
+ for i := len(name) - 1; i > start; i-- {
+ if name[i] != '-' || !localeTag.MatchString(name[i+1:]) {
+ continue
+ }
+ if t, ok := c.templates[name[:i]]; ok {
+ return t
+ }
+ }
+ return nil
}
// RegisterPartials loads declared partial names from fsys. Each name must
@@ -490,7 +523,7 @@ type renderSource struct {
// render renders msg.Template: the file version, or the file version with
// opts.overrides applied. Both go through renderFrom.
func (c *Catalog) render(msg Message, opts renderOptions) (RenderedMessage, error) {
- t, err := c.lookupTemplate(msg.Template)
+ t, err := c.resolveTemplate(msg.Template)
if err != nil {
return RenderedMessage{}, err
}
@@ -869,6 +902,19 @@ func (c *Catalog) Template(name string) (TemplateFile, bool) {
return t.file(), true
}
+// TemplateFor returns the file a template name renders from: the name's
+// own file, or, for a - name whose locale ships no file,
+// the file of the base template (see the send-resolution rule in the
+// package README). The returned Name is the base's in the second case,
+// which is how a caller tells the two apart.
+func (c *Catalog) TemplateFor(name string) (TemplateFile, bool) {
+ t, err := c.resolveTemplate(name)
+ if err != nil {
+ return TemplateFile{}, false
+ }
+ return t.file(), true
+}
+
// Layout returns the registered layout of that full name.
func (c *Catalog) Layout(name string) (LayoutFile, bool) {
c.mu.RLock()
@@ -939,3 +985,15 @@ func TemplateLocale(name string, locales []string) string {
}
return best
}
+
+// TemplateBase returns the name of the template a locale variant belongs
+// to: name without the locale suffix TemplateLocale finds in it, or name
+// itself when it has none. acme.blog::mail.welcome-en and
+// acme.blog::mail.welcome share the base acme.blog::mail.welcome.
+func TemplateBase(name string, locales []string) string {
+ locale := TemplateLocale(name, locales)
+ if locale == "" {
+ return name
+ }
+ return name[:len(name)-len(locale)-1]
+}