lotus-mailer 0.0.0 → 0.1.0

data/lib/lotus/mailer/configuration.rb

@@ -0,0 +1,307 @@
+require 'set'
+require 'lotus/utils/kernel'
+
+module Lotus
+  module Mailer
+    # Framework configuration
+    #
+    # @since 0.1.0
+    class Configuration
+      # Default root
+      #
+      # @since 0.1.0
+      # @api private
+      DEFAULT_ROOT = '.'.freeze
+
+      # Default delivery method
+      #
+      # @since 0.1.0
+      # @api private
+      DEFAULT_DELIVERY_METHOD = :smtp
+
+      # Default charset
+      #
+      # @since 0.1.0
+      # @api private
+      DEFAULT_CHARSET = 'UTF-8'.freeze
+
+      # @since 0.1.0
+      # @api private
+      attr_reader :mailers
+
+      # @since 0.1.0
+      # @api private
+      attr_reader :modules
+
+      # Initialize a configuration instance
+      #
+      # @return [Lotus::Mailer::Configuration] a new configuration's instance
+      #
+      # @since 0.1.0
+      def initialize
+        @namespace = Object
+        reset!
+      end
+
+      # Set the Ruby namespace where to lookup for mailers.
+      #
+      # When multiple instances of the framework are used, we want to make sure
+      # that if a `MyApp` wants a `Mailers::Signup` mailer, we are loading the
+      # right one.
+      #
+      # If not set, this value defaults to `Object`.
+      #
+      # This is part of a DSL, for this reason when this method is called with
+      # an argument, it will set the corresponding instance variable. When
+      # called without, it will return the already set value, or the default.
+      #
+      # @overload namespace(value)
+      #   Sets the given value
+      #   @param value [Class, Module, String] a valid Ruby namespace identifier
+      #
+      # @overload namespace
+      #   Gets the value
+      #   @return [Class, Module, String]
+      #
+      # @api private
+      # @since 0.1.0
+      #
+      # @example Getting the value
+      #   require 'lotus/mailer'
+      #
+      #   Lotus::Mailer.configuration.namespace # => Object
+      #
+      # @example Setting the value
+      #   require 'lotus/mailer'
+      #
+      #   Lotus::Mailer.configure do
+      #     namespace 'MyApp::Mailers'
+      #   end
+      def namespace(value = nil)
+        if value
+          @namespace = value
+        else
+          @namespace
+        end
+      end
+
+      # Set the root path where to search for templates
+      #
+      # If not set, this value defaults to the current directory.
+      #
+      # When this method is called with an argument, it will set the corresponding instance variable.
+      # When called without, it will return the already set value, or the default.
+      #
+      # @overload root(value)
+      #   Sets the given value
+      #   @param value [String, Pathname, #to_pathname] an object that can be
+      #     coerced to Pathname
+      #
+      # @overload root
+      #   Gets the value
+      #   @return [Pathname]
+      #
+      # @since 0.1.0
+      #
+      # @see http://www.ruby-doc.org/stdlib/libdoc/pathname/rdoc/Pathname.html
+      # @see http://rdoc.info/gems/lotus-utils/Lotus/Utils/Kernel#Pathname-class_method
+      #
+      # @example Getting the value
+      #   require 'lotus/mailer'
+      #
+      #   Lotus::Mailer.configuration.root # => #<Pathname:.>
+      #
+      # @example Setting the value
+      #   require 'lotus/mailer'
+      #
+      #   Lotus::Mailer.configure do
+      #     root '/path/to/templates'
+      #   end
+      #
+      #   Lotus::Mailer.configuration.root # => #<Pathname:/path/to/templates>
+      def root(value = nil)
+        if value
+          @root = Utils::Kernel.Pathname(value).realpath
+        else
+          @root
+        end
+      end
+
+      # Prepare the mailers.
+      #
+      # The given block will be yielded when `Lotus::Mailer` will be included by
+      # a mailer.
+      #
+      # This method can be called multiple times.
+      #
+      # @param blk [Proc] the code block
+      #
+      # @return [void]
+      #
+      # @raise [ArgumentError] if called without passing a block
+      #
+      # @since 0.1.0
+      #
+      # @see Lotus::Mailer.configure
+      def prepare(&blk)
+        if block_given?
+          @modules.push(blk)
+        else
+          raise ArgumentError.new('Please provide a block')
+        end
+      end
+
+      # Add a mailer to the registry
+      #
+      # @since 0.1.0
+      # @api private
+      def add_mailer(mailer)
+        @mailers.add(mailer)
+      end
+
+      # Duplicate by copying the settings in a new instance.
+      #
+      # @return [Lotus::Mailer::Configuration] a copy of the configuration
+      #
+      # @since 0.1.0
+      # @api private
+      def duplicate
+        Configuration.new.tap do |c|
+          c.namespace  = namespace
+          c.root       = root.dup
+          c.modules    = modules.dup
+          c.delivery_method = delivery_method
+          c.default_charset = default_charset
+        end
+      end
+
+      # Load the configuration
+      def load!
+        mailers.each { |m| m.__send__(:load!) }
+        freeze
+      end
+
+      # Reset the configuration
+      def reset!
+        root(DEFAULT_ROOT)
+        delivery_method(DEFAULT_DELIVERY_METHOD)
+        default_charset(DEFAULT_CHARSET)
+
+        @mailers = Set.new
+        @modules = []
+      end
+
+      alias_method :unload!, :reset!
+
+      # Copy the configuration for the given mailer
+      #
+      # @param base [Class] the target mailer
+      #
+      # @return void
+      #
+      # @since 0.1.0
+      # @api private
+      def copy!(base)
+        modules.each do |mod|
+          base.class_eval(&mod)
+        end
+      end
+
+      # Specify a global delivery method for the mail gateway.
+      #
+      # It supports the following delivery methods:
+      #
+      #   * Exim (<tt>:exim</tt>)
+      #   * Sendmail (<tt>:sendmail</tt>)
+      #   * SMTP (<tt>:smtp</tt>, for local installations)
+      #   * SMTP Connection (<tt>:smtp_connection</tt>,
+      #     via <tt>Net::SMTP</tt> - for remote installations)
+      #   * Test (<tt>:test</tt>, for testing purposes)
+      #
+      # The default delivery method is SMTP (<tt>:smtp</tt>).
+      #
+      # Custom delivery methods can be specified by passing the class policy and
+      # a set of optional configurations. This class MUST respond to:
+      #
+      #   * <tt>initialize(options = {})</tt>
+      #   * <tt>deliver!(mail)<tt>
+      #
+      # @param method [Symbol, #initialize, deliver!] delivery method
+      # @param options [Hash] optional settings
+      #
+      # @return [Array] an array containing the delivery method and the optional settings as an Hash
+      #
+      # @since 0.1.0
+      #
+      # @example Setup delivery method with supported symbol
+      #   require 'lotus/mailer'
+      #
+      #   Lotus::Mailer.configure do
+      #     delivery_method :sendmail
+      #   end
+      #
+      # @example Setup delivery method with supported symbol and options
+      #   require 'lotus/mailer'
+      #
+      #   Lotus::Mailer.configure do
+      #     delivery_method :smtp, address: "localhost", port: 1025
+      #   end
+      #
+      # @example Setup custom delivery method with options
+      #   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
+      def delivery_method(method = nil, options = {})
+        if method.nil?
+          @delivery_method
+        else
+          @delivery_method = [method, options]
+        end
+      end
+
+      # @since 0.1.0
+      def default_charset(value = nil)
+        if value.nil?
+          @default_charset
+        else
+          @default_charset = value
+        end
+      end
+
+      protected
+      # @api private
+      # @since 0.1.0
+      attr_writer :root
+
+      # @api private
+      # @since 0.1.0
+      attr_writer :delivery_method
+
+      # @api private
+      # @since 0.1.0
+      attr_writer :default_charset
+
+      # @api private
+      # @since 0.1.0
+      attr_writer :namespace
+
+      # @api private
+      # @since 0.1.0
+      attr_writer :modules
+    end
+  end
+end

