lotus-mailer 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 376a615362a8b09e1ed02f98bc625e788dcc781f
-  data.tar.gz: 756ab718d25f778a6c30a2eb922f19ec32cc1df9
+  metadata.gz: 010f5e6d0f8485fe6d90af54b84181fceb6d639e
+  data.tar.gz: be1bbd47898677b7f6a6179377d86c0457944899
 SHA512:
-  metadata.gz: d217f39b95869118b6d339b124bd301f320a06e6425ae02951947eb319226d977aa6d428e7e19736c8e9e556426183678fdddda8d75a74f77a0d8ec806458a45
-  data.tar.gz: 5ecb5dfad868949e6ee9bfbbeb509d4fe4d5dd04487bb0bc2309f2fae4d7e6e63a1f122ca086c49a96116bbbaf7a9ffb4556ac964fed422551ea9e7c99d38d81
+  metadata.gz: 71838f83857156392f4cd227676ac025a3dca6ba8021b0c05aa5c03b4e00ffa0f87eb5df58c7d1333d9a21520237f9e9dcb2c9294035a3992966e2381285eba3
+  data.tar.gz: 9eefa471b50fa187498e31a58eb484dcded69b0f43f540655f42a2966c055cd5d165a4e895aa43b6e529e2ffad66d5fab5eea4f0bd38493277d81a9056988339

data/CHANGELOG.md

@@ -1,2 +1,10 @@
 # Lotus::Router
 Mail for Ruby applications
+
+## 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/README.md

@@ -42,24 +42,375 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+### Conventions
 
-## Versioning
+  * Templates are searched under `Lotus::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: `Lotus::Mailer.load!`.
 
-__Lotus::Mailer__ uses [Semantic Versioning 2.0.0](http://semver.org)
+### Mailers
 
-## Development
+A simple mailer looks like this:
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake false` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+```ruby
+require lotus/mailer
 
-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).
+class InvoiceMailer
+  include Lotus::Mailer
+end
+```
 
