hanami-mailer 0.0.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: cef366dbcaa8cf1afc3b7ec6d9bb6d38729259e8
-  data.tar.gz: 5a950a344faed3561c681ff262ffbd252be3ec7f
+  metadata.gz: cb739b22196267893812b43fcf2c2e7b37185e3f
+  data.tar.gz: d0686236004144e85a9a1d1bac67447b3f344acf
 SHA512:
-  metadata.gz: 67f164eefa5f801e38eee7e893ef768d198959867f4d0d0a46c62eca6beafeac71d7c833ca100165fc0bc465610b271b1eafbb3e4d764192b06f242b276c4e99
-  data.tar.gz: ea3cbf25de4fda191539baf45801024503959f19c440dbfe3854e4b1951283684b36800872f195822300973131978ebd64686eedc917ad56eac326b03a5b195d
+  metadata.gz: 418c209b8b97286b1076579537bccb7cec64bf51abfaeb881a10ff374601bb564630aea514b1eb17b176427c5a51d1723d9833edf8cba03f348a9f8427cb7803
+  data.tar.gz: d495d3926cb1afe2f1fbb5769e262db19daa7296647c00ebf15232d156f6f8fb3b39c81f8116cd7d34ec8d1bc055b8b76c15742f807e23e2e62d7749cee5c307

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Hanami::Router
+Mail for Ruby applications
+
+## v0.2.0 - 2016-01-22
+### Changed
+- [Luca Guidi] Renamed the project
+
+## v0.1.0 - 2015-09-30
+### Added
+- [Ines Coelho & Rosa Faria & Luca Guidi] Email delivery
+- [Ines Coelho & Rosa Faria & Luca Guidi] Attachments
+- [Ines Coelho & Rosa Faria & Luca Guidi] Multipart rendering
+- [Ines Coelho & Rosa Faria & Luca Guidi] Configuration
+- [Ines Coelho & Rosa Faria & Luca Guidi] Official support for Ruby 2.0

data/LICENSE.md

