Giter Site home page Giter Site logo

phoenix_swoosh's Introduction

Phoenix.Swoosh

Elixir CI Module Version Hex Docs Total Download License Last Updated

Phoenix.View + Swoosh. (Discuss about the future post-Phoenix-1.7 here)

This module provides the ability to set the HTML and/or text body of an email by rendering templates.

Installation

Add :phoenix_swoosh to your list of dependencies in mix.exs:

def deps do
  [
    {:phoenix_swoosh, "~> 1.0"},

    # without phoenix_html, phoenix_swoosh only works with plain text templates
    # if you want to use HTML templates
    # {:phoenix_html, "~> 3.0"},
  ]
end

You probably also want to install finch, hackney or an HTTP client of your own choice, if you are using a provider that Swoosh talks to via their HTTP API.

Or :gen_smtp if you are working with a provider that only works through SMTP.

See Swoosh for more details.

Usage

1. Classic setup

Setting up the templates:

# path_to/templates/user_notifier/welcome.html.eex
<div>
  <h1>Welcome to Sample, <%= @name %>!</h1>
</div>
# path_to/views/user_notifier_view.ex
defmodule Sample.UserNotifierView do
  use Phoenix.View, root: "path_to/templates"
end

Passing values to templates:

# path_to/notifiers/user_notifier.ex
defmodule Sample.UserNotifier do
  use Phoenix.Swoosh, view: Sample.UserNotifierView

  def welcome(user) do
    new()
    |> from("[email protected]")
    |> to(user.email)
    |> subject("Hello, Avengers!")
    |> render_body("welcome.html", %{name: name})
  end
end

Maybe with a layout:

# path_to/templates/layout/email.html.eex
<html>
  <head>
    <title><%= @email.subject %></title>
  </head>
  <body>
    <%= @inner_content %>
  </body>
</html>
defmodule Sample.LayoutView do
  use Phoenix.View, root: "path_to/templates"
end
# path_to/notifiers/user_notifier.ex
defmodule Sample.UserNotifier do
  use Phoenix.Swoosh,
    view: Sample.NotifierView,
    layout: {Sample.LayoutView, :email}

  # ... same welcome ...
end

Layout can also be added/changed dynamically with put_new_layout/2 and put_layout/2

2. Standalone setup

# path_to/templates/user_notifier/welcome.html.eex
<div>
  <h1>Welcome to Sample, <%= @name %>!</h1>
</div>
# path_to/notifiers/user_notifier.ex
defmodule Sample.UserNotifier do
  use Phoenix.Swoosh,
    template_root: "path_to/templates",
    template_path: "user_notifier"

  # ... same welcome ...
end

In this setup, the notifier module itself serves as the view module

template_root, template_path and template_namespace will be passed to Phoenix.View as root, path and namespace.

Layout can be setup the same way as classic setup.

Customization

When using either the classic or standalone setup described above, the extensions of the templates used can be customized. For example, let's say MJML is the desired markup language to use for HTML emails, and there's a template such as:

# path_to/templates/user_notifier/welcome.mjml.eex

<mjml>
  <mj-body>
    <mj-text>Welcome to Sample, <%= @name %>!</mj-text>
  </mj-body>
</mjml>

Phoenix.Swoosh can be configured to use the "mjml" extension when rendering the HTML body of the email:

# path_to/notifiers/user_notifier.ex
defmodule Sample.UserNotifier do
  use Phoenix.Swoosh,
    formats: %{"mjml" => :html_body, "text" => :text_body}

  # ... same welcome as above ...
end

This requires that Phoenix knows how to handle templates using the "mjml" format. This can be done by creating a module that exports encode_to_iodata!/1:

defmodule Sample.Mjml do
  def encode_to_iodata!(mjml) do
    with {:ok, html} <- Mjml.to_html(mjml) do
      html
    end
  end
end

And then configuring Phoenix to use it:

config :phoenix, format_encoders: [mjml: Sample.Mjml]

The above example is using mjml, which would need to be installed as well.

Copyright and License

Copyright (c) 2021 Swoosh contributors

Released under the MIT License, which can be found in LICENSE.md.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.