Update version and docs

alexgaribay · Jul 4, 2017 · ce89baf · ce89baf
1 parent d1e113c
commit ce89baf
Show file tree

Hide file tree

Showing 5 changed files with 121 additions and 66 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,11 @@
 # Changelog
 
+## 1.5.0 (2017-7-3)
+* Enhancements
+  * update docs
+  * upgrade to Elixir 1.4
+  * add support for Phoenix Views
+
 ## 1.4.0 (2017-2-15)
 * Enhancements
   * update `httpoison` to 0.11.0 and `poison` to 3.0

diff --git a/README.md b/README.md
@@ -1,13 +1,25 @@
 # SendGrid
 
 A wrapper for SendGrid's API to create composable emails.
+Check the [docs](https://hexdocs.pm/sendgrid/) for complete usage.
+
+## Example
+
+```elixir
+  SendGrid.Email.build()
+  |> SendGrid.Email.add_to("[email protected]")
+  |> SendGrid.Email.put_from("[email protected]")
+  |> SendGrid.Email.put_subject("Hello from Elixir")
+  |> SendGrid.Email.put_text("Sent with Elixir")
+  |> SendGrid.Mailer.send()
+```
 
 ## Installation
 
 Add the following code to your dependencies in your **`mix.exs`** file:
 
 ```elixir
-{:sendgrid, "~> 1.4.0"}
+{:sendgrid, "~> 1.5.0"}
 ```
 
 ## Configuration
@@ -27,59 +39,46 @@ config :sendgrid,
   sandbox_enable: true
 ```
 
-
-
 Add `:sendgrid` to your list of applications
 ```elixir
 defp application do
   [applications: [:sendgrid]]
 end
 ```
 
-## Usage
 
-Check the [docs](https://hexdocs.pm/sendgrid/) for complete usage.
-
-### Simple Text Email
+## Phoenix Views
 
-```elixir
-alias SendGrid.{Mailer, Email}
-
-email = 
-  Email.build()
-  |> Email.put_from("[email protected]")
-  |> Email.add_to("[email protected]")
-  |> Email.put_subject("Hello From Elixir")
-  |> Email.put_text("Sent from Elixir!")
-
-Mailer.send(email)
-```
+You can use Phoenix Views to set your HTML and text content of your emails. You just have 
+to provide a view module and template name and you're good to go! See `SendGrid.Email.put_phoenix_template/3` for complete usage.
 
-### Simple HTML Email
+### Examples
 
 ```elixir
-alias SendGrid.{Mailer, Email}
-
-email = 
-  Email.build()
-  |> Email.put_from("[email protected]")
-  |> Email.add_to("[email protected]")
-  |> Email.put_subject("Hello From Elixir")
-  |> Email.put_html("<html><body><p>Sent from Elixir!</p></body></html>")
-
-Mailer.send(email)
+import SendGrid.Email
+
+# Using an HTML template
+%SendGrid.Email{}
+|> put_phoenix_view(MyApp.Web.EmailView)
+|> put_phoenix_template("welcome_email.html", user: user)
+
+# Using a text template
+%SendGridEmail{}
+|> put_phoenix_view(MyApp.Web.EmailView)
+|> put_phoenix_template("welcome_email.txt", user: user)
+
+# Using both an HTML and text template
+# Notice that there is no extension.
+%SendGrid.Email{}
+|> put_phoenix_view(MyApp.Web.EmailView)
+|> put_phoenix_template("welcome_email", user: user)
 ```
 
-### Using a SendGrid Predefined Template
+### Using a Default Phoenix View
 
-```elixir
-alias SendGrid.{Mailer, Email}
-
-email = 
-  Email.build()
-  |> Email.put_template("the_template_id")
-  |> Email.add_substitution("-foo-", "bar")
-  |> Email.put_html("<span>Some Text</span>")
-
-Mailer.send(email)
+You can set a default Phoenix View to use for rendering templates. Just set the `:phoenix_view` config value
+
+```elxir
+config :sendgrid,
+  :phoenix_view: MyApp.Web.EmailView
 ```
diff --git a/lib/sendgrid/email.ex b/lib/sendgrid/email.ex
@@ -2,20 +2,70 @@ defmodule SendGrid.Email do
   @moduledoc """
   Email primitive for composing emails with SendGrid's API.
 
-  ## Examples
+  You can easily compose on an Email to set the fields of your email.
+  
+  ## Example
+
+      Email.build()
+      |> Email.add_to("[email protected]")
+      |> Email.put_from("[email protected]")
+      |> Email.put_subject("Hello from Elixir")
+      |> Email.put_text("Sent with Elixir")
+      |> SendGrid.Mailer.send()
+
+  ## SendGrid Specific Features
+
+  Many common features of SendGrid V3 API for transactional emails are supported.
+
+  ### Templates
+
+  You can use a SendGrid template by providing a template id.
+
+      put_template(email, "some_template_id")
+
+  ### Substitutions
+
+  You can provided a key-value pair for subsititions to have text replaced.
+
+      add_substitution(email, "-key-", "value")
+
+  ### Scheduled Sending
+
+  You can provide a Unix timestamp to have an email delivered in the future.
+
+      send_at(email, 1409348513)
+
+  ## Phoenix Views
+
+  You can use Phoenix Views to set your HTML and text content of your emails. You just have 
+  to provide a view module and template name and you're good to go! See `put_phoenix_template/3` 
+  for complete usage.
+
+  ### Examples
+
+      # Using an HTML template
+      %Email{}
+      |> put_phoenix_view(MyApp.Web.EmailView)
+      |> put_phoenix_template("welcome_email.html", user: user)
+
+      # Using a text template
+      %Email{}
+      |> put_phoenix_view(MyApp.Web.EmailView)
+      |> put_phoenix_template("welcome_email.txt", user: user)
+
+      # Using both an HTML and text template
+      # Notice that there is no extension.
+      %Email{}
+      |> put_phoenix_view(MyApp.Web.EmailView)
+      |> put_phoenix_template("welcome_email", user: user)
+
+  ### Using a Default Phoenix View
+
+  You can set a default Phoenix View to use for rendering templates. Just set the `:phoenix_view` 
+  config value
 
-      iex> Email.build()
-      ...> |> Email.add_to("[email protected]")
-      ...> |> Email.put_from("[email protected]")
-      ...> |> Email.put_subject("Hello from Elixir")
-      ...> |> Email.put_text("Sent with Elixir")
-      %Email{
-        to: %{ email: "[email protected]" },
-        from %{ email: "[email protected]" },
-        subject: "Hello from Elixir",
-        content: [%{ type: "text/plain", value: "Sent with Elixir" }],
-        ...
-      }
+      config :sendgrid,
+        :phoenix_view: MyApp.Web.EmailView
 
   """
 
@@ -51,13 +101,13 @@ defmodule SendGrid.Email do
                     attachments: nil | [attachment],
                     __phoenix_view__: nil | atom}
 
