feat(mail): one admin record per mail template with a locale switcher

Gap G-35-1 (supersedes D-05), tracer slice:
- postcard: migration 202611130001_mail_template_base_code (base_code
  column and index); SyncIndex writes base_code; EnsureLocaleRows creates
  the <template>-<locale> rows of locales that ship no file; TemplateBase
  and Catalog.TemplateFor; send, preview and validation resolve a missing
  <template>-<locale> to the locale's customization, else the base's
  customization, else the base file. Names with their own file send as
  before.
- cabana: mail locales are the translator's plus the TranslationWriter's
  enabled locales; sync ensures the locale rows and re-syncs when the
  locale set changes; record lookups admit fallback-locale rows; the
  record title is the base code; RecordMeta.LocaleVariants
  (RecordLocaleVariant) on the show and update responses.
- admin: LocaleVariantSwitcher in the update form header, from
  meta.localeVariants, behind the unsaved-changes confirm.
- tests: TestMailOverrideSmoke/locale_fallback,
  TestMailScreensSmoke/locales, LocaleVariantSwitcher.test.ts.
This commit is contained in:
Jakub Zych
2026-11-13 20:29:42 +01:00
parent 9afe95ccef
commit 52c9c7eb18
22 changed files with 920 additions and 63 deletions

View File

