From 4b0ed4a8a00ead9a3f9dda46ee8b84649f900739 Mon Sep 17 00:00:00 2001 From: Alex Koutmos Date: Fri, 6 May 2022 18:56:01 -0400 Subject: [PATCH] Updating docs --- CHANGELOG.md | 3 ++- README.md | 21 +++++++++++++++++++-- lib/mjml_eex.ex | 26 +++++++++++++++++++++++++- lib/mjml_eex/component.ex | 16 ++++++++++++---- 4 files changed, 58 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f17073c..1e4dbed 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,7 +20,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changed - When calling `use MjmlEEx`, if the `:mjml_template` option is not provided, the module attempts to find a template - file that has the same file name as the module (with the `.mjml.eex` extension instead of `.ex`). + file in the same directory that has the same file name as the module (with the `.mjml.eex` extension instead + of `.ex`). This functions similar to how Phoenix and LiveView handle their templates. ### Removed diff --git a/README.md b/README.md index f2d2158..8171c62 100644 --- a/README.md +++ b/README.md @@ -183,8 +183,25 @@ And the following template: ``` -Be sure to look at the `MjmlEEx.Component` for additional usage information as you can also pass options -to your template and use them when generating the partial string. +Be sure to look at the `MjmlEEx.Component` module for additional usage information as you can also pass options to your +template and use them when generating the partial string. One thing to note is that when using +`render_static_component`, the data that is passed to the component must be defined at compile time. This means that you +cannot use any assigns that would bee to be evaluated at runtime. For example, this would raise an error: + +```elixir + + <%= render_static_component MyTextComponent, some_data: @some_data %> + +``` + +If you need to render your components dynamically, use `render_dynamic_component` instead and be sure to configure your +template module like so to generate the email HTML at runtime: + +```elixir +def MyTemplate do + use MjmlEEx, mode: :runtime +end +``` ### Using Layouts diff --git a/lib/mjml_eex.ex b/lib/mjml_eex.ex index 3619241..d9022c7 100644 --- a/lib/mjml_eex.ex +++ b/lib/mjml_eex.ex @@ -1,7 +1,31 @@ defmodule MjmlEEx do @moduledoc """ Documentation for `MjmlEEx` template module. This moule contains the macro - that is used to create an MJML EEx template. + that is used to create an MJML EEx template. The macro can be configured to + render the MJML template in a few different ways, so be sure to read the + option documentation. + + ## Macro Options + + - `:mjml_template`- A binary that specifies the name of the `.mjml.eex` template that the module will compile. The + directory path is relative to the template module. If this option is not provided, the MjmlEEx will look for a + file that has the same name as the module but with the `.mjml.ex` extension as opposed to `.ex`. + + - `:mode`- This option defines when the MJML template is actually compiled. The possible values are `:runtime` and + `:compile`. When this option is set to `:compile`, the MJML template is compiled into email compatible HTML at + compile time. It is suggested that this mode is only used if the template is relatively simple and there are only + assigns being used as text or attributes on html elements (as opposed to attributes on MJML elements). The reason + for that being that these assigns may be discarded as part of the MJML compilation phase. On the plus side, you + do get a performance bump here since the HTML for the email is already generated. When this is set to `:runtime`, + the MJML template is compiled at runtime and all the template assigns are applied prior to the MJML compilation + phase. These means that there is a performance hit since you are compiling the MJML template every time, but the + template can use more complex EEx constructs like `for`, `case` and `cond`. The default configuration is `:runtime`. + + - `:layout` - This option defines what layout the template should be injected into prior to rendering the template. + This is useful if you want to have reusable email templates in order to keep your email code DRY and reusable. + Your template will then be injected into the layout where the layout defines `<%= inner_content %>`. + + ## Example Usage You can use this module like so: diff --git a/lib/mjml_eex/component.ex b/lib/mjml_eex/component.ex index 8b4be32..2d1d28f 100644 --- a/lib/mjml_eex/component.ex +++ b/lib/mjml_eex/component.ex @@ -1,9 +1,17 @@ defmodule MjmlEEx.Component do @moduledoc """ - This module allows you to define a reusable MJML component that - can be injected into an MJML template prior to it being - rendered into HTML. To do so, create an `MjmlEEx.Component` - module that looks like so: + This module allows you to define a reusable MJML component that can be injected into + an MJML template prior to it being rendered into HTML. There are two different ways + that components can be rendered in templates. The first being `render_static_component` + and the other being `render_dynamic_component`. `render_static_component` should be used + to render the component when the data provided to the component is known at compile time. + If you want to dynamically render a component (make sure that the template is set to + `mode: :runtime`) with assigns that are passed to the template, then use + `render_dynamic_component`. + + ## Example Usage + + To use an MjmlEEx component, create an `MjmlEEx.Component` module that looks like so: ```elixir defmodule HeadBlock do