diff options
Diffstat (limited to 'src/lib.rs')
| -rw-r--r-- | src/lib.rs | 106 |
1 files changed, 106 insertions, 0 deletions
@@ -1,3 +1,109 @@ +//! 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 a mail as well +//! as a number of additional `Resources` used for embedded content (e.g. logo images) 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 +//! +//! ``` +//! +//! ``` +//! +//! # 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}}`. +//! extern crate mail_types as mail; extern crate mail_common as common; #[macro_use] |