docs: add a Role in the framework section to every module README
Each module README now says where the module sits in the dependency graph, why it is its own module, and lists use cases for application developers.
This commit is contained in:
@@ -10,6 +10,16 @@ Transactional mail from plugin-owned Markdown templates and layouts, delivered t
|
||||
|
||||
postcard is the mail layer of SummerCMS. Plugins that implement `pact.HasMailTemplates` ship WinterCMS-shaped mail files under `views/mail/`; at boot, `postcard.Activate` publishes one app-scoped `postcard.Mailer` built from the compass `mail.*` config, and `postcard.BootPlugin` registers each plugin's templates and layouts as the plugin boots. Callers then send a template by its dotted name with a map of variables. It is the counterpart of WinterCMS's `Mail::send` with `views/mail/*.htm` templates and mail layouts.
|
||||
|
||||
## Role in the framework
|
||||
|
||||
A service module on `backpack`, `compass` and `pact`; `party` registers the templates plugins contribute. It is separate so mail rendering and delivery can be tested and swapped (memory, log, SMTP) without touching the code that sends.
|
||||
|
||||
Use cases:
|
||||
|
||||
- Send account mail (welcome, password reset) from Markdown templates owned by the plugin.
|
||||
- Share one branded layout across all of an application's mail.
|
||||
- Capture sent mail in memory in tests, or log it in development instead of delivering it.
|
||||
|
||||
## Features
|
||||
|
||||
- Templates named `<plugin>::mail.<name>` and loaded from `views/mail/<name>.htm` (dots become directories). A plugin may only register names in its own namespace; missing files, duplicates and unknown layout aliases fail at boot.
|
||||
|
||||
Reference in New Issue
Block a user