diff options
Diffstat (limited to 'template/README.md')
| -rw-r--r-- | template/README.md | 126 |
1 files changed, 126 insertions, 0 deletions
diff --git a/template/README.md b/template/README.md new file mode 100644 index 0000000..104c9a8 --- /dev/null +++ b/template/README.md @@ -0,0 +1,126 @@ + +# mail-template + +**Provides mechanisms for generating mails based on templates** + +--- + +This crate provides a general interface for using template engine with the mail crate. + +It's core is the `TemplateEngine` trait which can be implemented to bind a template engine. +When rendering a template the template engine implementing the `TemplateEngine` trait will +produce a number of (wrapped) `Resource` instances representing the alternate bodies of amail as well as a number of additional `Resources` used for embedded content (e.g. logoimages) and attachments. This crate then takes this parts and composes a multipart mime mail from +it. + +## Template Engine implementations + +A mail template engine has to do more then just taking a single text +template (e.g. a handlebars template) and produce some output using +string magic. It has to: + +1. consider alternate bodies, so it should render at last two + "text templates" (one text/plain, one html) + +2. consider which additional embeddings/attachments should be included + (all in the given template data are included, but you might + add additional ones, e.g. some logo image) + +As such text template engines like `Handle` bar can not directly +be bound to the `TemplateEngine` trait. + +For using text template engine it's recommended to use +the `mail-template-render-engine` (also exposed through the +mail facade) which implements this overhead for any engine +which can "just" render some text and provides default +bindings to some common template engines (e.g. Handlebars). + +## Derive + +This crate requires template data to implement `InspectEmbeddedResources` +which combined with some typing/generic design decisions allows to bind +not just to template engines which use serialization to access template +data but also to such which use static typing (like `askama`). + +As such it re-exports the `InspectEmbeddedResources` derive from +`mail-derive`. Note that if you use the mail facade it also does +re-export the derive. + +## Features + +- `askama-engine`, includes bindings for the askama template engine. +- `serialize-to-content-id`, implements Serialize for `Embedded`, + `EmbeddedWithCId` which serializes the embedded type **into its + content id**. E.g. a image with content id `"q09cu3@example.com"` + will be serialized to the string `"q09cu3@example.com"`. This is + extremely useful for all template engines which use serialization + as their way to access template data. + +## Example + +```rust +``` + +## Road Map + +The current implementation has a number of limitations which should be lifted with +future versions: + +- Only a limited subset of headers are/can be set through the template engine + (`Sender`, `From`, `To`, `Subject`) while some headers are set implicitly + when encoding the mail (e.g. `Date`, `Content-Type`, `Content-Disposition`). + But sometimes it would be useful to add some custom headers through the template + engine (both on the outermost and inner bodies). +- `From`, `To`, `Subject` have to be given, but sometimes you might want to just + create the `Mail` type and then set them by yourself (through you _can_ currently + override them) +- Re-use/integration of existing mail instances: Some times you might want to + use a `Mail` instance created some where else as a body for a multipart mail + generated from a template (e.g. some thing generating "special" attachments). + +Also there are some parts which are likely to change: + +- `MailSendData`/`MailSendDataBuilder` the name is + not very good it also needs to change to handle + the thinks listed above +- `Embedded`, `EmbeddedWithCid`, embeddings and attachments + currently a `Embedded` instance is a wrapper around `Resource` + representing something which will become a mail body but is not + a main body (i.e. it not the text/html/.. you send) instead it + something embedded in the mail which is either used as attachment + or as a embedding (e.g. a logo image). Through the content disposition + the `Embedded` instance differs between thing embedded and internally + used or embedded and used as attachment at the same time many different + arrays are sometimes used to differ between them (e.g. in `MailParts`) + but there is no (type system) check to make sure a array of thinks used + as attachments can not contain a `Embedded` instance with content disposition + inline. The result will still be a valid mail, but likely not in the + way you expect it to be. This should be fixed one way or another (making + the different array type safe and lifting disposition to the type level + had been used but didn't play out nicely). +- `serialize-to-content-id`, is a nice idea but has some problems in + some edge cases (e.g. when you want to serialize anything containing + a `Embedded` type for any usage BUT accessing it in an template). So + it might be removed, which means a import like `cid:{{data.mything}}` + (using some mustach pseudo template syntax) would become `cid:{{data.mything.cid}}`. + + +## Documentation + + +Documentation can be [viewed on docs.rs](https://docs.rs/mail-template). +(once published) + +## License + +Licensed under either of + +* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0) +* MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT) + +at your option. + +### Contribution + +Unless you explicitly state otherwise, any contribution intentionally submitted +for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any +additional terms or conditions. |