diff --git a/README.md b/README.md index 808db41..db2055f 100644 --- a/README.md +++ b/README.md @@ -140,6 +140,52 @@ In order to render the email you would then call: `FunctionTemplate.render(first ### Using Components +In addition to compiling single MJML EEx templates, you can also create MJML partials and include them +in other MJML templates AND components using the special `render_component` function. With the following +modules: + +```elixir +defmodule FunctionTemplate do + use MjmlEEx, mjml_template: "component_template.mjml.eex" +end +``` + +```elixir +defmodule HeadBlock do + use MjmlEEx.Component + + @impl true + def render(_opts) do + """ + + Hello world! + + + """ + end +end +``` + +And the following template: + +```html + + <%= render_component HeadBlock %> + + + + + + Hello <%= generate_full_name(@first_name, @last_name) %>! + + + + +``` + +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. + ## Attribution - The logo for the project is an edited version of an SVG image from the [unDraw project](https://undraw.co/) diff --git a/lib/mjml_eex.ex b/lib/mjml_eex.ex index 2189543..15debd2 100644 --- a/lib/mjml_eex.ex +++ b/lib/mjml_eex.ex @@ -10,6 +10,28 @@ defmodule MjmlEEx do use MjmlEEx, mjml_template: "basic_template.mjml.eex" end ``` + + Along with the `basic_template.mjml.eex MJML` template located in the same + directory as the module containing the following: + + ```html + + + + + + Hello <%= @first_name %> <%= @last_name %>! + + + + + ``` + + Once that is in place, you can render the final HTML document by running: + + ```elixir + BasicTemplate.render(first_name: "Alex", last_name: "Koutmos") + ``` """ alias MjmlEEx.Utils diff --git a/lib/mjml_eex/component.ex b/lib/mjml_eex/component.ex index 398148f..2340f91 100644 --- a/lib/mjml_eex/component.ex +++ b/lib/mjml_eex/component.ex @@ -2,12 +2,51 @@ 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. + rendered into HTML. To do so, create an `MjmlEEx.Component` + module that looks like so: + + ```elixir + defmodule HeadBlock do + use MjmlEEx.Component + + @impl true + def render(_opts) do + \""" + + Hello world! + + + \""" + end + end + ``` + + With that in place, anywhere that you would like to use the component, you can add: + `<%= render_component HeadBlock %>` in your MJML EEx template. + + You can also pass options to the render function like so: + + ```elixir + defmodule HeadBlock do + use MjmlEEx.Component + + @impl true + def render(opts) do + \""" + + <%= opts[:title] %> + + + \""" + end + end + ``` + + And calling it like so: `<%= render_component(HeadBlock, title: "Some really cool title") %>` """ @doc """ - Returns the MJML markup for a particular component. This callback does - not take in any parameters + Returns the MJML markup for the component as a string. """ @callback render(opts :: keyword()) :: String.t()