@@ -2885,6 +2885,36 @@
],
"type": "object"
},
"cabana.RecordLocaleVariant": {
"properties": {
"current": {
"type": "boolean"
},
"id": {
"type": "integer"
},
"label": {
"type": "string"
},
"locale": {
"type": "string"
},
"states": {
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"current",
"id",
"label",
"locale",
"states"
],
"type": "object"
},
"cabana.RecordMeta": {
"properties": {
"actions": {
@@ -2906,6 +2936,13 @@
},
"type": "object"
},
"localeVariants": {
"description": "LocaleVariants are the locale versions of the record for the update\nform's locale switcher, in display order. Only the show and update\nresponses of a controller whose records have locale versions (the mail\ntemplates screen) carry it; it is omitted otherwise.",
"items": {
"$ref": "#/components/schemas/cabana.RecordLocaleVariant"
},
"type": "array"
},
"notices": {
"items": {
"$ref": "#/components/schemas/cabana.FieldNotice"

View File

@@ -6998,6 +6998,13 @@ export interface components {
data: components["schemas"]["cabana.AdminRecord"];
meta: components["schemas"]["cabana.RecordMeta"];
};
"cabana.RecordLocaleVariant": {
current: boolean;
id: number;
label: string;
locale: string;
states: string[];
};
"cabana.RecordMeta": {
actions?: components["schemas"]["cabana.RecordAction"][];
/**
@@ -7010,6 +7017,13 @@ export interface components {
labels: {
[key: string]: components["schemas"]["cabana.RelationOption"][];
};
/**
* @description 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?: components["schemas"]["cabana.RecordLocaleVariant"][];
notices?: components["schemas"]["cabana.FieldNotice"][];
/**
* @description PermissionLocks are, per permissioneditor field, the permissions this

View File

@@ -0,0 +1,68 @@
<script setup lang="ts">
// The locale switcher of a record with locale versions (meta.localeVariants:
// the mail templates screen). Each version is its own record id; choosing one
// opens it on the same route, behind the form's unsaved-changes confirm. When
// that navigation is refused the selection goes back to the open version.
// Labels and state words come translated from the server.
import { computed, ref, watch } from 'vue'
import { isNavigationFailure, useRoute, useRouter } from 'vue-router'
import type { RecordMeta } from '../../api/types'
import { t } from '../../app/i18n'
type LocaleVariant = NonNullable<RecordMeta['localeVariants']>[number]
const props = defineProps<{ variants: LocaleVariant[]; controlId?: string }>()
const route = useRoute()
const router = useRouter()
const current = computed(() => props.variants.find((variant) => variant.current)?.id ?? props.variants[0]?.id ?? 0)
const selected = ref(current.value)
watch(current, (id) => {
selected.value = id
})
const selectId = computed(() => props.controlId ?? 'locale-variant')
function optionText(variant: LocaleVariant): string {
const states = variant.states ?? []
return states.length > 0 ? `${variant.label} — ${states.join(', ')}` : variant.label
}
async function onChange(event: Event): Promise<void> {
const select = event.target as HTMLSelectElement
const id = Number(select.value)
if (!Number.isFinite(id) || id === current.value) {
return
}
selected.value = id
let failed = false
try {
const result = await router.push({ name: route.name ?? undefined, params: { ...route.params, id: String(id) }, query: route.query })
failed = isNavigationFailure(result)
} catch {
failed = true
}
if (failed) {
selected.value = current.value
select.value = String(current.value)
}
}
</script>
<template>
<div class="flex flex-wrap items-center gap-2">
<label :for="selectId" class="text-[13px] text-muted">{{ t('backend::lang.form.locale_variant') }}</label>
<select
:id="selectId"
data-locale-variant
class="rounded-control border border-border-strong bg-surface px-2 py-1 text-[13px]"
:value="String(selected)"
@change="onChange"
>
<option v-for="variant in variants" :key="variant.id" :value="String(variant.id)" :data-locale="variant.locale">
{{ optionText(variant) }}
</option>
</select>
</div>
</template>

View File

@@ -22,6 +22,7 @@ import { mapWinterUrl } from '../app/winterUrl'
import FormErrorBanner from '../components/form/FormErrorBanner.vue'
import FormGrid from '../components/form/FormGrid.vue'
import FormTabs from '../components/form/FormTabs.vue'
import LocaleVariantSwitcher from '../components/form/LocaleVariantSwitcher.vue'
import {
DEPENDENT_CACHE,
FORM_ASSETS,
@@ -105,6 +106,8 @@ const recordTitle = ref('')
const actions = ref<RecordAction[]>([])
/** When false, Delete is hidden; absent means true (existing controllers). */
const deletable = ref(true)
/** The record's locale versions (meta.localeVariants); the switcher shows from two. */
const localeVariants = ref<NonNullable<RecordMeta['localeVariants']>>([])
const acting = ref(false)
const partialReload = ref(0)
const errors = ref<Record<string, string[]>>({})
@@ -266,6 +269,9 @@ function adopt(record: RecordEnvelope | undefined): void {
recordTitle.value = record.meta.title ?? ''
actions.value = record.meta.actions ?? []
deletable.value = record.meta.deletable !== false
if (record.meta.localeVariants) {
localeVariants.value = record.meta.localeVariants
}
}
saved.value = snapshot(editablePayload(fields.value, values.value, mode, permissionLocks.value))
}
@@ -705,6 +711,12 @@ void load()
<div class="flex min-w-0 flex-1 flex-col">
<h1 class="truncate text-[24px] font-bold tracking-[-0.02em]">{{ loading ? '' : title }}</h1>
<p v-if="subtitle" class="text-muted">{{ subtitle }}</p>
<LocaleVariantSwitcher
v-if="!loading && localeVariants.length > 1"
class="mt-1.5"
:variants="localeVariants"
:control-id="`${ID_PREFIX}-locale-variant`"
/>
</div>
<FormTabs v-if="tabs.length > 0" v-model="activeTab" :tabs="tabs" :id-prefix="ID_PREFIX" />
</header>

View File

@@ -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<HTMLSelectElement>('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',

View File

@@ -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<HTMLSelectElement>('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<HTMLSelectElement>('select')
await select.setValue('8')
await flushPromises()
expect(router.currentRoute.value.params.id).toBe('7')
expect(select.element.value).toBe('7')
})
})

View File

@@ -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

View File

@@ -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 `<template>-<locale>` where `<template>` is registered and `<locale>` 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 <name>`. So a plugin can pass `<template>-<locale>` 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`.

File diff suppressed because one or more lines are too long

View File

@@ -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

View File

@@ -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
}

View File

@@ -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{}
}
}

View File

@@ -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.

View File

@@ -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

View File

@@ -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

View File

@@ -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

View File

@@ -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.<path>` 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 `<template>-<locale>` 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 `<template>-<tag>` where `<template>` is a registered template and `<tag>` 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 <name>`. 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 `<template>-<locale>` 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 `<template>-<locale>` 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 `<template>-<locale>` 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

View File

@@ -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
}

View File

@@ -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 <template>-<locale>
// 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)

View File

@@ -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 {

View File

@@ -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
// <base>-<locale> file, it upserts the row <base>-<locale>: 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 {

View File

@@ -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 <base>-<tag>, where <base> is a registered template
// and <tag> 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 <template>-<locale> 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]
}