-  @type recipient :: %{ email: String.t, name: String.t | nil }
-  @type content :: %{ type: String.t, value: String.t }
-  @type header :: { String.t, String.t }
+  @type recipient :: %{email: String.t, name: String.t | nil}
+  @type content :: %{type: String.t, value: String.t}
+  @type header :: {String.t, String.t}
   @type attachment :: %{content: String.t, type: String.t, filename: String.t, disposition: String.t, content_id: String.t}
 
-  @type substitutions :: %{ String.t => String.t }
-  @type custom_args :: %{ String.t => String.t }
+  @type substitutions :: %{String.t => String.t}
+  @type custom_args :: %{String.t => String.t}
 
   @doc """
   Builds an an empty email to compose on.
@@ -351,7 +401,7 @@ defmodule SendGrid.Email do
 
   ## Examples
 
-      Email.put_phoenix_view(email, MyApp.Web.EmailView)
+      put_phoenix_view(email, MyApp.Web.EmailView)
   
   """
   @spec put_phoenix_view(t, atom) :: t
@@ -383,13 +433,13 @@ defmodule SendGrid.Email do
 
   ## Examples
 
-      iex> Email.put_phoenix_template(email, "some_template.html") 
+      iex> put_phoenix_template(email, "some_template.html") 
       %Email{content: [%{type: "text/html", value: ...}], ...}
 
-      iex> Email.put_phoenix_template(email, "some_template.txt", name: "John Doe") 
+      iex> put_phoenix_template(email, "some_template.txt", name: "John Doe") 
       %Email{content: [%{type: "text/plain", value: ...}], ...}
 
-      iex> Email.put_phoenix_template(email, "some_template", user: user)
+      iex> put_phoenix_template(email, "some_template", user: user)
       %Email{content: [%{type: "text/plain", value: ...}, %{type: "text/html", value: ...}], ...}
 
   """

diff --git a/mix.exs b/mix.exs
@@ -3,7 +3,7 @@ defmodule SendGrid.Mixfile do
 
   def project do
     [app: :sendgrid,
-     version: "1.4.0",
+     version: "1.5.0",
      elixir: "~> 1.4",
      package: package(),
      compilers: compilers(Mix.env),
@@ -37,7 +37,7 @@ defmodule SendGrid.Mixfile do
       {:earmark,      "~> 1.2",  only: :dev},
       {:ex_doc,       "~> 0.16.2", only: :dev},
       {:httpoison,    "~> 0.11.0"},
-      {:poison,       "~> 3.1", override: true},
+      {:poison,       "~> 2.0"},
       {:phoenix,      "~> 1.2", only: :test},
       {:phoenix_html, "~> 2.9", only: :test}
     ]

diff --git a/mix.lock b/mix.lock
@@ -13,6 +13,6 @@
   "phoenix_html": {:hex, :phoenix_html, "2.9.3", "1b5a2122cbf743aa242f54dced8a4f1cc778b8bd304f4b4c0043a6250c58e258", [:mix], [{:plug, "~> 1.0", [hex: :plug, optional: false]}]},
   "phoenix_pubsub": {:hex, :phoenix_pubsub, "1.0.2", "bfa7fd52788b5eaa09cb51ff9fcad1d9edfeb68251add458523f839392f034c1", [:mix], []},
   "plug": {:hex, :plug, "1.3.5", "7503bfcd7091df2a9761ef8cecea666d1f2cc454cbbaf0afa0b6e259203b7031", [:mix], [{:cowboy, "~> 1.0.1 or ~> 1.1", [hex: :cowboy, optional: true]}, {:mime, "~> 1.0", [hex: :mime, optional: false]}]},
-  "poison": {:hex, :poison, "3.1.0", "d9eb636610e096f86f25d9a46f35a9facac35609a7591b3be3326e99a0484665", [:mix], []},
+  "poison": {:hex, :poison, "2.2.0", "4763b69a8a77bd77d26f477d196428b741261a761257ff1cf92753a0d4d24a63", [:mix], []},
   "ssl_verify_fun": {:hex, :ssl_verify_fun, "1.1.1", "28a4d65b7f59893bc2c7de786dec1e1555bd742d336043fe644ae956c3497fbe", [:make, :rebar], []},
   "ssl_verify_hostname": {:hex, :ssl_verify_hostname, "1.0.5"}}