feat(email): convert reset template to shared partials

2026-06-26 23:22:02 +02:00
parent af7271d851
commit bf5c710c2b
2 changed files with 114 additions and 0 deletions
@@ -0,0 +1,69 @@
+# Build note: the email templates import `emails/partials/header.html` and `emails/partials/footer.html` through NodeBB's `emails/` view namespace.
+
+# Email templates
+
+HTML email templates for the Westgate theme. NodeBB renders these and mails
+them to users on various events (password reset, digest, ban, etc.).
+
+## How NodeBB uses them
+
+- **Discovery.** NodeBB looks for email templates under a theme/plugin's
+  templates directory. Core ships them in `src/views/emails/*.tpl`; a theme
+  overrides one by shipping a file of the same name. The `email/` directory
+  here is built into NodeBB's `emails/` view namespace, so `email/reset.html`
+  overrides the core `reset` template. Run `./nodebb build` after editing so
+  the changes are compiled into `build/`.
+- **Template engine.** [Benchpress](https://github.com/benchpressjs/benchpressjs),
+  the same engine as the rest of the theme's `.tpl` files. Syntax:
+  - `{var}` / `{obj.field}` — interpolate a value from the params object.
+  - `{{{ if cond }}} … {{{ else }}} … {{{ end }}}` — conditionals
+    (e.g. `{{{ if logo.src }}}`, `{{{ if showUnsubscribe }}}`, `{{{ if rtl }}}`).
+  - `[[namespace:key]]` — i18n translation key, resolved server-side after
+    render (e.g. `[[email:reset.cta]]`, `[[email:greeting-no-name]]`). Strings
+    live in NodeBB's language files, not here.
+- **Send path.** `Emailer.send(template, uid, params)` →
+  `sendToEmail` → `renderAndTranslate('emails/<name>', params)`. `<name>` is
+  the filename without extension (`reset.html` → template name `reset`).
+- **Default params** available in every template: `url`, `site_title`,
+  `logo.{src,width,height}`, `uid`, `username`, `displayname`, `rtl`, plus
+  `showUnsubscribe` / `unsubUrl` for digest- and notification-type mails.
+  Each template also gets its own event-specific params (see table).
+
+## Templates and what triggers them
+
+| File | NodeBB event | Notable params |
+|------|--------------|----------------|
+| `welcome.html` | New registration needing email confirmation | confirmation link |
+| `verify-email.html` | User adds/changes an email and must confirm it | confirmation link |
+| `reset.html` | User requests a password reset | `{reset_link}` |
+| `reset_notify.html` | Confirmation that the password was changed | — |
+| `registration_accepted.html` | Admin approves a queued registration | — |
+| `banned.html` | User is banned | ban reason / expiry |
+| `invitation.html` | A user is invited to the forum | invite link |
+| `notification.html` | Per-event notification (reply, mention, etc.); also post-queue items | `showUnsubscribe`, `unsubUrl` |
+| `digest.html` | Scheduled activity digest (daily/weekly/monthly) | unread topics, `showUnsubscribe` |
+| `test.html` | "Send test email" button in the ACP | — |
+
+## Partials
+
+`partials/` holds fragments included by the templates above:
+
+- `header.html` — shared email head/header markup.
+- `footer.html` — shared footer with the unsubscribe block
+  (`{{{ if showUnsubscribe }}}`).
+- `post-queue-body.html` — renders a queued post (category, topic, author,
+  content) inside `notification.html` for post-queue notifications.
+
+## Editing notes
+
+- These are emails: inline CSS, table layout, MSO/Outlook conditional
+  comments. Keep that structure — don't refactor into modern CSS.
+- Don't hardcode user-facing copy; add/replace `[[email:…]]` keys and define
+  them in the language files.
+- Rebuild (`./nodebb build`) and use the ACP test-email button to verify.
+
+## References
+
+- [NodeBB themes](https://docs.nodebb.org/development/themes/)
+- [NodeBB templating](https://docs.nodebb.org/development/themes/templates/)
+- [Email templating discussion](https://community.nodebb.org/topic/1502/email-templating)