data/lib/lotus/mailer/dsl.rb

@@ -0,0 +1,288 @@
+require 'lotus/mailer/rendering/template_name'
+require 'lotus/mailer/rendering/templates_finder'
+
+module Lotus
+  module Mailer
+    # Class level DSL
+    #
+    # @since 0.1.0
+    module Dsl
+      # Set the template name IF it differs from the convention.
+      #
+      # For a given mailer named <tt>Signup::Welcome</tt> it will look for
+      # <tt>signup/welcome.*.*</tt> templates under the root directory.
+      #
+      # If for some reason, we need to specify a different template name, we can
+      # use this method.
+      #
+      # This is part of a DSL, for this reason when this method is called with
+      # an argument, it will set the corresponding class variable. When
+      # called without, it will return the already set value, or the default.
+      #
+      # @overload template(value)
+      #   Sets the given value
+      #   @param value [String, #to_s] relative template path, under root
+      #   @return [NilClass]
+      #
+      # @overload template
+      #   Gets the template name
+      #   @return [String]
+      #
+      # @since 0.1.0
+      #
+      # @see Lotus::Mailers::Configuration.root
+      #
+      # @example Custom template name
+      #   require 'lotus/mailer'
+      #
+      #   class MyMailer
+      #     include Lotus::Mailer
+      #     template 'mailer'
+      #   end
+      def template(value = nil)
+        if value.nil?
+          @template ||= ::Lotus::Mailer::Rendering::TemplateName.new(name, configuration.namespace).to_s
+        else
+          @template = value
+        end
+      end
+
+      # Returns a set of associated templates or only one for the given format
+      #
+      # This is part of a DSL, for this reason when this method is called with
+      # an argument, it will set the corresponding class variable. When
+      # called without, it will return the already set value, or the default.
+      #
+      # @overload templates(format)
+      #   Returns the template associated with the given format
+      #   @param value [Symbol] the format
+      #   @return [Hash]
+      #
+      # @overload templates
+      #   Returns all the associated templates
+      #   Gets the template name
+      #   @return [Hash] a set of templates
+      #
+      # @since 0.1.0
+      # @api private
+      def templates(format = nil)
+        if format.nil?
+          @templates = ::Lotus::Mailer::Rendering::TemplatesFinder.new(self).find
+        else
+          @templates.fetch(format, nil)
+        end
+      end
+
+      # Sets the sender for mail messages
+      #
+      # It accepts a hardcoded value as a string, or a symbol that represents
+      # an instance method for more complex logic.
+      #
+      # This value MUST be set, otherwise an exception is raised at the delivery
+      # time.
+      #
+      # When a value is given, specify the sender of the email
+      # Otherwise, it returns the sender of the email
+      #
+      # This is part of a DSL, for this reason when this method is called with
+      # an argument, it will set the corresponding class variable. When
+      # called without, it will return the already set value, or the default.
+      #
+      # @overload from(value)
+      #   Sets the sender
+      #   @param value [String, Symbol] the hardcoded value or method name
+      #   @return [NilClass]
+      #
+      # @overload from
+      #   Returns the sender
+      #   @return [String, Symbol] the sender
+      #
+      # @since 0.1.0
+      #
+      # @example Hardcoded value (String)
+      #   require 'lotus/mailer'
+      #
+      #   class WelcomeMailer
+      #     include Lotus::Mailer
+      #
+      #     from "noreply@example.com"
+      #   end
+      #
+      # @example Method (Symbol)
+      #   require 'lotus/mailer'
+      #
+      #   class WelcomeMailer
+      #     include Lotus::Mailer
+      #     from :sender
+      #
+      #     private
+      #
+      #     def sender
+      #       "noreply@example.com"
+      #     end
+      #   end
+      def from(value = nil)
+        if value.nil?
+          @from
+        else
+          @from = value
+        end
+      end
+
+      # Sets the recipient for mail messages
+      #
+      # It accepts a hardcoded value as a string or array of strings.
+      # For dynamic values, you can specify a symbol that represents an instance
+      # method.
+      #
+      # This value MUST be set, otherwise an exception is raised at the delivery
+      # time.
+      #
+      # When a value is given, specify the recipient of the email
+      # Otherwise, it returns the recipient of the email
+      #
+      # This is part of a DSL, for this reason when this method is called with
+      # an argument, it will set the corresponding class variable. When
+      # called without, it will return the already set value, or the default.
+      #
+      # @overload to(value)
+      #   Sets the recipient
+      #   @param value [String, Array, Symbol] the hardcoded value or method name
+      #   @return [NilClass]
+      #
+      # @overload to
+      #   Returns the recipient
+      #   @return [String, Array, Symbol] the recipient
+      #
+      # @since 0.1.0
+      #
+      # @example Hardcoded value (String)
+      #   require 'lotus/mailer'
+      #
+      #   class WelcomeMailer
+      #     include Lotus::Mailer
+      #
+      #     to "user@example.com"
+      #   end
+      #
+      # @example Hardcoded value (Array)
+      #   require 'lotus/mailer'
+      #
+      #   class WelcomeMailer
+      #     include Lotus::Mailer
+      #
+      #     to ["user-1@example.com", "user-2@example.com"]
+      #   end
+      #
+      # @example Method (Symbol)
+      #   require 'lotus/mailer'
+      #
+      #   class WelcomeMailer
+      #     include Lotus::Mailer
+      #     to :email_address
+      #
+      #     private
+      #
+      #     def email_address
+      #       user.email
+      #     end
+      #   end
+      #
+      #   user = User.new(name: 'L')
+      #   WelcomeMailer.deliver(user: user)
+      #
+      # @example Method that returns a collection of recipients
+      #   require 'lotus/mailer'
+      #
+      #   class WelcomeMailer
+      #     include Lotus::Mailer
+      #     to :recipients
+      #
+      #     private
+      #
+      #     def recipients
+      #       users.map(&:email)
+      #     end
+      #   end
+      #
+      #   users = [User.new(name: 'L'), User.new(name: 'MG')]
+      #   WelcomeMailer.deliver(users: users)
+      def to(value = nil)
+        if value.nil?
+          @to
+        else
+          @to = value
+        end
+      end
+
+      # Sets the subject for mail messages
+      #
+      # It accepts a hardcoded value as a string, or a symbol that represents
+      # an instance method for more complex logic.
+      #
+      # This value MUST be set, otherwise an exception is raised at the delivery
+      # time.
+      #
+      # This is part of a DSL, for this reason when this method is called with
+      # an argument, it will set the corresponding class variable. When
+      # called without, it will return the already set value, or the default.
+      #
+      # @overload subject(value)
+      #   Sets the subject
+      #   @param value [String, Symbol] the hardcoded value or method name
+      #   @return [NilClass]
+      #
+      # @overload subject
+      #   Returns the subject
+      #   @return [String, Symbol] the subject
+      #
+      # @since 0.1.0
+      #
+      # @example Hardcoded value (String)
+      #   require 'lotus/mailer'
+      #
+      #   class WelcomeMailer
+      #     include Lotus::Mailer
+      #
+      #     subject "Welcome"
+      #   end
+      #
+      # @example Method (Symbol)
+      #   require 'lotus/mailer'
+      #
+      #   class WelcomeMailer
+      #     include Lotus::Mailer
+      #     subject :greeting
+      #
+      #     private
+      #
+      #     def greeting
+      #       "Hello, #{ user.name }"
+      #     end
+      #   end
+      #
+      #   user = User.new(name: 'L')
+      #   WelcomeMailer.deliver(user: user)
+      def subject(value = nil)
+        if value.nil?
+          @subject
+        else
+          @subject = value
+        end
+      end
+
+      protected
+
+      # Loading mechanism hook.
+      #
+      # @api private
+      # @since 0.1.0
+      #
+      # @see Lotus::Mailer.load!
+      def load!
+        templates.freeze
+        configuration.freeze
+      end
+    end
+  end
+end