-## Contributing
+A mailer with `.to` and `.from` addresses and mailer delivery:
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/lotus/mailer.
+```ruby
+require lotus/mailer
 
-## Copyright
+Lotus::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!
 
-Copyright © 2015 Luca Guidi – Released under MIT License
+class WelcomeMailer
+  include Lotus::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 lotus/mailer
+
+User = Struct.new(:name, :username)
+user = User.new('Luca', 'jodosha')
+
+Lotus::Mailer.load!
+
+class WelcomeMailer
+  include Lotus::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 lotus/mailer
+
+class WelcomeMailer
+  include Lotus::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
+Lotus::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 Lotus::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
+
+__Lotus::Mailer__ can be configured with a DSL that determines its behavior.
+It supports a few options:
+
+```ruby
+require 'lotus/mailer'
+
+Lotus::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 Lotus::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 __Lotus::Mailer__ configuration, as:
+
+```ruby
+Lotus::Mailer.configuration do
+  delivery_method :smtp
+end
+```
+
+```ruby
+Lotus::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 'lotus/mailer'
+
+class MandrillDeliveryMethod
+  def initialize(options)
+    @options = options
+  end
+
+  def deliver!(mail)
+    # ...
+  end
+end
+
+Lotus::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
+```
+
+Please note that **they aren't both mandatory, but at least one of them MUST** be present.
+
+## Versioning
+
+__Lotus::Mailer__ uses [Semantic Versioning 2.0.0](http://semver.org)
+
+## Copyright
+
+Copyright © 2015 Luca Guidi – Released under MIT License

data/lib/lotus-mailer.rb

@@ -0,0 +1 @@
+require 'lotus/mailer'

data/lib/lotus/mailer.rb

@@ -1,7 +1,316 @@
-require "lotus/mailer/version"
+require 'lotus/utils/class_attribute'
+require 'lotus/mailer/version'
+require 'lotus/mailer/configuration'
+require 'lotus/mailer/dsl'
+require 'mail'
 
 module Lotus
+  # Lotus::Mailer
+  #
+  # @since 0.1.0
   module Mailer
-    # Your code goes here...
+    # Base error for Lotus::Mailer
+    #
+    # @since 0.1.0
+    class Error < ::StandardError
+    end
+
+    # Missing delivery data error
+    #
+    # It's raised when a mailer doesn't specify <tt>from</tt> or <tt>to</tt>.
+    #
+    # @since 0.1.0
+    class MissingDeliveryDataError < Error
+      def initialize
+        super("Missing delivery data, please check 'from', or 'to'")
+      end
+    end
+
+    # Content types mapping
+    #
+    # @since 0.1.0
+    # @api private
+    CONTENT_TYPES = {
+      html: 'text/html',
+      txt:  'text/plain'
+    }.freeze
+
+    include Utils::ClassAttribute
+
+    # @since 0.1.0
+    # @api private
+    class_attribute :configuration
+    self.configuration = Configuration.new
+
+    # Configure the framework.
+    # It yields the given block in the context of the configuration
+    #
+    # @param blk [Proc] the configuration block
+    #
+    # @since 0.1.0
+    #
+    # @see Lotus::Mailer::Configuration
+    #
+    # @example
+    #   require 'lotus/mailer'
+    #
+    #   Lotus::Mailer.configure do
+    #     root '/path/to/root'
+    #   end
+    def self.configure(&blk)
+      configuration.instance_eval(&blk)
+      self
+    end
+
+    # Override Ruby's hook for modules.
+    # It includes basic Lotus::Mailer modules to the given Class.
+    # It sets a copy of the framework configuration
+    #
+    # @param base [Class] the target mailer
+    #
+    # @since 0.1.0
+    # @api private
+    #
+    # @see http://www.ruby-doc.org/core/Module.html#method-i-included
+    def self.included(base)
+      conf = self.configuration
+      conf.add_mailer(base)
+
+      base.class_eval do
+        extend Dsl
+        extend ClassMethods
+
+        include Utils::ClassAttribute
+        class_attribute :configuration
+
+        self.configuration = conf.duplicate
+      end
+
+      conf.copy!(base)
+    end
+
+    # Test deliveries
+    #
+    # This is a collection of delivered messages, used when <tt>delivery_method</tt>
+    # is set on <tt>:test</tt>
+    #
+    # @return [Array] a collection of delivered messages
+    #
+    # @since 0.1.0
+    #
+    # @see Lotus::Mailer::Configuration#delivery_mode
+    #
+    # @example
+    #   require 'lotus/mailer'
+    #
+    #   Lotus::Mailer.configure do
+    #     delivery_method :test
+    #   end.load!
+    #
+    #   # In testing code
+    #   Signup::Welcome.deliver
+    #   Lotus::Mailer.deliveries.count # => 1
+    def self.deliveries
+      Mail::TestMailer.deliveries
+    end
+
+    # Load the framework
+    #
+    # @since 0.1.0
+    # @api private
+    def self.load!
+      Mail.eager_autoload!
+      configuration.load!
+    end
+
+    # @since 0.1.0
+    module ClassMethods
+      # Delivers a multipart email message.
+      #
+      # When a mailer defines a <tt>html</tt> and <tt>txt</tt> template, they are
+      # both delivered.
+      #
+      # In order to selectively deliver only one of the two templates, use
+      # <tt>Signup::Welcome.deliver(format: :txt)</tt>
+      #
+      # All the given locals, excepted the reserved ones (<tt>:format</tt> and
+      # <tt>charset</tt>), are avaliable as rendering context for the templates.
+      #
+      # @param locals [Hash] a set of objects that acts as context for the rendering
+      # @option :format [Symbol] specify format to deliver
+      # @option :charset [String] charset
+      #
+      # @since 0.1.0
+      #
+      # @see Lotus::Mailer::Configuration#default_charset
+      #
+      # @example
+      #   require 'lotus/mailer'
+      #
+      #   Lotus::Mailer.configure do
+      #     delivery_method :smtp
+      #   end.load!
+      #
+      #   module Billing
+      #     class Invoice
+      #       include Lotus::Mailer
+      #
+      #       from    'noreply@example.com'
+      #       to      :recipient
+      #       subject :subject_line
+      #
+      #       def prepare
+      #         mail.attachments['invoice.pdf'] = File.read('/path/to/invoice.pdf')
+      #       end
+      #
+      #       private
+      #
+      #       def recipient
+      #         user.email
+      #       end
+      #
+      #       def subject_line
+      #         "Invoice - #{ invoice.number }"
+      #       end
+      #     end
+      #   end
+      #
+      #   invoice = Invoice.new
+      #   user    = User.new(name: 'L', email: 'user@example.com')
+      #
+      #   Billing::Invoice.deliver(invoice: invoice, user: user)                      # Deliver both text, HTML parts and the attachment
+      #   Billing::Invoice.deliver(invoice: invoice, user: user, format: :txt)        # Deliver only the text part and the attachment
+      #   Billing::Invoice.deliver(invoice: invoice, user: user, format: :html)       # Deliver only the text part and the attachment
+      #   Billing::Invoice.deliver(invoice: invoice, user: user, charset: 'iso-8859') # Deliver both the parts with "iso-8859"
+      def deliver(locals = {})
+        new(locals).deliver
+      end
+    end
+
+    # Initialize a mailer
+    #
+    # @param locals [Hash] a set of objects that acts as context for the rendering
+    # @option :format [Symbol] specify format to deliver
+    # @option :charset [String] charset
+    #
+    # @since 0.1.0
+    def initialize(locals = {})
+      @locals  = locals
+      @format  = locals.fetch(:format, nil)
+      @charset = charset = locals.fetch(:charset, self.class.configuration.default_charset)
+      @mail    = Mail.new.tap do |m|
+        m.from    = __dsl(:from)
+        m.to      = __dsl(:to)
+        m.subject = __dsl(:subject)
+
+        m.charset   = charset
+        m.html_part = __part(:html)
+        m.text_part = __part(:txt)
+
+        m.delivery_method(*Lotus::Mailer.configuration.delivery_method)
+      end
+
+      prepare
+    end
+
+    # Render a single template with the specified format.
+    #
+    # @param format [Symbol] format
+    #
+    # @return [String] the output of the rendering process.
+    #
+    # @since 0.1.0
+    # @api private
+    def render(format)
+      self.class.templates(format).render(self, @locals)
+    end
+
+    # Delivers a multipart email, by looking at all the associated templates and render them.
+    #
+    # @since 0.1.0
+    # @api private
+    def deliver
+      mail.deliver
+    rescue ArgumentError
+      raise MissingDeliveryDataError
+    end
+
+    protected
+
+    # Prepare the email message when a new mailer is initialized.
+    #
+    # This is a hook that can be overwritten by mailers.
+    #
+    # @since 0.1.0
+    #
+    # @example
+    #   require 'lotus/mailer'
+    #
+    #   module Billing
+    #     class Invoice
+    #       include Lotus::Mailer
+    #
+    #       subject 'Invoice'
+    #       from    'noreply@example.com'
+    #       to      ''
+    #
+    #       def prepare
+    #         mail.attachments['invoice.pdf'] = File.read('/path/to/invoice.pdf')
+    #       end
+    #
+    #       private
+    #
+    #       def recipient
+    #         user.email
+    #       end
+    #     end
+    #   end
+    #
+    #   invoice = Invoice.new
+    #   user    = User.new(name: 'L', email: 'user@example.com')
+    def prepare
+    end
+
+    # @private
+    # @since 0.1.0
+    def method_missing(m)
+      @locals.fetch(m) { super }
+    end
+
+    # @since 0.1.0
+    attr_reader :mail
+
+    # @private
+    # @since 0.1.0
+    attr_reader :charset
+
+    private
+
+    # @private
+    # @since 0.1.0
+    def __dsl(method_name)
+      case result = self.class.__send__(method_name)
+      when Symbol
+        __send__(result)
+      else
+        result
+      end
+    end
+
+    # @private
+    # @since 0.1.0
+    def __part(format)
+      Mail::Part.new.tap do |part|
+        part.content_type = "#{ CONTENT_TYPES.fetch(format) }; charset=#{ charset }"
+        part.body         = render(format)
+      end if __part?(format)
+    end
+
+    # @private
+    # @since 0.1.0
+    def __part?(format)
+      @format == format ||
+        (!@format && !self.class.templates(format).nil?)
+    end
   end
 end