@@ -0,0 +1,22 @@
+Copyright © 2015-2016 Luca Guidi
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,8 +1,28 @@
 # Hanami::Mailer
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/hanami/mailer`. To experiment with that code, run `bin/console` for an interactive prompt.
+Mail for Ruby applications.
 
-TODO: Delete this and the text above, and describe your gem
+## Status
+
+[![Gem Version](http://img.shields.io/gem/v/hanami-mailer.svg)](https://badge.fury.io/rb/hanami-mailer)
+[![Build Status](http://img.shields.io/travis/hanami/mailer/master.svg)](https://travis-ci.org/hanami/mailer?branch=master)
+[![Coverage](http://img.shields.io/coveralls/hanami/mailer/master.svg)](https://coveralls.io/r/hanami/mailer)
+[![Code Climate](http://img.shields.io/codeclimate/github/hanami/mailer.svg)](https://codeclimate.com/github/hanami/mailer)
+[![Dependencies](http://img.shields.io/gemnasium/hanami/mailer.svg)](https://gemnasium.com/hanami/mailer)
+[![Inline Docs](http://inch-ci.org/github/hanami/mailer.svg)](http://inch-ci.org/github/hanami/mailer)
+
+## Contact
+
+* Home page: http://hanamirb.org
+* Mailing List: http://hanamirb.org/mailing-list
+* API Doc: http://rdoc.info/gems/hanami-mailer
+* Bugs/Issues: https://github.com/hanami/mailer/issues
+* Support: http://stackoverflow.com/questions/tagged/hanami
+* Chat: http://chat.hanamirb.org
+
+## Rubies
+
+__Hanami::Mailer__ supports Ruby (MRI) 2.2+.
 
 ## Installation
 
@@ -22,15 +42,377 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+### Conventions
+
+  * Templates are searched under `Hanami::Mailer.configuration.root`, set this value according to your app structure (eg. `"app/templates"`).
+  * A mailer will look for a template with a file name that is composed by its full class name (eg. `"articles/index"`).
+  * A template must have two concatenated extensions: one for the format and one for the engine (eg. `".html.erb"`).
+  * The framework must be loaded before rendering the first time: `Hanami::Mailer.load!`.
+
+### Mailers
+
+A simple mailer looks like this:
+
+```ruby
+require 'hanami/mailer'
+
+class InvoiceMailer
+  include Hanami::Mailer
+end
+```
+
+A mailer with `.to` and `.from` addresses and mailer delivery:
+
+```ruby
+require 'hanami/mailer'
+
+Hanami::Mailer.configuration do
+  delivery_method :smtp,
+    address:              "smtp.gmail.com",
+    port:                 587,
+    domain:               "example.com",
+    user_name:            ENV['SMTP_USERNAME'],
+    password:             ENV['SMTP_PASSWORD'],
+    authentication:       "plain",
+    enable_starttls_auto: true
+end.load!
+
+class WelcomeMailer
+  include Hanami::Mailer
+
+  from    'noreply@sender.com'
+  to      'noreply@recipient.com'
+  subject 'Welcome'
+end
+
+WelcomeMailer.deliver
+```
+
+### Locals
+
+The set of objects passed in the `deliver` call are called `locals` and are avaliable inside the mailer and the template.
+
+```ruby
+require 'hanami/mailer'
+
+User = Struct.new(:name, :username)
+user = User.new('Luca', 'jodosha')
+
+Hanami::Mailer.load!
+
+class WelcomeMailer
+  include Hanami::Mailer
+
+  from    'noreply@sender.com'
+  subject 'Welcome'
+  to      :recipient
+
+  private
+
+  def recipient
+    user.email
+  end
+end
+
+InvoiceMailer.deliver(user: luca)
+```
+
+The corresponding `erb` file:
+
+```erb
+Hello <%= user.name %>!
+```
+
+### Scope
+
+All public methods defined in the mailer are accessible from the template:
+
+```ruby
+require 'hanami/mailer'
+
+class WelcomeMailer
+  include Hanami::Mailer
+
+  from    'noreply@sender.com'
+  to      'noreply@recipient.com'
+  subject 'Welcome'
+
+  def greeting
+    'Ahoy'
+  end
+end
+```
+
+```erb
+<h2><%= greeting %></h2>
+```
+
+### Template
+
+The template file must be located under the relevant `root` and must match the inflected snake case of the mailer class name.
+
+```ruby
+# Given this root
+Hanami::Mailer.configuration.root      # => #<Pathname:app/templates>
+
+# For InvoiceMailer, it looks for:
+#  * app/templates/invoice_mailer.html.erb
+#  * app/templates/invoice_mailer.txt.erb
+```
+
+If we want to specify a different template, we can do:
+
+```ruby
+class InvoiceMailer
+  include Hanami::Mailer
+
+  template 'invoice'
+end
+
+# It will look for:
+#  * app/templates/invoice.html.erb
+#  * app/templates/invoice.txt.erb
+```
+
+### Engines
+
+The builtin rendering engine is [ERb](http://en.wikipedia.org/wiki/ERuby).
+
+This is the list of the supported engines.
+They are listed in order of **higher precedence**, for a given extension.
+For instance, if [ERubis](http://www.kuwata-lab.com/erubis/) is loaded, it will be preferred over ERb to render `.erb` templates.
+
+<table>
+  <tr>
+    <th>Engine</th>
+    <th>Extensions</th>
+  </tr>
+  <tr>
+    <td>Erubis</td>
+    <td>erb, rhtml, erubis</td>
+  </tr>
+  <tr>
+    <td>ERb</td>
+    <td>erb, rhtml</td>
+  </tr>
+  <tr>
+    <td>Redcarpet</td>
+    <td>markdown, mkd, md</td>
+  </tr>
+  <tr>
+    <td>RDiscount</td>
+    <td>markdown, mkd, md</td>
+  </tr>
+  <tr>
+    <td>Kramdown</td>
+    <td>markdown, mkd, md</td>
+  </tr>
+  <tr>
+    <td>Maruku</td>
+    <td>markdown, mkd, md</td>
+  </tr>
+  <tr>
+    <td>BlueCloth</td>
+    <td>markdown, mkd, md</td>
+  </tr>
+  <tr>
+    <td>Asciidoctor</td>
+    <td>ad, adoc, asciidoc</td>
+  </tr>
+  <tr>
+    <td>Builder</td>
+    <td>builder</td>
+  </tr>
+  <tr>
+    <td>CSV</td>
+    <td>rcsv</td>
+  </tr>
+  <tr>
+    <td>CoffeeScript</td>
+    <td>coffee</td>
+  </tr>
+  <tr>
+    <td>WikiCloth</td>
+    <td>wiki, mediawiki, mw</td>
+  </tr>
+  <tr>
+    <td>Creole</td>
+    <td>wiki, creole</td>
+  </tr>
+  <tr>
+    <td>Etanni</td>
+    <td>etn, etanni</td>
+  </tr>
+  <tr>
+    <td>Haml</td>
+    <td>haml</td>
+  </tr>
+  <tr>
+    <td>Less</td>
+    <td>less</td>
+  </tr>
+  <tr>
+    <td>Liquid</td>
+    <td>liquid</td>
+  </tr>
+  <tr>
+    <td>Markaby</td>
+    <td>mab</td>
+  </tr>
+  <tr>
+    <td>Nokogiri</td>
+    <td>nokogiri</td>
+  </tr>
+  <tr>
+    <td>Plain</td>
+    <td>html</td>
+  </tr>
+  <tr>
+    <td>RDoc</td>
+    <td>rdoc</td>
+  </tr>
+  <tr>
+    <td>Radius</td>
+    <td>radius</td>
+  </tr>
+  <tr>
+    <td>RedCloth</td>
+    <td>textile</td>
+  </tr>
+  <tr>
+    <td>Sass</td>
+    <td>sass</td>
+  </tr>
+  <tr>
+    <td>Scss</td>
+    <td>scss</td>
+  </tr>
+  <tr>
+    <td>Slim</td>
+    <td>slim</td>
+  </tr>
+  <tr>
+    <td>String</td>
+    <td>str</td>
+  </tr>
+  <tr>
+    <td>Yajl</td>
+    <td>yajl</td>
+  </tr>
+</table>
+
+
+### Configuration
+
+__Hanami::Mailer__ can be configured with a DSL that determines its behavior.
+It supports a few options:
+
+```ruby
+require 'hanami/mailer'
+
+Hanami::Maler.configure do
+  # Set the root path where to search for templates
+  # Argument: String, Pathname, #to_pathname, defaults to the current directory
+  #
+  root '/path/to/root'
+
+  # Set the default charset for emails
+  # Argument: String, defaults to "UTF-8"
+  #
+  default_charset 'iso-8859'
+
+  # Set the delivery method
+  # Argument: Symbol
+  # Argument: Hash, optional configurations
+  delivery_method :stmp
+```
+
+### Attachments
+
+Attachments can be added with the following API:
+
+```ruby
+class InvoiceMailer
+  include Hanami::Mailer
+  # ...
+
+  def prepare
+    mail.attachments['invoice.pdf'] = '/path/to/invoice.pdf'
+    # or
+    mail.attachments['invoice.pdf'] = File.read('/path/to/invoice.pdf')
+  end
+end
+```
+
+### Delivery Method
+
+The global delivery method is defined through the __Hanami::Mailer__ configuration, as:
+
+```ruby
+Hanami::Mailer.configuration do
+  delivery_method :smtp
+end
+```
+
+```ruby
+Hanami::Mailer.configuration do
+  delivery_method :smtp, address: "localhost", port: 1025
+end
+```
+
+Builtin options are:
+
+  * Exim (`:exim`)
+  * Sendmail (`:sendmail`)
+  * SMTP (`:smtp`, for local installations)
+  * SMTP Connection (`:smtp_connection`, via `Net::SMTP` - for remote installations)
+  * Test (`:test`, for testing purposes)
+
+### Custom Delivery Method
+
+Developers can specify their own custom delivery policy:
+
+```ruby
+require 'hanami/mailer'
+
+class MandrillDeliveryMethod
+  def initialize(options)
+    @options = options
+  end
+
+  def deliver!(mail)
+    # ...
+  end
+end
+
+Hanami::Mailer.configure do
+  delivery_method MandrillDeliveryMethod,
+    username: ENV['MANDRILL_USERNAME'],
+    password: ENV['MANDRILL_API_KEY']
+end.load!
+```
+
+The class passed to `.delivery_method` must accept an optional set of options
+with the constructor (`#initialize`) and respond to `#deliver!`.
+
+### Multipart Delivery
+
+All the email are sent as multipart messages by default.
+For a given mailer, the framework looks up for associated text (`.txt`) and `HTML` (`.html`) templates and render them.
+
+```ruby
+InvoiceMailer.deliver               # delivers both text and html templates
+InvoiceMailer.deliver(format: :txt) # delivers only text template
+```
 
-## Development
+Please note that **they aren't both mandatory, but at least one of them MUST** be present.
 
-After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+## Versioning
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+__Hanami::Mailer__ uses [Semantic Versioning 2.0.0](http://semver.org)
 
-## Contributing
+## Copyright
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/hanami-mailer.
+Copyright © 2015-2016 Luca Guidi – Released under MIT License
 
+This project was formerly known as Lotus (`lotus-mailer`).